Skip to content

Git Refspec

In one line

A refspec is a mapping that tells Git which local and remote refs correspond during push and fetch operations.

In simple words

A refspec (reference specification) is a string that maps source refs to destination refs during git push and git fetch. The format is +src:dst — the optional + allows non-fast-forward updates, src is the source ref, and dst is the destination. Refspecs are what make push and fetch move refs between repos.

When you run git push origin main, Git uses the refspec main:main (from your config's remote.origin.push, or inferred from main). You can write explicit refspecs to do unusual things: git push origin feature:experimental pushes your feature branch to the remote's experimental branch. The + prefix forces the update even if it is not a fast-forward.

Refspecs in the gitconfig ([remote "origin"] fetch = +refs/heads/*:refs/remotes/origin/*) define the default fetch mapping — all remote branches are mirrored under refs/remotes/origin/. Understanding refspecs unlocks precise control over which refs move where, useful for mirroring, partial sync, and CI workflows.

Example

bash
# Push local feature to remote experimental branch
git push origin feature:experimental

# Force-push (non-fast-forward allowed)
git push origin +feature:feature

# Fetch a remote tag into a local tag
git fetch origin refs/tags/v1.0:refs/tags/v1.0

# Delete a remote branch by pushing an empty source
git push origin :old-branch

# Default fetch refspec in .git/config
# [remote "origin"]
#   fetch = +refs/heads/*:refs/remotes/origin/*

src:dst maps source to destination ref. + allows force. An empty src deletes the dst. The default fetch refspec mirrors all remote branches locally.

Related terms

Related Resources

Related Lessons

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary