[PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section

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.

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.

changes in v3:

 * mention that git push also needs to send data in addition to updating the
   branch, from Junio's review
 * fix a newline, from Junio's review
 * un-rename urls-remotes.adoc, from Junio's review
 * mention pushRemote and git checkout in the UPSTREAM BRANCHES section and
   be clearer about what's meant by "the relationship between the current
   branch and the upstream", from Junio's review
 * fix AsciiDoc formatting issue, from Junio's review

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-push.adoc     | 43 +++++++++++++++++---------------
 Documentation/urls-remotes.adoc | 44 ++++++++++++++++++++++++++++++---
 2 files changed, 64 insertions(+), 23 deletions(-)

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

Range-diff vs v2:

 1:  270edd2b00 ! 1:  2870c77e80 doc: git-push: clarify intro
     @@ Documentation/git-push.adoc: SYNOPSIS
      -every time you push into it, by setting up 'hooks' there.  See
      -documentation for linkgit:git-receive-pack[1].
      +Updates one or more branches, tags, or other references in a remote
     -+repository from your local repository.
     ++repository from your local repository, and sends all necessary data
     ++that isn't already on the remote.
       
       When the command line does not specify where to push with the
       `<repository>` argument, `branch.*.remote` configuration for the
     @@ Documentation/git-push.adoc: corresponding upstream branch, but as a safety meas
      +You can make interesting things happen to a repository
      +every time you push into it, by setting up 'hooks' there.  See
      +documentation for linkgit:git-receive-pack[1].
     ++
       
       OPTIONS[[OPTIONS]]
       ------------------
 2:  0ec629d403 ! 2:  3ecfb5c3a6 doc: add an UPSTREAM BRANCHES section to pull/push/fetch
     @@ Commit message
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     - ## Documentation/git-fetch.adoc ##
     -@@ Documentation/git-fetch.adoc: include::pull-fetch-param.adoc[]
     - 	Read refspecs, one per line, from stdin in addition to those provided
     - 	as arguments. The "tag <name>" format is not supported.
     - 
     --include::urls-remotes.adoc[]
     -+include::urls-remotes-upstreams.adoc[]
     - 
     - 
     - CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
     -
     - ## Documentation/git-pull.adoc ##
     -@@ Documentation/git-pull.adoc: include::fetch-options.adoc[]
     - 
     - include::pull-fetch-param.adoc[]
     - 
     --include::urls-remotes.adoc[]
     -+include::urls-remotes-upstreams.adoc[]
     - 
     - include::merge-strategies.adoc[]
     - 
     -
     - ## Documentation/git-push.adoc ##
     -@@ Documentation/git-push.adoc: further recursion will occur. In this case, "only" is treated as "on-demand".
     - --ipv6::
     - 	Use IPv6 addresses only, ignoring IPv4 addresses.
     - 
     --include::urls-remotes.adoc[]
     -+include::urls-remotes-upstreams.adoc[]
     - 
     - OUTPUT
     - ------
     -
     - ## Documentation/urls-remotes.adoc => Documentation/urls-remotes-upstreams.adoc ##
     -@@ Documentation/urls-remotes-upstreams.adoc: git push uses:
     + ## Documentation/urls-remotes.adoc ##
     +@@ Documentation/urls-remotes.adoc: git push uses:
       	HEAD:refs/heads/<head>
       ------------
       
     @@ Documentation/urls-remotes-upstreams.adoc: git push uses:
      +Git defaults to using the upstream branch for remote operations, for example:
      +
      +* It's the default for `git pull` or `git fetch` with no arguments
     -+* It's sometimes the default for `git push` with no arguments. See the
     -+  `push.default` section of linkgit:git-config[1] for the details.
     -+* `git status` and `git branch -v` will show the
     -+  relationship between the current branch and the upstream,
     -+  for example "Your branch is up to date with origin/main"
     ++* It's the default for `git push` with no arguments, with some exceptions.
     ++  For example, you can use the `branch.<name>.pushRemote` option to push
     ++  to a different remote than you pull from, and by default with
     ++  `push.default=simple` the upstream branch you configure must have
     ++  the same name.
     ++* Various commands, including `git checkout` and `git status`, will
     ++  show you how many commits have been added to your current branch and
     ++  the upstream since you forked from it, for example "Your branch and
     ++  'origin/main' have diverged, and have 2 and 3 different commits each
     ++  respectively"
      +
      +The upstream is stored in `.git/config`, in the "remote" and "merge"
      +fields. For example, if `main`'s upstream is `origin/main`:
      +
     -+```
     -+[branch "main"]
     -+   remote = origin
     -+   merge = refs/heads/main
     -+```
     ++	[branch "main"]
     ++	   remote = origin
     ++	   merge = refs/heads/main
      +
      +You can set an upstream branch explicitly with
      +`git push --set-upstream <remote> <branch>` or `git branch --track`,
 3:  374740c678 ! 3:  bfd6072983 doc: git-push: clarify "where to push"
     @@ Commit message
          doc: git-push: clarify "where to push"
      
          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"
     +    "where to push"), and start with a positive "try X, then Y, then Z"
          instead of a negative ("if X is not specified..").
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## Documentation/git-push.adoc ##
     -@@ Documentation/git-push.adoc: DESCRIPTION
     - Updates one or more branches, tags, or other references in a remote
     - repository from your local repository.
     +@@ Documentation/git-push.adoc: Updates one or more branches, tags, or other references in a remote
     + repository from your local repository, and sends all necessary data
     + that isn't already on the remote.
       
      -When the command line does not specify where to push with the
      -`<repository>` argument, `branch.*.remote` configuration for the
 4:  59732f1e47 = 4:  be6453d010 doc: git-push: clarify "what to push"