Hi,
I've recently been experimenting with using git to make software more
human-readable. Presenting software for humans to read is not a new
idea (Knuth's 'literate programming'), but I think git can be a new
tool for showing the development of code in a structured way.
Merge-commits can break a flat sequence of commits into sections and
subsections, in the same way that a document's paragraphs are
arranged. The hierarchical organisation is helpful when reading the
history, and also allows that history to be rendered into a structured
document explaining the code's development.
As a demo, I've created:
http://www.redfrontdoor.org/20160813-literate-git-demo/index.html
This was generated directly from the git repo of the project, using
tools I wrote:
https://github.com/bennorth/literate-git
For working with hierarchical git histories, I wrote another tool:
https://github.com/bennorth/git-dendrify
The READMEs of the two projects give more details of these ideas.
This is at the prototype / proof-of-concept stage --- any feedback welcome!
Thanks,
Ben.
On Wed, Aug 31, 2016 at 1:41 PM, Ben North [off-list ref] wrote:
https://github.com/bennorth/git-dendrify
So looking at the Readme there:
* 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
...
This reminds me of the workflow of git itself.
(As a literate consumer) You get an easy top-level overview what
the community is interested in via e.g.:
git log --first-parent --oneline
That would be equivalent to showing only
* Add printing facility
If you run that command on "* Add printing facility"^2
you would see the headlines of the section.
However in gits reality we do not have these nice sections
building on top of each other, as many people are interested in
different things and build where they see fit.
The hierarchical organisation is helpful when reading the
history, and also allows that history to be rendered into a structured
document explaining the code's development.
How does the linearify/dendrify work with already non-linear history?
Thanks,
Stefan
Hi Stefan,
Thanks for the remarks.
quoted
https://github.com/bennorth/git-dendrify
[...] You get an easy top-level overview what
the community is interested in via e.g.:
git log --first-parent --oneline
That would be equivalent to showing only
* Add printing facility
If you run that command on "* Add printing facility"^2
you would see the headlines of the section.
That's a nice observation on how to use the existing git tools to view a
structured history with different levels of detail.
However in gits reality we do not have these nice sections
building on top of each other, as many people are interested in
different things and build where they see fit.
Yes, reality isn't always clean! But each individual contributor can
structure their own branch in a hierarchical way if they think it would
be helpful, before publishing it for review.
How does the linearify/dendrify work with already non-linear history?
If you attempt to 'linearize' a section of history which isn't of the
required hierarchical form, the tool exits without doing anything.
(Because this is only at the experimenting stage, there may well be
situations where it fails to detect an unexpected structure, but see
also next paragraph.) Similarly, if you attempt to 'dendrify' a section
of history which isn't purely linear, it refuses.
In any case, the tool only ever creates a new branch so your original
history is unaltered.
Thanks,
Ben.