2026-03-149 min read

git-reflog[1] (Git & Dev Tools)

Learn git-reflog[1] (Git & Dev Tools) step by step with clear examples and exercises.

Why This Matters

Git is an indispensable version control system for developers, and understanding its intricacies can greatly enhance productivity. One such essential feature is git-reflog, a command that helps manage your project's history effectively. In this lesson, we will delve deep into the world of git-reflog, exploring its practical applications, common mistakes, and how to use it to solve real-world problems.

Importance of Git-Reflog

Git-reflog is crucial for developers because it allows you to recover lost commits or changes that were accidentally discarded. It's particularly useful when dealing with complex projects where frequent commits are common. In addition, git-reflog can help during debugging sessions and code reviews by providing a historical record of your project's evolution.

Prerequisites

To fully grasp this lesson, you should have a basic understanding of Git and its core commands such as git init, git add, git commit, and git push. Familiarity with the command line is also essential. Additionally, it's beneficial to have experience working on a project that involves multiple commits and potential issues where git-reflog can be useful.

Basic Git Commands (Expanded)

git init: Initialize a new Git repository in your current directory.
git add : Stage changes to the specified file for the next commit.
git add .: Stage all changes in your working directory for the next commit.
git commit -m "": Create a new commit with the given message and stage any unstaged changes.
git push : Send commits from your local repository to a remote repository.
git status: Display the current state of your working directory, including staged and unstaged files.
git log: Show the commit history for your current branch, including commit messages and author information.

Core Concept

What is git-reflog?

Git-reflog is a Git internal command that maintains a record of all changes made to your local repository, even after commits have been deleted or discarded. It stores this information in a reflog file associated with each branch and tag in your repository.

How git-reflog works (Expanded)

Every time you make a commit, Git creates an entry in the corresponding reflog file. This entry contains metadata about the commit, such as its SHA-1 hash, author, date, and message. Additionally, it stores information about the changes made during the commit, including deleted files, added files, and modified files.

When you delete a commit using git reset or git revert, Git does not immediately remove the associated entry from the reflog file. Instead, it marks the entry as "reachable" or "unreachable" based on its connection to other commits in your repository. Unreachable entries are preserved in the reflog file until they are garbage collected by Git.

Accessing git-reflog data (Expanded)

You can access the data stored in the reflog files using various git-reflog commands. Some common ones include:

git reflog: List all reachable and unreachable commits in your repository, along with their metadata.
git reflog : Display only the commits related to a specific branch.
git cherry-pick : Recover a specific commit by its SHA-1 hash and apply its changes to your working directory.
git reset --hard : Restore your working directory, index, and HEAD to the state of a specific commit.
git reflog expire: Mark all unreachable entries as eligible for garbage collection. This command does not remove the entries but marks them for deletion during the next garbage collection cycle.
git reflog prune: Remove all unreachable entries from the reflog files. Be cautious when using this command, as it permanently deletes the specified entries.
git log --graft --all --graph --decorate: Display a graphical representation of your repository's history, including reachable and unreachable commits. This command can help you visualize the structure of your project and identify lost commits.

Worked Example

Let's consider a scenario where you accidentally discard a commit containing important changes to a file named main.js.

Make some changes to the main.js file and commit them with a descriptive message:

$ git add main.js
$ git commit -m "Adding important changes to main.js"

Realize that you've made a mistake and want to recover the discarded commit. First, check the reflog for available commits:

$ git reflog --all

Find the SHA-1 hash of the commit you want to recover and use it to cherry-pick the changes:

$ git cherry-pick <commit-hash>

If you want to restore your working directory, index, and HEAD to the state of the recovered commit, use git reset --hard:

$ git reset --hard <commit-hash>

Additional Worked Example - Recovering a Deleted File (Expanded)

In this example, we will recover a deleted file named config.json.

Delete the config.json file from your project:

$ rm config.json

Commit the deletion:

$ git add .
$ git commit -m "Delete config.json"

Realize that you need the config.json file back. First, check the reflog for available commits before the delete:

$ git reflog --all --date=<date-before-delete>

Find the SHA-1 hash of the commit that contained the config.json file and use it to recover the file:

$ git checkout <commit-hash> config.json

This will restore the config.json file in your project to its previous state.

Common Mistakes

Not understanding the difference between git reflog expire and git reflog prune: Both commands remove unreachable entries from the reflog files, but they do so at different times. expire marks unreachable entries as eligible for garbage collection, while prune actually removes them.
Not using git-reflog to recover lost commits: Developers often forget about git-reflog and manually recreate lost work instead of leveraging its power to quickly recover the discarded changes.
Not properly configuring git-reflog retention settings: By default, Git keeps unreachable reflog entries for 30 days before garbage collecting them. However, you can adjust this setting using the gc.reflogExpire and gc.reflogExpireUnreachable configuration options.
Not using a descriptive commit message: A clear and concise commit message helps when searching for specific commits in the reflog file.
Ignoring unreachable entries: Unreachable entries can still be valuable, so it's essential to review them periodically and consider whether they should be kept or deleted.
Not using git log --graft --all --graph --decorate: This command provides a visual representation of your repository's history, which can help you identify lost commits more easily.
Not checking the reflog before discarding changes: It's always a good practice to check the reflog before discarding changes, as it may contain valuable work that was accidentally deleted or discarded.
Not using git stash when switching branches: When switching between branches, it's essential to use git stash to save any uncommitted changes so they can be applied later if needed.
Not understanding the difference between a soft reset and a hard reset in Git, and how it affects git-reflog: A soft reset (git reset --soft) moves the HEAD pointer but keeps the commit history intact, while a hard reset (git reset --hard) resets both the head and the working directory to a specific commit, discarding changes made after that commit. In this case, any unreachable commits or changes in the local reflog file will be lost if you perform a hard reset.
Not using git merge instead of git revert: While both commands can help resolve conflicts, git merge preserves the original commit history, while git revert creates new commits that undo the changes made in the original commit. Using git merge allows you to keep a cleaner and more accurate project history.

Common Mistakes - Subheadings

Not understanding the difference between git reflog expire and git reflog prune
Not using git-reflog to recover lost commits
Not properly configuring git-reflog retention settings
Not using a descriptive commit message
Ignoring unreachable entries
Not using git log --graft --all --graph --decorate
Not checking the reflog before discarding changes
Not using git stash when switching branches
Not understanding the difference between a soft reset and a hard reset in Git, and how it affects git-reflog
Not using git merge instead of git revert

Practice Questions

What happens when you delete a commit using git reset --hard? How can you recover it using git-reflog?
How can you use git-reflog to compare changes between two commits?
Explain the difference between "reachable" and "unreachable" entries in a reflog file.
What is the purpose of the git reflog expire command, and when would you use it?
How can you configure git-reflog to keep unreachable entries for a longer period before garbage collection?
What is the difference between git reflog prune and manually deleting unreachable entries from the reflog file?
What is the purpose of using a descriptive commit message, and how does it help when recovering lost commits with git-reflog?
How can you use git-reflog to recover deleted files in your project?
In what scenarios would you want to review unreachable entries in the reflog file?
What is the purpose of using git log --graft --all --graph --decorate, and how does it help when working with git-reflog?
What are some best practices for using git-reflog effectively in your workflow?
How can you use git-reflog to recover lost branches in your repository?
In what situations would you want to manually delete entries from the reflog file?
How does the git config command help with managing git-reflog settings?
What are some potential drawbacks of using git-reflog, and how can they be mitigated?

FAQ

Why does Git keep unreachable commits in the reflog file?

Git keeps unreachable commits to allow users to recover lost changes or accidentally discarded commits.

Can I use git-reflog to compare changes between two branches?

While you can't directly compare changes between two branches using git-reflog, you can cherry-pick individual commits from one branch and apply them to another branch.

How often should I run git reflog prune to keep my repository clean?

It's generally not necessary to manually run prune, as Git will automatically garbage collect unreachable entries during its regular garbage collection process. However, if you want to remove them immediately, you can use the command whenever needed.

Can I recover deleted files using git-reflog?

Yes, you can recover deleted files using git-reflog by cherry-picking the commit that contained the file before it was deleted.

What happens to reflog entries when I push my repository to a remote origin?

When you push your repository to a remote origin, Git only sends reachable commits and discards unreachable ones. This means that any unreachable commits or changes in the local reflog file will not be included in the pushed repository.

Can I use git-reflog on a remote repository?

No, git-reflog only works on local repositories. However, you can clone the remote repository to your local machine and then use git-reflog.

What is the difference between a soft reset and a hard reset in Git, and how does it affect git-reflog?

A soft reset (git reset --soft) moves the HEAD pointer but keeps the commit history intact, while a hard reset (git reset --hard) resets both the head and the working directory to a specific commit, discarding changes