Question

How do I create a branch? How do I merge that with trunk?

Answer 1

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:

You just need to give the branch 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 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:

Answer 2

Rob Conery posted a video showing how to use the TortoiseHG client to branch & merge. It is specifically for CodePlex but it is a good insight into using TortoiseHG.

Answer 3

Hello,

I think your branching model is nice. However, I have a comment regarding your statement:

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.

As I understand, on your servers you perform a "hg clone" to hardlink as much as possible (saving disk space). Here, suggesting cloning from the remote server I think is not the best idea. You could just do locally (the user, on his/her computer) a "hg clone foo foo-featureX" modifying .hg/hgrc to point to the branched repo, so disk space is also saved in user's hard disk.

Answer 4

As I understand, on your servers you perform a "hg clone" to hardlink as much as possible (saving disk space). Here, suggesting cloning from the remote server I think is not the best idea. You could just do locally (the user, on his/her computer) a "hg clone foo foo-featureX" modifying .hg/hgrc to point to the branched repo, so disk space is also saved in user's hard disk.

Correct, but you can also fix that after the fact using the relink extension (or the hg-relink script in contrib/ for older versions of mercurial).

Answer 5

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. ...

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.

What if another user pushes to the trunk in between the time you pull from the trunk and merge locally/push back to the trunk? There will be changes in the trunk that are not in your local repository, opening you up to conflicts (as indicated by the last sentence).

Isn't it better to think of this process as trying to minimize conflicts rather than being able to prevent them outright?

Answer 6

FYI, to do a TortoiseHG pull from the trunk:

• From Workbench, File>Settings
• Select your projects tab, click "Edit File" button near the top
• Change URL path to "trunk path"
• Close and reopen workbench
• Do a normal Pull/merge. You just pulled changes from trunk into branch.
• Change path settings back to your branch.
• Close and reopen workbench

Now your back to being pointed at your branch repository on the server.

Obviously the command line is easier, but if you live in Tortoise this might be helpful.

Answer 7

How to update a branch repository after branching the repository from kiln?......