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:
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:
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:
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:
- Show commit hash, author, and message:
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
- Include the date in a relative format:
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
- Include branch/tag information:
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:
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:
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:
- By author:
git log --author="John Doe" --pretty=format:"%h - %s"
- By date range:
git log --after="2023-06-01" --before="2023-07-01" --pretty=format:"%h - %s"
- By file:
git log -- path/to/file.js --pretty=format:"%h - %s"
- By content (search commits that add or remove specific text):
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:
git config --global alias.logline "log --pretty=format:'%h - %an: %s' --date=short"
Now you can simply use:
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:
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:
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:
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:
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
Exercises
-
Create a custom git log format that shows the commit hash, author name, and commit message with each field in a different color.
-
Write a git command to show all commits from the last month that modified JavaScript files.
-
Create a git alias that produces a compact log format showing just the date, commit message, and tags/branches.
-
Use git log to find all commits that added or removed references to a specific function name.
-
Create a visual graph of your repository's commit history that clearly shows branching and merging patterns.
If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)