Mastering git log: Understanding your Commit History

If you are a software engineer, you will work on projects that require you to use a version control system - a system that allows you to have multiple versions of a project, keeps track of the changes in these projects and gives you the ability to view and analyse the tracked changes.

Git is the most popular version control system used by software engineers. In this article, you will learn how to use variations of the git log command to examine the tracked changes (also called commit history) of a project. You’ll also learn how to read and apply Git’s official documentation for git log.

For a hands-on experience, you should have Git installed on your computer. You can download and install Git by following the instructions on the Git download website.

What is a Commit History?

A commit history is a record of the changes that have been made in a Git repository. Each commit represents a snapshot of the repository, including details such as the time that the change was recorded, the author of the change and a unique identifier for the recorded change. The identifier can be used to revisit the snapshot even after more commits have been made.

Git commits are made using the git commit command. Every successful git commit command generates a unique alphanumeric string that acts as an identifier for the commit. 

Cloning the Practice Repository

Clone the devcenter-square/Learning-Resource-Path-Front-End repository to be used for practice. The repository is ideal for practice because it has: 

• Multiple commit authors
• A long commit history
• Merge and direct commits
• A relatively small size (242kb)

If you do not know how to clone a repository, take a look at the cloning a repository article section on GitHub and follow the instructions to clone the repository.

After cloning the repository, change the terminal directory to the folder of the repository using the cd Learning-Resource-Path-Front-End command, as annotated in the image above. You will run Git commands for the cloned repository in the terminal directory.

If you have completed all these steps successfully, congratulations!

Understanding the default git log Output

Now that you are in the terminal of the repository’s folder, you can run Git commands and learn about git log to understand the commit history of this repository. Your first attempt will be to use the default git log command and understand the output.

Run the git log command in the terminal. You will see an output similar to that in the image below (without the annotations).

The image above displays

• The hash of a commit (labelled 1). The hash is a forty-character alphanumeric string used to identify and reference the commit. In most cases, only the first seven characters of the hash are enough to identify the commit and distinguish it from other commits.
• The type of the commit (labelled 2). While some commits are made directly to the repository, some commits are generated as a result of merging a commit or a branch to another commit or branch. These types of commits are called merge commits. If a commit is a merge commit, it is highlighted with output like label 2. Not all commits have that label. For example, commit - 2a16d20 (labelled 6) is not a merge commit but a direct commit.

The second alphanumeric string (2a16d20) in label 2 is a prefix of the commit hash of the commit (labelled 6 - the original work done). That commit was merged into the receiving commit - 9b07acb (labelled 8). Both commits merged to create a new commit - e716d37 (labelled 1).

The author who creates a merge commit is called the committer (Gift Egwuenu, labelled 3). The author who did the original work that was merged is called the author (Sonia M, labelled 7).

• The date and time that a commit was made are recorded with the commit (labelled 4). Did you notice that the timezone of the author’s computer is also included in the date? For example, +0100 and +0530.

• A description of the commit. When making a commit, you are prompted to include a commit message which describes the change(s) that you made. Commit messages are optional but important in understanding how a project changed over time and in examining what was done at each point in time.

From the commit messages (labelled 5), you can infer what change was made because of the description. You will see how to know the exact changes that were made per commit in the Format git log Output section.

The default output of the git log command displays commits in reverse chronological order - the most recent commits appearing before the earliest commits.

Filter or Limit git log Output

The output from running the git log command may be verbose for what you want to achieve. Sometimes, you want to see only commits that affected a specific file, commits from a specific author or commits between two dates. 

git log has flags that you can use to limit the information displayed to only what you want to see. The flags are included as additional commands when you run git log, and some of them can be combined to give a desired output.

View commits from specific authors

You may want to see commits made by specific authors or committers. git log has a flag for that: --committer="committer_name". You can replace committer_name with the name of the committer, for example, git log --committer="Dominic" will display commits made by committers with the string "Dominic" in their name or email address. You can use --author instead of --committer if you want.

View commits that affected a specific file

You may be concerned with only commits that affected a specific file, for example, contributing.md. You can view the commit history of contributing.md by appending its file path to the git log command as the last flag: git log --follow contributing.md.

‍

The output will show you all commits that made a change in contributing.md, even if the file name had been changed after its creation in the repository. This is possible because of the --follow option in the command used above.

View commits within a time period

You may be interested in viewing only commits within a time period. With the --after and the --before flags, you can display git commits after a date and before a date, respectively; and you can combine both flags in the same command as --after="YYYY-MM-DD" --before="YYYY-MM-DD" to view the commit history between two dates.

The values for both flags can be a date in the format YYYY-MM-DD, or a human-readable time expression such as "2 years 1 day 3 hours ago". The image below is output from the command git log --before="5 years 6 months ago" --no-merges.

View commits related to a specific string

One of the most helpful filters in using git log is the -S option (also known as Git’s "pickaxe search" option). It accepts a string and displays only those commits that changed the occurrence(s) of the string in the repository.

For instance, if you want to find commits that removed or added the string "javascript" to the repository, you will run the following command: git log -S javascript, and get the result in the image below.

Note that the string will be treated in a case-sensitive manner.

Format git log Output

You can change the format in which git log displays information. You can include or exclude information per commit. This section shows you how to do that.

View commits in one line

The output of git log can seem noisy to you. If you want to view only the commit hash and the commit message subject, you can use the --oneline flag. You will get output similar to what you see in the image below.

View commits in a graph

git log can display the commit history and also the merge history in the form of a graph if you use the --graph option. With this format, you can visualise how different branches and commits were merged to form the current state of the repository.

‍

The output in the image below comes from running gitlog --graph.

Understand Documentation Help for git log

To know more about git log and find out more flags that you can use to format or filter output, you can view the git log documentation on your terminal by running the command: git help log.

The output shows you the format for using git log with instructions for how to use them. For example, you will see git log [<options>] [<revision-range>] [[--] <path>...] under the synopsis section.

The flags in square braces mean that they are optional; in other words, you can run git log without including the flags in square braces and it would work fine. <options> includes flag values like --follow and --source and since they are optional, it can be omitted.

What Next?

You have learnt how to understand, format and filter git log output. You have also learnt how to understand and use the git log documentation. Mastering git log doesn’t just help you track code; it helps you understand the history of your project. Keep exploring other Git commands, and use git log regularly to gain deeper insights into your workflow and team collaboration.

Can you test how much you understand by using git log to display the commit history of the repository in the output formats shown below?

‍

Output format One:

‍

Output format Two:

Output format three:

‍

Frequently Asked Questions

How do I find the first commit in a repository?

You can run the command git rev-list --max-parents=0 HEAD to display the first commit in a repository. Under the hood, git log uses git rev-list to generate lists of commits. Understanding git rev-list gives you deeper control over how commit ranges are selected.

How do I see the actual changes for each commit?

To include the names of the files modified, the content modified and the location of the content modified, use the git log -p command, where the long form of -p is --patch.

How do I use the --pretty option to format git log output?

This --pretty option changes the git log output to formats other than the default. A few prebuilt options are available:

• git log --pretty="oneline" - displays only the commit hash and the commit message subject
• git log --pretty="short" - displays the commit hash, the author and the commit message subject

The --pretty=format:"<format>" can be used to create a custom format for display, different from the built-ins. For instance, 

git log --pretty=format:"%h | %an | %ar | %s" --no-merges

produces the output in the image below