README

branchlog is a modified form of the Mercurial graphlog command (log -G), which aims to make it easier to understand complicated branching and merging structures.

This is the untested product of a few hours of weekend hackery: expect some rough edges (up to and including not working at all).

What would I use it for?

If you're working with a large number of named branches, and you want to see just the large-scale branch structure without focusing too much on the individual commits.

Sample output:

$ hg branchlog -G -r 6640:6693 --template '{rev} {tags},{branches} {desc|firstline} --{author|user}'
o   6687 ,sd-175-search-issues hg up -r 3.52 &&hg branch sd-175-search-issues --Jan-Wijbrand
|
|  :   (14 changesets e.g. 6679)
|  |
|  o   6678 ,md-1636-content-service-client merge default --Jan-Jaap
|  |\
|  | \
|  |  |  o   6674 ,md-222-mondriaan hg merge default --Niels
|  |  | /|
|  |  |/ |
|  |  :  |   (1 changeset: 6673)
|  |  |  |
|  |  |  :   (1 changeset: 6672)
|  |  |  |
|  |  |  o   6671 ,md-222-mondriaan hg merge default --Niels
|  |  | /|
|  |  |/ |
|  o  |  |   6670 ,md-1636-content-service-client Merge with default --sviollon
|  |\ |  |
|  | \|  |
|  |  |  |  :   (4 changesets e.g. 6666)
|  |  |  |  |
|  |  |  |  |  :   (4 changesets e.g. 6657)
|  |  |  |  |  |
|  |  | -|--o  |   6656 ,md-1831-references-everywhere MD-1831 Branch to enable references between documents in every tool --sviollon
|  |  |/ |    /
|  |  |  |   /
|  |  :  |  |   (1 changeset: 6655)
|  |  |  |  |
|  | -|--|--o   6654 ,md-1183-diary-schema-migration mergedefault --Jan-Jaap
|  |/ |  |  |
|  |  |  |  :   (2 changesets e.g. 6652)
|  |  |  |  |
|  |  | -|--o   6651 ,md-1183-diary-schema-migration merge default --Jan-Jaap
|  |  |/ |  |
|  |  |  |  o   6650 ,md-1183-diary-schema-migration merge default --Jan-Jaap
|  |  |  |  |\
|  |  |  |  | \
|  |  o--|--|- |   6649 , 3.53 (unreleased) --Jan-Jaap
|  |  |  |  | \|
|  |  :  |  |  |   (1 changeset: 6648)
|  |  |  |  |  |
| -|--:  |  |  |   (1 changeset: 6647)
|/ |    /  /  /
|  |   /  /  /
o  |  |  |  |   6646 3.52,release-3.51 Preparing release 3.52 --Jan-Jaap
|  |  |  |  |
o  |  |  |  |   6645 ,release-3.51 3.52 (unreleased) --Jan-Jaap
|  |  |  |  |
|  |  |  |  o   6643 , work on angular 1.3.4 --Jan-Jaap
|  |  |  |  |\
|  |  |  |  | \
| -|--|--|--|--:   (2 changesets e.g. 6641)
|/ |  |  |  |
o  |  |  |  |   6640 3.51, Preparing release 3.51 --Jan-Jaap
|  |  |  |  |

Things to notice about the sample output:

• 53 commits in 56 lines.
• Every merge from one branch to another is shown, as are tagged revisions.
• Sequences of commits (including merges) on the same branch are usually collapsed.
• Standard options like -r and --template work as usual.
• A bunch of "close branch" commits were suppressed invisibly (you'll have to take my word for it).
• Wider spacing makes the branch structure easier to see...
• ...but it can also make the ascii-art slightly trickier to interpret (see e.g. rev 6649).
• Not all sequences of commits are collapsed (see e.g. 6647 and 6648). See below for why.

What exactly are we seeing and not seeing?

Experimental feature: changesets that close a branch are simply silently dropped. I'm not sure this will survive.

Apart from that, we basically just classify changesets as "interesting" or "boring". "Interesting" changesets are shown as usual; "boring" changesets are suppressed. A changeset is interesting if:

• it's tagged, or
• it's a head (no children) or a root (no parents), or
• it has a parent on a different branch to its own.

However, there are some cases where if we follow this logic rigorously we end up with an ascii DAG which is very hard to interpret. To avoid a particular kind of confusion, some commits are "half-interesting": these are shown as boring (: in the DAG and the commit message is suppressed) but are never collapsed together with other commits. 6648 is an example, which is why it does not merge with 6647. (Technical detail for interested parties: parents of a commit that has children on a different branch are marked "half-interesting"; the reason is to avoid merging those parents with children of the interesting commit, since this produces an ascii DAG which appears to show changesets out of order.)

How do I use it?

Put it somewhere on your pythonpath, and enable the extension in your .hgrc. Mine looks like this:

[extensions]
branchlog = ~/code/branchlog/branchlog.py

Who do I talk to?

Tikitu de Jager <tikitu@logophile.org>

A note on originality

This is really just a hacked-together modification of something other people wrote. To make clearer how little is original here, there's a branch named originals in the repository. That contains the code that I've stolen from other places, before I started making alterations. (They are very lightly edited for imports and qualified function names, since I'm moving things around.) By diffing this with default you can see exactly what I've added and modified with respect to the original graphlog behaviour.