Using Mercurial Bookmarks
Tutorial on how to use Mercurial bookmarks and submit a patch to Bugzilla.
This is a brief "quick start" guide to using Mercurial Bookmarks for Thunderbird development. For more in-depth documentation see the Using Bookmarks section of Mercurial for Mozillians and the Bookmarks page on the Mercurial Wiki.
If you have used git, it will help to know that bookmarks in Mercurial are very similar to branches in git and involve similar workflows. (Note that Mercurial's branches are very different from git branches.) You may find it helpful learn more about the similarities and differences between Mercurial and Git. For example, see the in-depth discussion in Mercurial for Git Users (and vice versa).
Bookmarks are basically labels that point to a given changeset (or a given "commit" in git terminology). They can point to different changesets at different times (more on this below).
For any of the commands below, you can learn more about them by running
hg commandname --help.
A common use case for bookmarks is for working on a given feature or bug. A bookmark is a label you use to manage your work on one bug or feature, alongside other work on other bugs or features. Here's an example.
hg pullto download the latest changes from the remote repository.
hg update tipto update your current working directoryto the most recent changeset that you just downloaded.
- 3.Run the command
hg bookmark some-bookmark-nameto create a bookmarkthat points to the current changeset.Usually the name of the bookmark is related to the bug or feature you are working on.
hg bookmarksto list all of your bookmarks and see which one is currently active.The one you just created should now be active.
- 5.You can run
hg log --graphor
hg wipto see which bookmarks point to which changesets.Or you may prefer using a GUI tool likethat provides a more graphical overview.
- 6.Make changes to the code until you are ready to commit them.
hg diffto check what files and changes you are about to commit.If you need to add a new file use
hg add some-filenamebefore committing.
- 8.Commit your changes with
hg commit -m "Bug ##### - fixing something amazing".The
-mis short for
--messageand lets you provide a commit message for your changeset."Bug ##### - fixing something amazing" is the format we recommend for the commit message,specifying the number of the Bug you're working on and a small description stating what you fixed.Use
hg log --graphto see examples of commit messages.
hg log --graphor
hg wipand note how the bookmark has moved to the changeset that youjust committed.The active bookmark will automatically move to the most recent changeset as you commit your changes.That way you can make a series of commits and the bookmark will always point to the most recent one.
- 10.You can use
hg commit --amendto modify the current changeset rather than making a new one.
Let's say you now have a single changeset that fixes a bug (the simplest case), and you are ready to create a patch file to upload to the bug on bugzilla. You have used a bookmark named "feature-A" and it points to this changeset.
hg export --rev feature-A > my-feature-a-file.patchto create a patch file. The
--rev feature-Apart indicates which revision (changeset) you want, in this case the changeset that the bookmark
Being able to work on more than one bug or feature, and easily switch between working on one or the other, is a typical use case for bookmarks.
Say you have been working on feature A using the bookmark
feature-Aas described above, but now you want to switch to working on feature B. Here is how that can work.
hg log --graphor
hg wipand copy the identifying number of the first changesetthat comes before your changesets for feature A.For example if you see "changeset: 26858:4a2e39cfc820",you can copy either the "26858" or the "4a2e39cfc820" to identify this changeset.Let's say we use 26858.
hg update --rev 26858to change the state of your current working directory to that changeset.
hg bookmark feature-Bto create a new bookmark to work on feature B.It will currently point to changeset 26858.
- 4.Make some changes and do one or more commits for feature B.
- 5.To go back to working on feature A, you run the command
hg update feature-A.That updates your working directory to the
feature-Athe active bookmark.
- 6.Once you've made some changes and done some commits for feature A,you may want to go back to working on feature B.To do that you would run
hg update feature-B.That updates your working directory to the
feature-Bthe active bookmark.
Say you are ready to export one or more patches to upload to Bugzilla. Often other changes will have landed in the Thunderbird code base since you started your work. In that case it is best to make sure that your changes will still apply to the current state of comm-central. We can do that using
- 1.Pull down any new changesets with
hg log --graphor
hg wipto see if there are new changesets andget the number (or the hash) of the first changesetfrom the newly pulled changesets.Let's say its number is 54321.
- 3.Rebase your branch on to the newest changesetwith the command
hg rebase -b my-bookmark-name -d 54321.The
-bis for bookmark and the
-dis for destination.We are rebasing the changesets from the bookmark
my-bookmark-nameonto the destination changeset
For example, you have a series of changesets like so:
A -> B -> C -> D -> E
Where C, D, and E are new changesets you have created, and your bookmark "my-bookmark-name" points to changeset E.
Then, after you do
hg pullyou have this:
A -> B -> F -> G -> H
C -> D -> E
Where F, G, and H are changesets that have been added to comm-central since you started working on your changes in C, D, and E.
Then, after you do
hg rebase -b my-bookmark-name -d tipyou have:
A -> B -> F -> G -> H -> C2 -> D2 -> E2
Where Mercurial has re-applied C on top of H, then D on top of C2, then E on top of D2.
Now you know your changesets will apply to the current state of comm-central and you can export them by doing
hg export --rev NNN > my-patch-file.patchfor each of C2, D2, and E2, where NNN is the number (or hash) for the changeset.
Rebasing can be useful in other situations too. Another variation is
hg rebase -s 44444 -d 54321. Where
-sindicates a source changset. That will apply the source changeset on top of the destination changeset.
So, in the example above, if changeset C had the number 44444, then
hg rebase -s 44444 -d 54321would do the same thing as
hg rebase -b my-bookmark-name -d 54321.
What if there are "merge conflicts"? Say, in the example above, what if the same lines of a given file were changed in different ways by both changesets H and D, and Mercurial couldn't figure out what to do?
In that case, Mercurial will pause the rebase operation and guide you through the process of resolving the conflicts.
First Mercurial will tell you which files have conflicts. Open those files in your editor to fix the conflicts manually. There you will find something like the following, where you can see the two versions of the code that conflict:
// These are lines that were changed by changeset H!
// But in changeset D they were changed in a different way!
Edit those lines to resolve the conflict, so that the code is what it should be after changeset D. Once all such conflicts are fixed, save the file(s).
Then back in the terminal run the command
hg resolve --markto mark the conflicts as resolved.
And then do
hg rebase --continueand Mercurial will continue the rebase operation.
To get back to the state of things before the rebase operation started, do
hg rebase --abort.