Differences between revisions 25 and 26
⇤ ← Revision 25 as of 2009-10-23 20:23:10 →
Size: 3457
Editor: MartinGeisler
Comment: Removed unnecessary and outdated links, mentioned track.current, fixed formatting
← Revision 26 as of 2010-06-17 21:32:48 → ⇥
Size: 4509
Editor: mpm
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
'''<<TableOfContents([maxdepth])>>'''
Line 10: Line 11:
Bookmarks are markers on commits that move when new commits are made. Therefore you can do a `hg bookmark newfeature` and work on that and the bookmark will move forward with every commit you do.
Line 11: Line 13:
Bookmarks are markers on commits that move when new commits are made. Therefore you can
do a `hg bookmark newfeature` and work on that and the bookmark will move
forward with every commit you do.		 Bookmarks can be used to access the commit whenever a usual lookup is allowed, therefore you can merge and update bookmarks by their names.
Line 15: Line 15:
Bookmarks can be used to access the commit whenever a usual lookup is
allowed, therefore you can merge and update bookmarks by their names.

Bookmarks are stored localy. You can use rsync or scp to copy the .hg/bookmarks file
to a remote repository. You can also use `hg id -r <bookmark> <repourl>` to get the id
of a bookmark (and therefore might manually track it).		 Bookmarks are stored localy. You can use rsync or scp to copy the .hg/bookmarks file to a remote repository. You can also use `hg id -r <bookmark> <repourl>` to get the id of a bookmark (and therefore might manually track it).
Line 23: Line 18:
Line 33: Line 29:
Line 41: Line 36:

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`		 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`
Line 51: Line 42:

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.		 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.
Line 57: Line 45:
Line 60: Line 47:
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:		 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:
Line 67: Line 53:
Create a bookmark on the current tip of the repository:
Line 68: Line 55:
Create a bookmark on the current tip of the repository:
Line 74: Line 60:
Let’s create a bookmark on another revision in the history:
Line 75: Line 62:
Let’s create a bookmark on another revision in the history:
Line 82: Line 68:
We can then update to the revision:
Line 83: Line 70:
We can then update to the revision:
Line 91: Line 77:
We also can now commit to this bookmark and create a new head:
Line 92: Line 79:
We also can now commit to this bookmark and create a new head:
Line 100: Line 86:
Let’s go back to our tip and merge our change into it:
Line 101: Line 88:
Let’s go back to our tip and merge our change into it:
Line 107: Line 93:
Now we can just delete our bookmarks:
Line 108: Line 95:
Now we can just delete our bookmarks:
Line 115: Line 101:
Line 120: Line 107:
Line 123: Line 109:
=== Working With Remote Repositories ===
Bookmarks in remote repositories are "visible" as identifier for pull, for instance with `hg pull -r web-fix`.
Line 124: Line 112:
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.

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 Extension

<<TableOfContents: execution failed [Argument "maxdepth" must be an integer value, not "[maxdepth]"] (see also the log)>>

This extension is distributed with Mercurial.

Author: DavidSoria

Additional information, also for people coming from Git: bookmarks extension explained

Overview

Bookmarks are markers on commits that move when new commits are made. Therefore you can do a hg bookmark newfeature and work on that and the bookmark will move forward with every commit you do.

Bookmarks can be used to access the commit whenever a usual lookup is allowed, therefore you can merge and update bookmarks by their names.

Bookmarks are stored localy. You can use rsync or scp to copy the .hg/bookmarks file to a remote repository. You can also use hg id -r <bookmark> <repourl> to get the id of a bookmark (and therefore might manually track it).

An example usage: 

$ hg bookmark ds/feature-x
.. hack .. hack ..
$ hg commit
.. hack .. hack ..
$ hg commit
$ hg update 4
# go back to old rev
$ hg merge ds/feature-x

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.

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: 

 $ hg bookmarks
 no bookmarks set

Create a bookmark on the current tip of the repository: 

 $ hg bookmark my-tip
 $ hg bookmarks
   * my-tip                    7348:1a5c9ca2bfd5

Let’s create a bookmark on another revision in the history: 

 $ hg bookmark -r 7300 hgweb-fix
 $ hg bookmarks
   * my-tip                  7348:1a5c9ca2bfd5
     hgweb-fix               7300:591767e6ea7a

We can then update to the revision: 

 $ 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

We also can now commit to this bookmark and create a new head: 

 ...hack..hack..
 $ hg commit -m’Another hgweb bugfix’
 $ hg bookmarks
      my-tip                  7348:1a5c9ca2bfd5
   *  hgweb-fix               7349:ca3fbad32554

Let’s go back to our tip and merge our change into it: 

 $ hg update -C my-tip
 $ hg merge hgweb-fix
 $ hg commit -m’Merge bookmark hgweb-fix’

Now we can just delete our bookmarks: 

 $ hg bookmark -d hgweb-fix
 $ hg bookmarks
   * my-tip                  7350:3acda44343da

Delete the changeset as well (requires 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.

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.

CategoryExtension