From: Elijah Newren via GitGitGadget Date: Sun, 01 Aug 2021 00:07:41 GMT Subject: [PATCH 2/2] Update docs for change of default merge backend Message-ID: <35490397590ae4d39ba98c7eb206bfadc22ddf35.1627776462.git.gitgitgadget@gmail.com> In-Reply-To: From: Elijah Newren Make multiple documentation updates to bring things up to date as we change the default merge backend... Add a section for `ort` within merge-strategies.txt; while it accepts the same flags as `recursive` (even if it ignores three of them) and is meant as a drop in replacement, it still makes sense to explicitly cover it. Change several locations in the docs that referred to `recursive` as the default merge backend, and fix a few that said or implied that only `recursive` had certain abilities (such as rename detection). Fix up some wording in directory-rename-detection.txt due to some restructurings performed while optimizing both the ort backend and the rename detection machinery. Drop the "is considered generally safe and fast" from the description of the `resolve` strategy, since that implies the other strategies are not. While such an implication may have been true in 2005 when written, it may well be that `ort` is faster today (since it does not need to recurse into all directories). Also, since `resolve` was the default for less than a year while `recursive` has been the default for a decade and a half, I think `recursive` is more battle-tested than `resolve` is. Move the description of `resolve` near `octopus` and `ours` while at it since it is no longer the default merge algorithm and hasn't been for a very long time. Signed-off-by: Elijah Newren --- Documentation/git-rebase.txt | 17 ++-- Documentation/gitfaq.txt | 2 +- Documentation/merge-options.txt | 4 +- Documentation/merge-strategies.txt | 98 +++++++++++-------- .../technical/directory-rename-detection.txt | 14 +-- Documentation/user-manual.txt | 2 +- 6 files changed, 78 insertions(+), 59 deletions(-) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 55af6fd24e2..41b68423444 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -340,9 +340,10 @@ See also INCOMPATIBLE OPTIONS below. -m:: --merge:: - Use merging strategies to rebase. When the recursive (default) merge - strategy is used, this allows rebase to be aware of renames on the - upstream side. This is the default. + Use merging strategies to rebase. When either the `ort` + (default) or `recursive` merge strategy is used, this allows + rebase to be aware of renames on the upstream side. This is the + default. + Note that a rebase merge works by replaying each commit from the working branch on top of the branch. Because of this, when a merge @@ -355,8 +356,8 @@ See also INCOMPATIBLE OPTIONS below. -s :: --strategy=:: Use the given merge strategy. - If there is no `-s` option 'git merge-recursive' is used - instead. This implies --merge. + If there is no `-s` option the `ort` strategy is the default. + This implies --merge. + Because 'git rebase' replays each commit from the working branch on top of the branch using the given strategy, using @@ -369,7 +370,7 @@ See also INCOMPATIBLE OPTIONS below. --strategy-option=:: Pass the through to the merge strategy. This implies `--merge` and, if no strategy has been - specified, `-s recursive`. Note the reversal of 'ours' and + specified, `-s ort`. Note the reversal of 'ours' and 'theirs' as noted above for the `-m` option. + See also INCOMPATIBLE OPTIONS below. @@ -530,7 +531,7 @@ The `--rebase-merges` mode is similar in spirit to the deprecated where commits can be reordered, inserted and dropped at will. + It is currently only possible to recreate the merge commits using the -`recursive` merge strategy; Different merge strategies can be used only via +`ort` merge strategy; different merge strategies can be used only via explicit `exec git merge -s [...]` commands. + See also REBASING MERGES and INCOMPATIBLE OPTIONS below. @@ -1219,7 +1220,7 @@ successful merge so that the user can edit the message. If a `merge` command fails for any reason other than merge conflicts (i.e. when the merge operation did not even start), it is rescheduled immediately. -At this time, the `merge` command will *always* use the `recursive` +At this time, the `merge` command will *always* use the `ort` merge strategy for regular merges, and `octopus` for octopus merges, with no way to choose a different one. To work around this, an `exec` command can be used to call `git merge` explicitly, diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index afdaeab8503..072bf84fa8a 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -275,7 +275,7 @@ best to always use a regular merge commit. [[merge-two-revert-one]] If I make a change on two branches but revert it on one, why does the merge of those branches include the change?:: - By default, when Git does a merge, it uses a strategy called the recursive + By default, when Git does a merge, it uses a strategy called the ort strategy, which does a fancy three-way merge. In such a case, when Git performs the merge, it considers exactly three points: the two heads and a third point, called the _merge base_, which is usually the common ancestor of diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index eb0aabd396f..72b53188504 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -112,8 +112,8 @@ With --squash, --commit is not allowed, and will fail. Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. If there is no `-s` option, a built-in list of strategies - is used instead ('git merge-recursive' when merging a single - head, 'git merge-octopus' otherwise). + is used instead (`ort` when merging a single head, + `octopus` otherwise). -X