|
Size: 1971
Comment: as posted by Matt Mackall on Sat Mar 29 13:21:06 CDT 2008 to mercurial-devel
|
Size: 7934
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| ''From the posting "Bookmark concept" by Matt Mackall, Sat Mar 29 13:21:06 CDT 2008 (http://selenic.com/pipermail/mercurial-devel/2008-March/005602.html)'' | == Bookmarks == '''<<TableOfContents(3)>>''' |
| Line 3: | Line 4: |
| Currently we have three ways of labeling revisions: | '''This used to be an extension in Mercurial versions prior to 1.8 (BookmarksExtension).''' |
| Line 5: | Line 6: |
| * tags: point to single revisions, modifiable, stored in history, shared * local tags (tag -l): point to single revisions, modifiable, not stored or shared * branches: stored in changesets themselves, not modifiable, stored in history and shared |
{i} Since version [[WhatsNew#Mercurial_1.8_.282011-03-01.29|1.8]] (Cset:d4ab9486e514) the bookmark command is part of core. |
| Line 9: | Line 8: |
| Our branch concept is fairly similar to the one in CVS and similar systems, but very different from the one in git. Git's notion of a branch is instead much more like our local tag: a modifiable pointer to a branch head that isn't stored in history. This has the advantage that it's very easy to make private branches, but the disadvantage that there's no recorded history of branching for public branches. |
Additional information, also for people coming from Git: [[http://blog.experimentalworks.net/2008/11/mercurial-bookmarks/|bookmarks extension explained]]. |
| Line 16: | Line 10: |
| One obvious approach to git-like functionality here is to add a "local branch" analogous to local tags. Unfortunately, that's problematic as currently a changeset can only be on a single branch |
=== Overview === Bookmarks are references to commits that can be 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. |
| Line 20: | Line 13: |
| So I've been tinkering with a new concept which I call a 'bookmark'. A bookmark would be like a local tag that gets updated every commit. So to work on a feature, you'd run 'hg bookmark myfeature', do a bunch of commits, and the myfeature bookmark would follow along. Switching between features (or branches, etc.) would be an 'hg update <id>'. |
Bookmarks can be ''active'' or ''inactive''. A single bookmark can be active at a time, and only a bookmark that points to the current revision can be active. Mercurial only tracks and updates the currently active bookmark (if there is any). This is similar to Git's approach to branching and can be used to replicate the traditional Git branching workflow. |
| Line 26: | Line 15: |
| This works fine until we want to share with other people. Pushing branches to a server would simply be 'hg push <bookmark>'. But because our bookmarks live outside the history and push/pull -only- transmit history, the server won't have any knowledge of our bookmark. This is both a good and a bad thing: in general, we don't want to spread our bookmarks all over the world. But we probably do want a way to be able to make our bookmarks visible on a server so that our branch can be pulled by name. |
When a bookmark is created it is ''active'' by default, but it can be created inactive by using the `--inactive` (or `-i`) flag. The current active bookmark can be made inactive by executing `hg bookmark --inactive`. A given bookmark can be activated by updating to that bookmark (e.g. `hg update --rev feature` updates to the revision pointed to by `feature` and activates the `feature` bookmark as well). Note that updating to a revision that has a bookmark without using the bookmark name will not activate the bookmark (e.g. if the `feature` bookmark points to revision #20 and you do `hg udpate --rev 20` the `feature` bookmark will ''not'' be activated). |
| Line 35: | Line 17: |
| ---- CategoryNewFeatures |
Since active 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`, 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 [[MqExtension|mq extension]]). Bookmarks are stored in an untracked file called ''`.hg/bookmarks`''. They are not part of committed changes but they are transferred when cloning, and can also be transferred on pull and push. This is done using the pushkey protocol as described below under "[[#Working_With_Remote_Repositories|working with remote repositories]]". === Configuration === Bookmarks are a core feature of Mercurial and as such it does not need to be enabled or configured. === Usage === Let’s give you a short example how bookmarks work. Start with an existing Mercurial repository. For the example we will use the [[http://mercurial.selenic.com/hg/hg|main mercurial repository]]. 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 }}} The fact that we updated to the bookmark means that the bookmark became active. If we had done `hg update 7300` the bookmark `hgweb-fix` would not be active after the update. If we commit at this point in the graph we'll create a new head. Note how since the bookmark was active the bookmark followed 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 identifiers for pull, for instance with `hg pull -r web-fix`. Bookmarks can also be pushed and pulled between repositories. 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. |
Bookmarks
This used to be an extension in Mercurial versions prior to 1.8 (BookmarksExtension).
Since version 1.8 (d4ab9486e514) the bookmark command is part of core.
Additional information, also for people coming from Git: bookmarks extension explained.
Overview
Bookmarks are references to commits that can be 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.
Bookmarks can be active or inactive. A single bookmark can be active at a time, and only a bookmark that points to the current revision can be active. Mercurial only tracks and updates the currently active bookmark (if there is any). This is similar to Git's approach to branching and can be used to replicate the traditional Git branching workflow.
When a bookmark is created it is active by default, but it can be created inactive by using the --inactive (or -i) flag. The current active bookmark can be made inactive by executing hg bookmark --inactive. A given bookmark can be activated by updating to that bookmark (e.g. hg update --rev feature updates to the revision pointed to by feature and activates the feature bookmark as well). Note that updating to a revision that has a bookmark without using the bookmark name will not activate the bookmark (e.g. if the feature bookmark points to revision #20 and you do hg udpate --rev 20 the feature bookmark will not be activated).
Since active 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, 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 an untracked file called .hg/bookmarks. They are not part of committed changes but they are transferred when cloning, and can also be transferred on pull and push. This is done using the pushkey protocol as described below under "working with remote repositories".
Configuration
Bookmarks are a core feature of Mercurial and as such it does not need to be enabled or configured.
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 mercurial repository. 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:1a5c9ca2bfd5We 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:591767e6ea7aThe fact that we updated to the bookmark means that the bookmark became active. If we had done hg update 7300 the bookmark hgweb-fix would not be active after the update.
If we commit at this point in the graph we'll create a new head. Note how since the bookmark was active the bookmark followed 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:1a5c9ca2bfd5If 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:4d3b1ced5c40If 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:4d3b1ced5c40If 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 identifiers for pull, for instance with hg pull -r web-fix.
Bookmarks can also be pushed and pulled between repositories. 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.
![/!\](/moin-static/modernized/img/alert.png "/!\"){kind=small}
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.