Summarise Git History with git shortlog

Release day arrives and someone asks "what actually went into this build", and git shortlog is the fastest way to answer without scrolling a raw log. It groups commits by author, counts them, and can pull in email addresses or a message trailer such as Reviewed-by. This guide covers the whole-history form and the ranged form you actually want for release notes.

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.

1. Confirm the command and repository

Check the installed Git version, then move into the repository you want to report on:

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 one; fix the path rather than trying to run the report elsewhere.

2. Get a count grouped by author

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 drops the subjects. You get a count per author instead of a list of commit messages.
• --numbered sorts by count. Not by author name, which matters once a list gets long.
• HEAD makes the scope explicit. Without a revision range, shortlog would summarise the history leading to the current commit anyway, but naming it removes any doubt.

Nothing here edits commits, tags or configuration, so there is no undo to worry about.

3. Report only one release range

Replace the placeholder boundary with the last release reference, then 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 looks like this:

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

That means commits reachable from HEAD but not from v2.4.0, which is usually the boundary you actually want for release notes. Verify it before copying the result into an announcement:

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

4. Add author emails and subjects

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 the grouped subjects under each author, and --email adds the author identity in angle brackets. Treat that output as contact data: check your project's privacy policy before publishing addresses in the open.

For a tidier, script-friendly subject line, hand it a Git log pretty format instead:

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

5. Count reviewers or other trailers

Group the range by a trailer your project actually uses:

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

• Matching is case-insensitive. Commits without that trailer simply are not counted.
• One commit can add several counts. Multiple distinct values in one trailer produce multiple counts, so this tallies trailer attributions, not unique reviewed commits.
• Mailmap rules still apply. If a trailer contains a name <email> identity, Git normalises it and normally drops the email unless --email is also given.

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

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

Use that deliberately: the totals combine separate groupings, so do not present them as a single commit total.

Common traps

A trailing path narrows the scope. Put -- before it when a revision and a filename could be confused:

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

The result covers commits relevant to that path, not every commit in the range, and you should quote a path that contains spaces.

Shortlog reads standard input too. Pipe formatted log output straight in:

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 whatever arrives without consulting the repository. That is handy in a pipeline but an easy way to report the wrong range if the preceding git log is missing its boundary. Check both commands if the numbers look off.

Authors and committers are different people. 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