Selecting and formatting the git log output

Now that you know how to select revisions to examine and to limit which revisions are shown (selecting those that are interesting), it is time to see how to select which part of information associated with the queried revisions to show, and how to format this output. There is a huge number and variety of options of the git log command available for this.

Predefined and user defined output formats

A very useful git log option is --pretty. This option changes the format of log output. There are a few prebuilt formats available for you to use. The oneline format prints each commit on a single line, which is useful if you're looking at a lot of commits; there exists --oneline, shorthand for --pretty=oneline --abbrev-commit used together. In addition, the short, medium (the default), full, and fuller formats show the output in roughly the same format, but with less or more information, respectively. The raw format shows commits in the internal Git representation. It is possible to change the format of dates shown in those verbose pretty formats with an appropriate --date option: make Git show relative dates, like for example 2 hours ago, with --date=relative, dates in your local time zone with --date=local, and so on.

You can also specify your own log format with --pretty=format:"<string>" (and its tformat variant). This is especially useful when you're generating output for machine parsing, for use in scripts, because when you specify the format explicitly you know it won't change with updates to Git. The format string works a little bit like in printf:

$ git log --pretty="%h - %an, %ar : %s"
50f84e3 - Junio C Hamano, 7 days ago : Update draft release notes
0953113 - Junio C Hamano, 10 days ago : Second batch for 2.1
afa53fe - Nick Alcock, 2 weeks ago : t5538: move http push tests out

There is a very large number of placeholders selected of those are listed in the following table:

Tip

Author versus committer

The author is the person who originally wrote the patch (authored the changes), whereas the committer is the person who last applied the patch (created a commit object with those changes, representing the revision in the DAG). So, if you send a patch to a project and one of the core members applies the patch, both of you get credit—you as the author and the core member as the committer.

The --oneline format option is especially useful together with another git log option called --graph; though it can be used with any format. The latter option adds a nice little ASCII graph showing your branch and merge history. To see where tags and branches are, you can use an option named --decorate:

$ git log --graph --decorate --oneline origin/maint
* bce14aa (origin/maint) Sync with 1.9.4
|\
| * 34d5217 (tag: v1.9.4) Git 1.9.4
| * 12188a8 Merge branch 'rh/prompt' into maint
| |\
| * \ 64d8c31 Merge branch 'mw/symlinks' into maint
| |\ \
* | | | d717282 t5537: re-drop http tests
* | | | e156455 (tag: v2.0.0) Git 2.0

You might want to use a graphical tool to visualize your commit history. One such tool is a Tcl/Tk program called gitk that is distributed with Git. You can find more information about various types of graphical tools in Chapter 10, Customizing and Extending Git.

Including, formatting, and summing up changes

You can examine single revision with the git show command, which, in addition to the commit metadata, shows changes in the unified diff format. Sometimes, however, you might want to display changes alongside the selected part of the history in the git log output. You can do this with the help of the -p option. This is very helpful for code review, or to quickly browse what happened during a series of commits that a collaborator has added.

Ordinarily, Git would not show the changes for a merge commit. To show changes from all parents, you need to use the –c option (or –cc for compressed output), and to show changes from each parent inpidually, use –m.

The git log accepts various options to change the format of diff output. Sometimes, it's easier to review changes on the word level rather than on the line level. The git log command accepts various options to change the format of diff output. One of those options is --word-diff. This way of viewing differences is useful for examining changes in documents (for example, documentation):

commit 06ab60c06606613f238f3154cb27cb22d9723967
Author: Jason St. John <jstjohn@purdue.edu>
Date: Wed May 21 14:52:26 2014 -0400

 Documentation: use "command-line" when used as a compound adjective, and fix

 Signed-off-by: Jason St. John <jstjohn@purdue.edu>
 Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1932e9b..553b300 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -381,7 +381,7
 Set the path to the root of the working tree.
 This can be overridden by the GIT_WORK_TREE environment
 variable and the '--work-tree' [-command line-]{+command-line+} option.
 The value can be an absolute path or relative to the path to
 the .git directory, which is either specified by --git-dir
 or GIT_DIR, or automatically discovered.

Another useful set of options are about ignoring changes in whitespace, including –w / --ignore-all-space to ignore all whitespace changes, and -b / --ignore-space-change to ignore changes in the amount of whitespace.

Sometimes, you are interested only in the summary of changes, and not the details. There is a series of diff summarizing options that you can use. If you want to know only which files changed, use --names-only (or --raw --abbrev). If you also want to know how much those files changed, you can use the --stat option (or perhaps its machine-parse friendly version, --numstat) to see some abbreviated stats. If you are interested only in short summary of changes, use --shortstat or --summary.

Summarizing contributions

Ever wondered how many commits you've contributed to a project? Or perhaps, who is the most active developer during the last month (with respect to the number of commits)? Well, wonder no more, because this is what git shortlog is good for:

$ git shortlog -s -n
 13885 Junio C Hamano
 1399 Shawn O. Pearce
 1384 Jeff King
 1108 Linus Torvalds
 743 Jonathan Nieder

The -s option squashes all of the commit messages into the number of commits; without it, git shortlog would list summary of all the commits, grouped by developer (its output can be configured to some extent with pretty like the --format option.) The -n option sorts the list of developers by the number of commits; otherwise, it is sorted alphabetically. You can add an –e option to show also an e-mail address; note that, however, with this option, Git will separate contributions made by the same author under different e-mail.

The git shortlog command accepts a revision range, and other revision limiting options such as --since=1.month.ago; almost options that git log command accepts makes sense for shortlog. For example, to see who contributed to the last release candidate you can use the following command:

$ git shortlog -e v2.0.0-rc2..v2.0.0-rc3
Jonathan Nieder <jrnieder@gmail.com> (1):
 shell doc: remove stray "+" in example

Junio C Hamano <gitster@pobox.com> (14):
 Merge branch 'cl/p4-use-diff-tree'
 Update draft release notes for 2.0
 Merge branch 'km/avoid-cp-a' into maint

Note

One needs to remember that the number of revisions authored is only one way of measuring contribution. For example, somebody, who creates buggy commits only to fix them later, would have a larger number of commits than the developer who doesn't make mistakes (or cleans the history before publishing changes).

There are other measures of programmer productivity, for example, the number of changed lines in authored commits, or the number of surviving lines—these can be calculated with the help of Git, but there is no built-in command to calculate them.

Tip

Mapping authors

One problem with running git shortlog –s -n -e or git blame in Git repositories of long running projects is that authors may change their name or e-mail, or both during the course of the project, due to many reasons: changing work (and work e-mail), misconfiguration, spelling mistakes, and others:

Bob Hacker <bob@example.com>
Bob <bob@example.com>

When that happens, you can't get proper attribution. Git allows you to coalesce author/e-mail pairs with the help of the .mailmap file in the top directory of your project. It allows us to specify canonical names for contributors, for example:

Bob Hacker <bob@example.com>

(Actually it allows us to specify the canonical name, canonical e-mail, or both name and email, matching by email or name and email.)

By default, those corrections are applied to git blame and to git shortlog, but not to the git log output. With custom output, you can, however, use placeholders that output corrected name, or corrected e-mail; or you can use the --use-mailmap option, or the log.mailmap configuration variable.

Viewing a revision and a file at revision

Sometimes, you might want to examine a single revision (for example, a commit suspected to be buggy, found with git bisect) in more detail, examining together changes with their description. Or perhaps, you want to examine the tag message of an annotated tag together with the commit it points to. Git provides a generic git show command for this; it can be used for any type of object.

For example, to examine the grandparent of the current version, use the following command:

$ git show HEAD^^
commit ca3cdd6bb3fcd0c162a690d5383bdb8e8144b0d2
Author: Bob Hacker <bob@virtech.com>
Date: Sun Jun 1 02:36:32 2014 +0200

 Added COPYRIGHT

diff --git a/COPYRIGHT b/COPYRIGHT
new file mode 100644
index 0000000..862aafd
--- /dev/null
+++ b/COPYRIGHT
@@ -0,0 +1,2 @@
+Copyright (c) 2014 VirTech Inc.
+All Rights Reserved

The git show command can also be used to display directories (trees) and file contents (blobs). To view a file (or a directory), you need to specify where it is from (from which revision) and the path to the file, using : to connect them. For example, to view the contents of the src/rand.c file as it was in the version tagged v0.1 use:

$ git show v0.1:src/rand.c

This might be more convenient than checking out the required version of the file into the working directory with git checkout v0.1 -- src/rand.c. Before the colon may be anything that names a commit (v0.1 here), and after that, it may be any path to a file tracked by Git (src/rand.c here). The pathname here is the full path from the top of the project directory, but you can use ./ after the colon for relative paths, for example, v0.1:./rand.c if you are in the src/ subdirectory.

You can use the same trick to compare arbitrary files at arbitrary revisions.