Branch

hg branch

hg branches

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

Branches occur if lines of development diverge. The term "branch" may thus refer to a "diverged line of development". For Mercurial, a "line of development" is a linear sequence of consecutive changesets.

Combining a line of development into an existing one is called merging.

1. Creating a branch

Branching can happen by committing a changeset within a single repository or by committing diverging changes in distinct (but related) repositories. Two repositories are said to be related if they were once cloned from the same repository but later may have diverged.

In contrast, merging — the act of combining two diverged development lines — can only be done in one repository. If you want to merge a diverged line of development that only exists in a separate related repository, you must first pull the head of that development line from the other repository into your local repository and then do the merge.

1.1. Single repository

Strictly speaking, a branch is created when a user creates a new changeset C2 in a repository R0, if its parent changeset P already has a child C1, thus adding a second child changeset C2 to that parent P. This adds a new head to R0.

1.2. Two Repositories

The creation of a branch can also happen in 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".

• Note: after doing a hg --repository R1 pull --rev 3b978afa9ee5 R2, repository R1 will look the same as repository R0. This finally adds a new head to R1 as well.

As such, each changeset in Mercurial forms an element of a branch. A changeset thus can be said to "belong to a branch". Per that definition, a branch is simply a linear sequence of changesets.

2. Named branches

Mercurial supports giving names to branches, by using the branch name property of the changeset (see NamedBranches). If no branch name was set, Mercurial assigns the branch name "default". So the name of the default branch in a repository is "default" (which, for example, is not displayed when doing a hg log).

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 set a branch name, which will be used for subsequent commits:

> 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.

Some Mercurial users do not use branch names at all. And there is indeed no need to assign branch names in Mercurial. Some users find them helpful, some not. Establish and apply your local consensus.

3. A Changeset attribute

(from a posting by Yao Zhang on the mercurial mailing list)

There is a subtle difference between the concept "diverging development line" and Mercurial "branch" name.

Mercurial branch name is an attribute associated with a changeset. A new branch name can be started in the middle of a development line, not necessarily at a diverging point. For example:

hg branch branch-1          # start a new branch name
                            # modify something in the repository
hg commit -m "branch-1"     # the changeset has branch name "branch-1"

hg branch branch-2          # start another branch name
                            # modify something in the repository
hg commit -m "branch-2"     # the changeset has branch name "branch-2"

Although there is no "diverging development line" above, the Mercurial branch name can be changed.

Another case is that if a "diverging development line" occurs later, both diverged lines will inherit the parent's branch name if no new branch name is started.

4. See also

• Merge

• TutorialMerge

• MultipleHeads

• NamedBranches

• LocalbranchExtension

• BranchPlan

• PruningDeadBranches

• Bookmarks

• MutableBranches

5. External links

• A Guide to Branching in Mercurial

• Managing releases and branchy development in "Mercurial: The Definitive Guide"

CategoryCommand CategoryGlossary

Français