git-dendrify — a tool for transforming git histories
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.