Git Cleanup: "git Remote Prune" Explained

Mastering the git remote prune command and its role in keeping a healthy workflow

Photo by Zac Edmonds on Unsplash

Git is a powerful version control system that allows developers to collaborate and manage code effectively. One of the key features of Git is the ability to work with remote repositories, which allows teams to work on the same code from different locations. However, as the remote repository is updated and branches are added or removed, it’s important to keep your local repository in sync to avoid confusion and errors.

In this blog post, we will delve into the inner workings of the Git command git remote prune and how it helps keep your local repository organized and up-to-date with the remote repository. Whether you are new to Git or an experienced user, this post will give you a deeper understanding of the git remote prune command and its role in maintaining a healthy Git workflow.

When we run the command git remote prune origin, Git is essentially cleaning up any remote-tracking branches that no longer exist on the remote repository. Quoting the official docs:

Deletes stale references associated with <name>. By default, stale remote-tracking branches under <name> are deleted, but depending on global configuration and the configuration of the remote we might even prune local tags that haven’t been pushed there. Equivalent to git fetch --prune <name>, except that no new references will be fetched.

A remote-tracking branch is a local copy of a branch that exists on a remote repository. When you clone a repository, Git automatically creates remote-tracking branches for all branches that exist on the remote repository. These remote-tracking branches are used to keep track of the state of the corresponding branches on the remote repository.

When you run the command git remote prune origin, Git will check the remote repository (in this case, "origin") to see which branches still exist on the remote. It then compares this list of branches to the list of remote-tracking branches that you have locally. Any remote-tracking branches that are not present on the remote will be deleted from your local repository.

Internals

Internally, Git will check the .git/refs/remotes/origin directory, which contains all the remote-tracking branches for the remote named origin. It will then compare the branches in that directory with the branches present in the remote, and remove the branches that are not present in the remote from the .git/refs/remotes/origin directory.

Git uses a Directed Acyclic Graph (DAG) to manage all the commits, branches, and other objects in the repository. Each commit object has a unique hash, which is calculated based on the contents of the commit. When you run git remote prune origin, Git will also check the .git/objects directory, which contains all the objects in the repository, including commits. It will remove the commits that are no longer reachable from any of the remaining branches.

Photo by Zach Reiner on Unsplash

Let’s dive into an example and see how the git remote prune command works.

Example

Let’s imagine that you are working on a project called “Rabbit” with a team of other developers. You have cloned the repository from a remote server and have been working on a new feature branch called “alice”.

At some point, one of your team members decides to delete the “alice” branch from the remote repository, as it is no longer needed. However, your local repository still has a remote-tracking branch for “alice”.

If you were to run git branch -r you would see the remote branches including the “alice”, even though it's deleted from the remote repository:

$ git branch -r
origin/HEAD -> origin/master
origin/alice
origin/my-awesome-feature

In addition, we can list files inside .git/refs/remotes/origin:

$ ls .git/refs/remotes/origin
HEAD*
alice
my-awesome-feature

Running git remote prune origin will remove this stale branch from your local repository.

This command will check the remote repository and compare the list of branches on the remote to the list of remote-tracking branches in your local repository. It will then remove the “feature-x” remote-tracking branch from your local repository, as it is no longer present on the remote repository.

Additionally, the command git remote prune origin will also check the .git/objects directory, which contains all the objects in the repository, including commits. it will remove the commits that are no longer reachable from any of the remaining branches.

Bring it all together:

1. Git retrieves the list of branches from the specified remote repository
2. It compares the list of branches retrieved from the remote with the list of local remote-tracking branches
3. For each remote-tracking branch that exists locally but not on the remote, it removes the remote-tracking branch from the local repository
4. It also checks the commits in the local repository, if it finds any commits that are no longer reachable from any of the remaining branches, it removes them

Tip: Create an alias for git remote prune origin as git rpo, you can add the following line to your ~/.gitconfig:

[alias]
    rpo = "remote prune origin"

After saving the file, you can use the alias by simply running git rpo.

Over time, as branches are deleted from the remote repository, your local repository may contain references to these deleted branches. Running “git remote prune origin” removes these stale references, ensuring that your local repository accurately reflects the current state of the remote repository. This helps avoid confusion and potential errors when working with the repository and helps ensure that your local repository is in sync with the latest changes.