== 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|repository]] clones. One advantage these have over regular clones is that they '''share a [[WorkingDirectory|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 ===

[[NamedBranches|Named branches]] are nice for long-lived [[Branch|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/)

=== See also ===

 * ShareExtension - for sharing the repository
 * BookmarksExtension - An alternative to branching, more akin to how git handles branches

----
CategoryExtensionsByOthers