What are the differences between git remote prune, git prune, git fetch --prune, etc

Understanding Git Pruning: remote prune vs. fetch --prune

Demystify the various Git commands for cleaning up stale remote-tracking branches, including git remote prune, git fetch --prune, and git prune.

Maintaining a clean and accurate local Git repository is crucial for efficient development. Over time, remote branches that have been deleted on the origin server can leave behind 'stale' remote-tracking branches in your local repository. These can clutter your branch list and lead to confusion. Git provides several commands to address this, primarily git remote prune <remote_name> and git fetch --prune. This article will clarify the differences between these commands, explain when to use each, and briefly touch upon the less common git prune.

The Problem: Stale Remote-Tracking Branches

When a branch is deleted on a remote repository (e.g., GitHub, GitLab), your local Git repository doesn't automatically remove its corresponding remote-tracking branch. For instance, if a branch named feature/xyz is deleted on origin, you might still see origin/feature/xyz when you run git branch -r locally. These are called stale remote-tracking branches. They don't point to any existing remote branch and can make your local git branch -r output unnecessarily long and confusing.

# Example: Listing remote-tracking branches
git branch -r

# Sample output showing a stale branch
  origin/HEAD -> origin/main
  origin/main
  origin/develop
  origin/feature/new-feature
  origin/feature/old-deleted-feature # This is stale!

Identifying stale remote-tracking branches.

git remote prune <remote_name>: Explicit Cleanup

The git remote prune <remote_name> command is used to explicitly remove any remote-tracking branches that no longer exist on the specified remote. It performs a cleanup operation without first fetching new data from the remote. This means it relies on the last known state of the remote from your local repository's perspective. If you haven't fetched recently, it might not prune branches that were deleted very recently on the remote.

# Prune stale branches from the 'origin' remote
git remote prune origin

Using git remote prune to clean up the 'origin' remote.

git fetch --prune (or -p): Fetch and Clean

The git fetch --prune (or its shorthand git fetch -p) command is arguably the most common and recommended way to clean up stale remote-tracking branches. This command first fetches all new changes and updates from the remote repository, and then it removes any remote-tracking branches that no longer exist on the remote. This ensures that your local repository's view of the remote is completely up-to-date before any pruning occurs.

# Fetch all updates from 'origin' and prune stale branches
git fetch --prune origin

# Shorthand version
git fetch -p origin

Using git fetch --prune for a combined fetch and cleanup operation.

flowchart TD
    A[Start]
    A --> B{Remote Branch Deleted?}
    B -- Yes --> C[Local Remote-Tracking Branch Becomes Stale]
    B -- No --> D[Local Remote-Tracking Branch Still Valid]

    C --> E["git remote prune <remote>"]
    E --> F[Removes Stale Local Remote-Tracking Branch]

    C --> G["git fetch --prune <remote>"]
    G --> H[Fetches Latest Remote State]
    H --> I[Removes Stale Local Remote-Tracking Branch]

    D --> J[No Action Needed]

    style E fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#bbf,stroke:#333,stroke-width:2px

Comparison of git remote prune and git fetch --prune workflows.

git prune: Cleaning Up Loose Objects

It's important not to confuse git prune with the previous commands. git prune is a low-level command that cleans up loose objects in your local repository's object database that are no longer reachable from any ref (branches, tags, etc.). This is part of Git's garbage collection mechanism and is typically run automatically by git gc. It does not deal with remote-tracking branches directly. You rarely need to run git prune manually.

# This command cleans up unreachable objects, not remote branches
git prune

The git prune command for cleaning up loose Git objects.

Summary and Best Practices

For most users, git fetch --prune is the go-to command for keeping remote-tracking branches clean. It combines fetching the latest remote state with the pruning operation, ensuring your local repository is both up-to-date and tidy. git remote prune is useful if you specifically want to clean up based on your current local knowledge of the remote, without performing a full fetch first. git prune is a different beast entirely, dealing with internal Git objects rather than branches.

1. Regularly Prune

Make it a habit to use git fetch --prune (or git fetch -p) whenever you fetch updates from a remote. This keeps your local branch list clean and accurate.

2. Use Dry Run

If you're unsure what will be pruned, always use the --dry-run option with git remote prune or git fetch --prune first to preview the changes.

3. Understand the Scope

Remember that these commands only affect your local remote-tracking branches. They do not delete branches on the actual remote repository.