Branch

Branch

hg branch

hg branches

The term "branch" is sometimes used for slighlty different concepts. This may be confusing for new users of Mercurial.

Strictly speaking, a branch is created when a user creates a new [:ChangeSet:changeset] in a [:Repository:repository], if it's [:Parent:parent] changeset already has a child, thus adding a second child changeset to that parent.

This creation of a branch can also happen it two different repositories R1 and R2, both containing the same parent changeset P, and a user committing a new changeset C1 in R1 using P as its parent and a second user (or the same user) committing another new changeset C2 in R2 using the same changeset P as parent. From that perspective, each of these repositories may be seen as a "branch" of the other.

As such, each changeset in Mercurial forms an element of branch. A changeset thus always belongs to a branch. Per that definition, a branch is simply a linear sequence of changesets.

Mercurial supports giving names to branches, by using the branch name property of the changeset (see NamedBranches). If no branch name is specified when commiting a new changeset, Mercurial assigns the branch name "default". So the name of the default branch in a repository is "default".

The command hg branches lists all branch names existing in a repository:

> hg help branches
hg branches [-a]

list repository named branches

    List the repository's named branches, indicating which ones are
    inactive.  If active is specified, only show active branches.

    A branch is considered active if it contains unmerged heads.

options:

 -a --active  show only branches that have unmerged heads

use "hg -v help branches" to show global options

The command hg branch may be used to specify a branch name for the next commit:

> hg help branch
hg branch [-f] [NAME]

set or show the current branch name

    With no argument, show the current branch name. With one argument,
    set the working directory branch name (the branch does not exist in
    the repository until the next commit).

    Unless --force is specified, branch will not let you set a
    branch name that shadows an existing branch.

options:

 -f --force  set branch name even if it shadows an existing branch

use "hg -v help branch" to show global options

Mercurial branch names may be used for whatever reasons users want. However, a good rule of thumb is to use branch names sparingly and for rather longer lived concepts like "release branches" (rel-1, rel-2, etc) and rather not for short lived work of single developers.

CategoryCommand