[PATCH v2 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.

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