{i} This page does not meet our wiki style guidelines. Please help improve this page by cleaning up its formatting.

Named branches

Named branches allow assigning persistent symbolic names to branches of development inside a single repository. It is neccessary to add, that all branches are actually named, the "unnamed" ones bearing the name "default".

Find What Branch You're On

Calling hg branch without a name shows the current branch name of the working directory. Calling hg branch after a hg init outputs "default", the (reserved) name of the default branch:

$ hg init
$ hg branch
default

Create a Branch

To begin a new branch, set the branch name of the working directory and then commit it:

...

$ hg branch newfeature
marked working directory as branch newfeature
$ hg branch
newfeature
$ hg ci -m "start feature branch"
$ hg parents
changeset:   3899:c08bfc770d37
branch:      newfeature
tag:         tip
user:        Matt Mackall <mpm@selenic.com>
date:        Tue Dec 19 14:20:11 2006 -0600
summary:     start feature branch

From this point on, all committed changesets will be associated with the supplied branch name. Unless overridden with the hg branch other_name command, the working directory inherits the branch name associated with a changeset. This way, a sequence of changesets will typically all have the same branch name.

When Mercurial lists a changeset, it will only show the branch name associated with the changeset if the branch name differs from the reserved branch name "default".

Create a Branch From an Older Revision

This can be done by updating your working copy to the revision in question and then creating the new branch.

$ hg update -r 500
hg 613 files updated, 0 files merged, 16 files removed, 0 files unresolved
$ hg branch newbranch
$ hg commit -m 'made a new branch from revision 500'

Switch Among Branches

Switch among branches using the hg update command:

$ hg update newfeature
$ hg update -C newbranch

By providing a branch name, hg update will update your working copy to the tip on this branch. Note: the -C option discards local changes, so be careful before using this option.

Merge Branches

When merging with another branch, the local branch name takes precedence:

$ hg up newfeature
$ hg incoming http://example.net/repos/remote
searching for changes
changeset:   3901:3be94ff00829
branch:      main
tag:         tip
parent:      3898:93e5f07baf75
user:        Matt Mackall <mpm@selenic.com>
date:        Tue Dec 19 14:26:52 2006 -0600
summary:     bug fix

$ hg pull http://example.net/repos/remote
pulling from http://example.net/repos/remote
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)

$ hg merge
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
$ hg branch
newfeature

Branch names can be used anywhere that tag names can, including log, diff, push, and pull. When a branch has multiple heads, the tipmost revision of the branch will be found. Here are some examples:

$ hg branches
main                           3901:3be94ff00829
newbranch                      3900: ...
newfeature                     3899:c08bfc770d37

$ hg log -r main
changeset:   3901:3be94ff00829
branch:      main
tag:         tip
parent:      3898:93e5f07baf75
user:        Matt Mackall <mpm@selenic.com>
date:        Tue Dec 19 14:26:52 2006 -0600
summary:     bug fix

$ hg in -r main ../bd2
searching for changes
no changes found

Delete Branches

PruningDeadBranches

Undoing a Bad Merge

Mercurial does not yet offer a foolproof way to back out an erroneous merge. The latest information I've been able to find on this matter is at http://stackoverflow.com/questions/265944/backing-out-a-backwards-merge-on-mercurial and is currently marked unresolved.

See also


CategoryHowTo

NamedBranches (last edited 2013-12-26 09:53:26 by Tovim)