# git remote prune: Usage, Options & Common CI Errors

> git remote prune deletes local remote-tracking refs whose upstream branches are gone. Reference for --dry-run, fetch --prune, and stale-branch cleanup in CI.

Source: https://latchkey.dev/learn/command-reference/git-remote-prune  
Updated: 2026-06-25

git remote prune removes the local stand-ins for branches that were deleted on the remote.

After PRs merge and branches are deleted upstream, your origin/* refs go stale. Pruning keeps branch listings and ref iterations honest in long-lived caches and CI workspaces.

## What it does

git remote prune deletes remote-tracking references under refs/remotes/<remote>/ that no longer have a corresponding branch on the remote. It does not touch local branches or remote data.

## Common usage

```Terminal
git remote prune origin
git remote prune --dry-run origin
# equivalent during a fetch:
git fetch --prune origin
```

## Options

| Flag | What it does |
| --- | --- |
| <remote> | The remote whose stale refs to prune |
| -n / --dry-run | Show what would be pruned |
| (via fetch) --prune | Prune as part of a fetch |

## Common errors in CI

Pruning only removes remote-tracking refs, not your local branches - a local branch whose upstream vanished still lingers and may show "gone" in git branch -vv. Use git fetch --prune to refresh and prune in one step; --dry-run first if a script deletes based on the output.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git remote prune: Usage, Options & Common CI Errors?

After PRs merge and branches are deleted upstream, your origin/* refs go stale. Pruning keeps branch listings and ref iterations honest in long-lived caches and CI workspaces.

### What it does?

git remote prune deletes remote-tracking references under refs/remotes/<remote>/ that no longer have a corresponding branch on the remote. It does not touch local branches or remote data.

### Common errors in CI?

Pruning only removes remote-tracking refs, not your local branches - a local branch whose upstream vanished still lingers and may show "gone" in git branch -vv. Use git fetch --prune to refresh and prune in one step; --dry-run first if a script deletes based on the output.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt