How to Use Git Prune to Remove Outdated References in Git

When working with Git, repositories can accumulate outdated references to branches, commits, and objects that no longer serve any purpose. These obsolete references can lead to confusion, unnecessary storage usage, and slower performance. Git provides a useful command called git prune, which helps remove such outdated references, keeping repositories clean and efficient.

In this guide, we’ll have a detailed discussion on the git prune command, its advantages, the scenarios where we can use it, and how we can remove outdated references both locally and remotely in Git.

What is git prune?

git prune is a Git command used to prune or remove unreachable objects, such as commits and blobs, that are no longer referenced by any branch or tag in a repository. These objects might exist due to branch deletions, rebases, or resets. By cleaning up these objects, git prune helps maintain an optimized repository, improve performance, and reduce disk space usage.

It’s important to note that git prune operates only on objects that are truly unreachable. If an object is referenced by any branch, tag, or reflog entry, it will not be pruned. Pruning is often used automatically with Git’s garbage collection mechanism to ensure the repository is efficiently maintained.

Now that we know what git prune is and how it works, let’s discuss the advantages of using this command.

Advantages of using git prune

The several advantages of using the git prune command include:

• Reduces Clutter: Helps keep the repository clean by removing obsolete references.
• Frees Up Space: Reclaims disk space by deleting unreachable objects.
• Improves Performance: Enhances the performance of a repository by deleting unnecessary objects.
• Prevents Confusion: Reduces the chances of accidental usage of obsolete branches or commits by eliminating outdated references.

With the advantages covered, let’s next look at the ideal scenarios for using git prune.

When to use git prune?

We can use the git prune command in multiple scenarios, such as:

• After deleting branches to remove unnecessary references.
• When cleaning up stale references after performing a fetch operation.
• After performing a rebase or reset, which can leave behind unreachable commits that are no longer needed.

We’re now aware of the scenarios where we can use git prune, but do we know how to use it?

In the next section, we’ll learn how to use git prune to remove outdated references locally in Git.

How to remove outdated references locally in Git

The git prune command is a handy tool when it comes to removing unreachable objects locally. Before starting the process, fork and clone the docs remote repository to your local machine to follow along with the tutorial.

Now, while on the repository locally, the first step is to run this command in the terminal:

git prune --dry-run

to clipboard
Copy to clipboard

The --dry-run flag with the git prune command lists all the local outdated references in the repository that can be pruned. Here is a sample output:

01268db12e0e708a525a4d4291625a4edc842784 commit
01a8025a253f5574213041277487b95c0a4b4148 commit
01de9fd25808933693cfe9a7de30bf87a44176dd commit
...

to clipboard
Copy to clipboard

All the references that we can see in the output are commits. However, the references can include blobs (files), trees (directory snapshots), and tags as well.

Then, run the git prune command to get rid of all these references at once:

git prune

to clipboard
Copy to clipboard

Sometimes, a few references that can be pruned don’t appear on the list shown after executing git prune --dry-run, because they are still referenced in the reflog. The reflog is a record of all the actions that a user performs in Git, including branch switches, rebases, resets, and commits. These references expire from the reflog after a particular amount of time. However, if we want to remove them now, we can run this command:

git reflog expire --expire-unreachable=now –all

to clipboard
Copy to clipboard

In this command:

• git reflog expire: Expires or removes a reference from the reflog.
• --expire-unreachable=now: Sets the expiry date of all the local unreachable references to now, effectively setting them up to be removed immediately.
• --all: Targets all the reflog entries that currently exist in the repository.

We can also use the git prune command to set an expiration time for the local outdated references, after which they will be pruned:

git prune --expire=3.weeks.ago

to clipboard
Copy to clipboard

Here, the --expire flag sets an expiration time of 3.weeks.ago, which indicates that Git will remove all the references that have been unreachable for more than 3 weeks. Some more examples of the expiration time can be 2.months.ago, 5.days.ago, yesterday, etc.

We discussed how to remove outdated references locally in Git, but what about removing them remotely?

In the next section, we’ll learn how to remove outdated references remotely in Git.

How to remove outdated references remotely in Git

When working on a remote repository, we may occasionally need to delete remote branches that are no longer required. Upon deletion, they are removed from the repository, but the references to these remote branches aren’t. Instead, these references exist in the repository as remote outdated references.

To remove these references, we can use the git fetch command with --prune flag:

git fetch --prune origin

to clipboard
Copy to clipboard

In this command:

• git fetch: Fetches the latest changes (including any new remote outdated references) from origin to the local repository.
• --prune: Removes all the remote outdated references in the repository.
• origin: An alias for the forked docs remote repository.

If we want to remove outdated references remotely without fetching the latest changes, we can use this command instead:

git remote prune origin

to clipboard
Copy to clipboard

In this command:

• git remote: Specifies the target remote repository (origin).
• prune: Removes all the remote outdated references in the repository.

Now that we’re done discussing how to remove outdated references locally and remotely in Git, let’s have a quick summary of the topics discussed in this guide.

Conclusion

In this tutorial, we explored the git prune command and learned how to remove local and remote outdated references in Git. We also covered its advantages and the ideal scenarios for using it.

Keeping our Git repositories clean using git prune ensures efficient repository management, better performance, and easier navigation of branches. Regular pruning helps maintain a well-structured repository, preventing unnecessary clutter and confusion.

If you want to learn more about Git branching and collaboration, check out the Learn Git: Branching and Collaboration course on Codecademy.