Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Revisions and Pathspecs

Refspec: source:destination mappings

Reference for Git refspecs: the optional +, source and destination parts, wildcard mappings for fetch and push, deleting remote refs and negative refspecs.

A refspec tells git fetch and git push how names on one side map to names on the other. Its shape is [+]<src>:<dst>. For a fetch, <src> is a ref on the remote and <dst> is where it is stored locally. For a push, <src> is a local ref or commit and <dst> is the ref to update on the remote.

Most of the time you never type one. The default fetch refspec written by git clone is +refs/heads/*:refs/remotes/origin/*, which is why remote branches show up as origin/main. Writing refspecs yourself lets you fetch tags into a custom namespace, push a local branch under another name, delete a remote branch, or mirror whole ref hierarchies.

Terminal
git fetch origin '+refs/heads/*:refs/remotes/origin/*'
git push origin main:release
git push origin :old-branch        # delete old-branch on the remote

Try it

Bash Push under another name, and delete

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Wildcard fetch refspecs and a custom namespace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
[+]<src>[:<dst>]
[+]<pattern>/*:<pattern>/*
^<pattern>                      # negative refspec (Git 2.29 and later)
:<dst>                          # push only: delete <dst>
Part Meaning
+ Allow a non-fast-forward update. Without it, Git refuses to move <dst> unless the update is a fast-forward (fetch) or the remote ref is an ancestor (push).
<src> For fetch, the remote ref; for push, a local ref or any revision such as HEAD~2. May be empty on a push to delete.
<dst> The ref to update. A short name is expanded using rules like branch or tag; use the full refs/... form when the kind is unclear.
* One wildcard per side, matching the same text on both. Only one * is allowed and it must follow a / or begin the name.
^<pattern> Exclude matching refs from a fetch that other refspecs would otherwise take.

Errors and edge cases: ! [rejected] ... (non-fast-forward) means the update needed +. error: unable to push to unqualified destination means Git cannot tell whether <dst> is a branch or tag; write refs/heads/<name>. fatal: invalid refspec is reported for malformed patterns, such as two wildcards.

Usage notes

  • Where configuration lives: remote.<name>.fetch holds fetch refspecs (several allowed) and remote.<name>.push holds push refspecs. A git fetch with no arguments uses the first set, and git fetch <remote> <refspec> ignores the configured ones for storing, although it still updates remote-tracking refs opportunistically.
  • Default stored under refs/remotes/. Because the destination is outside refs/heads/, remote branches cannot be checked out accidentally and cannot be fast-forwarded by a normal commit.
  • A push without a destination (git push origin main) uses the same name on the remote. HEAD as a source pushes the current branch under its own name only with the right push.default rule; spelling HEAD:branch is explicit.
  • Delete with an empty source (:branch) or the clearer --delete. Deleting a remote branch does not remove your remote-tracking ref until the next git fetch --prune.
  • Tags: the default refspec does not include them; Git fetches tags that point into the history it receives. Use '+refs/tags/*:refs/tags/*' to mirror all tags, or --tags for the same effect on a single run.
  • Pushing a commit directly: git push origin a1b2c3d:refs/heads/rescue creates a branch from any commit you have.
  • Forced updates with + are as dangerous as --force; use git push --force-with-lease for a checked version of the same idea.
  • Mirror clones use +refs/*:refs/*, which copies every ref, including your local branches; that is what git clone --mirror configures.