What is the Git Reflog?

The Git reflog (short for "reference log") is a powerful and handy utility in Git that keeps a record of all reference updates in your Git repository. It's like a magical notebook that keeps a record of all the changes you've made, so that if something goes wrong, you can refer to your Git journal to find a way to fix it! 🧙

That's one of the great things about Git: it never really loses anything, even when performing history rewriting operations like rebasing or commit amending.

The reflog is a record that maintains a chronological history of significant changes made to the HEAD, branches, and tags. These changes consist of:

Commits
Checkouts
Merges
Rebases

The reflog is a powerful tool for maintaining a safety net in your Git repository and recovering from various accidental or unexpected changes, such as those times when you need to recover lost commits or branches and have lost track of your Git history.

How the Git Reflog Works

Whenever a reference is updated (e.g., a new commit is added to a branch, or you switch to a different branch), Git records this change in the reflog. Each entry in the reflog contains information about the action performed, a timestamp, and the old and new values of the reference.

On any Git repository, you can type git reflog to try it out — it will output the reflog of the HEAD reference by default.

You can view the reflog entries for a specific reference, such as a branch, by using the git reflog <ref> command. For example, if you run git reflog main, it will show the reflog for the main branch.

How to Recover Lost Commits or Branches with the Reflog

As mentioned previously, one of the most common use cases for the reflog is to recover lost commits or branches. If you accidentally delete a branch or reset it to an unintended commit, you can use the reflog to find the commit SHA-1 hash associated with the branch before the change and then recreate the branch or restore it to the desired state.

As an example, let's go through the entire process to recover a lost branch called "new-feature" that you accidentally deleted or lost track of.

Step 1: Run git reflog to view the history of recent reference updates.

Step 2: Go through the reflog entries to find the reference related to the branch you want to recover (in this case, "new-feature"). Each entry should have a description of the action and a commit hash.

The entry related to the branch might look something like this:

<commit hash> HEAD@{7}: checkout: moving from main to new-feature

Take note of the commit hash associated with the creation of the branch as you will need it for the final step.

Step 3: Now that you have found the commit hash, you have two options:

Create a new branch with the same information by typing git checkout -b new-branch-for-feature <commit hash>.
Restore the existing branch by typing git branch -f new-feature <commit hash>. This command will either create a new branch at the specified commit or reset the current branch to that commit.

If you run the git branch command, you should see your branch now 🥳

The reflog helped you find the commit where the branch was created or last existed, and you used that information to recreate or restore the branch.

How to Clean Up the Reflog

Git automatically prunes older entries in the reflog over time to prevent it from growing indefinitely and consuming too much disk space. You can manually clean up the reflog using the git reflog expire and git reflog delete commands if necessary, but it is not recommended, as there is a potential risk of data loss with both commands.

The expire subcommand is used for removing old or inaccessible reflog entries. You can perform a dry run by adding the --dry-run option to see which reflog entries are marked to be pruned.