[PATCH 0/2] doc: git-push: clarify section

[PATCH 0/2] doc: git-push: clarify section

[Julia Evans via GitGitGadget]

This is a continuation of the changes to git push, from
https://lore.kernel.org/git/pull.1964.git.1756240823.gitgitgadget@gmail.com/
. These changes to the refspec section got kind of big so I'm moving them
into a separate topic.

Since the last review, the main change is to move the rules for pushing out
of the section and into their own section ("PUSH RULES") so that it can be
easily referenced from other places in the man page.

I don't love the nested list in PUSH RULES but the sentence starting with
"If the source is a tag or commit object..." is really a tough one to read,
it's not going to be relevant to the vast majority of people, and I think
keeping it contained inside a bullet point will make it much easier to skip
over to get to later information which is more likely to be relevant to
folks.

Other changes:

 * removed "+:<dst> is optional.", from Junio's review
 * kept "+ is optional and does the same thing as --force", since now the
   push rules are in their own section.
 * fixed the fully expanded refspec form (main:refs/heads/main =>
   refs/heads/main:refs/heads/main)
 * switched from a numbered list to an unordered list, from Junio's review.
   I think the numbered list looks a lot nicer in the terminal output, but
   it's true that there isn't any order. I briefly attempted to understand
   how AsciiDoc's nroff (?) generation works to see if it's possible to make
   unordered lists indent with fewer spaces (2 instead of 4) but I was left
   feeling that nroff/troff/etc are not for mere mortals like me to
   understand.
 * made it clear that "tag v1.0" is not really a refspec, from Junio's
   review

Julia Evans (2):
  doc: git-push: create PUSH RULES section
  doc: git-push: rewrite refspec specification

 Documentation/git-push.adoc | 198 +++++++++++++++++++-----------------
 1 file changed, 102 insertions(+), 96 deletions(-)


base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1973%2Fjvns%2Fclarify-refspec-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1973/jvns/clarify-refspec-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1973
-- 
gitgitgadget

[PATCH 1/2] doc: git-push: create PUSH RULES section

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

Right now the rules for when a `git push` is allowed are buried at the
bottom of the description of `<refspec>`. Put them in their own section
so that we can reference them from `--force` and give some context for
why they exist.

Having the "PUSH RULES" section also lets us be a little bit more
specific with the rule in `--force`: we can just focus on the rule
for pushing for a branch (which is likely the one that's most relevant)
and leave the details about what happens when you push to a tag or a ref
that isn't a branch to the later section.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-push.adoc | 93 ++++++++++++++++++-------------------
 1 file changed, 44 insertions(+), 49 deletions(-)

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index d1978650d6..193016e291 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -91,48 +91,6 @@ is ambiguous.
   configuration (see linkgit:git-config[1]) suggest what refs/
   namespace you may have wanted to push to.
 
---
-+
-The object referenced by <src> is used to update the <dst> reference
-on the remote side. Whether this is allowed depends on where in
-`refs/*` the <dst> reference lives as described in detail below, in
-those sections "update" means any modifications except deletes, which
-as noted after the next few sections are treated differently.
-+
-The `refs/heads/*` namespace will only accept commit objects, and
-updates only if they can be fast-forwarded.
-+
-The `refs/tags/*` namespace will accept any kind of object (as
-commits, trees and blobs can be tagged), and any updates to them will
-be rejected.
-+
-It's possible to push any type of object to any namespace outside of
-`refs/{tags,heads}/*`. In the case of tags and commits, these will be
-treated as if they were the commits inside `refs/heads/*` for the
-purposes of whether the update is allowed.
-+
-I.e. a fast-forward of commits and tags outside `refs/{tags,heads}/*`
-is allowed, even in cases where what's being fast-forwarded is not a
-commit, but a tag object which happens to point to a new commit which
-is a fast-forward of the commit the last tag (or commit) it's
-replacing. Replacing a tag with an entirely different tag is also
-allowed, if it points to the same commit, as well as pushing a peeled
-tag, i.e. pushing the commit that existing tag object points to, or a
-new tag object which an existing commit points to.
-+
-Tree and blob objects outside of `refs/{tags,heads}/*` will be treated
-the same way as if they were inside `refs/tags/*`, any update of them
-will be rejected.
-+
-All of the rules described above about what's not allowed as an update
-can be overridden by adding an the optional leading `+` to a refspec
-(or using `--force` command line option). The only exception to this
-is that no amount of forcing will make the `refs/heads/*` namespace
-accept a non-commit object. Hooks and configuration can also override
-or amend these rules, see e.g. `receive.denyNonFastForwards` in
-linkgit:git-config[1] and `pre-receive` and `update` in
-linkgit:githooks[5].
-+
 Pushing an empty <src> allows you to delete the <dst> ref from the
 remote repository. Deletions are always accepted without a leading `+`
 in the refspec (or `--force`), except when forbidden by configuration
@@ -145,6 +103,7 @@ the local side, the remote side is updated if a branch of the same name
 already exists on the remote side.
 +
 `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+Not all updates are allowed: see PUSH RULES below for the details.
 
 --all::
 --branches::
@@ -332,14 +291,12 @@ allowing a forced update.
 
 -f::
 --force::
-	Usually, the command refuses to update a remote ref that is
-	not an ancestor of the local ref used to overwrite it.
-	Also, when `--force-with-lease` option is used, the command refuses
-	to update a remote ref whose current value does not match
-	what is expected.
+	Usually, `git push` will refuse to update a branch that is not an
+	ancestor of the local branch or commit being pushed.
 +
-This flag disables these checks, and can cause the remote repository
-to lose commits; use it with care.
+This flag disables that check, the other safety checks in PUSH RULES
+below, and the checks in --force-with-lease. It can cause the remote
+repository to lose commits; use it with care.
 +
 Note that `--force` applies to all the refs that are pushed, hence
 using it with `push.default` set to `matching` or with multiple push
@@ -508,6 +465,44 @@ reason::
 	refs, no explanation is needed. For a failed ref, the reason for
 	failure is described.
 
+PUSH RULES
+----------
+
+As a safety feature, the `git push` command only allows certain kinds of
+updates to prevent you from accidentally losing data on the remote.
+
+Because branches and tags are intended to be used differently, the
+safety rules for pushing to a branch are different from the rules
+for pushing to a tag. In the following rules "update" means any
+modifications except deletes. Deletions are always allowed, except when
+forbidden by configuration or hooks.
+
+1. If the push destination is a **branch** (`refs/heads/*`): only
+   fast-forward updates are allowed: the destination must be an ancestor
+   of the source commit. The source must be a commit.
+2. If the push destination is a **tag** (`refs/tags/*`): all updates will
+   be rejected. The source can be any object
+   (since commits, trees and blobs can be tagged).
+3. If the push destination is not a branch or tag:
+   * If the source is a tree or blob object, any updates will be rejected
+   * If the source is a tag or commit object, any fast-forward update
+     is allowed, even in cases where what's being fast-forwarded is not a
+     commit, but a tag object which happens to point to a new commit which
+     is a fast-forward of the commit the last tag (or commit) it's
+     replacing. Replacing a tag with an entirely different tag is also
+     allowed, if it points to the same commit, as well as pushing a peeled
+     tag, i.e. pushing the commit that existing tag object points to, or a
+     new tag object which an existing commit points to.
+
+You can override these rules by passing `--force` or by adding the
+optional leading `+` to a refspec. The only exception to this is that no
+amount of forcing will make a branch accept a non-commit object.
+
+Hooks and configuration can also override or amend these rules,
+see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes`
+in linkgit:git-config[1] and `pre-receive` and `update` in
+linkgit:githooks[5].
+
 NOTE ABOUT FAST-FORWARDS
 ------------------------
 
-- 
gitgitgadget

Re: [PATCH 1/2] doc: git-push: create PUSH RULES section

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  --force::
> -	Usually, the command refuses to update a remote ref that is
> -	not an ancestor of the local ref used to overwrite it.
> -	Also, when `--force-with-lease` option is used, the command refuses
> -	to update a remote ref whose current value does not match
> -	what is expected.
> +	Usually, `git push` will refuse to update a branch that is not an
> +	ancestor of the local branch or commit being pushed.

I read this as "there are two conditions, and satisifying only one of
them is sufficient for the push to be allowed.  (1) the local branch
is a decendant of the remote branch being updated, or (2) the commit
we push to update the remote branch is a descendant of the remote
branch being updated".

But of course that is not what you wanted to say.  (1) would mean

    $ git reset origin/foo && git push origin anything:foo

would allow us to push literally anything to overwrite origin's foo
branch.

I think

    "... not an ancestor of the commit being pushed to update it."

would be a way to avoid such confusion.

The problem the original description has is the phrase "the local
ref used to overwrite it".  It wasn't as commonly done to push a
specific commit that may not necessarily at the tip of the branch
back when this paragraph was written.

> -This flag disables these checks, and can cause the remote repository
> -to lose commits; use it with care.
> +This flag disables that check, the other safety checks in PUSH RULES
> +below, and the checks in --force-with-lease. It can cause the remote
> +repository to lose commits; use it with care.

OK.

> +PUSH RULES
> +----------
> +
> +As a safety feature, the `git push` command only allows certain kinds of
> +updates to prevent you from accidentally losing data on the remote.
> +
> +Because branches and tags are intended to be used differently, the
> +safety rules for pushing to a branch are different from the rules
> +for pushing to a tag. In the following rules "update" means any
> +modifications except deletes. Deletions are always allowed, except when
> +forbidden by configuration or hooks.

One important operation is omitted.  "update" does not include
"create" in the following, no?  Obviously since refs/tags/ would
never take any "update" (unless forced), if "create" were thrown
into the same category as "update", you cannot push a new tag out.

So, next to "Deletions are always allowed", shouldn't we describe
what rules apply to creations?  I presume that they are also always
allowed?

> +1. If the push destination is a **branch** (`refs/heads/*`): only
> +   fast-forward updates are allowed: the destination must be an ancestor
> +   of the source commit. The source must be a commit.

Reads very well and also correct.

The first colon might be acceptable (I find it a bit odd, though).
The second colon is very weird.  ": only" -> ", only" & "allowed:
the" -> "allowed. The", perhaps?

> +2. If the push destination is a **tag** (`refs/tags/*`): all updates will
> +   be rejected. The source can be any object
> +   (since commits, trees and blobs can be tagged).

Again, I might prefer ":" -> ",".  I cannot decide which I prefer
between "all updates will be rejected" and "by default no updates
are allowed".  Either should be OK, so let's take what has already
been written.

The second sentence is not wrong per-se, and I can see that this was
inherited from the original, but gives me a strange aftertaste. When
you list object types in the context of "tag" and have only commit,
tree, and blob, a little voice in the back of my head asks "oh, what
happend to tags?".  It is made a bit worse with the phrase "can be
tagged", as it typically means either (1) to create an annotated or
signed tag object, or (2) to create a ref in refs/tags/ hierarchy
locally, but usually you do not think of pushing to refs/tags/
hierarchy as "tagging that object remotely".

I think the untold assumption here is that refs/tags/foo at the
remote is being updated most of the time from refs/tags/foo we have
locally, and "any kind of object can be tagged" is trying to say
that refs/tags/foo we have locally can be an object of any type, as
the act of creating a ref "refs/tags/foo" and pointing it directly
at an object is "to create a light-weight tag" for the object.
Since we can have not just tags but any kind of object locally
(because any object "can be tagged"), a push can ask object of any
kind to be pushed to refs/tags/* hierarchy.  But it is an awkward
concept to explain.

Would side-stepping what exactly "tagging a thing" means, and
phrasing it like this

    The source is not limited to an annotated or signed tag object,
    but can be a commit, a tree or even a blob.

work better, I wonder?

> +3. If the push destination is not a branch or tag:

Here, I do understand and support the colon, so I'd equally support
the first colon of the previous 2 sections for consistency.

> +   * If the source is a tree or blob object, any updates will be rejected

OK, so this is the same rule as the refs/tags/ hierarchy.

> +   * If the source is a tag or commit object, any fast-forward update
> +     is allowed, even in cases where what's being fast-forwarded is not a
> +     commit, but a tag object which happens to point to a new commit which
> +     is a fast-forward of the commit the last tag (or commit) it's
> +     replacing. Replacing a tag with an entirely different tag is also
> +     allowed, if it points to the same commit, as well as pushing a peeled
> +     tag, i.e. pushing the commit that existing tag object points to, or a
> +     new tag object which an existing commit points to.
> +
> +You can override these rules by passing `--force` or by adding the
> +optional leading `+` to a refspec. The only exception to this is that no
> +amount of forcing will make a branch accept a non-commit object.
> +
> +Hooks and configuration can also override or amend these rules,
> +see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes`
> +in linkgit:git-config[1] and `pre-receive` and `update` in
> +linkgit:githooks[5].

Very well written.  refs/heads/ not taking any non-commit, and
receiver side hooks that may reject a push, are not something
"--force" can override.  The mention to "the only exception" above
sounded as if it forgot to mention the latter.

Looking mostly good.  Thanks.

Re: [PATCH 1/2] doc: git-push: create PUSH RULES section

[Julia Evans]

>>  --force::
>> -	Usually, the command refuses to update a remote ref that is
>> -	not an ancestor of the local ref used to overwrite it.
>> -	Also, when `--force-with-lease` option is used, the command refuses
>> -	to update a remote ref whose current value does not match
>> -	what is expected.
>> +	Usually, `git push` will refuse to update a branch that is not an
>> +	ancestor of the local branch or commit being pushed.
>
> I read this as "there are two conditions, and satisifying only one of
> them is sufficient for the push to be allowed.  (1) the local branch
> is a decendant of the remote branch being updated, or (2) the commit
> we push to update the remote branch is a descendant of the remote
> branch being updated".
>
> But of course that is not what you wanted to say.  (1) would mean
>
>     $ git reset origin/foo && git push origin anything:foo
>
> would allow us to push literally anything to overwrite origin's foo
> branch.
>
> I think
>
>     "... not an ancestor of the commit being pushed to update it."
>
> would be a way to avoid such confusion.

I like this, will use that phrasing.

>
>> +PUSH RULES
>> +----------
>> +
>> +As a safety feature, the `git push` command only allows certain kinds of
>> +updates to prevent you from accidentally losing data on the remote.
>> +
>> +Because branches and tags are intended to be used differently, the
>> +safety rules for pushing to a branch are different from the rules
>> +for pushing to a tag. In the following rules "update" means any
>> +modifications except deletes. Deletions are always allowed, except when
>> +forbidden by configuration or hooks.
>
> One important operation is omitted.  "update" does not include
> "create" in the following, no?  Obviously since refs/tags/ would
> never take any "update" (unless forced), if "create" were thrown
> into the same category as "update", you cannot push a new tag out.
>
> So, next to "Deletions are always allowed", shouldn't we describe
> what rules apply to creations?  I presume that they are also always
> allowed?

> The first colon might be acceptable (I find it a bit odd, though).
> The second colon is very weird.  ": only" -> ", only" & "allowed:
> the" -> "allowed. The", perhaps?

I agree the second colon is weird, will fix it. (probably ", which means the
destination must be an ancestor of the source commit")

>
>> +2. If the push destination is a **tag** (`refs/tags/*`): all updates will
>> +   be rejected. The source can be any object
>> +   (since commits, trees and blobs can be tagged).
>
> Again, I might prefer ":" -> ",".  I cannot decide which I prefer
> between "all updates will be rejected" and "by default no updates
> are allowed".  Either should be OK, so let's take what has already
> been written.
>
> The second sentence is not wrong per-se, and I can see that this was
> inherited from the original, but gives me a strange aftertaste. When
> you list object types in the context of "tag" and have only commit,
> tree, and blob, a little voice in the back of my head asks "oh, what
> happend to tags?".  It is made a bit worse with the phrase "can be
> tagged", as it typically means either (1) to create an annotated or
> signed tag object, or (2) to create a ref in refs/tags/ hierarchy
> locally, but usually you do not think of pushing to refs/tags/
> hierarchy as "tagging that object remotely".
>
> I think the untold assumption here is that refs/tags/foo at the
> remote is being updated most of the time from refs/tags/foo we have
> locally, and "any kind of object can be tagged" is trying to say
> that refs/tags/foo we have locally can be an object of any type, as
> the act of creating a ref "refs/tags/foo" and pointing it directly
> at an object is "to create a light-weight tag" for the object.
> Since we can have not just tags but any kind of object locally
> (because any object "can be tagged"), a push can ask object of any
> kind to be pushed to refs/tags/* hierarchy.  But it is an awkward
> concept to explain.
>
> Would side-stepping what exactly "tagging a thing" means, and
> phrasing it like this
>
>     The source is not limited to an annotated or signed tag object,
>     but can be a commit, a tree or even a blob.
>
> work better, I wonder?

I think it depends on whether the reader is more familiar with lightweight
tags or annotated tags. The only kind of tag I've ever used personally is a
lightweight tag, so the sentence
"The source is not limited to an annotated or signed tag object,"
feels confusing to me ("why would it be limited to an annotated tag?
I'm not even totally sure what an annotated tag is!")

But I can see that it would be different if the reader is more familiar
with annotated tags. Will think about this. 

Maybe we can just say "the source can be any object" to just be clear that there
are no restrictions without trying to educate the reader about the nature of
Git tags.

>> +3. If the push destination is not a branch or tag:
>
> Here, I do understand and support the colon, so I'd equally support
> the first colon of the previous 2 sections for consistency.
>
>> +   * If the source is a tree or blob object, any updates will be rejected
>
> OK, so this is the same rule as the refs/tags/ hierarchy.
>
>> +   * If the source is a tag or commit object, any fast-forward update
>> +     is allowed, even in cases where what's being fast-forwarded is not a
>> +     commit, but a tag object which happens to point to a new commit which
>> +     is a fast-forward of the commit the last tag (or commit) it's
>> +     replacing. Replacing a tag with an entirely different tag is also
>> +     allowed, if it points to the same commit, as well as pushing a peeled
>> +     tag, i.e. pushing the commit that existing tag object points to, or a
>> +     new tag object which an existing commit points to.
>> +
>> +You can override these rules by passing `--force` or by adding the
>> +optional leading `+` to a refspec. The only exception to this is that no
>> +amount of forcing will make a branch accept a non-commit object.
>> +
>> +Hooks and configuration can also override or amend these rules,
>> +see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes`
>> +in linkgit:git-config[1] and `pre-receive` and `update` in
>> +linkgit:githooks[5].
>
> Very well written.  refs/heads/ not taking any non-commit, and
> receiver side hooks that may reject a push, are not something
> "--force" can override.  The mention to "the only exception" above
> sounded as if it forgot to mention the latter.

Will mention the receiver side hooks there, I didn't think of that.

> Looking mostly good.  Thanks.

[PATCH 2/2] doc: git-push: rewrite refspec specification

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

From user feedback, there was a request for examples, as well as a
comment that one person found "If git push [<repository>] without
any <refspec> argument is set to update some ref at the destination
with <src> with remote.<repository>.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 <julia@jvns.ca>
---
 Documentation/git-push.adoc | 105 ++++++++++++++++++++----------------
 1 file changed, 58 insertions(+), 47 deletions(-)

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 193016e291..068441d09d 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -55,54 +55,65 @@ OPTIONS[[OPTIONS]]
 
 <refspec>...::
 	Specify what destination ref to update with what source object.
-	The format of a <refspec> parameter is an optional plus
-	`+`, followed by the source object <src>, followed
-	by a colon `:`, followed by the destination ref <dst>.
-+
-The <src> 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 <dst> 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 [<repository>]` without any `<refspec>` argument is set to
-update some ref at the destination with `<src>` with
-`remote.<repository>.push` configuration variable, `:<dst>` part can
-be omitted--such a push will update a ref that `<src>` normally updates
-without any `<refspec>` on the command line.  Otherwise, missing
-`:<dst>` means to update the same ref as the `<src>`.
-+
-If <dst> doesn't start with `refs/` (e.g. `refs/heads/master`) we will
-try to infer where in `refs/*` on the destination <repository> it
-belongs based on the type of <src> being pushed and whether <dst>
-is ambiguous.
 +
---
-* If <dst> unambiguously refers to a ref on the <repository> remote,
-  then push to that ref.
-
-* If <src> resolves to a ref starting with refs/heads/ or refs/tags/,
-  then prepend that to <dst>.
-
-* 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 <src> allows you to delete the <dst> 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 <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+The format for a refspec is [+]<src>[:<dst>], for example `main`,
+`main:other`, or `HEAD^:refs/heads/main`.
++
+The `<src>` is often the name of the local branch to push, but it can be
+any arbitrary "SHA-1 expression" (see linkgit:gitrevisions[7]).
++
+The `<dst>` 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:
++
+ *  `<src>` without a `:<dst>` means to update the same ref as the
+    `<src>`, unless the `remote.<repository>.push` configuration specifies a
+    different <dst>. For example, if `main` is a branch, then the refspec
+    `main` expands to `main:refs/heads/main`.
+ *  If `<dst>` unambiguously refers to a ref on the <repository> 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 `<src>` resolves to a ref starting with `refs/heads/` or `refs/tags/`,
+    then prepend that to <dst>. 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.
+ *  <src> 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 `<src>` and `<dst>`.
+    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 `<src>`.
+    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 `<src>` is empty, it deletes the `<dst>` ref from the remote
+    repository. For example, `git push origin :dev` will
+    delete the `dev` branch.
+ *  `tag <tag>` expands to `refs/tags/<tag>:refs/tags/<tag>`.
+	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::
-- 
gitgitgadget

Re: [PATCH 0/2] doc: git-push: clarify section

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 2850 bytes --]

On 2025-09-17 at 21:33:33, Julia Evans via GitGitGadget wrote:
> This is a continuation of the changes to git push, from
> https://lore.kernel.org/git/pull.1964.git.1756240823.gitgitgadget@gmail.com/
> . These changes to the refspec section got kind of big so I'm moving them
> into a separate topic.
> 
> Since the last review, the main change is to move the rules for pushing out
> of the section and into their own section ("PUSH RULES") so that it can be
> easily referenced from other places in the man page.
> 
> I don't love the nested list in PUSH RULES but the sentence starting with
> "If the source is a tag or commit object..." is really a tough one to read,
> it's not going to be relevant to the vast majority of people, and I think
> keeping it contained inside a bullet point will make it much easier to skip
> over to get to later information which is more likely to be relevant to
> folks.
> 
> Other changes:
> 
>  * removed "+:<dst> is optional.", from Junio's review
>  * kept "+ is optional and does the same thing as --force", since now the
>    push rules are in their own section.
>  * fixed the fully expanded refspec form (main:refs/heads/main =>
>    refs/heads/main:refs/heads/main)
>  * switched from a numbered list to an unordered list, from Junio's review.
>    I think the numbered list looks a lot nicer in the terminal output, but
>    it's true that there isn't any order. I briefly attempted to understand
>    how AsciiDoc's nroff (?) generation works to see if it's possible to make
>    unordered lists indent with fewer spaces (2 instead of 4) but I was left
>    feeling that nroff/troff/etc are not for mere mortals like me to
>    understand.

I have used groff for many years to write letters and address envelopes
(as well as write a few manual pages and design some awards) and I still
don't understand much of it, so I understand how you feel.

In this case we have two possible implementations, AsciiDoc and
Asciidoctor, but both use the man macros.  I think if there were some
way to control the value generated as the argument to the `.RS` macro,
then that would be what you want, but I have no idea how to adjust that
in either one.  Personally, I would just leave it as it is, since I
believe 4 is the traditional value used with the man macros, even if
typographically or aesthetically it might be suboptimal.

Having said all that, I think this documentation is much improved and
easier to understand, so thank you for that.  I don't have specific
comments on the patches (although I see that Junio has suggested some
clarifying comments), but I do deeply appreciate your efforts to improve
the documentation (and, outside of the list, to clarify difficult
technical topics in general).
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

Re: [PATCH 0/2] doc: git-push: clarify section

[Jeff King]

On Fri, Sep 19, 2025 at 12:39:12AM +0000, brian m. carlson wrote:

> In this case we have two possible implementations, AsciiDoc and
> Asciidoctor, but both use the man macros.  I think if there were some
> way to control the value generated as the argument to the `.RS` macro,
> then that would be what you want, but I have no idea how to adjust that
> in either one.  Personally, I would just leave it as it is, since I
> believe 4 is the traditional value used with the man macros, even if
> typographically or aesthetically it might be suboptimal.

I think both implementations will just generate XML via our Makefile,
and ultimately it is DocBook which will convert the <orderedlist> into
actual roff. So something like:

diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
index beb5ff8ec2..b494fbb5df 100644
--- a/Documentation/manpage-normal.xsl
+++ b/Documentation/manpage-normal.xsl
@@ -11,4 +11,6 @@
 <!-- unset maximum length of title -->
 <xsl:param name="man.th.title.max.length"/>
 
+<xsl:param name="man.indent.width" select="2"/>
+
 </xsl:stylesheet>

would affect that process. And I think there might even be a specific
list-indent variable, but I didn't dig very far. I agree it's probably
not worth going too far into the rabbit hole of manpage styling. The
parameter docs are here:

  https://docbook.sourceforge.net/release/xsl/1.78.1/doc/manpages/indent.html

I believe Asciidocttor _can_ generate roff directly, but we don't use it
that way. I don't think it would make sense to do so unless we are ready
to drop AsciiDoc support entirely (since keeping them as close together
as possible reduces the maintenance burden).

-Peff

Re: [PATCH 0/2] doc: git-push: clarify section

[Julia Evans]

On Fri, Sep 19, 2025, at 12:25 AM, Jeff King wrote:
> On Fri, Sep 19, 2025 at 12:39:12AM +0000, brian m. carlson wrote:
>
>> In this case we have two possible implementations, AsciiDoc and
>> Asciidoctor, but both use the man macros.  I think if there were some
>> way to control the value generated as the argument to the `.RS` macro,
>> then that would be what you want, but I have no idea how to adjust that
>> in either one.  Personally, I would just leave it as it is, since I
>> believe 4 is the traditional value used with the man macros, even if
>> typographically or aesthetically it might be suboptimal.
>
> I think both implementations will just generate XML via our Makefile,
> and ultimately it is DocBook which will convert the <orderedlist> into
> actual roff. So something like:
>
> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
> index beb5ff8ec2..b494fbb5df 100644
> --- a/Documentation/manpage-normal.xsl
> +++ b/Documentation/manpage-normal.xsl
> @@ -11,4 +11,6 @@
>  <!-- unset maximum length of title -->
>  <xsl:param name="man.th.title.max.length"/>
> 
> +<xsl:param name="man.indent.width" select="2"/>
> +
>  </xsl:stylesheet>
> would affect that process.

That's good to know, thanks. We'd need a way to indent unordered lists
by 2 and ordered lists by 4 anyway (to make space for the numbers in the
ordered lists) and at that point I'm not sure if it would even
look good. I think I'll leave this rabbit hole as is :)

> And I think there might even be a specific
> list-indent variable, but I didn't dig very far. I agree it's probably
> not worth going too far into the rabbit hole of manpage styling. The
> parameter docs are here:
>
>   https://docbook.sourceforge.net/release/xsl/1.78.1/doc/manpages/indent.html
>
> I believe Asciidocttor _can_ generate roff directly, but we don't use it
> that way. I don't think it would make sense to do so unless we are ready
> to drop AsciiDoc support entirely (since keeping them as close together
> as possible reduces the maintenance burden).
>
> -Peff

[PATCH v2 0/2] doc: git-push: clarify section

[Julia Evans via GitGitGadget]

This is a continuation of the changes to git push, from
https://lore.kernel.org/git/pull.1964.git.1756240823.gitgitgadget@gmail.com/
. These changes to the refspec section got kind of big so I'm moving them
into a separate topic.

I don't love the nested list in PUSH RULES but the sentence starting with
"If the source is a tag or commit object..." is really a tough one to read,
it's not going to be relevant to the vast majority of people, and I think
keeping it contained inside a bullet point will make it much easier to skip
over to get to later information which is more likely to be relevant to
folks.

Changes since the original thread:

 * The main change is to move the rules for pushing out of the section and
   into their own section ("PUSH RULES") so that it can be easily referenced
   from other places in the man page.
 * removed "+:<dst> is optional.", from Junio's review
 * kept "+ is optional and does the same thing as --force", since now the
   push rules are in their own section.
 * fixed the fully expanded refspec form (main:refs/heads/main =>
   refs/heads/main:refs/heads/main)
 * switched from a numbered list to an unordered list, from Junio's review.
   I think the numbered list looks a lot nicer in the terminal output, but
   it's true that there isn't any order. I briefly attempted to understand
   how AsciiDoc's nroff (?) generation works to see if it's possible to make
   unordered lists indent with fewer spaces (2 instead of 4) but I was left
   feeling that nroff/troff/etc are not for mere mortals like me to
   understand.
 * made it clear that "tag v1.0" is not really a refspec, from Junio's
   review

Changes in v2:

 * Say just "The source can be any object." and don't try to educate folks
   further about tags, from Junio's review
 * Mention both exceptions to --force working, from Junio's review
 * Change "local branch or commit being pushed" => "commit being pushed" to
   make it clear that it's just 1 condition, from Junio's review
 * Remove an awkward double colon, from Junio's review
 * Be explicit that creations are always allowed, from Junio's revew

Julia Evans (2):
  doc: git-push: create PUSH RULES section
  doc: git-push: rewrite refspec specification

 Documentation/git-push.adoc | 199 +++++++++++++++++++-----------------
 1 file changed, 103 insertions(+), 96 deletions(-)


base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1973%2Fjvns%2Fclarify-refspec-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1973/jvns/clarify-refspec-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1973

Range-diff vs v1:

 1:  2f2dc22c47 ! 1:  8be0554d02 doc: git-push: create PUSH RULES section
     @@ Documentation/git-push.adoc: allowing a forced update.
      -	to update a remote ref whose current value does not match
      -	what is expected.
      +	Usually, `git push` will refuse to update a branch that is not an
     -+	ancestor of the local branch or commit being pushed.
     ++	ancestor of the commit being pushed.
       +
      -This flag disables these checks, and can cause the remote repository
      -to lose commits; use it with care.
     @@ Documentation/git-push.adoc: reason::
      +Because branches and tags are intended to be used differently, the
      +safety rules for pushing to a branch are different from the rules
      +for pushing to a tag. In the following rules "update" means any
     -+modifications except deletes. Deletions are always allowed, except when
     -+forbidden by configuration or hooks.
     ++modifications except deletions and creations. Deletions and creations
     ++are always allowed, except when forbidden by configuration or hooks.
      +
      +1. If the push destination is a **branch** (`refs/heads/*`): only
     -+   fast-forward updates are allowed: the destination must be an ancestor
     -+   of the source commit. The source must be a commit.
     ++   fast-forward updates are allowed, which means the destination must be
     ++   an ancestor of the source commit. The source must be a commit.
      +2. If the push destination is a **tag** (`refs/tags/*`): all updates will
     -+   be rejected. The source can be any object
     -+   (since commits, trees and blobs can be tagged).
     ++   be rejected. The source can be any object.
      +3. If the push destination is not a branch or tag:
      +   * If the source is a tree or blob object, any updates will be rejected
      +   * If the source is a tag or commit object, any fast-forward update
     @@ Documentation/git-push.adoc: reason::
      +     new tag object which an existing commit points to.
      +
      +You can override these rules by passing `--force` or by adding the
     -+optional leading `+` to a refspec. The only exception to this is that no
     -+amount of forcing will make a branch accept a non-commit object.
     ++optional leading `+` to a refspec. The only exceptions are that no
     ++amount of forcing will make a branch accept a non-commit object,
     ++and forcing won't make the remote repository accept a push that it's
     ++configured to deny.
      +
      +Hooks and configuration can also override or amend these rules,
      +see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes`
 2:  e1b667f645 = 2:  11ad190c3e doc: git-push: rewrite refspec specification

-- 
gitgitgadget

[PATCH v2 1/2] doc: git-push: create PUSH RULES section

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

Right now the rules for when a `git push` is allowed are buried at the
bottom of the description of `<refspec>`. Put them in their own section
so that we can reference them from `--force` and give some context for
why they exist.

Having the "PUSH RULES" section also lets us be a little bit more
specific with the rule in `--force`: we can just focus on the rule
for pushing for a branch (which is likely the one that's most relevant)
and leave the details about what happens when you push to a tag or a ref
that isn't a branch to the later section.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-push.adoc | 94 ++++++++++++++++++-------------------
 1 file changed, 45 insertions(+), 49 deletions(-)

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index d1978650d6..4faf915f94 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -91,48 +91,6 @@ is ambiguous.
   configuration (see linkgit:git-config[1]) suggest what refs/
   namespace you may have wanted to push to.
 
---
-+
-The object referenced by <src> is used to update the <dst> reference
-on the remote side. Whether this is allowed depends on where in
-`refs/*` the <dst> reference lives as described in detail below, in
-those sections "update" means any modifications except deletes, which
-as noted after the next few sections are treated differently.
-+
-The `refs/heads/*` namespace will only accept commit objects, and
-updates only if they can be fast-forwarded.
-+
-The `refs/tags/*` namespace will accept any kind of object (as
-commits, trees and blobs can be tagged), and any updates to them will
-be rejected.
-+
-It's possible to push any type of object to any namespace outside of
-`refs/{tags,heads}/*`. In the case of tags and commits, these will be
-treated as if they were the commits inside `refs/heads/*` for the
-purposes of whether the update is allowed.
-+
-I.e. a fast-forward of commits and tags outside `refs/{tags,heads}/*`
-is allowed, even in cases where what's being fast-forwarded is not a
-commit, but a tag object which happens to point to a new commit which
-is a fast-forward of the commit the last tag (or commit) it's
-replacing. Replacing a tag with an entirely different tag is also
-allowed, if it points to the same commit, as well as pushing a peeled
-tag, i.e. pushing the commit that existing tag object points to, or a
-new tag object which an existing commit points to.
-+
-Tree and blob objects outside of `refs/{tags,heads}/*` will be treated
-the same way as if they were inside `refs/tags/*`, any update of them
-will be rejected.
-+
-All of the rules described above about what's not allowed as an update
-can be overridden by adding an the optional leading `+` to a refspec
-(or using `--force` command line option). The only exception to this
-is that no amount of forcing will make the `refs/heads/*` namespace
-accept a non-commit object. Hooks and configuration can also override
-or amend these rules, see e.g. `receive.denyNonFastForwards` in
-linkgit:git-config[1] and `pre-receive` and `update` in
-linkgit:githooks[5].
-+
 Pushing an empty <src> allows you to delete the <dst> ref from the
 remote repository. Deletions are always accepted without a leading `+`
 in the refspec (or `--force`), except when forbidden by configuration
@@ -145,6 +103,7 @@ the local side, the remote side is updated if a branch of the same name
 already exists on the remote side.
 +
 `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+Not all updates are allowed: see PUSH RULES below for the details.
 
 --all::
 --branches::
@@ -332,14 +291,12 @@ allowing a forced update.
 
 -f::
 --force::
-	Usually, the command refuses to update a remote ref that is
-	not an ancestor of the local ref used to overwrite it.
-	Also, when `--force-with-lease` option is used, the command refuses
-	to update a remote ref whose current value does not match
-	what is expected.
+	Usually, `git push` will refuse to update a branch that is not an
+	ancestor of the commit being pushed.
 +
-This flag disables these checks, and can cause the remote repository
-to lose commits; use it with care.
+This flag disables that check, the other safety checks in PUSH RULES
+below, and the checks in --force-with-lease. It can cause the remote
+repository to lose commits; use it with care.
 +
 Note that `--force` applies to all the refs that are pushed, hence
 using it with `push.default` set to `matching` or with multiple push
@@ -508,6 +465,45 @@ reason::
 	refs, no explanation is needed. For a failed ref, the reason for
 	failure is described.
 
+PUSH RULES
+----------
+
+As a safety feature, the `git push` command only allows certain kinds of
+updates to prevent you from accidentally losing data on the remote.
+
+Because branches and tags are intended to be used differently, the
+safety rules for pushing to a branch are different from the rules
+for pushing to a tag. In the following rules "update" means any
+modifications except deletions and creations. Deletions and creations
+are always allowed, except when forbidden by configuration or hooks.
+
+1. If the push destination is a **branch** (`refs/heads/*`): only
+   fast-forward updates are allowed, which means the destination must be
+   an ancestor of the source commit. The source must be a commit.
+2. If the push destination is a **tag** (`refs/tags/*`): all updates will
+   be rejected. The source can be any object.
+3. If the push destination is not a branch or tag:
+   * If the source is a tree or blob object, any updates will be rejected
+   * If the source is a tag or commit object, any fast-forward update
+     is allowed, even in cases where what's being fast-forwarded is not a
+     commit, but a tag object which happens to point to a new commit which
+     is a fast-forward of the commit the last tag (or commit) it's
+     replacing. Replacing a tag with an entirely different tag is also
+     allowed, if it points to the same commit, as well as pushing a peeled
+     tag, i.e. pushing the commit that existing tag object points to, or a
+     new tag object which an existing commit points to.
+
+You can override these rules by passing `--force` or by adding the
+optional leading `+` to a refspec. The only exceptions are that no
+amount of forcing will make a branch accept a non-commit object,
+and forcing won't make the remote repository accept a push that it's
+configured to deny.
+
+Hooks and configuration can also override or amend these rules,
+see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes`
+in linkgit:git-config[1] and `pre-receive` and `update` in
+linkgit:githooks[5].
+
 NOTE ABOUT FAST-FORWARDS
 ------------------------
 
-- 
gitgitgadget

[PATCH v2 2/2] doc: git-push: rewrite refspec specification

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

From user feedback, there was a request for examples, as well as a
comment that one person found "If git push [<repository>] without
any <refspec> argument is set to update some ref at the destination
with <src> with remote.<repository>.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 <julia@jvns.ca>
---
 Documentation/git-push.adoc | 105 ++++++++++++++++++++----------------
 1 file changed, 58 insertions(+), 47 deletions(-)

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 4faf915f94..ff125297b0 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -55,54 +55,65 @@ OPTIONS[[OPTIONS]]
 
 <refspec>...::
 	Specify what destination ref to update with what source object.
-	The format of a <refspec> parameter is an optional plus
-	`+`, followed by the source object <src>, followed
-	by a colon `:`, followed by the destination ref <dst>.
-+
-The <src> 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 <dst> 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 [<repository>]` without any `<refspec>` argument is set to
-update some ref at the destination with `<src>` with
-`remote.<repository>.push` configuration variable, `:<dst>` part can
-be omitted--such a push will update a ref that `<src>` normally updates
-without any `<refspec>` on the command line.  Otherwise, missing
-`:<dst>` means to update the same ref as the `<src>`.
-+
-If <dst> doesn't start with `refs/` (e.g. `refs/heads/master`) we will
-try to infer where in `refs/*` on the destination <repository> it
-belongs based on the type of <src> being pushed and whether <dst>
-is ambiguous.
 +
---
-* If <dst> unambiguously refers to a ref on the <repository> remote,
-  then push to that ref.
-
-* If <src> resolves to a ref starting with refs/heads/ or refs/tags/,
-  then prepend that to <dst>.
-
-* 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 <src> allows you to delete the <dst> 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 <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+The format for a refspec is [+]<src>[:<dst>], for example `main`,
+`main:other`, or `HEAD^:refs/heads/main`.
++
+The `<src>` is often the name of the local branch to push, but it can be
+any arbitrary "SHA-1 expression" (see linkgit:gitrevisions[7]).
++
+The `<dst>` 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:
++
+ *  `<src>` without a `:<dst>` means to update the same ref as the
+    `<src>`, unless the `remote.<repository>.push` configuration specifies a
+    different <dst>. For example, if `main` is a branch, then the refspec
+    `main` expands to `main:refs/heads/main`.
+ *  If `<dst>` unambiguously refers to a ref on the <repository> 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 `<src>` resolves to a ref starting with `refs/heads/` or `refs/tags/`,
+    then prepend that to <dst>. 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.
+ *  <src> 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 `<src>` and `<dst>`.
+    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 `<src>`.
+    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 `<src>` is empty, it deletes the `<dst>` ref from the remote
+    repository. For example, `git push origin :dev` will
+    delete the `dev` branch.
+ *  `tag <tag>` expands to `refs/tags/<tag>:refs/tags/<tag>`.
+	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::
-- 
gitgitgadget

Re: [PATCH v2 0/2] doc: git-push: clarify section

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> This is a continuation of the changes to git push, from
> https://lore.kernel.org/git/pull.1964.git.1756240823.gitgitgadget@gmail.com/
> . These changes to the refspec section got kind of big so I'm moving them
> into a separate topic.

It is somewhat awkward to have two outstanding sets of patches to
the same file under the same theme from the same author.  How would
this relate to the other "git push documentation" topic?

Thanks.

Re: [PATCH v2 0/2] doc: git-push: clarify section

[Julia Evans]

> It is somewhat awkward to have two outstanding sets of patches to
> the same file under the same theme from the same author.  How would
> this relate to the other "git push documentation" topic?

I split this one out because they were logically separate and I was concerned that
together they were becoming unmanageable. 

Happy to re-combine them if you'd prefer.

> Thanks.

Re: [PATCH v2 0/2] doc: git-push: clarify section

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

>> It is somewhat awkward to have two outstanding sets of patches to
>> the same file under the same theme from the same author.  How would
>> this relate to the other "git push documentation" topic?
>
> I split this one out because they were logically separate and I was concerned that
> together they were becoming unmanageable. 

Oh as long as they can independently advance and join cleanly, it is
fine.  It would be easier on the reviewers to keep each of them
small.

Thanks.

Re: [PATCH v2 0/2] doc: git-push: clarify section

[Junio C Hamano]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> I don't love the nested list in PUSH RULES but the sentence starting with
> "If the source is a tag or commit object..." is really a tough one to read,
> it's not going to be relevant to the vast majority of people, and I think
> keeping it contained inside a bullet point will make it much easier to skip
> over to get to later information which is more likely to be relevant to
> folks.
> ...
> Changes in v2:
>
>  * Say just "The source can be any object." and don't try to educate folks
>    further about tags, from Junio's review
>  * Mention both exceptions to --force working, from Junio's review
>  * Change "local branch or commit being pushed" => "commit being pushed" to
>    make it clear that it's just 1 condition, from Junio's review
>  * Remove an awkward double colon, from Junio's review
>  * Be explicit that creations are always allowed, from Junio's revew

Nothing questionable stood out during my re-read of these two
patches.

Further comments from other reviewers are always welcome, but we
find needs for immediate improvements, let's mark the topic for
'next'.  Thanks.