[PATCH v2 0/5] doc: git-rebase: clarify DESCRIPTION section

Thanks for the review comments, here are the new changes which:

 * make the intro to the man page less dry, with the suggested wording
 * clarify the merge conflict resolution explanation & fix the HTML
   formatting issues
 * move the explanation of the git rebase <upstream> <branch> syntax up into
   the intro

I'm still curious about the intention for the git rebase master topic syntax, since I'd never heard of it before. Is it just to save on typing, since it's fewer characters than git switch topic and then git rebase master? I ask because someone mentioned to me on Mastodon (https://hachyderm.io/@simontatham/114988051822317920) that they sometimes use git rebase HEAD main as part of their workflow, which is not equivalent to git checkout main && git rebase HEAD. That made me think that there might be some broader intent to enable rebases that wouldn't otherwise be possible without that syntax.

I'll wrap my text to 80 characters in the future, still learning the process for emailing a plain-text mailing list :)

Julia Evans (5):
  doc: git-rebase: start with an example
  doc: git rebase: dedup merge conflict discussion
  doc: git rebase: clarify arguments syntax
  doc: git-rebase: move --onto explanation down
  doc: git-rebase: update discussion of internals

 Documentation/git-rebase.adoc | 285 ++++++++++++++++------------------
 1 file changed, 137 insertions(+), 148 deletions(-)

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

Range-diff vs v1:

 1:  ac3a91c04bf ! 1:  26b742eb49f doc: git-rebase: start with an example
     @@ Documentation/git-rebase.adoc: SYNOPSIS
       -----------
      +Transplant a series of commits onto a different starting point.
      +
     -+For example, assume the following history exists and the current branch is `topic`:
     ++For example, imagine that you have been working on the `topic` branch in this
     ++history, and you want to "catch up" to the work done on the `master` branch.
      +
      +------------
      +          A---B---C topic
     @@ Documentation/git-rebase.adoc: SYNOPSIS
      +    D---E---F---G master
      +------------
      +
     -+Then `git rebase master` will find all of the commits since `topic` diverged
     -+from `master` and copy the changes in each of those commits on top of the
     -+`master` branch.
     ++You want to transplant the commits you made on `topic` since it diverged from
     ++`master` (i.e. A, B, and C), on top of the current `master`.  You can do this
     ++by running `git rebase master` while the `topic` branch is checked out.  If you
     ++want to rebase `topic` while on another branch, `git rebase master topic` is a
     ++short-cut for `git switch topic && git rebase master`.
      +
      +------------
      +                  A'--B'--C' topic
 2:  f4f0a5a1172 ! 2:  249a5127904 doc: git rebase: dedup merge conflict discussion
     @@ Commit message
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## Documentation/git-rebase.adoc ##
     -@@ Documentation/git-rebase.adoc: from `master` and copy the changes in each of those commits on top of the
     +@@ Documentation/git-rebase.adoc: short-cut for `git switch topic && git rebase master`.
           D---E---F---G master
       ------------
       
      +If there is a merge conflict during this process, `git rebase` will stop at the
     -+first problematic commit and leave conflict markers. If this happens, you can:
     ++first problematic commit and leave conflict markers. If this happens, you can do
     ++one of these things:
      +
      +1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<)
      +   and make edits to resolve the conflict. For each file you edit, you need to
     -+   tell Git that the conflict has been resolved. Typically this would be
     -+   done with
     -+
     -+   git add <filename>
     -+
     -+   You can then continue the rebasing process with
     ++   tell Git that the conflict has been resolved. You can mark the conflict as
     ++   resolved with  `git add <filename>`. After resolving all of the conflicts,
     ++   you can continue the rebasing process with
      +
      +   git rebase --continue
      +
 3:  b27117ea19a ! 3:  ce7ab74ea0f doc: git rebase: clarify arguments syntax
     @@ Metadata
       ## Commit message ##
          doc: git rebase: clarify arguments syntax
      
     -    I found this extremely hard to understand as it was and this seemed like
     -    a clearer wording to me.
     +    This removes the explanation of `git rebase <upstream> <branch>`, since
     +    it was already explained above that it's shorthand for `git switch
     +    <branch> && git rebase <upstream>`
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## Documentation/git-rebase.adoc ##
     -@@ Documentation/git-rebase.adoc: first problematic commit and leave conflict markers. If this happens, you can:
     +@@ Documentation/git-rebase.adoc: one of these things:
       
          git rebase --skip
       
     -+`git rebase <upstream> <branch>` is shorthand for `git switch <branch>`
     -+followed by `git rebase <upstream>`.
     - 
     +-
      -If `<branch>` is specified, `git rebase` will perform an automatic
      -`git switch <branch>` before doing anything else.  Otherwise
      -it remains on the current branch.
 4:  28b00d3b32f = 4:  590d7486d3d doc: git-rebase: move --onto explanation down
 5:  7d4dc6d2c04 = 5:  ad97cd9e671 doc: git-rebase: update discussion of internals