One of the best things about DVCS in general is that branching and forking actually works really well. They work 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”, which are forks, in Kiln:
- You want to work on a feature, but you don’t want to impact other developers working in your “trunk” repository.
- You want to create a long-running branch/fork 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/fork 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”/fork:
You just need to give the branch/fork a name. Kiln will copy the contents and history of the repository to the new branch.
It is important to reiterate here that the branch/fork 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 repository”/fork, 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”/fork 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”/fork, if desired. While you are working in the “branch repository”/fork, 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”/fork, 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/forked 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”/fork 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/fork are now included in “trunk” repository on the server and vice versa. You now have the choice to either remove the “branch repository”/fork, or keep it around if you plan on continuing development there. You must be an administrator to remove a repository, and you do so through the Settings tab in the repository view:
