Git Log Formatting

Introduction

When working with Git repositories, especially on larger projects, you'll often need to review the commit history. While the basic git log command provides essential information, its default output can be overwhelming and might not show exactly what you need. This is where Git log formatting comes in - allowing you to customize the output to display precisely the information you want in a format that's easy to read and analyze.

In this tutorial, you'll learn how to use Git's powerful formatting options to create custom log outputs that suit your specific needs.

Basic Git Log Command

Before diving into formatting, let's review the basic git log command:

bash

git log

This displays the commit history with full details including:

• Commit hash
• Author name and email
• Date and time
• Complete commit message

The output looks something like this:

commit 7d1b53a7d42e29a7e24187e336b6e8b3c89552c1
Author: John Doe <[email protected]>
Date:   Mon Jul 10 15:32:47 2023 +0200

    Fix navigation bar overflow on mobile devices

commit 3a2b6c9d8f0e1g7h6i5j4k3l2m1n0o9p8q7r6s5t
Author: Jane Smith <[email protected]>
Date:   Sun Jul 9 18:45:23 2023 +0200

    Add user authentication feature
    
    - Implement login form
    - Add JWT token validation
    - Create protected routes

While informative, this format can be hard to scan quickly, especially when reviewing many commits.

Using the --oneline Flag

For a more compact view, try the --oneline flag:

bash

git log --oneline

Output:

7d1b53a Fix navigation bar overflow on mobile devices
3a2b6c9 Add user authentication feature
5f7e6d5 Update README with installation instructions

This displays just the shortened commit hash and the first line of each commit message - perfect for getting a quick overview of recent changes.

Customizing Output with --pretty Format

Git's true formatting power comes from the --pretty option, which allows you to define exactly what information is shown and how it's formatted.

The basic syntax is:

bash

git log --pretty=format:"FORMAT_STRING"

Where FORMAT_STRING contains placeholders that Git replaces with commit information.

Common Format Placeholders

Here are some of the most useful placeholders:

Placeholder	Description
%H	Full commit hash
%h	Abbreviated commit hash
%an	Author name
%ae	Author email
%ad	Author date (format respects --date=option)
%ar	Author date, relative (e.g., "2 days ago")
%cn	Committer name
%ce	Committer email
%cd	Committer date
%cr	Committer date, relative
%s	Subject (commit message)
%d	Ref names (e.g., branch or tag names)

Example Format Strings

Let's look at some practical examples:

1. Show commit hash, author, and message:

bash

git log --pretty=format:"%h - %an: %s"

Output:

7d1b53a - John Doe: Fix navigation bar overflow on mobile devices
3a2b6c9 - Jane Smith: Add user authentication feature
5f7e6d5 - John Doe: Update README with installation instructions

2. Include the date in a relative format:

bash

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

Output:

7d1b53a - 2 days ago - John Doe: Fix navigation bar overflow on mobile devices
3a2b6c9 - 3 days ago - Jane Smith: Add user authentication feature
5f7e6d5 - 1 week ago - John Doe: Update README with installation instructions

3. Include branch/tag information:

bash

git log --pretty=format:"%h %ad%d | %s [%an]" --date=short

Output:

7d1b53a 2023-07-10 (HEAD -> main) | Fix navigation bar overflow on mobile devices [John Doe]
3a2b6c9 2023-07-09 | Add user authentication feature [Jane Smith]
5f7e6d5 2023-07-03 (tag: v1.0.0) | Update README with installation instructions [John Doe]

Adding Color to Your Git Log

To make your logs even more readable, you can add color:

bash

git log --pretty=format:"%C(yellow)%h%Creset %C(blue)%ad%Creset%C(red)%d%Creset | %s %C(green)[%an]%Creset" --date=short

The color codes used:

• %C(yellow) - Sets color to yellow
• %C(blue) - Sets color to blue
• %C(red) - Sets color to red
• %C(green) - Sets color to green
• %Creset - Resets color to default

This produces a colorful output that makes different parts of the log easier to distinguish.

Limiting the Number of Commits

To see only a specific number of recent commits, use the -n option:

bash

git log -n 5 --pretty=format:"%h - %s"

This shows only the 5 most recent commits.

Filtering Commits

You can filter commits in various ways:

1. By author:

bash

git log --author="John Doe" --pretty=format:"%h - %s"

2. By date range:

bash

git log --after="2023-06-01" --before="2023-07-01" --pretty=format:"%h - %s"

3. By file:

bash

git log -- path/to/file.js --pretty=format:"%h - %s"

4. By content (search commits that add or remove specific text):

bash

git log -S"function login" --pretty=format:"%h - %s"

Creating Custom Aliases

If you frequently use a particular format, you can create a Git alias to save time:

bash

git config --global alias.logline "log --pretty=format:'%h - %an: %s' --date=short"

Now you can simply use:

bash

git logline

To get your custom formatted log output.

Real-World Examples

Let's look at some practical scenarios where custom git log formatting is useful:

Scenario 1: Preparing a Release Changelog

When preparing a changelog for a release, you might want to see all commits since the last tag:

bash

git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"- %s (%h)" --no-merges

Output:

- Fix navigation bar overflow on mobile devices (7d1b53a)
- Add user authentication feature (3a2b6c9)
- Update error handling in API requests (5f7e6d5)

This gives you a nicely formatted list of changes that you can include in your release notes.

Scenario 2: Reviewing Team Contributions

To see who has contributed to the project and how much:

bash

git shortlog -sn --no-merges

Output:

    15  John Doe
    12  Jane Smith
     7  Alice Johnson

This shows the number of commits by each author, sorted numerically.

Scenario 3: Investigating a Bug

When debugging an issue, you might want to see all changes to a specific file:

bash

git log -p -- src/components/Button.js

This shows the full patches (changes) for each commit that modified the specified file.

Advanced: Using the --graph Option

To visualize the branching and merging in your repository, add the --graph option:

bash

git log --graph --pretty=format:"%C(yellow)%h%Creset%C(red)%d%Creset | %s %C(blue)[%an]%Creset" --all

Output:

* 7d1b53a (HEAD -> main) | Fix navigation bar overflow on mobile devices [John Doe]
| * 2e3f4a5 (feature/login) | Refactor login form validation [Jane Smith]
| * 9b8c7d6 | Add password strength meter [Jane Smith]
|/
* 3a2b6c9 | Add user authentication feature [Jane Smith]
* 5f7e6d5 (tag: v1.0.0) | Update README with installation instructions [John Doe]

This visual representation helps you understand the relationship between different commits and branches.

The git log Format Syntax

For reference, here's a summary of the syntax elements you can use in format strings:

• %placeholder - Outputs information about the commit
• %C(color) - Sets the color for the text that follows
• %Creset - Resets color to default
• %n - Newline
• %x## - Inserts a character with hex code ##
• %(trailers) - Commit message trailers

Summary

Git log formatting is a powerful tool that helps you extract and visualize exactly the information you need from your project's commit history. By mastering the various formatting options and placeholders, you can create custom views that make it easier to:

• Get a quick overview of recent changes
• Prepare release notes
• Identify who made specific changes
• Debug issues
• Understand the project's development flow

Remember that the key to effective Git log formatting is to include only the information that's relevant to your current task, presented in a way that's easy to read and understand.

Additional Resources

• Git - git-log Documentation
• Pro Git Book - Viewing the Commit History

Exercises

1. Create a custom git log format that shows the commit hash, author name, and commit message with each field in a different color.

2. Write a git command to show all commits from the last month that modified JavaScript files.

3. Create a git alias that produces a compact log format showing just the date, commit message, and tags/branches.

4. Use git log to find all commits that added or removed references to a specific function name.

5. Create a visual graph of your repository's commit history that clearly shows branching and merging patterns.