Mercurial named branches

Please refrain from creating any named mercurial branches on https://bitbucket.org/kokua/kokua and on any clones that you expect us to pull.

What is a 'named branch'?
In Mercurial, a 'named branch' is a set of commits (a.k.a. changesets, repository revisions) carrying a common branch name. The branch name is a permanent part of a commit, just like the commit message or the commit date. Note how this is different from branches in git, which are merely named tags (pointers to commits) that automatically move upon commit.

How are 'named branches' created?
Besides the commits, the working directory also has a branch name. If you create a new repository with, the working copy's branch name will be default. You can view the branch name of the working directory with the command hg branch without any argument. At any time, you can change the working directory's branch name with hg branch my_new_branch_name

When you commit, the new changeset's branch name will be set to whatever your working directory's branch name is at that point. If it's different from any previosly commited branch names, you've got a new named branch.

Why we don't want new named branches in Kokua
Other than git branches, mercurial's named branches are permanently encoded into the history. This means, once you have a named branch (i.e. once you have at least one commit with a a given branch name), you can't get rid of it without rewriting or discarding all commits of that branch. Doing so on already-published history would be a bad idea.

New named branches are unwanted in our upstream (Linden Lab's viewer-development), so we can't have them in any commits that we want to be pulled there.

Also, the precense of named branches affects commands like,  ,   etc. and can make their usage much more confusing.

Implicit branching
Branches (diverged lines of development) are created implicitly when making independent commits on top of a common changeset. This can either happen within a single repository (if you have moved back in history, e.g. with ) or in clones of the same repository. To distinguish this concept from branch names/named branches, it is sometimes referred to as "anonymous branches".

Branching on bitbucket
On bitbucket, click the "fork" link on any repository's page to clone it into your own bitbucket account.

Bookmarks
The Bookmarks Extension (or the built-in bookmark command in Mercurial 1.8 and later) implements a concept that's very similar to branches in git and can be used almost the same way.