A common use case of creating a release is to create a release note, containing, among other things, the bugs fixed in the release. A good practice is to write in the commit message whether a bug is fixed by the commit. A better practice is to have a standard way of doing this—for example, a line with the string "Fixes-bug: "
, followed by the bug identifier in the last part of the commit message. This makes it easy to compile a list of bugs fixed for a release note. The JGit project is a good example of this; their bug identifier in the commit messages is a simple "Bug: "
string followed by the bug ID.
This recipe will show you how to limit the output of git log
to only list the commits since the last release (tag), which contains a bug fix.
Clone the JGit repository using the following command lines:
$ git clone https://git.eclipse.org/r/jgit/jgit
$ cd jgit
If you want the exact same output as in this example, reset your master
branch to b14a93971837610156e815ae2eee3baaa5b7a44b
:
$ git checkout master && git reset --hard b14a939
You are now ready to look through the commit log for commit messages that describe the bugs fixed.
- First, let's limit the log to only look through the history since the last tag (release). To find the last tag, we can use
git describe
:
$ git describe
v3.1.0.201310021548-r-96-gb14a939
The preceding output tells us three things:
- The last tag was
v3.1.0.201310021548-r
- The number of commits since the tag was
96
- The current commit in abbreviated form is
b14a939
- The last tag was
Now, the log can be parsed from HEAD
to v3.1.0.201310021548-r
. But just running git log 3.1.0.201310021548-r..HEAD
will give us all 96 commits, and we just want the commits with the commit messages that contain "Bug: xxxxxx"
for our release note. The xxxxxx
is an identifier for the bug, and will be a number. We can use the --grep
option with git log
for this purpose, making the code phrase git log --grep "Bug: "
. This will give us all the commits containing "Bug: "
in the commit message; all we need to do now is just to format it to something that we can use for our release note.
- Now, let's say we want the release note format to look like the following template:
Commit-id: Commit subject Fixes-bug: xxx
- Our command line so far is as follows:
$ git log --grep "Bug: " v3.1.0.201310021548-r..HEAD
This gives us all the bug fix commits, but we can format this to a format that is easily parsed with the --pretty
option.
- First, we will print the abbreviated commit ID (
%h
), followed by a separator of our choice (|
), and then the commit subject (%s
, the first line of the commit message), followed by a new line (%n
), and the body (%b
):
--pretty="%h|%s%n%b"
The output, of course, needs to be parsed, but that's easy with regular Linux tools, such as grep
and sed
.
- First, we just want the lines that contain
"|"
or"Bug: "
:
grep -E "\||Bug: "
- Then, we replace these with
sed
:
sed -e 's/|/: /' -e 's/Bug:/Fixes-bug:/'
- The entire command put together is as follows:
$ git log --grep "Bug: " v3.1.0.201310021548-r..HEAD --pretty="%h|%s%n%b" | grep -E "\||Bug: " | sed -e 's/|/: /' -e 's/Bug:/Fixes-bug:/'
- The previous set of commands gives the following output:
f86a488: Implement rebase.autostash
Fixes-bug: 422951
7026658: CLI status should support --porcelain
Fixes-bug: 419968
e0502eb: More helpful InvalidPathException messages (include reason)
Fixes-bug: 413915
f4dae20: Fix IgnoreRule#isMatch returning wrong result due to missing reset
Fixes-bug: 423039
7dc8a4f: Fix exception on conflicts with recursive merge
Fixes-bug: 419641
99608f0: Fix broken symbolic links on Cygwin.
Fixes-bug: 419494
...
Now, we can extract the bug information from the bug tracker and put the preceding code in the release note as well, if necessary.
First, we limit the git log
command to only show the range of commits we are interested in, and then we further limit the output by filtering the "Bug: "
string in the commit message. We pretty print the string so we can easily format it to a style we need for the release note, and finally, find "Bug: "
and replace it by "Fixes-bug: "
using grep
and sed
to completely match the style of the release note.
If we just wanted to extract the bug IDs from the commit messages and didn't care about the commit IDs, we could have just used grep
after the git log
command, still limiting the log to the last tag:
$ git log v3.1.0.201310021548-r..HEAD | grep "Bug: "
If we just want the commit IDs and their subjects, but not the actual bug IDs, we can use the --oneline
feature of git log
combined with the --grep
option:
$ git log --grep "Bug: " --oneline v3.1.0.201310021548-r..HEAD