From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 4/4] doc: git-push: rewrite refspec specification
Date: Wed, 27 Aug 2025 09:10:28 -0400 [thread overview]
Message-ID: <15c8cf10-e1a1-404a-8a99-d2aab098104a@app.fastmail.com> (raw)
In-Reply-To: <xmqqsehdfyho.fsf@gitster.g>
>> +`:<dst>` is optional.
>
> It may be technically true, but I am not sure if it is a good idea
> to say it here. Without "when missing, <dst> is inferred with these
> rules", saying just "is optional" naturally invites a puzzlement:
> when do we need to supply it and for what?
>
> As you are going to say what happens when you omit it very soon, and
> you already have said with [:<dst>] that it is optional, perhaps you
> can scratch this sentence.
The reason I mentioned this early on is that when I read this for the first time
it was quite confusing. Since `main` (or another branch name on its own) was
the only push refspec I had experience using, it was disorienting to be told
that the format was `<src>:<dst>`. It made me wonder if maybe `main` was not a
refspec after all and I'd misunderstood the SYNOPSIS.
I know that I'm not alone in this: it's very common for Git users (even very
experienced ones!) to learn the form `git push origin main`, but to
otherwise not be familiar at all with the concept of a "refspec".
So I'd like to do something here to help those folks connect their
existing knowledge to the broader concept of a "refspec".
That said `:<dst> is optional` may not be necessary: I think the examples
here accomplish more or less the same thing.
>> +The format for a refspec is [+]<src>[:<dst>], for example `main`,
> > +`main:other`, or `HEAD^:refs/heads/main`.
>> +`+` is optional and does the same thing as `--force`.
>
> Ditto; this one is less bad than the :<dst> thing, because at least
> it tells us what it means. But we are going to talk about when an
> update is not allowed (we haven't even hinted that some updates may
> not be allowed yet) much later, "the same as `--force`" is probably
> a bit premature at this point in the documentation.
The reason I mentioned this so early is similar -- It's very common
for experienced users to be familiar with the `--force` option, and
so this is a quick way to explain to them what the `+` does.
As an aside, I noticed while reading this that it looks like
the description of `--force` right now is not quite accurate,
since the rule about pushing to tags is not "it must be
an ancestor".
>--force::
> Usually, the command refuses to update a remote ref that is
> not an ancestor of the local ref used to overwrite it.
I'm going to think about whether there's a way to format the
"rules for updates" so that they can be referred to from the `--force`
section. Or maybe just move them to the `--force` option, and refer
people there if they want to understand exactly when `--force`
is required.
It's certainly much more common for users to use `--force` to force
a push than to use `+`, from that perspective it would make more
sense to document the rules next to `--force` than next to the
description of `+`.
>> +You can write a refspec using the fully expanded form (for
>> +example `main:refs/heads/main`) which specifies the exact source
>
> This example is not fully expanded. refs/heads/main:refs/heads/main
> would be, though.
Makes sense, will change.
> I am not sure it is easier to read with numbered list. It is not
> like these rules are applied in this order, or anything like that,
> right?
I had a similar concern. I'm still trying to figure out how to manage
unordered lists, since lists with a `*` are formatted by AsciiDoc in a
weird way in the terminal: there's a tab character after the • character
which I don't understand the reason for.
> A tangent.
> Is this a refspec you can write in .git/config, e.g.
>
> [remote "origin"]
> push = tag v1.0"
>
> If not, it might be easier to explain if we tweaked the command line
> synopsis to say that the command takes, after the destination
> repository, zero or more refspec or "tag <tag>". I dunno.
I checked and it's not a valid refspec:
$ git push
fatal: invalid refspec 'tag v1.0'
This list seems like a more natural place for that information than the
synopsis though: the synopsis is already quite hard to read and we
can't use it as the only place to communicate that information.
I can add a note to say that 'tag v1.0' is technically not a refspec.
Git already has enough weird exceptions like that that I don't think
it'll be too jarring.
> Perhaps move it down together with the "push void to remove"
> at the top of the list?
I'll also move it down.
> Good. Somehow we have added the description of these to "git fetch"
> side, without updating "git push" side of the documentation.
Yes, I copied this part from the `git fetch` documention after checking
that they worked with `git push` as well.
>> + Deletions are always accepted without a leading `+` in the
>> + refspec (or `--force`), except when forbidden by configuration or hooks.
>
> This can be read in two ways, making two opposing answers to this
> question possible: when forbidden, can you make a deletion accepted
> by giving a `+` in front?
> "except when forbidden, deletions are accepted with or without `+`"
> might be less confusion-prone, but I dunno. I just wanted to make
> sure that it is clear that forcing or prepending `+` would not
> change anything when forbidden by configuration or hooks on the
> remote end.
>
> But because you haven't mentioned that not all updates are allowed,
> this might be a bit out of place in this list. How about limiting
> this bullet point to only say that this is the syntax to use to
> delete a ref from the remote, and move the "deletions do not have to
> be forced and operations forbidden at the remote cannot be forced
> anyway" down, near the "Not all updates are allowed" below ...
Will do, that's much cleaner.
>> + See `receive.denyDeletes` in linkgit:git-config[1] and `pre-receive` and
>> + `update` in linkgit:githooks[5].
>
> ... together with this?
This makes sense.
- Julia
next prev parent reply other threads:[~2025-08-27 13:12 UTC|newest]
Thread overview: 87+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-26 20:40 [PATCH 0/4] doc: git-push: clarify DESCRIPTION section & refspec definition Julia Evans via GitGitGadget
2025-08-26 20:40 ` [PATCH 1/4] doc: git-push: update intro Julia Evans via GitGitGadget
2025-08-28 13:53 ` D. Ben Knoble
2025-08-28 16:18 ` Junio C Hamano
2025-08-29 7:20 ` Kristoffer Haugsbakk
2025-08-28 17:47 ` Julia Evans
2025-08-28 19:39 ` D. Ben Knoble
2025-08-26 20:40 ` [PATCH 2/4] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-08-27 0:05 ` Junio C Hamano
2025-08-26 20:40 ` [PATCH 3/4] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-08-26 23:57 ` Junio C Hamano
2025-08-27 13:52 ` Julia Evans
2025-08-28 14:25 ` D. Ben Knoble
2025-08-26 20:40 ` [PATCH 4/4] doc: git-push: rewrite refspec specification Julia Evans via GitGitGadget
2025-08-26 23:34 ` Junio C Hamano
2025-08-27 13:10 ` Julia Evans [this message]
2025-08-28 19:28 ` D. Ben Knoble
2025-09-12 18:55 ` [PATCH v2 0/4] doc: git-push: clarify DESCRIPTION section & refspec definition Julia Evans via GitGitGadget
2025-09-12 18:55 ` [PATCH v2 1/4] doc: git-push: clarify intro Julia Evans via GitGitGadget
2025-09-12 20:54 ` Junio C Hamano
2025-09-15 20:00 ` Julia Evans
2025-09-16 1:44 ` Junio C Hamano
2025-09-16 18:46 ` Julia Evans
2025-09-16 20:38 ` Ben Knoble
2025-09-16 21:59 ` Junio C Hamano
2025-09-17 18:42 ` Junio C Hamano
2025-09-18 14:20 ` Julia Evans
2025-09-12 18:55 ` [PATCH v2 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Julia Evans via GitGitGadget
2025-09-12 21:17 ` Junio C Hamano
2025-09-15 20:19 ` Julia Evans
2025-09-15 21:48 ` Junio C Hamano
2025-09-15 23:09 ` Julia Evans
2025-09-16 5:25 ` Junio C Hamano
2025-09-16 5:33 ` Junio C Hamano
2025-09-16 5:39 ` Junio C Hamano
2025-09-18 21:02 ` Julia Evans
2025-09-12 18:55 ` [PATCH v2 3/4] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-09-12 21:18 ` Junio C Hamano
2025-09-12 21:19 ` Junio C Hamano
2025-09-15 20:52 ` Julia Evans
2025-09-12 18:55 ` [PATCH v2 4/4] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 1/4] doc: git-push: clarify intro Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Julia Evans via GitGitGadget
2025-09-24 19:51 ` Junio C Hamano
2025-09-30 19:20 ` Julia Evans
2025-09-23 17:44 ` [PATCH v3 3/4] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 4/4] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-09-24 20:01 ` Junio C Hamano
2025-09-25 20:50 ` Julia Evans
2025-09-25 21:15 ` Junio C Hamano
2025-09-25 22:34 ` Julia Evans
2025-09-26 1:27 ` Junio C Hamano
2025-09-26 15:29 ` Junio C Hamano
2025-09-26 17:31 ` Julia Evans
2025-09-26 19:03 ` Junio C Hamano
2025-09-26 22:27 ` Julia Evans
2025-09-26 23:07 ` Junio C Hamano
2025-09-28 21:38 ` D. Ben Knoble
2025-09-23 17:56 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section D. Ben Knoble
2025-09-30 19:58 ` [PATCH v4 0/5] " Julia Evans via GitGitGadget
2025-09-30 19:58 ` [PATCH v4 1/5] doc: git-push: clarify intro Julia Evans via GitGitGadget
2025-09-30 19:58 ` [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Julia Evans via GitGitGadget
2025-09-30 23:39 ` Junio C Hamano
2025-10-03 18:23 ` Julia Evans
2025-10-03 19:12 ` Junio C Hamano
2025-10-01 17:30 ` Jean-Noël AVILA
2025-10-03 17:54 ` Julia Evans
2025-09-30 19:58 ` [PATCH v4 3/5] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-09-30 19:58 ` [PATCH v4 4/5] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-09-30 21:01 ` Junio C Hamano
2025-10-01 17:36 ` Jean-Noël AVILA
2025-09-30 19:58 ` [PATCH v4 5/5] doc: git-push: Add explanation of `git push origin main` Julia Evans via GitGitGadget
2025-10-01 22:29 ` D. Ben Knoble
2025-10-03 17:58 ` Julia Evans
2025-10-01 22:28 ` [PATCH v4 0/5] doc: git-push: clarify DESCRIPTION section D. Ben Knoble
2025-10-06 18:58 ` [PATCH v5 " Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 1/5] doc: git-push: clarify intro Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Julia Evans via GitGitGadget
2025-10-07 12:23 ` Kristoffer Haugsbakk
2025-10-07 13:35 ` Julia Evans
2025-10-07 18:35 ` D. Ben Knoble
2025-10-06 18:58 ` [PATCH v5 3/5] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 4/5] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 5/5] doc: git-push: Add explanation of `git push origin main` Julia Evans via GitGitGadget
2025-10-06 21:53 ` [PATCH v5 0/5] doc: git-push: clarify DESCRIPTION section D. Ben Knoble
2025-10-06 22:07 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=15c8cf10-e1a1-404a-8a99-d2aab098104a@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox