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

From: "brian m. carlson" <[email-masked]>
Date: Fri, 19 Sep 2025 00:39:12 +0000

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/[email-masked]/
> . 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