[PATCH v2 0/4] doc: git-push: clarify DESCRIPTION section & refspec definition

I surveyed 16 Git users about the git push man page. Here's a rewrite of the DESCRIPTION section and the definition of <refspec> based on the feedback. The goal is to clarify it while communicating the same information. The most common piece of feedback was that folks didn't understand what the term "ref" means. Most of the users who said they did not understand the term "ref" have been using Git for 10+ years.

The rewrite of the <refspec> section is more invasive than I usually prefer: I've tried to keep as much of the original text as possible, but if there are too many issues with it then I'll drop that patch from this series.

changes in v2:

 * The biggest change is to add a new UPSTREAM BRANCHES section to explain
   what an upstream is
 * Drop the "refspec" changes from this patch series, I've made revisions to
   them based on the comments here but I felt like this was getting too big.
 * Added some backticks `` that I'd missed, from Ben's review
 * From Junio's review, "The current branch must have a configured upstream
   with the same name, so this will fail when pushing a new branch" was not
   true, so replace it with a less detailed but hopefully true statement.
   After a very long conversation with Ben I realized that actually
   push.default=simple's behaviour is not really that simple (perhaps I
   should think of it as more "safe" than "simple", since "current" seems
   simpler), so it's more realistic to refer any questions to the
   CONFIGURATION section which describes the behaviour in more detail.
 * Rewrite all the commits to explain the problem they're trying to solve &
   thinking behind them in more detail. Let me know if I added too much /
   not enough detail.

Julia Evans (4):
  doc: git-push: clarify intro
  doc: add an UPSTREAM BRANCHES section to pull/push/fetch
  doc: git-push: clarify "where to push"
  doc: git-push: clarify "what to push"

 Documentation/git-fetch.adoc                  |  2 +-
 Documentation/git-pull.adoc                   |  2 +-
 Documentation/git-push.adoc                   | 43 ++++++++++---------
 ...motes.adoc => urls-remotes-upstreams.adoc} | 41 ++++++++++++++++--
 4 files changed, 62 insertions(+), 26 deletions(-)
 rename Documentation/{urls-remotes.adoc => urls-remotes-upstreams.adoc} (63%)

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1964

Range-diff vs v1:

 1:  2fa98fb5ca ! 1:  270edd2b00 doc: git-push: update intro
     @@ Metadata
      Author: Julia Evans <julia@jvns.ca>
      
       ## Commit message ##
     -    doc: git-push: update intro
     +    doc: git-push: clarify intro
      
     -    - Users don't understand what a "ref" is, expand it
     -    - Remove "complete the given refs" (that phrase is confusing to many
     -      users, and it's obvious that pushing a branch involves sending the
     -      new code)
     -    - Move down the reference to hooks, it's less important than the
     -      command's basic usage
     +    From user feedback, 5 users are unsure what "ref" and/or "objects" means
     +    in this context. 3 users said they don't know what "complete the refs"
     +    means.
     +
     +    Many users also commented that receive hooks do not seem like the most
     +    important thing to know about `git push`, and that this information
     +    should not be the second sentence in the man page.
     +
     +    Use more familiar language to make it more accessible to users who do
     +    not know what a "ref" is and move the "hooks" comment to the end.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
 -:  ---------- > 2:  0ec629d403 doc: add an UPSTREAM BRANCHES section to pull/push/fetch
 2:  36112c30bc ! 3:  374740c678 doc: git-push: clarify "where to push"
     @@ Metadata
       ## Commit message ##
          doc: git-push: clarify "where to push"
      
     -    Signed-off-by: Julia Evans <julia@jvns.ca>
     -
          Be clearer about what we're describing ("which repository" instead of
          "what to push"), and start with a positive "try X, then Y, then Z"
          instead of a negative ("if X is not specified..").
     @@ Documentation/git-push.adoc: DESCRIPTION
      -configuration is missing, it defaults to 'origin'.
      +To decide which repository to push to, Git uses the `<repository>`
      +argument (for example `git push dev`), then if that's not specified the
     -+`branch.*.remote` configuration for the current branch, and then defaults
     ++upstream configuration for the current branch, and then defaults
      +to `origin`.
       
       When the command line does not specify what to push with `<refspec>...`
 3:  ac554cbe75 ! 4:  59732f1e47 doc: git-push: clarify "what to push"
     @@ Metadata
       ## Commit message ##
          doc: git-push: clarify "what to push"
      
     -    - Be more explicit about what we're describing ("which branches" instead
     -      of "what to push")
     -    - Split out the ways to specify which branches into a numbered list,
     -      since there are 5 different ways to specify it and it's a lot to parse
     -      in paragraph form
     -    - The explanation of "push.default=simple" is confusing to some users,
     -      use an explanation more similar to the one in `man git-config`
     -    - Mention the most common case where push.default=simple is likely to
     -      fail, and how to handle it
     +    From user feedback: 6 users says they found the "what to push"
     +    paragraphs confusing, for many different reasons, including:
     +
     +    * what does "..." in <refspec>... mean?
     +    * "consult XXX configuration" is hard to parse
     +    * it refers to the `git-config` man page even though the config
     +      information for `git push` is included in this man page under
     +      CONFIGURATION
     +    * the default ("push to a branch with the same name") is what they use
     +      99% of the time, they would have expected it to appear earlier instead
     +      of at the very end
     +    * not understanding what the term "upstream" means in Git
     +      ("are branches tracked by some system besides their names?"")
     +
     +    Address all of these by using a numbered "in order of precedence" list
     +    (similar to the previous commit), by giving a little bit of context
     +    around "upstream branch": it's something that you may have to set
     +    explicitly, and referring to the new UPSTREAM BRANCHES section.
     +
     +    The default behaviour is still discussed pretty late but it should be
     +    easier to skim now to get to the relevant information.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## Documentation/git-push.adoc ##
      @@ Documentation/git-push.adoc: argument (for example `git push dev`), then if that's not specified the
     - `branch.*.remote` configuration for the current branch, and then defaults
     + upstream configuration for the current branch, and then defaults
       to `origin`.
       
      -When the command line does not specify what to push with `<refspec>...`
     @@ Documentation/git-push.adoc: argument (for example `git push dev`), then if that
      -the default `<refspec>` by consulting `remote.*.push` configuration,
      -and if it is not found, honors `push.default` configuration to decide
      -what to push (See linkgit:git-config[1] for the meaning of `push.default`).
     -+To decide which branches, tags, or other refs to push, Git uses
     -+(in order of precedence):
     -+
     -+1. The <refspec> argument(s) (for example `main` in `git push origin main`)
     -+   or the `--all`, `--mirror`, or `--tags` options
     -+2. The `remote.*.push` configuration for the current branch
     -+3. The `push.default` configuration (See linkgit:git-config[1] for
     -+   the meaning of `push.default`).
     - 
     - When neither the command-line nor the configuration specifies what to
     +-
     +-When neither the command-line nor the configuration specifies what to
      -push, the default behavior is used, which corresponds to the `simple`
      -value for `push.default`: the current branch is pushed to the
      -corresponding upstream branch, but as a safety measure, the push is
      -aborted if the upstream branch does not have the same name as the
      -local one.
     -+push, the current branch is pushed to the branch with the same name
     -+on the remote. The current branch must have a configured upstream with
     -+the same name, so this will fail when pushing a new branch.
     -+You can run `git push -u <repository> <current-branch>`
     -+to configure the upstream.
     ++To decide which branches, tags, or other refs to push, Git uses
     ++(in order of precedence):
     ++
     ++1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
     ++   or the `--all`, `--mirror`, or `--tags` options
     ++2. The `remote.*.push` configuration for the repository being pushed to
     ++3. The `push.default` configuration. The default is `push.default=simple`,
     ++   which will push to a branch with the same name as the current branch.
     ++   See the CONFIGURATION section below for more on `push.default`.
     ++
     ++As a safety measure, `git push` may fail if you haven't set an upstream
     ++for the current branch, depending on what `push.default` is set to.
     ++See the UPSTREAM BRANCHES section below for more on how to set and
     ++use upstreams.
       
       You can make interesting things happen to a repository
       every time you push into it, by setting up 'hooks' there.  See
 4:  72114133aa < -:  ---------- doc: git-push: rewrite refspec specification