git fetch: Usage, Options & Common CI Errors
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
git fetch origin
git fetch --all --prune
git fetch --unshallow # convert shallow clone to full
git fetch --depth=50 origin main
git fetch origin --tagsOptions
| 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.
- 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