From: Julia Evans Date: Tue, 23 Sep 2025 18:10:49 +0000 (+0000) Subject: doc: git-push: rewrite refspec specification X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=657586a5a6ddfa1d6c732b8b0f4670d198a4be02;p=thirdparty%2Fgit.git doc: git-push: rewrite refspec specification From user feedback, there was a request for examples, as well as a comment that one person found "If git push [] without any argument is set to update some ref at the destination with with remote..push configuration variable..." impossible to understand. To make the section easier to navigate, create a list of every possible refspec form, with examples for each form as well as 2 forms which were previously missing (patterns and negative refspecs). Made a few changes to use more familiar language, but ultimately refspecs are a pretty advanced feature so I've mostly left the terminology alone. Signed-off-by: Julia Evans Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index cf506ab8b4..cc5cadcdfc 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -55,54 +55,65 @@ OPTIONS[[OPTIONS]] ...:: Specify what destination ref to update with what source object. - The format of a parameter is an optional plus - `+`, followed by the source object , followed - by a colon `:`, followed by the destination ref . -+ -The is often the name of the branch you would want to push, but -it can be any arbitrary "SHA-1 expression", such as `master~4` or -`HEAD` (see linkgit:gitrevisions[7]). -+ -The tells which ref on the remote side is updated with this -push. Arbitrary expressions cannot be used here, an actual ref must -be named. -If `git push []` without any `` argument is set to -update some ref at the destination with `` with -`remote..push` configuration variable, `:` part can -be omitted--such a push will update a ref that `` normally updates -without any `` on the command line. Otherwise, missing -`:` means to update the same ref as the ``. -+ -If doesn't start with `refs/` (e.g. `refs/heads/master`) we will -try to infer where in `refs/*` on the destination it -belongs based on the type of being pushed and whether -is ambiguous. + --- -* If unambiguously refers to a ref on the remote, - then push to that ref. - -* If resolves to a ref starting with refs/heads/ or refs/tags/, - then prepend that to . - -* Other ambiguity resolutions might be added in the future, but for - now any other cases will error out with an error indicating what we - tried, and depending on the `advice.pushUnqualifiedRefname` - configuration (see linkgit:git-config[1]) suggest what refs/ - namespace you may have wanted to push to. - -Pushing an empty allows you to delete the ref from the -remote repository. Deletions are always accepted without a leading `+` -in the refspec (or `--force`), except when forbidden by configuration -or hooks. See `receive.denyDeletes` in linkgit:git-config[1] and -`pre-receive` and `update` in linkgit:githooks[5]. -+ -The special refspec `:` (or `+:` to allow non-fast-forward updates) -directs Git to push "matching" branches: for every branch that exists on -the local side, the remote side is updated if a branch of the same name -already exists on the remote side. -+ -`tag ` means the same as `refs/tags/:refs/tags/`. +The format for a refspec is [+][:], for example `main`, +`main:other`, or `HEAD^:refs/heads/main`. ++ +The `` is often the name of the local branch to push, but it can be +any arbitrary "SHA-1 expression" (see linkgit:gitrevisions[7]). ++ +The `` determines what ref to update on the remote side. It must be the +name of a branch, tag, or other ref, not an arbitrary expression. ++ +The `+` is optional and does the same thing as `--force`. ++ +You can write a refspec using the fully expanded form (for +example `refs/heads/main:refs/heads/main`) which specifies the exact source +and destination, or with a shorter form (for example `main` or +`main:other`). Here are the rules for how refspecs are expanded, +as well as various other special refspec forms: ++ + * `` without a `:` means to update the same ref as the + ``, unless the `remote..push` configuration specifies a + different . For example, if `main` is a branch, then the refspec + `main` expands to `main:refs/heads/main`. + * If `` unambiguously refers to a ref on the remote, + then expand it to that ref. For example, if `v1.0` is a tag on the + remote, then `HEAD:v1.0` expands to `HEAD:refs/tags/v1.0`. + * If `` resolves to a ref starting with `refs/heads/` or `refs/tags/`, + then prepend that to . For example, if `main` is a branch, then + `main:other` expands to `main:refs/heads/other` + * The special refspec `:` (or `+:` to allow non-fast-forward updates) + directs Git to push "matching" branches: for every branch that exists on + the local side, the remote side is updated if a branch of the same name + already exists on the remote side. + * may contain a * to indicate a simple pattern match. + This works like a glob that matches any ref matching the pattern. + There must be only one * in both the `` and ``. + It will map refs to the destination by replacing the * with the + contents matched from the source. For example, `refs/heads/*:refs/heads/*` + will push all branches. + * A refspec starting with `^` is a negative refspec. + This specifies refs to exclude. A ref will be considered to + match if it matches at least one positive refspec, and does not + match any negative refspec. Negative refspecs can be pattern refspecs. + They must only contain a ``. + Fully spelled out hex object names are also not supported. + For example, `git push origin 'refs/heads/*' '^refs/heads/dev-*'` + will push all branches except for those starting with `dev-` + * If `` is empty, it deletes the `` ref from the remote + repository. For example, `git push origin :dev` will + delete the `dev` branch. + * `tag ` expands to `refs/tags/:refs/tags/`. + This is technically a special syntax for `git push` and not a refspec, + since in `git push origin tag v1.0` the arguments `tag` and `v1.0` + are separate. + * If the refspec can't be expanded unambiguously, error out + with an error indicating what was tried, and depending + on the `advice.pushUnqualifiedRefname` configuration (see + linkgit:git-config[1]) suggest what refs/ namespace you may have + wanted to push to. + Not all updates are allowed: see PUSH RULES below for the details. --all::