One of the most fundamental services provided by Git is the history of the project. Since Git keeps track of all changes made to files in a repository, it can offer very powerful journaling features. You can query the history of a project in different ways, and you can extract and display various data using a single flexible control.
The git log is huge, the largest of all classic Git commands. His manual has more than 2,500 lines. Fortunately, git log provides much of its most useful behavior from a few key options.
Basic logging with default behavior
By default, git log displays a reverse chronological list of commits. Each commit includes its hash, author, date, and commit message:
The command uses a pager (eg less, more) to display the full output so that you can easily navigate through the results. You can configure Git to use a program of your choice, such as the plus pager.
Here is an output from the git log of the git source code repository itself:
commit 670b81a890388c60b7032a4f5b879f2ece8c4558 (HEAD -> master, origin/next,
Author: Junio C Hamano
Date: Mon Jun 14 13:23:28 2021 +0900
The second batch
Signed-off-by: Junio C Hamano
The result begins with the validation hash (670…) followed by a list of branches that currently point to this commit (HEAD -> master, etc.)
The next line describes the author of this commit, giving his name and email address.
The full date and time of the commit follow on the next line.
Finally, the full content of the validation message appears. You can control most of everything that git log offers with command line options. There are two main types of options:
- Formatting, which defines how Git displays each commit.
- Filtering, which defines which commits git log understand.
In addition to command line options, git log accepts arguments that specify files, commits, branches, or other types of references. These apply additional filtering.
Formatting the output of the Git log
One of the simplest adjustments is the –a line option which produces a very short output:
git log --oneline
Each log line now only contains an abbreviated validation hash and the subject of the validation message. This is a great way to get an overview of recent project commits:
Unfortunately, without further context, this information is not always so useful. This may give you a vague idea of the project, but dates and other useful information about the authors and files are missing.
Viewing a branch graph
The –graphic The option allows you to view the relationships between the branches. It’s very basic but can help unravel a complicated story.
git log --oneline --graph
Nice personalized outing
You can achieve more complicated formatting by specifying it in detail using the –attractive option. The syntax ranges from very simple to much more complex, so consult a manual for details.
git log --pretty=short
is essentially the same as git log without the date or the full message:
git log --pretty=oneline
Is equivalent to git log –oneline.
git log --pretty=fuller
Includes a lot of details. It even separates author and committer who can, in theory, be different people:
With the format: variant, you can supply a string containing whatever content you want, including placeholders that are replaced with various data. Here are some examples of placeholders:
- % H commit hash
- % h abbreviated validation hash
- % a d author date
- % ar author date, parent
- % s commit post subject
- % b validation message body
- % p abbreviated parent hashes
You can add fixed characters to the output and colorize it. This example also shows a variation of the date format:
git log --pretty=format:'%C(auto) %h [%ad] %s' --date=short
Note that square brackets surround the date. Whichever formatting you choose, if you want the output to be useful in a pipeline or for other forms of word processing, you need to think about how to delimit each part of the output.
Viewing Differences in the Log
An important detail when examining the history of a repository is the differences themselves. They represent what has actually changed in the code, after all! To get started, you can get a summary of changes next to each commit using –shortstat:
git log --shortstat
This adds a line like:
1 file changed, 48 insertions(+), 2 deletions(-)
At the bottom of each commit. You’ll see this kind of summary often — throughout pages on GitHub, for example — and it’s a useful way to quickly assess the scope of a specific commit. For more detailed information, you can include full patch output (diffs) using the -p flag:
git log -p
Filtering Git Log Output
No matter what formatting you apply, you will always see the full log of all commits in the current branch. Even if Git breaks them down into pages, it can still represent a lot of output. The following options allow you to customize the commits included in the log.
Restriction by amount
If you just want to crop the results to show the few most recent commits, use the -[number] syntax:
git log -2
Restriction by date
To restrict all commits to a given date range, use the –since (–after) and –up to (–before) options. These each take a date in ISO 8601 format. You can use either –since Where –up to alone, or both together to specify a range. The options –after and –before are synonyms.
git log --since="2021-01-01" --until="2021-05-01"
Restriction by file
The Git log can focus on a specific file rather than each file in your repository. This is great for helping you find out how a particular file has changed over time. Just add the filename to the end of your git command:
git log filename
You will only see the commits that affected file name.
Differences between branches
You may have unique requirements when viewing a branch log. For example, rather than seeing the full history, you might just want to see what has changed in that specific branch. Git log can help you through the ref1..ref2 syntax. You can use three slightly different approaches:
- Show commits that are in the main, but not in the branch:
git log --oneline origin/branch..origin/main
- Show commits that are in the branch, but not in the main:
git log --oneline origin/main..origin/branch
- Show commits that only exist in the branch or the main:
git log --oneline origin/branch...origin/main
Differences between two tags
Just as you can view the history between branches using the ref1..ref2 syntax, you can also view the history between tags in the same way. After all, tags and branches are reference types.
git log --abbrev-commit --pretty=format:'%h %ar %s' v2.32.0-rc3..v2.32.0
If you are preparing release notes for a larger project, git shortlog should be your first port of call. It produces a list of authors with commit topics alongside them. You can pass it a reference range to limit the history in the same way as git log:
git shortlog v2.32.0-rc3..v2.32.0
The git show command is even more versatile than git log. It can work with tags and other types of git objects beyond the commit history. It shares many options with git log, but you’ll only really need it if you need to dig deeper into the lower level details.
Review the past with Git Log
Git log is a complicated command, but you can get a lot of use out of its most basic options. Going through the history of a repository is a great way to understand how often changes are occurring and how many people are making them. Once you have a good understanding of the history of a project, you will be in a great position to contribute to it yourself.
Want to exercise your coding muscles and help out with open source projects? Here’s how to contribute to GitHub.
About the Author