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.

---

(0)

Login to post a comment!