[v3,00/10] Documentation updates: merge-strategies

Message

blanet via GitGitGadget Aug. 4, 2021, 11:50 p.m. UTC

I noticed while updating my switch-default-merge-strategy-to-ort submission,
that many of the changes were good documentation updates that we might want
for Git v2.33.0. So I pulled those changes out and split them into lots of
little commits so that if any parts need discussion or are objectionable, we
can just drop those from this series and apply the rest for v2.33.0.

The first 9 commits are just small documentation updates, but there is one
commit at the end that updates an error message and a code comment.

Changes since v1:

 * Multiple tweaks suggested by Eric, Dscho, and Junio
 * Removed patch 7 explaining no-renames since that probably belongs in git
   diff --no-renames instead, and this series is about merge-strategies.
 * Inserted a new patch 8 that strikes some misleading or at least
   no-longer-important text from git-rebase.txt (due changes back in late
   2006).

Changes since v2:

 * Removed sentence from commit message of patch 8 referring to a change in
   v1 that was since removed.
 * Added Stolee's and Dscho's Acked-bys.

Elijah Newren (10):
  git-rebase.txt: correct antiquated claims about --rebase-merges
  directory-rename-detection.txt: small updates due to merge-ort
    optimizations
  Documentation: edit awkward references to `git merge-recursive`
  merge-strategies.txt: update wording for the resolve strategy
  merge-strategies.txt: do not imply using copy detection is desired
  merge-strategies.txt: avoid giving special preference to patience
    algorithm
  merge-strategies.txt: fix simple capitalization error
  git-rebase.txt: correct out-of-date and misleading text about renames
  merge-strategies.txt: add coverage of the `ort` merge strategy
  Update error message and code comment

 Documentation/git-rebase.txt                  | 27 ++++++-----
 Documentation/merge-options.txt               |  4 +-
 Documentation/merge-strategies.txt            | 48 +++++++++++--------
 .../technical/directory-rename-detection.txt  | 14 +++---
 builtin/merge.c                               |  2 +-
 sequencer.c                                   |  2 +-
 6 files changed, 55 insertions(+), 42 deletions(-)


base-commit: 66262451ec94d30ac4b80eb3123549cf7a788afd
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1059%2Fnewren%2Fort-doc-updates-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1059/newren/ort-doc-updates-v3
Pull-Request: https://github.com/git/git/pull/1059

Range-diff vs v2:

  1:  34352397168 !  1:  75b81598a80 git-rebase.txt: correct antiquated claims about --rebase-merges
     @@ Commit message
          was not updated.  Update it now.
      
          Acked-by: Johannes Schindelin <[e-mail]>
     +    Acked-by: Derrick Stolee <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/git-rebase.txt ##
  2:  3fdd068231a !  2:  69fa233483c directory-rename-detection.txt: small updates due to merge-ort optimizations
     @@ Commit message
          directory-rename-detection.txt had claims that all of that logic was
          found in merge-recursive.  Update the documentation.
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/technical/directory-rename-detection.txt ##
  3:  2a38320c2be !  3:  48f72d7e028 Documentation: edit awkward references to `git merge-recursive`
     @@ Commit message
          when rebase was a shell script, but it seems like a rather indirect way
          to refer to the `recursive` strategy.  Simplify the references.
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/git-rebase.txt ##
  4:  e422a1bc7d4 !  4:  81a3092b9b0 merge-strategies.txt: update wording for the resolve strategy
     @@ Commit message
          the same is not true of other strategies.  Rather than adding this text
          to all the strategies, just remove it from this one.
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/merge-strategies.txt ##
  5:  b1db5fdebe5 !  5:  1d144757a2e merge-strategies.txt: do not imply using copy detection is desired
     @@ Commit message
          anything else that would make sense either.  Change the wording to
          simply state that we ignore any copies.
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/merge-strategies.txt ##
  6:  44101062e0e !  6:  a8381a89065 merge-strategies.txt: avoid giving special preference to patience algorithm
     @@ Commit message
          important than other diff algorithms, so just refer to it as a
          deprecated shorthand for `diff-algorithm=patience`.
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/merge-strategies.txt ##
  7:  d1521f98dee !  7:  2c82aacbcbd merge-strategies.txt: fix simple capitalization error
     @@ Metadata
       ## Commit message ##
          merge-strategies.txt: fix simple capitalization error
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/git-rebase.txt ##
  8:  8978132397e !  8:  032dcf7c18e git-rebase.txt: correct out-of-date and misleading text about renames
     @@ Commit message
          backend).  However, git-am -3 gained that same ability in commit
          579c9bb198 ("Use merge-recursive in git-am -3.", 2006-12-28).  As such,
          the comment about being able to detect renames is not particularly
     -    noteworthy.  Remove it.  While tweaking this description, add a quick
     -    comment about when --merge became the default.
     +    noteworthy.  Remove it.
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/git-rebase.txt ##
  9:  bc92826f7e5 !  9:  9ae77dbc291 merge-strategies.txt: add coverage of the `ort` merge strategy
     @@ Metadata
       ## Commit message ##
          merge-strategies.txt: add coverage of the `ort` merge strategy
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## Documentation/merge-strategies.txt ##
 10:  4a78ac53424 ! 10:  0b881131b2b Update error message and code comment
     @@ Commit message
          but which were also applicable to 'merge-ort'.  Update them to more
          general wording.
      
     +    Acked-by: Derrick Stolee <[e-mail]>
     +    Acked-by: Johannes Schindelin <[e-mail]>
          Signed-off-by: Elijah Newren <[e-mail]>
      
       ## builtin/merge.c ##