Turn Git History into a Release Summary with git shortlog

You will produce a compact release summary from a Git repository, first for the whole history and then for a chosen range. The same command can count commits, show subjects, add author email addresses, or group commits by a message trailer.

Prerequisites: Git, a local repository, and a reference for the release boundary, such as a tag or remote-tracking branch. This is a read-only task, so it does not need sudo or elevated privileges. Allow about five minutes if you already know the boundary you want to report.

Checkpoint 1: confirm the command and repository

1. Check the installed Git version and move into the repository you want to report.

git --version
cd /path/to/repository

On the machine used for this guide, the installed version is Git 2.43.0, supplied by the git-man documentation package for the local manual. The examples below use behaviour documented by that version. If cd lands outside a repository, Git will report that it cannot find a repository; correct the path rather than trying to run the report elsewhere.

Checkpoint 2: get a count grouped by author

1. Run the summary form against HEAD.

git shortlog --summary --numbered HEAD

Typical output has one line per author, with the count first:

     42	Ada Example
     17	Ben Example

--summary removes commit subjects. --numbered sorts by commit count instead of author name. Supplying HEAD makes the scope explicit: without another revision range, shortlog normally summarises the history leading to the current commit. The command does not edit commits, tags, or configuration, so there is no undo operation to perform.

Checkpoint 3: report only one release range

1. Replace the placeholder boundary with the last release reference and count commits through HEAD.

git shortlog --summary --numbered <previous-release>..HEAD

For a repository whose previous release is tagged v2.4.0, the real command is:

git shortlog --summary --numbered v2.4.0..HEAD

This means commits reachable from HEAD but not from v2.4.0. It is usually the useful boundary for release notes. Verify the boundary before copying the result into an announcement:

git rev-parse --verify v2.4.0
git log --oneline v2.4.0..HEAD

If the first command fails, the reference is absent or misspelled. Do not silently substitute the current branch: that can produce a plausible count for the wrong release.

Checkpoint 4: include useful detail

1. Show each author, their email address, and the commit subjects in the selected range.

git shortlog --numbered --email v2.4.0..HEAD

Without --summary, shortlog prints grouped subjects below each author. --email adds the author identity in angle brackets. Treat that output as contact data: check your project's privacy policy before publishing addresses.

For a machine-readable-looking subject line, choose a Git log pretty format:

git shortlog --numbered --format='%h %s' v2.4.0..HEAD

The format is passed to Git's log formatter. Keep the quotes around it so the shell does not interpret characters intended for Git. Shortlog rewraps formatted entries; use -w0 if you want indentation without line wrapping.

Checkpoint 5: count reviewers or other trailers

1. Group the range by a trailer used by your project.

git shortlog --summary --numbered --group=trailer:Reviewed-by v2.4.0..HEAD

This counts commit-message trailers case-insensitively. Commits without that trailer are not counted. Multiple distinct values in one commit can create multiple counts, so this is a count of trailer attributions, not necessarily a count of unique reviewed commits. If a trailer contains a name <email> identity, Git applies its mailmap rules and normally omits the email unless --email is also present.

You can count more than one grouping in the same report:

git shortlog --summary --group=author --group=trailer:Co-authored-by v2.4.0..HEAD

Use this deliberately. The totals combine separate groupings and therefore should not be presented as a single commit total.

Common traps

A path changes the scope. Put -- before it when there could be confusion between a revision and a filename:

git shortlog --summary --numbered v2.4.0..HEAD -- src/

The result covers commits relevant to the path, not every commit in the release range. If the path contains spaces, quote it.

Shortlog can also read formatted log output from standard input:

git log --pretty=short v2.4.0..HEAD | git shortlog --summary --numbered

When standard input is not a terminal and no revision is supplied, shortlog summarises that input without consulting the current repository. This is useful for a pipeline, but it is an easy way to report the wrong range if the preceding git log command is missing its boundary. Check both commands when the numbers look surprising.

Commit authors and committers are different identities. The default grouping is by author. Use --committer when the question is who recorded the commits instead:

git shortlog --summary --numbered --committer v2.4.0..HEAD