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

 * move "You can also use git rebase to reorder or combine commits:" to the
   beginning
 * replace "detailed description" with "simplified description" -- I thought
   that I could write something that was relatively readable and also
   accurate, but as usual Git has proven me wrong :). I tried to leave in
   the details that I think seem relevant to using git: for example git
   checkout --detach is relevant because it explains why git reflog works
   well after a rebase.
 * replace the git switch with git checkout that I'd missed previously

I didn't use the git log --cherry-pick option in the explanation because I had personally never heard of that option before today, and I don't want people to have to read the git log man page to be able to understand the explanation. I also left out --reapply-cherry-picks just because I don't understand the use case so I couldn't evaluate how likely it is to be relevant to the person reading.

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 | 302 +++++++++++++++-------------------
 1 file changed, 136 insertions(+), 166 deletions(-)

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

Range-diff vs v5:

 1:  c2f2e05078f ! 1:  e7a8fbbe53c doc: git-rebase: start with an example
     @@ Documentation/git-rebase.adoc: SYNOPSIS
       DESCRIPTION
       -----------
      +Transplant a series of commits onto a different starting point.
     ++You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
     ++MODE below for how to do that.
      +
      +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.
     @@ Documentation/git-rebase.adoc: SYNOPSIS
      +    D---E---F---G master
      +------------
      +
     -+You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
     -+MODE below for how to do that.
      +
       If `<branch>` is specified, `git rebase` will perform an automatic
       `git switch <branch>` before doing anything else.  Otherwise
 2:  5459b7ff560 ! 2:  ad63f69918d doc: git rebase: dedup merge conflict discussion
     @@ Commit message
      
       ## Documentation/git-rebase.adoc ##
      @@ Documentation/git-rebase.adoc: shortcut for `git checkout topic && git rebase master`.
     - You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
     - MODE below for how to do that.
     + ------------
     + 
       
      +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 do
 3:  948c205f1e6 = 3:  7ee6b0afe88 doc: git rebase: clarify arguments syntax
 4:  e229b9fccb2 = 4:  4686417b28e doc: git-rebase: move --onto explanation down
 5:  5ab235b067b ! 5:  9c7f2716bc8 doc: git-rebase: update discussion of internals
     @@ Documentation/git-rebase.adoc: linkgit:git-config[1] for details) and the `--for
      -`--onto` option was supplied.  This has the exact same effect as
      -`git reset --hard <upstream>` (or `<newbase>`). `ORIG_HEAD` is set
      -to point at the tip of the branch before the reset.
     -+Here is a more detailed description of what `git rebase <upstream>` does:
     ++Here is a simplified description of what `git rebase <upstream>` does:
      +
     -+1. Make a list of all commits in the current branch that are not in
     -+   `<upstream>`. This is the same set of commits that would be shown by `git log
     -+   <upstream>..HEAD`. You can use `--fork-point` or `--root` to change how this
     -+   list of commits is constructed.
     ++1. Make a list of all new commits on your current branch since it branched
     ++   off from `<upstream>`. This is the same set of commits that would be shown
     ++   by `git log  <upstream>..HEAD`. You can use `--fork-point` or  `--root` to
     ++   change how this list of commits is constructed.
      +2. Check whether any of those commits are duplicates of commits already
     -+   in `<upstream>`, remove them from the list, and print out a warning about
     -+   each removed commit. You can use `--reapply-cherry-picks` to include
     -+   duplicate commits.
     -+3. Check out `<upstream>` (or `<newbase>` if the `--onto` option was
     -+   supplied) with the equivalent of `git checkout --detach <upstream>`.
     ++   in `<upstream>` and remove them from the list.
     ++3. Check out `<upstream>` with the equivalent of `git checkout --detach <upstream>`.
      +4. Replay the commits, one by one, in order. This is similar to running
      +   `git cherry-pick <commit>` for each commit. See REBASING MERGES for how merges
      +   are handled.
      +5. Update your branch to point to the final commit with the equivalent
     -+   of `git switch -C <branch>`.
     ++   of `git checkout -C <branch>`.
       
       [NOTE]
      -`ORIG_HEAD` is not guaranteed to still point to the previous branch tip