Linking documentation to Git commit comments

Question

Using git to track modifications to the project allows contributors to include comments with each commit. If the project's guidelines, and managers' control, keeps those comments limited to a format useful for inclusion in the projects documentation - history, changelog, or users manual as the case may be, it would be nice to link to the commit comments rather than retype, or copy/paste, them into the relevant documents. How do I create, and maintain, those links while also being able to select which ones are included in which documentation streams (i.e.: users manual, history, specifications, maintenance manual, etc.)?

Of note here is that while git is known for software development, it is not limited to that. It is equally useful for any system where multiple contributors need to coordinate, and track, their efforts. Such alternatives include a business presentation developed by a team, a textbook with multiple authors, and a research project - both data collection and reports.

---

Additional information:

The git repository is always available locally, though not always on the web (such as on GitHub). As such, a method which relies on the API developed for/at a specific web host is probably not usable. Though there are some rich features available in those APIs.

The documentation itself might be in a git, and often parts of it will be, though neither is a guarantee. Only the git commit comments are assured of being in the git, wherever it is hosted. The parts of the docs in a git are in markdown, however they are created. The majority of the time, the bulk of the document writing is done in a graphical word processor (MS Word, LibreOffice Writer, etc) and can be saved as either XML or RTF, though the preference is for DocBook XML format.

The tool to use is subject to change, this ability will be part of the decision process. The output formats are primarily PDF and HTML, though markdown is useful at times as well. The commit comments themselves are either reformated into the body of the documentation as a paragraph or annotation, or kept as-is (raw text) for an information bubble or footnote, depending on the target document, and the project objectives.

The key objective is to have the tool "pull" the comments into the documentation, dynamically by preference, rather than having to either retype them by hand, or copy/paste from the git to the documentation source.

Answer 1

I'm not sure I can provide a full solution to this, as the workflow seems to have so many variables. If what you are after is just getting the comment without copying or pasting, you can use something similar to the following Unix command:

$ git log --format=%B -n 1 <sha-1> > filename.txt

This gives you the comment for the specified SHA-1 commit and redirects it to a file. As long as you have the SHA-1 value, you should be able to wrap this in your favorite language and tailor it to dynamically insert the output where needed.

Answer 2

Identifying a commit

A universal identifier for each commit is its SHA1 — a 40 digit hexadecimal number, like this one:

3e0b5fb09d70d0457d7e5ae7892504f6e1b45f33

This commit is from the Sphinx documentation builder's repo. The comment says:

Merge pull request #4556 from tk0miya/4543_autodoc_test_fails_with_py353

Fix #4543: test for autodoc fails with python 3.5.3

A reasonable way to make a persistent link to a commit is to store its SHA1 and use it to access the commit through various interfaces — see examples below.

Getting commit details

Say, you're programming a system that builds documentation. You want to programmatically get the commit's message and add it to the changelog.

Command line and local repository

First option is when the code has filesystem access to the repository.

$ git show -s --format=%B 3e0b5fb09d70d0457d7e5ae7892504f6e1b45f33

Merge pull request #4556 from tk0miya/4543_autodoc_test_fails_with_py353

Fix #4543: test for autodoc fails with python 3.5.3

There are various --format options to get the required commit details.

API and remote repository

You can also use SHA1 to get the commit details from a remote repository. Say, you have a self-hosted GitLab installation and would like to get the commit's message via GitLab API. Here's what the GET request could look like:

curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" \
"https://gitlab.example.com/api/v4/projects/5/sphinx/commits/3e0b5fb09d70d0457d7e5ae7892504f6e1b45f33"

Response is a JSON with lots of commit details.

Selecting commits

If you want to automatically select meaningful commits, you need some rule or convention for your team to mark such commits.

For example, many teams work with “git flow” or “GitHub/GitLab flow” methodologies, in which job is done in feature branches and then merged into a stable branch. Each merge results in a merge commit. If your team members write meaningful messages in merge commits, that's a good source for a changelog.

To get the merge commit messages, use git log --merges. In this example we get the hash (SHA1, %H), authoring date (%ad), and the commit message (%B), separated with newlines (%n):

$ git log --format='%H%n%at%n%B' --merges   

You may want to pack the output in some convenient format, like JSON:

$ git log  --merges --format='{%n  "hash": "%H",%n  "timestamp": %at,%n  "subject": "%s"%n}'
{
  "hash":3e0b5fb09d70d0457d7e5ae7892504f6e1b45f33,
  "timestamp": 1517848081,
  "subject": "Merge pull request #4556 from tk0miya/4543_autodoc_test_fails_with_py353"
}

...

The same list of --format options applies here.

---

Answer 3

I saw a post on exactly this idea on WtD slack channel a few days back - I want to say the approach was called typson+docson, and was directly pulling comments into a documentation system off the bat - the userbase discussion seemed to indicate that were this aimed as an internal docs system, it'd need little tweaks but would suffice out of the gate.

Found it in my history - hope this helps.

link to demo page: http://lbovet.github.io/typson-demo/

link to docson github page: https://github.com/lbovet/docson

Answer 4

Git is like a backend database, so that means there can be a frontend. There are plenty of frontends, such as BitBucket. With these you can link to commit pages. Chances are your git administrator, or database administrator already has a front end in place.