# git fetch: Usage, Options & Common CI Errors

> git fetch downloads remote objects and refs without touching your working tree. Reference for --depth, --unshallow, --prune, and shallow-clone errors.

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

git fetch updates your remote-tracking branches but never changes your local branch or files.

Fetch is the safe way to see what is new upstream. It is also how you deepen a shallow clone in CI.

## What it does

git fetch retrieves commits, files, and refs from a remote into your local object store and updates remote-tracking refs like origin/main. Your checked-out branch and working tree are untouched.

## Common usage

```Terminal
git fetch origin
git fetch --all --prune
git fetch --unshallow          # convert shallow clone to full
git fetch --depth=50 origin main
git fetch origin --tags
```

## Options

| Flag | What it does |
| --- | --- |
| --all | Fetch from all remotes |
| --prune / -p | Delete remote-tracking refs that no longer exist |
| --unshallow | Fetch full history into a shallow clone |
| --depth=N | Limit (or deepen) to N commits |
| --tags | Fetch all tags |

## Common errors in CI

fatal: refusing to merge unrelated histories or "shallow update not allowed" / tools that need full history failing - the runner did a shallow clone (depth 1). Run git fetch --unshallow, or set fetch-depth: 0 in actions/checkout so tags and full history are present.

## 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 fetch: Usage, Options & Common CI Errors?

Fetch is the safe way to see what is new upstream. It is also how you deepen a shallow clone in CI.

### What it does?

git fetch retrieves commits, files, and refs from a remote into your local object store and updates remote-tracking refs like origin/main. Your checked-out branch and working tree are untouched.

### Common errors in CI?

fatal: refusing to merge unrelated histories or "shallow update not allowed" / tools that need full history failing - the runner did a shallow clone (depth 1). Run git fetch --unshallow, or set fetch-depth: 0 in actions/checkout so tags and full history are present.

---

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