View source for Labs/Bespin/DeveloperGuide/UsingMercurial

Here are some tips about using Mercurial, based on our experiences managing the Bespin project with it.

==== Getting Started ====

Our main code repository is hosted at http://hg.mozilla.org/labs/bespinclient. You can pull from that by:

* [http://www.selenic.com/mercurial/wiki/ Downloading Mercurial]
* Configuring your environment. For example you will at least want to setup a username. I use:

 [ui]
 username = Dion Almaer <dion@mozilla.com>
 
 [extensions]
 rebase =
 hgext.extdiff =
 
 [extdiff]
 cmd.opendiff = opendiff-w
 
 [merge-tools]
 filemerge.executable = opendiff-w
 filemerge.args = $local $other -ancestor $base -merge $output

* Setup a bitbucket.org account that you can use as your repository
** clone Bespin from our repo to yours and then checkout THAT repo locally to work on

* Read up:
** [https://developer.mozilla.org/en/Mozilla_Source_Code_%28Mercurial%29 Mozilla on Mercurial]
** [http://hgbook.red-bean.com/ Mercurial Definitive Guide]

==== Best Practices ====

* Use "hg pull --rebase"
** You need the "rebase =" line in your config
** It will automatically handle merging, so instead of manually doing hg pull / hg merge, just do hg pull --rebase and let it do its job. By rebasing, we don't end up with lots of merge commits in the history.

* Look ahead
** You can fetch away at will, but you can also run "hg incoming http://..." to see what would get pulled in. I have sometimes done this to release that there are a bunch of branches in there, and then I change my pull to only pull the tip default branch

* Eek, broken! How do I get back!
** If you do a fetch/pull and something messes up (or any operation) you can do a "hg rollback" to revert back

* When checking in, use the bug number at the beginning of the message and then the web view will auto link to the bug.
** E.g. hg ci -m "487459: Fixes the selection bug in Safari with -webkit-user-select: none;"

==== Contributing Back ====

When you are ready to send code back to the main repository, please take a look at [[Labs/Bespin/Contributing|Contributing to Bespin]].