git-dendrify — a tool for transforming git histories

Posted on by

I’ve been working with git for a while now, and have been experimenting with it as a way to present the history of a piece of code in a way which makes it easier for a human reader to understand. One way I think git can help with this is by adding structure to the collection of commits. Rather than just a simple flat list of commits, you can use branches and merges to give a hierarchical structure to the presentation. However, re-drafting your (local) history in the presence of merges is troublesome, so I wrote git-dendrify to help. It transforms your history between a linear form and a structured form.

For example, suppose we’re adding printing to a word processor. A flat list of commits to do this might be as follows, with the most recent at the top:

* Allow choice of colour for printing watermarks
* Add known-good test cases for watermarks
* Emit watermark 'underneath' main output (printing)
* Drop-down for printing common watermarks
* Submit PDF to system print service
* Add known-good PDF-generation test cases
* Generate PDF
* Sort paper size choices alphabetically
* Read paper size choices from database
* Add selection box for paper sizes
* Read printer list from system
* Add selection box for which printer
* Parse 'chosen pages' input like '5-8,11,12-15'
* Allow free-form CSV list of pages
* Radio list for 'pages' UI: current, all, chosen
:
: ( older history )

A hierarchical, or tree-like, structure shows the development more clearly:

* Add printing facility
|\
| * Add watermarks
| |\
| | * Allow choice of colour
| | * Add known-good test cases
| | * Emit watermark 'underneath' main output
| | * Drop-down for common watermarks
| |/
| * Add actual printing via PDF
| |\
| | * Submit PDF to system print service
| | * Add known-good test cases
| | * Generate PDF
| |/
| * Add paper selection UI
| |\
| | * Sort choices alphabetically
| | * Read paper size choices from database
| | * Add selection box for paper sizes
| |/
| * Add printer selection UI
| |\
| | * Read printer list from system
| | * Add selection box for which printer
| |/
| * Add page selection UI
| |\
| | * Parse input like '5-8,11,12-15'
| | * Allow free-form CSV list of pages
| | * Radio list: current, all, chosen
| |/
| |
|/
:
: ( older history )

The workflow would be to re-order, squash, re-word, split, etc., the history in its linear form, and then turn it into the tree-like structure (‘dendrify’ it) for presentation to others.

The github repository has a README with more details; it also explores some related questions.