[PATCH v5 0/5] 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

changes in v4:

 * Add "the simplest way to push is git push <remote> <branch>" at the
   beginning since (as discussed) this is the form of git push that's
   easiest to explain.
 * Remove "as a safety measure" since (as discussed with Junio) the reason
   that git push sometimes requires you to set an upstream is very
   confusing, and "as a safety measure..." makes it sound more principled
   than it is. Also update the commit message to say that the previous
   explanation was not describing push.default=simple's behaviour
   accurately.
 * Reword "To decide which repository to push to..." because I felt like it
   was still phrased in a clunky way.
 * Make UPSTREAM BRANCHES and CONFIGURATION into actual links in the HTML
   docs
 * Fix formatting in UPSTREAM BRANCHES section, from Junio's review
 * Fix some commit message mistakes, from Junio's review

changes in v5:

 * remove a bad example of git branch --track, from Junio's review
 * fix some formatting issues, from Jean-Noël's review

Julia Evans (5):
  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"
  doc: git-push: Add explanation of `git push origin main`

 Documentation/git-push.adoc     | 46 +++++++++++++++++++--------------
 Documentation/urls-remotes.adoc | 42 ++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 20 deletions(-)

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

Range-diff vs v4:

 1:  d3160fb0af = 1:  4811ce1c86 doc: git-push: clarify intro
 2:  69825d4634 ! 2:  10a9718421 doc: add an UPSTREAM BRANCHES section to pull/push/fetch
     @@ Documentation/urls-remotes.adoc: git push uses:
       ------------
       
       
     --
     --
     -+UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
     -+--------------------------------------
     ++[[UPSTREAM-BRANCHES]]
     ++UPSTREAM BRANCHES
     ++-----------------
      +
      +Branches in Git can optionally have an upstream remote branch.
      +Git defaults to using the upstream branch for remote operations, for example:
     @@ Documentation/urls-remotes.adoc: git push uses:
      +
      +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`,
     ++`git push --set-upstream <remote> <branch>`
      +but Git will often automatically set the upstream for you, for example:
      +
      +* When you clone a repository, Git will automatically set the upstream
 3:  244c35ef2b = 3:  336023fbf1 doc: git-push: clarify "where to push"
 4:  c1d4ea8d27 ! 4:  8e82c508f6 doc: git-push: clarify "what to push"
     @@ Documentation/git-push.adoc: a `git gc` command on the origin repository.
       
       include::transfer-data-leaks.adoc[]
       
     --CONFIGURATION
     -+CONFIGURATION[[CONFIGURATION]]
     ++[[CONFIGURATION]]
     + CONFIGURATION
       -------------
       
     - include::includes/cmd-config-section-all.adoc[]
 5:  9435f0ce8d = 5:  ddeb8ecabe doc: git-push: Add explanation of `git push origin main`