Introduction

Git has several commands with prune in the name, but they clean up different things. The important distinction is between remote-tracking branch cleanup and low-level object cleanup. If you mix those up, you can easily run a much more destructive command than you intended.

For everyday branch housekeeping, git fetch --prune is usually the right answer. git prune is a very different tool and is rarely the normal fix for stale branch names.

Remote Refs Versus Git Objects

Git stores multiple layers of data:

• local branches such as main
• remote-tracking branches such as origin/main
• objects such as commits, trees, and blobs

git fetch --prune and git remote prune deal with remote-tracking refs. git prune deals with unreachable objects in the object database. That is the entire mental model you need to keep the commands straight.

git fetch --prune

This is the most useful day-to-day command:

git fetch --prune

It does two things:

1. fetches updates from the remote
2. removes stale remote-tracking refs that no longer exist there

If a teammate deleted feature-x from the remote server, you may still see origin/feature-x locally until you run a fetch with pruning.

You can also target one remote:

git fetch --prune origin

This is usually the best routine cleanup command because it updates and cleans in one step.

git remote prune

This command also removes stale remote-tracking refs:

git remote prune origin

The difference is that it does not fetch new data first. It prunes based on the remote state Git already knows about.

That means:

• 'git fetch --prune is fetch plus prune'
• 'git remote prune origin is prune only'

If you were going to fetch anyway, git fetch --prune is generally the more useful choice.

git prune

git prune is a lower-level maintenance command:

git prune

It removes unreachable loose objects from the local repository. That is not the same thing as removing stale remote-tracking branches.

This is why git prune is almost never the right answer when the problem is origin/old-branch still showing up in git branch -r.

For object cleanup, the normal higher-level command is:

git gc

git gc performs repository maintenance and invokes prune-like cleanup in a safer, more coordinated way.

A Concrete Example

Suppose the remote branch feature-a was deleted on GitHub. Your local repo may still show:

git branch -r

Output:

origin/main
origin/feature-a

To clean that up:

git fetch --prune

Now origin/feature-a disappears if it no longer exists remotely.

Running git prune here would be conceptually wrong. The issue is an outdated ref, not an unreachable loose object.

Related Commands That Sound Similar

A few nearby commands are easy to confuse:

• 'git branch -d feature-a deletes a local branch'
• 'git branch -dr origin/feature-a deletes one remote-tracking ref manually'
• 'git clean -fd removes untracked files from the working tree'
• 'git gc performs repository maintenance'

These are all different from git prune, even if they all feel like cleanup.

Common Pitfalls

• Running git prune when the real goal is to remove stale origin/... refs.
• Assuming git remote prune fetches new branch information when it only prunes known stale refs.
• Confusing a remote-tracking branch with a local branch. Pruning origin/x does not delete your local x.
• Using git clean and git prune interchangeably even though one targets files and the other targets objects.
• Forgetting that git gc is the normal high-level maintenance command for object cleanup.

Summary

• 'git fetch --prune fetches updates and removes stale remote-tracking refs.'
• 'git remote prune <remote> removes stale remote-tracking refs without fetching first.'
• 'git prune removes unreachable loose objects from the local object database.'
• 'git gc is the usual safe high-level maintenance command for object cleanup.'
• Most branch-cleanup problems are about refs, not about low-level object pruning.