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

["Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>]

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