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

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Sep 19, 2025, 00:39 UTC
Message-ID: <aMymMLkJg7PkmxL7@fruit.crustytoothpaste.net>
In-Reply-To: <pull.1973.git.1758144815.gitgitgadget@gmail.com>

On 2025-09-17 at 21:33:33, Julia Evans via GitGitGadget wrote:

Show 30 quoted lines

> 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