5800
Comment: Get rid of short example. Extended example gives better sense of usage.
|
7408
Elaborate on example
|
Deletions are marked like this. | Additions are marked like this. |
Line 35: | Line 35: |
Now let’s go into a Mercurial repository. You can run `hg help bookmarks` to show the available flags. Let’s start with a basic listing of available bookmarks: | Start with an existing Mercurial repository. For the example we will use the [[http://mercurial.selenic.com/hg/hg|main repository for Mercurial itself]]. Let’s start with a basic listing of available bookmarks: |
Line 41: | Line 41: |
Create a bookmark on the current tip of the repository: | Create a bookmark on the current tip of the repository. This isn't a bookmark we're going to work on, instead it's meant to reference where tip was on the server-side repository when we started, a baseline for our work. Notice how the current bookmark is preceded by "`*`". |
Line 48: | Line 48: |
Let’s create a bookmark on another revision in the history: | Create a bookmark on another revision in the history. This is a bookmark we'll actually do work on. Note that creating a new bookmark does ''not'' create a new head. |
Line 55: | Line 55: |
$ hg heads -q 7348:1a5c9ca2bfd5 |
|
Line 56: | Line 58: |
We can then update to the revision: | We can then update to the bookmark we want to work on. |
Line 65: | Line 67: |
We also can now commit to this bookmark and create a new head: | If we commit at this point in the graph we'll create a new head. Note how the bookmark follows along, continuing to point to our working head. |
Line 68: | Line 70: |
...hack..hack.. $ hg commit -m’Another hgweb bugfix’ |
...hack...hack... $ hg commit -m ’Another hgweb bugfix’ |
Line 73: | Line 75: |
$ hg heads -q 7349:ca3fbad32554 7348:1a5c9ca2bfd5 |
|
Line 74: | Line 79: |
Let’s go back to our tip and merge our change into it: | If we go back to the bookmarked tip we can merge our change into it. Note that the merge doesn't get rid of either bookmark. Note also how only `my-tip` has moved forward with the merge changeset. `hgweb-fix` continues to point to the last work done while on that bookmark. This is because we've set `track.current` in our ''`.hgrc`''. |
Line 79: | Line 84: |
$ hg commit -m’Merge bookmark hgweb-fix’ | $ hg commit -m ’Merge hgweb-fix’ $ hg bookmarks * my-tip 7350:4d3b1ced5c40 hgweb-fix 7349:ca3fbad32554 $ hg heads -q 7350:4d3b1ced5c40 |
Line 81: | Line 91: |
Now we can just delete our bookmarks: | If we decide we want to continue working on our feature from the new tip, we can move the feature bookmark directly to match the tip. Note the need to use `-f` to force an existing bookmark to move. {{{ $ hg book -f hgweb-fix $ hg bookmarks my-tip 7350:4d3b1ced5c40 * hgweb-fix 7350:4d3b1ced5c40 }}} If we're done we can just delete our working bookmark. Note that this doesn't delete the changeset. This doesn't matter much if this is a line of work that gets merged (i.e. we decide to keep it), but it doesn't do everything we want for a branch we decide to discard. |
Line 88: | Line 106: |
Delete the changeset as well (requires mq extension): | To actually delete the changeset as well requires the `mq` extension. |
Line 91: | Line 109: |
hg tag -r hgweb-fix hgweb-fix-tag hg bookmark -d hgweb-fix hg strip hgweb-fix-tag |
$ hg tag -r hgweb-fix hgweb-fix-tag $ hg bookmark -d hgweb-fix $ hg strip hgweb-fix-tag |
Bookmarks Extension
This extension is distributed with Mercurial.
Author: DavidSoria
Additional information, also for people coming from Git: bookmarks extension explained
Overview
Bookmarks are references to commits that are automatically updated when new commits are made. If you do hg bookmark feature the feature bookmark refers to the current changeset. As you work and commit changes the bookmark will move forward with every commit you do. The bookmark will always point to the latest revision in your line of work. Since bookmarks are automatically updated when committing to the changeset they are pointing to, they are especially useful to keep track of different heads. They can therefore be used for trying out new features or pulling changes that have yet to be reviewed. Bookmarks can be used to access the commit whenever a usual lookup is allowed (wherever a command takes -r revision, revision can be a bookmark name), therefore you can merge and update bookmarks by their names.
If the new features don't work out, development can be re-started from an old changeset. Note however that while bookmarks can be deleted using hg book -d feature, but this merely removes the bookmark feature, not the changes it points to. The unwanted changes will remain in the repository. The bookmarked head can be stripped (using hg strip, supplied with the mq extension).
Bookmarks are stored in a file called .hg/bookmarks. They are not part of committed changes, which means that prior to Mercurial 1.6 they are local to their repository, with no builtin way to share them between repositories. You can use rsync or scp to copy the .hg/bookmarks file to a remote repository, or you can use hg id -r <bookmark> <repourl> to get the id of a bookmark and track it manually (though this is tedious). From Mercurial 1.6 and on bookmarks can be shared between repositories as described below under "working with remote repositories".
Configuration
Configure your .hgrc to enable the extension by adding following lines:
[extensions] bookmarks =
By default, when several bookmarks point to the same changeset, they will all move forward together. It is possible to obtain a more Git-like experience by adding the following configuration option to your .hgrc
[bookmarks] track.current = True
This will cause Mercurial to track the bookmark that you are currently using, and only update it. This is similar to Git's approach to branching.
Usage
Let’s give you a short example how bookmarks work.
Start with an existing Mercurial repository. For the example we will use the main repository for Mercurial itself. Let’s start with a basic listing of available bookmarks:
$ hg bookmarks no bookmarks set
Create a bookmark on the current tip of the repository. This isn't a bookmark we're going to work on, instead it's meant to reference where tip was on the server-side repository when we started, a baseline for our work. Notice how the current bookmark is preceded by "*".
$ hg bookmark my-tip $ hg bookmarks * my-tip 7348:1a5c9ca2bfd5
Create a bookmark on another revision in the history. This is a bookmark we'll actually do work on. Note that creating a new bookmark does not create a new head.
$ hg bookmark -r 7300 hgweb-fix $ hg bookmarks * my-tip 7348:1a5c9ca2bfd5 hgweb-fix 7300:591767e6ea7a $ hg heads -q 7348:1a5c9ca2bfd5
We can then update to the bookmark we want to work on.
$ hg update hgweb-fix 82 files updated, 0 files merged, 31 files removed, 0 files unresolved $ hg bookmarks my-tip 7348:1a5c9ca2bfd5 * hgweb-fix 7300:591767e6ea7a
If we commit at this point in the graph we'll create a new head. Note how the bookmark follows along, continuing to point to our working head.
...hack...hack... $ hg commit -m ’Another hgweb bugfix’ $ hg bookmarks my-tip 7348:1a5c9ca2bfd5 * hgweb-fix 7349:ca3fbad32554 $ hg heads -q 7349:ca3fbad32554 7348:1a5c9ca2bfd5
If we go back to the bookmarked tip we can merge our change into it. Note that the merge doesn't get rid of either bookmark. Note also how only my-tip has moved forward with the merge changeset. hgweb-fix continues to point to the last work done while on that bookmark. This is because we've set track.current in our .hgrc.
$ hg update -C my-tip $ hg merge hgweb-fix $ hg commit -m ’Merge hgweb-fix’ $ hg bookmarks * my-tip 7350:4d3b1ced5c40 hgweb-fix 7349:ca3fbad32554 $ hg heads -q 7350:4d3b1ced5c40
If we decide we want to continue working on our feature from the new tip, we can move the feature bookmark directly to match the tip. Note the need to use -f to force an existing bookmark to move.
$ hg book -f hgweb-fix $ hg bookmarks my-tip 7350:4d3b1ced5c40 * hgweb-fix 7350:4d3b1ced5c40
If we're done we can just delete our working bookmark. Note that this doesn't delete the changeset. This doesn't matter much if this is a line of work that gets merged (i.e. we decide to keep it), but it doesn't do everything we want for a branch we decide to discard.
$ hg bookmark -d hgweb-fix $ hg bookmarks * my-tip 7350:3acda44343da
To actually delete the changeset as well requires the mq extension.
$ hg tag -r hgweb-fix hgweb-fix-tag $ hg bookmark -d hgweb-fix $ hg strip hgweb-fix-tag
You can use bookmarks in every rev lookup. This means you can also do hg log -prf my-tip:0 or hg qimport -r my-tip. It is even possible to look them up using hg id -r.
Working With Remote Repositories
Bookmarks in remote repositories are "visible" as identifier for pull, for instance with hg pull -r web-fix.
Starting with Mercurial 1.6, bookmarks can also be pushed and pulled between repositories. This naturally requires the bookmark extension to be enabled on both sides.
By default bookmarks that are already present on both the client and server are updated on the client on pull and updated on the server on push.
To start sharing a bookmark present on a server, use hg pull -B bookmark and the bookmark along with the relevant changesets will be pulled to the client.
To publish a local bookmark to a server, use hg push -B bookmark and the bookmark along with the relevant changesets will be pushed to the server. To delete a bookmark from a server, delete it locally first, then use push -B on the deleted name.
To check which bookmarks exist on the remote repository but not locally use hg incoming -B. Use hg outgoing -B to check which bookmarks exists locally but not yet on the remote repository.
Be aware that there is only one namespace for bookmarks - it is advised to prefix your local-only bookmarks to avoid conflicts with other users.