One of the best things about DVCS in general is that branching actually works really well. Branching works well because merging works well. This kind of makes sense to anyone who has used Subversion or most other centralized version control systems. It’s never the branching that’s the problem; it’s that gigantic scary merge back to trunk. Sort of like that adage, “it’s not the fall that kills you, it is the sudden stop at the end.” But I digress…

There are generally two reasons to create branch repositories in Kiln:

  1. You want to work on a feature, but you don’t want to impact other developers working in your “trunk” repository.
  2. You want to create a long-running branch for yourself or another developer (workspace). The workspace allows you to work without disrupting anything that is going on in the “trunk” repository. This facilitates the “review everything before it goes into trunk” code-review process.

To branch in Kiln, you need to be logged into the Kiln web interface and browsing your repositories. Each repository has a small context menu marked by the blue arrow, and from that menu you can create a branch repository:

kilnbranch01

kilnbranch02

You just need to give the branch a name. Kiln will copy the contents and history of the repository to the new branch.

kilnbranch03

kilnbranch04

 

It is important to reiterate here that the branch you just created is actually a full-fledged repository. You work with it just like you would any other repository. That starts with cloning. When I am working in a branch, I usually just move my copy of the “trunk” repository out of the way by renaming the folder on my machine (e.g., kiln -> kiln-trunk), and then clone the branch repository to the old trunk location. That way I don’t have to change anything in my development environment.

> hg clone http://your.fogbugz.com/kiln/repo/my/kiln/branch kiln

Now you’re ready to start working and making changes. As always, you should commit your changes locally and then push them to the server. This acts as a backup, plus it allows you to collaborate with your teammates by all cloning/pulling/pushing from the branch repository, if desired. While you are working in the branch repository, you can make whatever changes you need without fear of destabilizing the development work that is continuing in the “trunk”.

Once you’ve finished your work in the branch repository, you need to get ready to merge back into “trunk”. This is where the power of DVCS comes in, but it is also a bit different than what you are used to if you are coming from a typical, centralized VCS.

Because you have a complete repository on your machine that shares history with the repository you branched from, you can actually perform the merge on your machine, and record that action in source control. The fact that you have both the state of the files and the changes made during the merge in source control means it is nearly impossible to lose information during the merge. You can always roll back and re-merge if anything goes wrong.

To perform the merge, you’ll first want to pull the changes from the “trunk” into your local repository and merge those changes with the changes you’ve made.

> hg pull https://your.fogbugz.com/kiln/repo/my/kiln/trunk
pulling from https://your.fogbugz.com/kiln/repo/my/kiln/trunk
searching for changes
adding changesets
adding manifests
adding file changes
added 4 changesets with 5 changes to 4 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)

> hg merge
4 files updated, 0 files merged, 0 files removed, 0 files unresolved

> hg commit -m "merge"

Once this is done, you will have saved, in your local repository, all of your changes plus all of the changes that have been going on in the “trunk” repository. You can now push your changes to the “trunk” repository and your branch repository without conflict.

> hg push https://your.fogbugz.com/kiln/repo/my/kiln/trunk
pushing to https://your.fogbugz.com/kiln/repo/my/kiln/trunk
searching for changes
kiln: successfully pushed 2 changesets

> hg push
pushing to https://your.fogbugz.com/kiln/repo/my/kiln/branch
searching for changes
kiln: successfully pushed 5 changesets

These pushes will ensure that all of the changes that were in the branch are now included in “trunk” repository on the server and vice versa. You now have the choice to either remove the branch repository, or keep it around if you plan on continuing development there. You must be an administrator to remove a repository, but you get to it through the Settings tab in the repository view:

kilnbranch05