Git Reflog: Understanding and Using Reference Logs in Git

There's nothing more annoying to a developer or data engineer than accidentally deleting git branches or resetting commits when you didn't want to. That's why I'm happy to share something I learned through my own experience and wished I had learned sooner, which is how to use git reflog. git reflog is one of those techniques that's definitely worth learning; if you put in a little time now, you can save a big headache down the road. 

While I'll be showing you git reflog, which I find really helpful in navigating and recovering from mistakes, I also want to recommend our Foundations of Git and Introduction to GitHub Concepts courses to learn everything there is to know about version control.

What Is git reflog?

Git reflog, or reference log, is a local tracking mechanism that records updates to branch tips and the HEAD reference in a Git repository. (In the context of Git, HEAD refers to the current commit that your working directory and staging area are based on.)

Unlike git log, which displays the commit history based on ancestry, showing how commits are connected in a branch, git reflog captures all movements of HEAD, including branch switches, rebases, resets, and commits. This makes reflog useful for recovering lost commits and debugging recent actions.

When are reflog entries created?

Reflog entries are created whenever you perform actions that change the state of HEAD or branch references. Common scenarios include the following:

• Committing changes using git commit.

• Checking out a different branch using git checkout branch_name.

• Creating a new branch using git branch new_branch.

• Rebasing git rebase

• Resetting to a previous commit git reset --hard.

• Merging branches using git merge.

Here is the code you use to track updates in the local repository:

git reflog

Using git reflog to track updates in the local repository. Image by Author.

How do you interpret the output of git reflog?

You can interpret the output as follows:

• HEAD@{0}: The most recent action was switching to the HEAD branch.

• HEAD@{1}: Before that, I had changed a file type from .xlxs to .csv format.

• HEAD@{2}: I made the first commit when pushing the files to the repository.

Each entry shows:

• The commit hash (fa82776)

• The reflog index (HEAD@{0}, HEAD@{1}, etc.)

• A description of the action taken (commit, checkout, rebase)

How to Use git reflog

Git reflog provides a way to track reference updates and restore your repository's previous states. By understanding how to navigate reflog entries, you can recover lost commits, undo changes, and compare past versions of your work. 

Basic git reflog command

Below is the basic reflog command:

git reflog

The above command displays a list of recent actions that updated HEAD or branch references, including commits, branch switches, resets, rebases, and more. Each entry is indexed, such as HEAD@{0}, and HEAD@{1}, to represent its position in the reflog history.

Referencing past states

Git reflog serves as a record of past reference updates, allowing us to locate and restore previous points in our repository’s history. Without it, these references wouldn’t exist, and we’d need exact commit hashes to return to specific past states. Now, let’s explore how Git enables us to navigate these past states using git checkout.

HEAD@{n}: Refers to a specific reflog entry, where n is the index. For example, HEAD@{2} refers to the third-most recent state of HEAD.

git checkout HEAD@{2}

Using git checkout to track past changes. Image by Author.

branch@{time}: Refers to the state of a branch at a specific time. For example, main@{1.week.ago} refers to the state of the main branch one week ago while feature@{yesterday} refers to the state of the feature branch yesterday.

git checkout main@{1.week.ago}

Using git checkout to track past changes. Image by Author.

Time-based qualifiers

git reflog not only helps us restore past states but also allows us to compare them. Since reflog tracks reference updates, we can use it to see how our repository has changed over time. Now, let’s look at how git diff makes use of reflog entries to compare past and present states.

The following are examples of time-qualifiers that make it easy to restore your repository to a specific point in time rather than relying solely on reflog index numbers.

git checkout HEAD@{1.minute.ago}     # State from one minute ago

git checkout HEAD@{1.hour.ago}       # State from one hour ago

git checkout HEAD@{1.week.ago}       # State from one week ago

git checkout HEAD@{yesterday}        # State from yesterday

git checkout HEAD@{2024-01-01.12:00:00} # State at a specific timestamp

Comparing past states with git diff

You can compare past states using commands like git diff. The following command compares the current state of the main branch main@{0} with its state from one day ago, main@{1.day.ago}. The output will show any differences between these two snapshots.

git diff main@{0} main@{1.day.ago}

Comparing past states with git diff. Image by Author.

Common Use Cases for Git Reflog

Git reflog is an invaluable tool for recovering lost changes, undoing mistakes, and fixing common Git mishaps. Below are some practical scenarios where git reflog can help.

Undoing a bad reset

If you mistakenly reset your branch using git reset --hard, you can use reflog to restore your previous state.

git reset --hard HEAD@{3}

Recovering lost commits

If you accidentally delete a branch or lose commits due to a reset or rebase, you can find the lost commit using git reflog.

git reflog

Locate the commit hash from the reflog output and check it out:

git checkout <commit-hash>

Once you verify the lost commit, you can create a new branch to preserve it:

git branch recovered-branch <commit-hash>

Fixing a botched rebase

If a rebase goes wrong, you can use git reflog to find the pre-rebase commit and reset your branch. Identify the commit before the rebase and reset it.

git reset --hard HEAD@{3}  # Adjust the number based on the reflog output

Restoring a deleted branch

If you accidentally delete a branch, you can recover it using git reflog. Find the last known commit of the deleted branch and recreate it:

git branch restored-branch <commit-hash>

Tracking stash history

Git reflog can also be used to view stash history. The command below lists stash operations, allowing you to recover older stashes if needed. 

git reflog stash

To apply a previous stash entry, use the following command:

git stash apply stash@{2}

Check out our Git Pull Force: How to Overwrite a Local Branch With Remote tutorial to learn the best practices for overwriting local changes.

Git Reflog Subcommands and Options

Git provides several subcommands and options for managing and interacting with reflogs. 

Git reflog subcommands

Below is a structured breakdown of key git reflog subcommands and their usage.

git reflog show: Displays the reflog entries for HEAD by default or for a specified reference like a branch.

git reflog show

Using git reflog show to display entries for specified reference. Image by Author.

git reflog list: This command displays all references with a reflog. It is useful for identifying branches and HEAD references with stored reflog entries.

git reflog list

git reflog delete <ref>@{<specifier>}: Cleans up old reflog entries that exceed the specified time limit. For example, the following command removes entries older than 30 days.

git reflog expire --expire=30.days.ago

git reflog delete <ref>@{<specifier>}: Deletes a particular reflog entry based on its reference and position. The command below removes the reflog entry at index 2 for HEAD.

git reflog delete HEAD@{2}

git reflog exists <ref>: Verifies whether a reflog exists for a specific reference. For example, the command below returns success if the main branch has a reflog.

git reflog exists main

Options for git reflog subcommands

The following are the options available for the git reflog subcommands and their usage.

--expire-unreachable=<time>: Prunes only those reflog entries that are unreachable from any ref. For example, the command below removes unreachable reflog entries older than 7 days.

git reflog expire --expire-unreachable=7.days.ago

--all: Processes reflogs for all references, not just HEAD. The command below cleans up all reflogs older than 60 days across all branches.

git reflog expire --expire=60.days.ago --all

--dry-run: Simulates a command execution, showing what would be pruned without actually deleting anything. For example, the command below displays which entries would be removed.

git reflog expire --expire=30.days.ago --dry-run

--verbose: Provides detailed output about the actions performed by the command. The command below shows verbose details while expiring old reflog entries.

git reflog expire --expire=90.days.ago --verbose

Git Reflog vs. Git Log: Key Differences

Both git log and git reflog provide insights into a repository's history, but they serve different purposes. Let us look at these differences to understand how each can be used for version control and recovery strategies.

• git log shows the commit history by following the ancestry of commits in a branch. It provides a chronological view of how the repository's content evolved.

• git reflog records updates to references like HEAD, branches, and stashes, including actions like branch switches, resets, rebases, and more. It tracks changes that may not be part of the commit ancestry.

• git reflog is strictly local to your machine and is not shared with remote repositories.

• While git log cannot recover commits that are no longer part of the branch ancestry, git reflog can help recover "lost" commits by tracking reference updates, even if those commits are no longer reachable from any branch.

The table below summarizes these key differences.

Git reflog is a powerful tool for recovering lost commits and fixing history issues, but using it effectively requires caution. Here are some best practices to follow when working with reflog.

• Use Reflog for Recovery and Debugging: If you accidentally reset or rebased a branch incorrectly, check git reflog to find a previous reference and restore it.

• Be Cautious with git reset --hard: git reset --hard can permanently remove uncommitted changes. Always check the reflog first to ensure you can recover if something goes wrong.

• Keep Backups Before Running Destructive Commands: To protect against data loss, implement automated backups of your Git repositories. Always store backups in a secure, off-site location to ensure recoverability in case of hardware failure or other disasters.

• Don’t Rely Solely on Reflog for Long-Term Recovery: By default, reflog entries are kept for 90 days. After this period, they may be garbage collected and become unrecoverable. Regularly push your commits to a remote repository to ensure they're preserved beyond your local reflog.

• Use git reflog expire to Manage Old Entries: If your repository’s reflog becomes cluttered, prune older or unreachable entries using git reflog expire.

Conclusion

Effectively managing a project's history in Git requires more than just basic commands. Exploring advanced tools that track reference updates can provide a valuable safety net for recovering lost commits, restoring deleted branches, and correcting mistakes. Gaining hands-on experience with these tools, along with commands like git reset, git checkout, and git revert, can significantly enhance your proficiency in version control.

Taking our courses is not only a great way to learn but it's also a great way to signal to employers that you take software development seriously. To that end, I recommend studying our Top 20 Git Interview Questions and Answers for All Levels blog post and taking our new Git Fundamentals skill track to become an expert in all things Git.