The days when Mercurial's (in)ability to deal with branches was infamous is long time gone. Time to set a new Mercurial repository up named and to improve our skills when dealing with branches. The repository serves as an area for publicly visible prototypes which may or may not ever be merged into the official main* repository family. Each prototype lives on its own named branch.

Update: the prototypes repo described here exists, but team repositories are also permitted to contain whatever named branches they like.

Technical setup

  • a clone initially of main-silver
  • broad push permissions (anyone with main* push access)
  • does not run hook, or runs modified version which forbids >1 head to share a single branch name
    • Update: all repos run this hook, which now just checks that there is not >1 head on a given named branch
  • does run special hook forbidding changesets on default branch unless authenticated push username is ffjre
  • push-to-prototypes job pushes new main-silver changesets on a regular basis


  • pick a short but descriptive branch name, preferably including Issuezilla reference number, e.g. faster-editor-123456 (where Issue 123456 is number of bug/enhancement assigned to your work):
  • make a clone and commit some stuff to your branch:
$ hg clone main-silver prototypes
$ cd prototypes
# edit .hg/hgrc to set default to
# and set default-push to https://yourname:***
$ hg branch faster-editor-123456
# edit some editor sources or whatever
$ hg ci -m 'Playing with #123456: faster editor'
$ hg push
  • (optionally) set up a Hudson job somewhere; just use as the repository and put faster-editor-123456 in the Branch field
  • work on changes as long as you like:
# synch with trunk:
$ hg pull
# if anything came in:
$ hg merge default
$ hg ci -m 'merged default into faster-editor-123456'
# edit more
$ hg ci -m '#123456 cont'd: even faster editor'
$  hg push
  • if you ever wish to merge your branch into the official trunk:
$ cd my-team-main
$ hg pull -u
$ hg pull -r faster-editor-123456 ../prototypes
$ hg merge faster-editor-123456
$ hg ci -m 'merged #123456'
$ hg out -pv
$ hg push
  • resume new experimental work on a branch that has already been closed:
$ cd prototypes
$ hg up -C faster-editor-123456
# edit, commit, and push more as before
  • start a new branch (no problem to have several open at once):
$ cd prototypes
$ hg pull
$ hg up -C default
$ hg branch prettier-editor-135791
# edit, commit, push
  • switch between open branches:
$ cd prototypes
$ hg up -C other-branch-128976
# edit, commit, push
  • collaborate with another developer on a branch:
$ cd prototypes
$ hg up -C complicated-branch-188833
$ hg fetch -r complicated-branch-188833
# work normally

Patch Branches

Patch Branches also works well with this style, as a partial replacement for MQ:

# start a patch:
hg up default
hg pnew -t 'Issue #123456: faster editor.' faster-editor-123456
# edit, commit, push as usual
# to synch with trunk:
hg pull
hg pmerge
# to switch to trunk or another branch:
hg up default
hg up prettier-editor-135791
# to finish: (pending
hg up faster-editor-123456
hg pdiff > /tmp/faster-editor-123456.diff
cd ../team-repo
hg import /tmp/faster-editor-123456.diff
hg push
# ...and probably also want to close branch:
cd ../prototypes
hg ci -m 'done' --close-branch

Closing the branch is currently ugly: request for pfinish command

See also HgPerDeveloperBranch for other usages of named branches.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo