Help: bookmarks

hg bookmarks [OPTIONS]... [NAME]...

aliases: bookmark

create a new bookmark or list existing bookmarks

Bookmarks are labels on changesets to help track lines of development. Bookmarks are unversioned and can be moved, renamed and deleted. Deleting or moving a bookmark has no effect on the associated changesets.

Creating or updating to a bookmark causes it to be marked as 'active'. The active bookmark is indicated with a '*'. When a commit is made, the active bookmark will advance to the new commit. A plain 'hg update' will also advance an active bookmark, if possible. Updating away from a bookmark will cause it to be deactivated.

Bookmarks can be pushed and pulled between repositories (see 'hg help push' and 'hg help pull'). If a shared bookmark has diverged, a new 'divergent bookmark' of the form 'name@path' will be created. Using 'hg merge' will resolve the divergence.

Specifying bookmark as '.' to -m/-d/-l options is equivalent to specifying the active bookmark's name.

A bookmark named '@' has the special property that 'hg clone' will check it out by default if it exists.


The following keywords are supported in addition to the common template keywords and functions such as "{bookmark}". See also 'hg help templates'.

Boolean. True if the bookmark is active.


  • create an active bookmark for a new line of development:
    hg book new-feature
  • create an inactive bookmark as a place marker:
    hg book -i reviewed
  • create an inactive bookmark on another changeset:
    hg book -r .^ tested
  • rename bookmark turkey to dinner:
    hg book -m turkey dinner
  • move the '@' bookmark from another branch:
    hg book -f @
  • print only the active bookmark name:
    hg book -ql .


-f --force force
-r --rev REV revision for bookmark action
-d --delete delete a given bookmark
-m --rename OLD rename a given bookmark
-i --inactive mark a bookmark inactive
-l --list list existing bookmarks
-T --template TEMPLATE display with template

global options ([+] can be repeated):

-R --repository REPO repository root directory or name of overlay bundle file
--cwd DIR change working directory
-y --noninteractive do not prompt, automatically pick the first choice for all prompts
-q --quiet suppress output
-v --verbose enable additional output
--color TYPE when to colorize (boolean, always, auto, never, or debug)
--config CONFIG [+] set/override config option (use '')
--debug enable debugging output
--debugger start debugger
--encoding ENCODE set the charset encoding (default: UTF-8)
--encodingmode MODE set the charset encoding mode (default: strict)
--traceback always print a traceback on exception
--time time how long the command takes
--profile print command execution profile
--version output version information and exit
-h --help display help and exit
--hidden consider hidden changesets
--pager TYPE when to paginate (boolean, always, auto, or never) (default: auto)