Question

My company is using branch repositories for feature and personal branches as suggested by Kiln. However, I'm not sure how to tell exactly what changes went into a feature branch as opposed to the parent branch.

For example, let's say I have a central repository repository with the following history:

[Central] a - ... - d (tip)

Now I create the feature branch, which initially looks like this:

[Feature] a - ... - d (tip)

Then I add some changes to the feature branch, so it looks like this:

[Feature] a - ... - d - e - ... - m - n (tip)

Now the history for my feature branch contains the entire repository history for all time ( "a" through "n" ) , with no clear indication of where it started ( which is actually at "e" ).

If I were using named branches, it would be a little more clear, as the branches would look like this:

[Central] a - ... - d 
                     \
[Feature]             e - ... - m - n (tip)

It only gets worse once you start merging changes from the central branch into the feature branch to keep up with current development while working on the feature.

At this point, the Mercurial commands hg incoming and hg outgoing (and the in/out tab in Kiln) can be used to see the changes in the filter branch, but how about after you push the feature changes back into the central branch? At that point, the two branches look like this:

[Central] a - ... - d - e - ... - m - n (tip)
[Feature] a - ... - d - e - ... - m - n (tip)

The two histories of the branch repositories are identical (assuming no changes were made separately in the central branch). Named branches don't appear have this problem, because the feature branch still exists and describes the changes:

[Central] a - ... - d ---------------- o (tip)
                     \               /
[Feature]             e - ... - m - n 

So, how do you know, at any given point in time, including after merging changes back into the central repository, what changes were made in the feature branch that are unique to that branch?

(Per Kevin's answer below, it looks like Kiln 2.3 will have a unified DAG that will help with this, but is there a good way to do this in general?)

Answer 1

Hi Chris,

As long as the changes are only in the branch, and haven't been merged into the central repo, you've got a few options for getting this information, both in Kiln and from the command line.

In Kiln, use the "In/Out" tab (called "Related" in Kiln 2.3 and later) on either repository (the central or the feature branch). On the feature branch, choose "Outgoing" to see changesets that are in the feature branch but not the central one -- that is, the changesets that would be pushed from the feature branch to trunk. If Outgoing reports "No changes", you know the central repo has everything that's in the feature branch. From the central repository, you can use the "Incoming" view of the In/Out tab to see the same information -- in this case, it's what you'd pull from the feature branch. Push & pull, and incoming & outgoing, are symmetric.

You can use the hg outgoing and hg incoming commands on the command line to get the same information. hg outgoing <target> lists the changes that you would be pushing to the <target> repository, just like the Outgoing tab in Kiln.

Once the changes are merged into the central repo, there's not an effective way (in Kiln or Mercurial) to see where a changeset originated. This is part of the Mercurial philosophy: every repository containing a changeset is a "first-class" repository, with the whole history and context of the change.

However, this sort of historical information about a changeset's past is the reason for Mercurial's named branches. Before committing a changeset, you can set a branch name for the changeset. This name becomes a permanent part of the changeset and the repository's history, and is displayed alongside the changeset in Kiln. If you use a name per feature, you can use the branch names from the hg branches to find the changesets for each feature. The Mercurial documentation has more details.

While Kiln supports named branches, Fog Creek recommends against using them, and in my opinion, named branches are not the best way to track a changeset's history. Ultimately, we find that there is little value in knowing which repository a changeset was first pushed to. We create and delete repositories regularly, so historical information like this isn't generally useful. I far more often use other changeset data in Kiln to know why and when a change was committed:

1. The changeset's author, to know who is responsible.
2. The context of the changeset in the electric DAG.
3. Comments in any code reviews on the changeset.
4. FogBugz cases associated with the changeset.

All of this information is easily accessible in Kiln, and forms a complete picture of a changeset and its context, beyond just the diffs. You are of course welcome to use named branches, but I find that Kiln's other data makes branch names or knowing a changeset's "first repo" unnecessary.

UPDATE: Kiln 2.4 has a new feature called the Related Graph. It will tell you which changesets belong to each branch, so as changesets are merged into more central repositories, you can see the relationship to the original branches. See the docs for more info and a ton of pictures.

Answer 2

[Central] a - ... - d - e - ... - m - n (tip)

[Feature] a - ... - d - e - ... - m - n (tip)

The two histories of the branch repositories are identical (assuming no changes were made separately in the central branch). Named branches don't appear have this problem, because the feature branch still exists and describes the changes:

I guess I'm not quite sure what the "this problem" you're describing is. Are you depending on the name of the branch repository to describe a task instead of writing descriptive commit messages?

We mandate an associated fogbugz case for commits, and use that product to describe features and tasks. Or perhaps I misunderstood...