LocalbranchExtension

Local Branch Extension

This extension is not distributed with Mercurial.

Author: Brendan Cully

Repository: https://bitbucket.org/brendan/mercurial-extensions-localbranch/

PK11 fork: https://bitbucket.org/pk11/mercurial-extensions-localbranch/

Timlee fork (works with Hg v2.4): https://bitbucket.org/timlee/mercurial-extensions-localbranch

Overview

This extension provides a new command lbranch, with which you can create and manage in-repository clones. One advantage these have over regular clones is that they share a working directory, so they are cheaper to create.

They are also less work to use. Often you have the path to your working directory mentioned in several other locations (external build tools, path, etc), so a full clone requires many other updates. This way everything works against your branch automatically.

lbranch with no arguments lists the local branches in the current repository. lbranch foo switches to local branch foo, creating it if it does not yet exist. lbranch -d foo deletes local branch foo.

You can pull from or push to local branches by their branch name, or by the unambiguous form lbranch://foo (which is often necessary to pull or push to default).

Configuration

Configure your .hgrc to enable the extension by adding following lines:

[extensions]
localbranch = /path/to/localbranch.py

Usage

host95106507h:~ $ mkdir test
host95106507h:~ $ cd test/
host95106507h:test $ hg init
host95106507h:test $ hg lbranch
* default
host95106507h:test $ echo "line" >file
host95106507h:test $ ls
file
host95106507h:test $ hg add
adding file
host95106507h:test $ hg commit -m "file"
host95106507h:test $ hg lbranch fix
host95106507h:test $ hg lbranch
default
* fix
host95106507h:test $ hg up -C
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
host95106507h:test $ ls
file
host95106507h:test $ echo "line2" >>file
host95106507h:test $ hg commit -m "branch"
host95106507h:test $ hg lbranch default
host95106507h:test $ hg lbranch
* default
fix
host95106507h:test $ hg up -C
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
host95106507h:test $ hg fetch lbranch://fix
pulling from lbranch://fix
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
host95106507h:test $ hg lbranch
* default
fix
host95106507h:test $ hg lbranch -d fix
host95106507h:test $ hg lbranch
* default
host95106507h:test $ hg log
changeset:   1:198e09c8b7d3
tag:         tip
user:        pk11
date:        Mon Jul 13 12:00:39 2009 +0100
summary:     branch

changeset:   0:05806bd26904
user:        pk11
date:        Mon Jul 13 12:00:11 2009 +0100
summary:     file

Design

Named branches are nice for long-lived branches (eg stable vs development). But sometimes you want to create short-lived branches, perhaps to develop a feature. Once the code has matured to the point where it is ready for mainline, the history of its development is often just uninteresting clutter. The usual answer is to use Mercurial's nice lightweight clones. But even these require duplication of the working directory for each branch, and often other setup work (configure runs etc).

Local branches are clones that live within a repository, allowing you to share one working directory across several branches, but then to be able to drop those branches trivially when you are done with them.

Mechanism:

local branches are clones of .hg/store, residing under .hg/branches.
hg lbranch foo will clone the current repo to foo (or switch to an existing clone of that name) and write the branch name to .hg/localbranch
hg lbranch without arguments displays the local branches, with a '*' by the currently checked-out branch
hg lbranch -d <foo> will delete the local branch foo
hg pull/push/incoming/outgoing resolve local branch names to the appropriate subdirectory. You can prefix the target with lbranch:// in case of ambiguity.

PK11 fork

Another developer has created a fork of the extension with the following changes:

How about untracked and committed files?

new files committed in a localbranch will be purged automatically when switching to a different branch, i.e., hg lbranch newbranch
on the other hand, untracked files in a local branch will prevent you from switching to a different localbranch (you either need to save the working copy using for example, mq or the attic ext or you need to commit)
the new -f flag can be used to force switching even if you have untracked files in a given branch (in this case these files will be purged. You have been warned!)

(the fork is available at http://bitbucket.org/pk11/mercurial-extensions-localbranch/)

LocalbranchExtension