Git History and Help Commands

Git History and Help Commands: Inspect, Search, and Understand Your Repository

A useful Git history is more than a list of old commits. It is a technical record that can explain when behavior changed, why a decision was made, which files were affected, who last touched a line, and how the current project evolved.

Git provides several complementary tools for exploring that record. git log walks through commits, git show inspects a selected object, git diff compares states, git blame traces lines to commits, and git reflog records movements of local references. Git also includes an extensive built-in help system, so you do not need to memorize every option before working effectively.

This guide explains these commands through a practical repository, then shows how to combine filters, revision syntax, path history, content searches, and documentation tools to answer real development questions.

What You Will Learn

• How Git history is organized as a graph of commits.

• How to read compact and detailed log output.

• How to filter history by author, date, message, path, and merge status.

• How to format logs for humans, reports, and scripts.

• How to inspect one commit with git show.

• How to compare commits, branches, files, and ranges with git diff.

• How revision names such as HEAD~2, A..B, and A...B work.

• How to search for the commit that added, removed, or changed particular code.

• How to follow a file through renames.

• How to use git blame responsibly.

• How local reflogs can help recover recently moved references.

• How to use Git’s short help, manual pages, guides, and command discovery tools.

History Is a Commit Graph, Not a Folder of Backups

Every normal commit stores a reference to a project snapshot, metadata, a message, and one or more parent commits.

A simple linear history looks like this:

A---B---C---D  main

Each commit points to its parent. Git can begin at D and walk backward through C, B, and A.

When branches diverge and later merge, the history becomes a graph:

A---B---C-------F  main
         \     /
          D---E    feature

The merge commit F has two parents. History commands can display the graph, follow all parents, or focus on a selected branch path.

This graph model explains why Git history tools accept revision starting points and ranges rather than merely displaying commits by timestamp.

Create a Practice Repository

The following repository creates enough history to demonstrate filters, file changes, branching, and merges.

macOS, Linux, or Git Bash

mkdir git-history-demo
cd git-history-demo
git init -b main

cat > app.txt <<'EOF'
Task Notes
Version: 1
EOF

git add app.txt
git commit -m "Create task notes application"

cat > README.md <<'EOF'
# Task Notes

A small project for practicing Git history.
EOF

git add README.md
git commit -m "Add project documentation"

cat >> app.txt <<'EOF'
Storage: local file
EOF

git add app.txt
git commit -m "Document local storage mode"

git switch -c feature/search

cat > search.txt <<'EOF'
Search tasks by keyword.
EOF

git add search.txt
git commit -m "Add keyword search description"

cat >> README.md <<'EOF'

## Search

Tasks can be searched by keyword.
EOF

git add README.md
git commit -m "Document task search"

git switch main

cat >> app.txt <<'EOF'
Format: plain text
EOF

git add app.txt
git commit -m "Document task storage format"

git merge --no-ff feature/search -m "Merge task search feature"

PowerShell

New-Item -ItemType Directory git-history-demo
Set-Location git-history-demo
git init -b main

@"
Task Notes
Version: 1
"@ | Set-Content app.txt

git add app.txt
git commit -m "Create task notes application"

@"
# Task Notes

A small project for practicing Git history.
"@ | Set-Content README.md

git add README.md
git commit -m "Add project documentation"

"Storage: local file" | Add-Content app.txt
git add app.txt
git commit -m "Document local storage mode"

git switch -c feature/search

"Search tasks by keyword." | Set-Content search.txt
git add search.txt
git commit -m "Add keyword search description"

@"

## Search

Tasks can be searched by keyword.
"@ | Add-Content README.md

git add README.md
git commit -m "Document task search"

git switch main

"Format: plain text" | Add-Content app.txt
git add app.txt
git commit -m "Document task storage format"

git merge --no-ff feature/search -m "Merge task search feature"

Verify the repository:

git status
git log --oneline --graph --decorate --all

Start with git log

The basic command is:

git log

By default, Git starts from the current branch tip and walks through reachable parent commits. The normal output includes:

• The full commit identifier.

• The author.

• The author date.

• The commit message.

Git usually displays the output through a pager. Common pager keys include:

• Space or Page Down: Move forward.

• b: Move backward in common pagers.

• /text: Search within displayed output.

• n: Move to the next search result.

• q: Quit.

If the terminal appears stuck after git log, it is often waiting inside the pager. Press q.

Compact History with --oneline

git log --oneline

This prints one commit per line using an abbreviated identifier and the commit subject.

Example:

f84b2d1 Merge task search feature
29d41ea Document task storage format
d00394c Document task search
8021abc Add keyword search description
29c22f8 Document local storage mode
b012890 Add project documentation
44aa731 Create task notes application

Your identifiers will be different.

--oneline is convenient for navigation, but it hides authors, dates, commit bodies, and changed content. Use it as an overview rather than the only history view.

Display the Branch Graph

git log --oneline --graph --decorate --all

These options work together:

• --graph draws an ASCII representation of parent relationships.

• --decorate shows branch names, tags, and other references near commits.

• --all starts from all references instead of only the current branch.

Example structure:

*   f84b2d1 (HEAD -> main) Merge task search feature
|\
| * d00394c (feature/search) Document task search
| * 8021abc Add keyword search description
* | 29d41ea Document task storage format
|/
* 29c22f8 Document local storage mode
* b012890 Add project documentation
* 44aa731 Create task notes application

The graph shows topology. Commit dates alone cannot reliably explain which commits are parents of others.

Limit the Number of Commits

Show the latest three commits:

git log -3

Equivalent long form:

git log --max-count=3

Combine it with compact formatting:

git log -5 --oneline

Show Files and Line Statistics

Display changed files and line counts:

git log --stat

Display only file status codes:

git log --name-status

Typical status letters include:

• A: Added.

• M: Modified.

• D: Deleted.

• R: Renamed when rename detection identifies it.

Display file names without status letters:

git log --name-only

Display the full patch for every selected commit:

git log -p

Limit patch output to recent commits when the repository is large:

git log -p -2

Custom Log Formatting

Git provides built-in pretty formats:

git log --pretty=short
git log --pretty=full
git log --pretty=fuller
git log --pretty=reference

For custom output, use --format:

git log --format="%h | %an | %ad | %s" --date=short

Useful placeholders include:

A reusable team-oriented format might be:

git log --graph --date=short \
  --format="%C(auto)%h%d %s %C(dim white)(%an, %ad)%C(reset)" \
  --all

Color placeholders depend on terminal support. Avoid parsing decorated, colored human output in scripts.

Filter History by Date

Show commits after a date:

git log --since="2026-01-01"

Show commits before a date:

git log --until="2026-06-30"

Use relative descriptions:

git log --since="2 weeks ago"
git log --since="yesterday"
git log --until="last month"

For repeatable scripts and reports, prefer explicit date formats and verify the timezone assumptions.

Combine both boundaries:

git log --since="2026-01-01" --until="2026-03-01" --oneline

Filter by Author or Committer

Search author identity:

git log --author="Jane"

The value is treated as a pattern, so it can match names or emails.

Search committer identity:

git log --committer="Alex"

Author and committer can differ after operations such as rebasing, applying patches, or cherry-picking.

Inspect full metadata for one commit:

git log -1 --format=fuller

Filter by Commit Message

Search commit messages:

git log --grep="search"

Use case-insensitive matching:

git log --grep="storage" -i

Search several patterns:

git log --grep="fix" --grep="bug"

Multiple --grep patterns normally match when at least one pattern matches. Use --all-match when all supplied limiting patterns must match according to the command’s filtering rules.

Message search is useful only when commit messages are descriptive. Vague messages make history investigation much harder.

Filter Merge and Non-Merge Commits

Show only merge commits:

git log --merges --oneline

Exclude merge commits:

git log --no-merges --oneline

Follow the first-parent path:

git log --first-parent --oneline

--first-parent is useful on an integration branch because it emphasizes the branch’s main sequence of merges rather than walking into every merged topic branch.

It does not erase the underlying history. It changes how the traversal is displayed.

View History for One File or Directory

Place -- before a path:

git log -- README.md

Compact version:

git log --oneline -- README.md

Show patches affecting the file:

git log -p -- README.md

Show history for a directory:

git log --oneline -- src/

The double dash removes ambiguity between revisions and paths.

Follow a File Through a Rename

For a single file, use:

git log --follow -- path/to/file

Add patches:

git log --follow -p -- path/to/file

--follow attempts to continue history beyond a rename for one file. Rename detection is based on similarity rather than permanent rename metadata, so results can be affected by large simultaneous content changes.

When the rename is obvious, also inspect name-status output:

git log --name-status --follow -- path/to/file

Show History in Oldest-to-Newest Order

git log --reverse --oneline

This is useful when studying how a feature was constructed from its earliest commit.

Combine with a path:

git log --reverse -p -- README.md

Inspect One Commit with git show

git show displays information about one or more Git objects. When given a commit, it normally shows the commit message and textual diff.

Show the current commit:

git show

Show a selected commit:

git show 29c22f8

Show summary statistics:

git show --stat 29c22f8

Show only names and status:

git show --name-status 29c22f8

Show metadata without the patch:

git show --no-patch --format=fuller 29c22f8

Inspect one file as stored in a selected commit:

git show 29c22f8:app.txt

This reads historical content without switching branches or modifying the working tree.

git log vs git show

Use git log to locate the relevant commit, then git show to study it closely.

Compare States with git diff

git diff answers a different question from git log. It compares content between two states.

Working Tree vs Staging Area

git diff

This shows unstaged changes.

Staging Area vs HEAD

git diff --staged

This shows the proposed next commit.

Working Tree vs HEAD

git diff HEAD

This combines staged and unstaged differences relative to the current commit.

One Commit vs Another

git diff commitA commitB

Git compares the snapshots identified by the two revisions.

Only One File Between Revisions

git diff commitA commitB -- README.md

Summary Instead of Full Patch

git diff --stat commitA commitB
git diff --name-status commitA commitB

Understand Revision Names

Many Git commands accept revisions. A revision can be named through a branch, tag, commit identifier, special reference, or relative expression.

Branch and Tag Names

git show main
git show feature/search
git show v1.0.0

HEAD

HEAD normally refers to the currently checked-out commit:

git show HEAD

Parent Syntax with ^

The first parent of HEAD:

HEAD^
HEAD^1

The second parent of a merge commit:

HEAD^2

The second-parent form matters because merge commits have more than one parent.

First-Parent Ancestors with ~

Two first-parent steps before HEAD:

HEAD~2

For a linear sequence, HEAD^^ and HEAD~2 reach the same commit. In merge histories, repeated first-parent traversal and choosing a specific parent express different intentions.

Previous Checkout Location

@{-1}

This commonly refers to the previously checked-out branch or commit and can be useful with commands such as git switch.

Revision Ranges: A..B

The two-dot range:

A..B

selects commits reachable from B that are not reachable from A.

Example:

git log --oneline main..feature/search

This asks: which commits are available from feature/search but not from main?

Reverse the range:

git log --oneline feature/search..main

Now Git shows commits reachable from main but not from the feature branch.

The direction matters.

Symmetric Difference: A...B

For git log, the three-dot notation:

A...B

selects commits reachable from either side but not from both.

git log --left-right --oneline main...feature/search

--left-right marks which side each commit belongs to.

This is useful when branches have diverged and you want to see unique commits on both sides.

Two Dots and Three Dots Mean Different Things in git diff

Revision notation can be context-sensitive.

This command:

git diff A B

compares the snapshot at A with the snapshot at B.

This form:

git diff A..B

is effectively another spelling of the same endpoint comparison for git diff.

But:

git diff A...B

compares the merge base of A and B with B. It answers a question similar to: what has the right-side branch changed since the branches diverged?

Do not assume range syntax has exactly the same selection meaning in every command. Read the command’s documentation when precision matters.

Find the Commit That Added or Removed a String

Use the pickaxe option -S:

git log -S"Storage: local file" --oneline

This searches for commits where the number of occurrences of the exact string changed.

Show patches:

git log -S"Storage: local file" -p

Limit the search to a path:

git log -S"Storage: local file" -p -- app.txt

This is useful when asking:

• When was this function name introduced?

• Which commit removed this configuration key?

• When did this error message first appear?

Search Changed Lines with -G

Use -G when the added or removed lines should match a regular expression:

git log -G"Storage:.*file" --oneline -p

The practical distinction is:

• -Stext looks for a change in the count of a string.

• -Gregex looks for added or removed lines matching a regular expression.

Depending on the code change, one can find a commit that the other does not. Start with the question you are trying to answer, then inspect the patch results.

Trace the History of a Function or Line Range

git log -L can trace the evolution of a line range or supported function pattern in a file.

Example using line numbers:

git log -L 1,3:app.txt

For supported source languages and patterns, function-based forms can be used:

git log -L :function_name:path/to/file

This feature is powerful when investigating how one function evolved without reading every full-file commit.

Syntax and function recognition vary with the target file and Git’s configured diff drivers, so consult git help log for exact forms.

Search Tracked Content with git grep

git grep searches patterns in tracked files in the working tree by default:

git grep "Task Notes"

Show line numbers:

git grep -n "Task Notes"

Search a historical tree:

git grep "Storage" HEAD~2

Search only selected paths:

git grep -n "Search" -- "*.md"

git grep searches content. git log -S and -G search the history of content changes.

Use git blame to Trace Lines

Run:

git blame app.txt

Git annotates each line with information about the commit that last changed it, including an identifier, author, date, and line number.

Limit the result to selected lines:

git blame -L 1,3 app.txt

Ignore whitespace-only changes when useful:

git blame -w app.txt

Detect moved or copied lines with additional options when investigation requires it:

git blame -M -C app.txt

These options can make analysis more expensive, especially in large histories.

Use Blame as a Starting Point, Not a Verdict

The line’s last modifier may not be the person who designed the behavior. A formatting commit, file move, mechanical refactor, or conflict resolution can become the latest recorded change.

A responsible investigation is:

1. Run git blame to locate a candidate commit.

2. Inspect it with git show.

3. Read the commit message and surrounding patch.

4. Check earlier file history with git log -p -- path.

5. Look for related issues or pull requests when available.

Use history to understand context, not to assign personal blame.

Inspect Local Reference History with git reflog

Branch logs show commits reachable through branch history. Reflogs record when local references such as branch tips and HEAD moved.

Run:

git reflog

Example structure:

f84b2d1 HEAD@{0}: merge feature/search: Merge made by the 'ort' strategy.
29d41ea HEAD@{1}: checkout: moving from feature/search to main
d00394c HEAD@{2}: commit: Document task search

Reflog entries can help locate commits after actions such as:

• A reset moved a branch backward.

• A rebase replaced commits.

• A branch was deleted locally.

• You checked out several commits and forgot an earlier location.

• An amend replaced the previous commit.

Show the selected old position:

git show HEAD@{2}

Create a recovery branch before making further changes:

git branch recovery HEAD@{2}

Important Reflog Limitations

• Reflogs are local to a repository clone.

• Another developer’s clone has its own reflogs.

• Entries are retained according to expiration and maintenance policies, not forever.

• A reflog is not a replacement for committed work, remote copies, or backups.

• Uncommitted file content is not automatically recoverable through reflog history.

Use reflog quickly when you suspect a commit became unreachable.

Summarize Contributors with git shortlog

Group commit subjects by author:

git shortlog

Show commit counts and author names:

git shortlog -sn

Include email addresses:

git shortlog -sne

When running in some contexts, specify a revision such as:

git shortlog -sn HEAD

Shortlog is useful for release notes and contribution summaries, but identity variations can split one person into several entries. A project may use a .mailmap file to normalize known names and email addresses.

Find a Regression with git bisect

When you know that one commit is good and a later commit is bad, git bisect performs a binary search through the history.

Start:

git bisect start

Mark the current commit as bad:

git bisect bad

Mark a known earlier commit as good:

git bisect good <good-commit>

Git checks out a midpoint. Test it, then mark it:

git bisect good
# or
git bisect bad

Repeat until Git identifies the first bad commit.

Finish and return to the original state:

git bisect reset

Automated test commands can also be used with bisect, but the test must reliably return success or failure exit codes.

Use Git’s Built-In Help System

Git provides several levels of help.

Short Option Summary

git log -h
git diff -h
git blame -h

The -h form prints a concise usage summary in the terminal. It is useful when you remember the command but not an option name.

Full Manual Page

git help log
git log --help

These forms open the full documentation for the command using the configured help viewer.

Web Format

git help --web log

This requests the HTML manual in a browser when the environment supports it.

List Common Commands

git help

With no specific command, Git prints the general synopsis and commonly used commands.

List All Available Commands

git help --all

List Concept Guides

git help --guides

Examples of useful conceptual documentation include:

git help revisions
git help gitrevisions
git help gitglossary
git help gitignore
git help gitattributes
git help gitcli

List Configuration Variables

git help --config

This gives a searchable summary of Git configuration variables.

Learn to Read a Git Manual Page

A Git manual page commonly contains these sections:

• Name: A one-line description.

• Synopsis: Accepted command forms.

• Description: The command’s model and behavior.

• Options: Flags and arguments.

• Examples: Practical combinations.

• Configuration: Variables affecting the command.

• See Also: Related commands and guides.

Synopsis notation is compact:

• Square brackets such as [option] usually mean optional.

• Angle brackets such as <commit> represent values you supply.

• Three dots indicate repetition or multiple values.

• A vertical bar often represents alternatives.

• -- separates options or revisions from paths.

Do not paste the angle brackets literally unless they are part of a shell-safe example.

Search Inside Help

When the manual opens in a pager, search with:

/pattern

Examples:

/--author
/pretty
/revision range

Press n for the next result and q to quit in common pager environments.

This is often faster than reading the manual from the beginning.

Command Discovery Without Guessing

Start with broad command categories:

git help
git help --all
git help --guides

Then request short usage:

git log -h

Finally, open full documentation for the exact command:

git help log

This three-step pattern reduces random command experimentation.

Create Safe History Aliases

A compact graph alias can reduce repetitive typing:

git config --global alias.lg \
"log --graph --decorate --oneline --all"

Then run:

git lg

A detailed alias:

git config --global alias.hist \
"log --graph --date=short --format=%h%d%x20%s%x20[%an,%x20%ad] --all"

Aliases are conveniences, not replacements for understanding the underlying commands. Documentation and teammates will normally use standard command names.

Practical Investigation: When Was a Setting Added?

Question: When did Storage: local file enter the project?

1. Search for a Count Change

git log -S"Storage: local file" --oneline -- app.txt

2. Inspect the Candidate

git show <commit>

3. Read Nearby File History

git log -p -- app.txt

4. Inspect the File Before and After

git show <commit>^:app.txt
git show <commit>:app.txt

This workflow gives evidence rather than relying on the latest line attribution alone.

Practical Investigation: What Changed on a Feature Branch?

Before merging a branch:

git log --oneline main..feature/search
git diff --stat main...feature/search
git diff main...feature/search

The log lists commits unique to the feature branch. The three-dot diff shows changes made on the feature side since its merge base with main.

Also inspect the branch graph:

git log --graph --decorate --oneline --all

Practical Investigation: Who Last Changed a Problematic Line?

Assume line 3 of app.txt is suspicious.

git blame -L 3,3 app.txt

Copy the candidate identifier, then inspect it:

git show <commit>

Search earlier changes to the same line area:

git log -p -- app.txt

Search for the text itself:

git log -S"Storage:" -p -- app.txt

The combined evidence is more reliable than stopping at the blame output.

Practical Investigation: Recover a Commit After reset

Suppose a local branch was moved backward and a recent commit no longer appears in ordinary log output.

1. Inspect the Reflog

git reflog --date=local

2. Inspect the Candidate Entry

git show HEAD@{1}

3. Preserve It

git branch recovery-before-reset HEAD@{1}

4. Verify

git log --oneline --graph --decorate --all

Create a recovery branch before experimenting further. Reflog entries are not permanent archival records.

Common History Mistakes

Assuming git log Shows Every Commit in the Repository

Plain git log starts from the current revision and shows reachable commits. Other branches may contain commits not reachable from the current branch. Use appropriate starting points or --all.

Reading History Only by Date

Git history is a parent graph. Author dates can be changed, rebases can rewrite commits, and branches can contain overlapping times.

Confusing A..B with B..A

The right side is the included reachability side in a two-dot log range. Reversing the operands changes the result.

Assuming Three Dots Mean the Same Thing Everywhere

git log A...B and git diff A...B answer related but different questions.

Using git blame to Assign Fault

Blame reports line provenance according to history, not responsibility, design ownership, or intent.

Searching Only Commit Messages

The relevant change may have a poor message. Use path filters, -S, -G, diffs, and blame as additional evidence.

Expecting Reflog to Exist Everywhere Forever

Reflogs are local and expire under maintenance policies.

Parsing Human Log Output in Automation

Human formats can include colors, decorations, localization, and changing spacing. Use deliberate machine-oriented formats and separators for scripts.

Forgetting the Pager

When output appears frozen, press q before assuming Git failed.

Best Practices for Reading Git History

• Begin with git status so you know the current branch and work state.

• Use a graph view to understand branch topology.

• Limit the history by path, date, author, or message before adding full patches.

• Use git show to inspect candidate commits individually.

• Compare snapshots with git diff rather than guessing from messages.

• Use -S and -G to investigate content changes.

• Treat git blame as an entry point to context.

• Create a recovery branch when reflog reveals a valuable commit.

• Use built-in help before copying destructive commands from unrelated examples.

• Write clear commit messages so future investigations are faster.

History Command Reference

Help Command Reference

History Investigation Checklist

When investigating a change, ask:

• Which branch or revision should the history start from?

• Do I need all branches or only commits reachable from the current branch?

• Can the search be limited by path?

• Am I looking for a message, author, date, exact string, or changed-line pattern?

• Do I need a list of commits or a comparison of snapshots?

• Should merge commits be included?

• Could the file have been renamed?

• Does blame identify only a mechanical or formatting change?

• Could a missing local commit still appear in reflog?

• Have I preserved the candidate commit before running more rewriting commands?

Frequently Asked Questions

Why Does git log Not Show a Commit from Another Branch?

Plain git log displays commits reachable from the current starting revision. Use the other branch name directly or include --all.

What Is the Difference Between git log and git reflog?

git log walks commit ancestry. git reflog records local movements of references such as HEAD and branch tips.

How Do I See What One Commit Changed?

Run git show <commit>. Add --stat for a summary or --name-status for changed paths.

How Do I See a File as It Existed in an Old Commit?

Use git show <commit>:path/to/file.

How Do I Find When a Function Was Added?

Try git log -S"functionName" -p -- path. Use -G when a regular expression over changed lines better matches the question.

Why Does git diff Show Nothing?

You may be comparing states that currently match, or the changes may be staged. Use git diff --staged for staged content and specify revisions for historical comparisons.

What Does HEAD~3 Mean?

It refers to the commit reached by following the first parent three times from HEAD.

What Does main..feature Mean?

For log traversal, it selects commits reachable from feature that are not reachable from main.

Can git blame Follow Renamed Files?

Blame has options for detecting moved and copied lines, but historical investigation often works best by combining blame with git log --follow, git show, and path history.

Can Reflog Recover Uncommitted Changes?

Not reliably. Reflog tracks reference movements. It is mainly useful for commits and reference positions that existed locally.

Which Help Command Should I Use First?

Use git command -h for a quick option reminder. Use git help command when you need complete behavior, syntax, or configuration details.

Conclusion

Git history is most useful when you approach it as evidence. A compact log gives orientation, the graph explains ancestry, filters reduce noise, git show reveals individual commits, and git diff compares exact snapshots.

For deeper investigations, revision ranges explain branch differences, -S and -G locate content changes, file history traces evolution, blame provides candidate provenance, and reflog can reveal recently moved local references.

You do not need to memorize every option. Git’s built-in help system is part of the workflow. Use short help for reminders, full manuals for precise behavior, and conceptual guides when revision syntax or command models are unclear.

The next article will focus on Git branches and merging, including branch creation, switching, fast-forward and three-way merges, merge conflicts, branch cleanup, and practical integration workflows.

Official References and Further Reading

• Official git-log Documentation

• Official Pretty Formats Documentation

• Official git-show Documentation

• Official git-diff Documentation

• Official gitrevisions Documentation

• Official git-blame Documentation

• Official git-reflog Documentation

• Official git-grep Documentation

• Official git-bisect Documentation

• Official git-help Documentation

• Pro Git: Viewing the Commit History

• Pro Git: Revision Selection

• Pro Git: Searching

• Pro Git: Debugging with Git