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.
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
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.
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
[+]<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>.fetchholds fetch refspecs (several allowed) andremote.<name>.pushholds push refspecs. Agit fetchwith no arguments uses the first set, andgit 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 outsiderefs/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.HEADas a source pushes the current branch under its own name only with the rightpush.defaultrule; spellingHEAD:branchis explicit. - Delete with an empty source (
:branch) or the clearer--delete. Deleting a remote branch does not remove your remote-tracking ref until the nextgit 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--tagsfor the same effect on a single run. - Pushing a commit directly:
git push origin a1b2c3d:refs/heads/rescuecreates 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 whatgit clone --mirrorconfigures.
Related
- git fetch, git push, git remote, Special refs
- Lessons: Remotes, Push and pull