[PATCH v6 00/12] In-core git merge-tree ("Server side merges")
- From
Elijah Newren via GitGitGadget <gitgitgadget@gmail.com>
- Date
- Feb 23, 2022, 07:46 UTC
- Message-ID
- <pull.1122.v6.git.1645602413.gitgitgadget@gmail.com>
- In-Reply-To
- <pull.1122.v5.git.1645340082.gitgitgadget@gmail.com>
== Basic Summary ==
This series introduces a new mode to git merge-tree allowing it to perform real merges (three-way text content merges, recursive ancestor consolidation, rename detection, proper directory/file conflict handling, etc.) and write the result as a toplevel tree. It doesn't touch the working tree or index, and doesn't create any commits or update any refs. It could be used to do merges when in a bare repository (thus potentially making it of interest to Git hosting sites, i.e. "Server side merges"), or for doing a merge of branches that aren't checked out.
It does not handle similar functionality for cherry-picks, rebases, or reverts; that is also of interest, but is being deferred for a future series.
== Quick Overview ==
* Patches 1-2: preparatory cleanups
* Patches 3-4: implement basic real merges
* Patches 5-6: include informational messages ("CONFLICT" messages and
such) in output
* Patches 7-10: add ability to include ls-files -u style of info in the
output
* Patch 11: support --allow-unrelated-histories
* Patch 12: augment the manual with potential usage mistakes== Updates Log ==
Stuff NOT included that reviewers brought up in various rounds (and which might still be an open question):
* Having -z affect the informational messages section[1] * Having a machine-parseable variant of information from the informational messages section[2] * Very generic (mode, oid, stage, filename) printing formatting[3] * Providing similar functionality for doing cherry-picks/rebases/reverts, i.e. a scheme for three-way merges with a specified merge-base[4]. That's being deferred to a future series. [1] https://lore.kernel.org/git/CABPp-BG7id0GfpDee_7ETZ_94BC_i-e_=-u=PrYJeD7d4sVbiw@mail.gmail.com/ [2] https://lore.kernel.org/git/nycvar.QRO.7.76.6.2202211059430.26495@tvgsbejvaqbjf.bet/, https://lore.kernel.org/git/220221.86y224b80b.gmgdl@evledraar.gmail.com/ [3] https://lore.kernel.org/git/CABPp-BGnOes7J_piDyBUeuLVm274w4-9G3k0vR-0it3z7TPn_w@mail.gmail.com/ [4] https://lore.kernel.org/git/CABPp-BEaemkGGm0cSofP0gau7YN-y6HFoi0yJbHA8+iGjxsYSA@mail.gmail.com/
Updates since v5:
* Used reverse_commit_list() to reverse a commit_list without extra allocations * Several documentation updates
Updates since v4:
* Fixed double "is" in documentation. * Fixed a few small items with testcases
Updates since v3:
* Dropped previous patches 5, 6, and 8 of the old series; they weren't being used and opened a can of worms[1] * [Patch 3] Restructured argument checking, including using an enum * [Patch 4] Restored the extended paragraph about the deprecated form of git-merge-tree, mentioned write-tree in plumbing commands, and a few other small fixups to the documentation * [Patch 4] Also provide an example of a clean merge rather than just a conflicted one * [Patch 6] Fix the incompatible arguments check and add some tests for it * [Patch 6] Introduce an anonymize_hash() shell function to make tests easier to read (less repeated sed) * [Patch 9] Rename --exclude-modes-oids-stages to --name-only; no short option for now * [Patch 10] When -z passed, the tree in the first section should have a trailing NUL rather than trailing newline [1] https://lore.kernel.org/git/CABPp-BEKuXHELVx4=5JJTj5HVOKZ=Y-4G4BK47BCZYYRSrkFsQ@mail.gmail.com/
Updates since v2:
* Improved patches from Dscho for the diff_warn_rename_limit() handling * Add a -z option for NUL-terminated conflict info lines (so that filenames do not have to be quoted)
Updates since v1 (or v3 depending on how you count; thanks to René, Ævar, Christian, Dscho for very helpful feedback):
* New patch from Dscho allowing diff_warn_rename_limit() to print somewhere other than stdout (I hope he's okay with me including his Signed-off-by) * Now prints filenames relative to prefix, much like ls-files * Renamed --exclude-oids-and-modes to --exclude-modes-oids-stages and gave it a -l shorthand; I'm wondering if I should just drop this option, though. * And numerous cleanups, in lots of areas: * Multiple parse-options cleanups * Lots of commit message cleanups * Wording tweaks to the "Description" section of the manual * Several small code cleanups * I dropped the RFC label
[There were also two submissions of a previous series; see https://lore.kernel.org/git/pull.1114.v2.git.git.1641403655.gitgitgadget@gmail.com/] [https://lore.kernel.org/git/pull.1114.v2.git.git.1641403655.gitgitgadget@gmail.com/%5D]
Updates since original submission v2 (thanks to Christian, Dscho, Ramsay, and René for suggestions and comments):
* Significant changes to output format:
* Flags no longer take a filename for additional output; they write to
stdout instead.
* More information included by default when there are conflicts (no need
to request it with additional flags, instead flags can be used to
suppress it).
* Provide (mode, oid, stage, file) tuples -- i.e. ls-files -u style of
information -- when there are conflicts. Add a flag to only list
conflicted files if that's preferred.
* Much more thorough manual for git-merge-tree.txt
* Renamed option from --real to --write-tree
* Accept an optional --trivial-merge option to get old style merge-tree
behavior
* Allow both --write-tree and --trivial-merge to be omitted since we can
deduce which from number of arguments
* Document exit code when the merge cannot be run (so we can distinguish
other error cases from conflicts)
* testcase cleanups: test_tick, early skip of test when using recursive
backend, variable renames, etc.
* various minor code cleanups
* Add a new --allow-unrelated-histories option (with same meaning as the
one used in git merge)
* Rebased on top of en/remerge-diff to avoid a small conflictUpdates since original submission v1 (thanks to Johannes Altmanninger and Fabian for suggestions):
* Fixed a bad patch splitting, and a style issue pointed out by Johannes Altimanninger * Fixed misleading commit messages in new test cases * Fixed my comments about how commit-tree could be used to correctly use two -p flags
Elijah Newren (12):
merge-tree: rename merge_trees() to trivial_merge_trees()
merge-tree: move logic for existing merge into new function
merge-tree: add option parsing and initial shell for real merge
function
merge-tree: implement real merges
merge-ort: split out a separate display_update_messages() function
merge-tree: support including merge messages in output
merge-ort: provide a merge_get_conflicted_files() helper function
merge-tree: provide a list of which files have conflicts
merge-tree: provide easy access to `ls-files -u` style info
merge-tree: allow `ls-files -u` style info to be NUL terminated
merge-tree: add a --allow-unrelated-histories flag
git-merge-tree.txt: add a section on potentional usage mistakesDocumentation/git-merge-tree.txt | 228 +++++++++++++++++++++++++++-- builtin/merge-tree.c | 186 ++++++++++++++++++++++-- git.c | 2 +- merge-ort.c | 109 +++++++++----- merge-ort.h | 29 ++++ t/t4301-merge-tree-write-tree.sh | 238 +++++++++++++++++++++++++++++++ 6 files changed, 730 insertions(+), 62 deletions(-) create mode 100755 t/t4301-merge-tree-write-tree.sh
base-commit: ea5df61cf358d3c831189e2f04863abc2157e3e1 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1122%2Fnewren%2Fin-core-merge-tree-v6 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1122/newren/in-core-merge-tree-v6 Pull-Request: https://github.com/gitgitgadget/git/pull/1122
Range-diff vs v5:
1: 4a7cd5542bb = 1: 4a7cd5542bb merge-tree: rename merge_trees() to trivial_merge_trees()
2: 4780ff6784d = 2: 4780ff6784d merge-tree: move logic for existing merge into new function
3: 60253745f5c = 3: 60253745f5c merge-tree: add option parsing and initial shell for real merge function
4: 7994775a934 ! 4: f8266d39c1b merge-tree: implement real merges
@@ Documentation/git-merge-tree.txt: git-merge-tree(1)
+'git merge-tree' [--write-tree] <branch1> <branch2>
+'git merge-tree' [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated)
++[[NEWMERGE]]
DESCRIPTION
-----------
-Reads three tree-ish, and output trivial merge results and
@@ Documentation/git-merge-tree.txt: git-merge-tree(1)
-index. For this reason, the output from the command omits
-entries that match the <branch1> tree.
+
++This command has a modern `--write-tree` mode and a deprecated
++`--trivial-merge` mode. With the exception of the
++<<DEPMERGE,DEPRECATED DESCRIPTION>> section at the end, the rest of
++this documentation describes modern `--write-tree` mode.
++
+Performs a merge, but does not make any new commits and does not read
+from or write to either the working tree or index.
+
-+The first form will merge the two branches, doing a real merge. A real
-+merge is distinguished from a trivial merge in that it includes:
++The performed merge will use the same feature as the "real"
++linkgit:git-merge[1], including:
+
+ * three way content merges of individual files
+ * rename detection
@@ Documentation/git-merge-tree.txt: git-merge-tree(1)
+ merge base, creating a virtual merge base by merging the merge bases)
+ * etc.
+
-+After the merge completes, the first form will create a new toplevel
-+tree object. See `OUTPUT` below for details.
-+
-+The second form is deprecated; it is kept for backward compatibility
-+reasons but may be deleted in the future. Other than the optional
-+`--trivial-merge`, it accepts no options. It can only do a trivial
-+merge. It reads three tree-ish, and outputs trivial merge results and
-+conflicting stages to the standard output in a semi-diff format.
-+Since this was designed for higher level scripts to consume and merge
-+the results back into the index, it omits entries that match
-+<branch1>. The result of this second form is similar to what
-+three-way 'git read-tree -m' does, but instead of storing the results
-+in the index, the command outputs the entries to the standard output.
-+This form not only has limited applicability, the output format is
-+also difficult to work with, and it will generally be less performant
-+than the first form even on successful merges (especially if working
-+in large repositories). The remainder of this manual will only
-+discuss the first form.
++After the merge completes, a new toplevel tree object is created. See
++`OUTPUT` below for details.
+
++[[OUTPUT]]
+OUTPUT
+------
+
@@ Documentation/git-merge-tree.txt: git-merge-tree(1)
+USAGE NOTES
+-----------
+
-+git-merge-tree was written to be low-level plumbing, similar to
-+hash-object, mktree, commit-tree, write-tree, update-ref, and mktag.
-+Thus, it could be used as a part of a series of steps such as
++This command is intended as low-level plumbing, similar to
++linkgit:git-hash-object[1], linkgit:git-mktree[1],
++linkgit:git-commit-tree[1], linkgit:git-write-tree[1],
++linkgit:git-update-ref[1], and linkgit:git-mktag[1]. Thus, it can be
++used as a part of a series of steps such as:
+
+ NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2)
+ test $? -eq 0 || die "There were conflicts..."
+ NEWCOMMIT=$(git commit-tree $NEWTREE -p $BRANCH1 -p $BRANCH2)
+ git update-ref $BRANCH1 $NEWCOMMIT
++
++[[DEPMERGE]]
++DEPRECATED DESCRIPTION
++----------------------
++
++Per the <<NEWMERGE,DESCRIPTION>> and unlike the rest of this
++documentation, this section describes the deprecated `--trivial-merge`
++mode.
++
++Other than the optional `--trivial-merge`, this mode accepts no
++options.
++
++This mode reads three tree-ish, and outputs trivial merge results and
++conflicting stages to the standard output in a semi-diff format.
++Since this was designed for higher level scripts to consume and merge
++the results back into the index, it omits entries that match
++<branch1>. The result of this second form is similar to what
++three-way 'git read-tree -m' does, but instead of storing the results
++in the index, the command outputs the entries to the standard output.
++
++This form not only has limited applicability (a trivial merge cannot
++handle content merges of individual files, rename detection, proper
++directory/file conflict handling, etc.), the output format is also
++difficult to work with, and it will generally be less performant than
++the first form even on successful merges (especially if working in
++large repositories).
GIT
---
@@ builtin/merge-tree.c: struct merge_tree_options {
{
- die(_("real merges are not yet implemented"));
+ struct commit *parent1, *parent2;
-+ struct commit_list *common;
+ struct commit_list *merge_bases = NULL;
-+ struct commit_list *j;
+ struct merge_options opt;
+ struct merge_result result = { 0 };
+
@@ builtin/merge-tree.c: struct merge_tree_options {
+ * Get the merge bases, in reverse order; see comment above
+ * merge_incore_recursive in merge-ort.h
+ */
-+ common = get_merge_bases(parent1, parent2);
-+ if (!common)
++ merge_bases = get_merge_bases(parent1, parent2);
++ if (!merge_bases)
+ die(_("refusing to merge unrelated histories"));
-+ for (j = common; j; j = j->next)
-+ commit_list_insert(j->item, &merge_bases);
++ merge_bases = reverse_commit_list(merge_bases);
+
+ merge_incore_recursive(&opt, merge_bases, parent1, parent2, &result);
+ if (result.clean < 0)
5: e0f95e094cf = 5: 6629af14919 merge-ort: split out a separate display_update_messages() function
6: 90c4adecb23 ! 6: 17b57efb714 merge-tree: support including merge messages in output
@@ Documentation/git-merge-tree.txt: git-merge-tree - Perform merge without touchin
+'git merge-tree' [--write-tree] [<options>] <branch1> <branch2>
'git merge-tree' [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated)
- DESCRIPTION
-@@ Documentation/git-merge-tree.txt: than the first form even on successful merges (especially if working
- in large repositories). The remainder of this manual will only
- discuss the first form.
+ [[NEWMERGE]]
+@@ Documentation/git-merge-tree.txt: linkgit:git-merge[1], including:
+ After the merge completes, a new toplevel tree object is created. See
+ `OUTPUT` below for details.
+OPTIONS
+-------
@@ Documentation/git-merge-tree.txt: than the first form even on successful merges
+ default is to include these messages if there are merge
+ conflicts, and to omit them otherwise.
+
+ [[OUTPUT]]
OUTPUT
------
-For either a successful or conflicted merge, the output from
-git-merge-tree is simply one line:
-+By default, for a successful merge, the output from git-merge-tree is
-+simply one line:
++For a successful merge, the output from git-merge-tree is simply one
++line:
+
+ <OID of toplevel tree>
+
@@ Documentation/git-merge-tree.txt: than the first form even on successful merges
-The printed tree object corresponds to what would be checked out in
-the working tree at the end of `git merge`, and thus may have files
-with conflict markers in them.
++[[OIDTLT]]
+OID of toplevel tree
+~~~~~~~~~~~~~~~~~~~~
+
@@ Documentation/git-merge-tree.txt: than the first form even on successful merges
+working tree at the end of `git merge`. If there were conflicts, then
+files within this tree may have embedded conflict markers.
+
++[[IM]]
+Informational messages
+~~~~~~~~~~~~~~~~~~~~~~
+
@@ Documentation/git-merge-tree.txt: than the first form even on successful merges
EXIT STATUS
-----------
-@@ Documentation/git-merge-tree.txt: Thus, it could be used as a part of a series of steps such as
+@@ Documentation/git-merge-tree.txt: used as a part of a series of steps such as:
NEWCOMMIT=$(git commit-tree $NEWTREE -p $BRANCH1 -p $BRANCH2)
git update-ref $BRANCH1 $NEWCOMMIT
-+Note that when the exit status is non-zero, NEWTREE in this sequence
++Note that when the exit status is non-zero, `NEWTREE` in this sequence
+will contain a lot more output than just a tree.
+
- GIT
- ---
- Part of the linkgit:git[1] suite
+ [[DEPMERGE]]
+ DEPRECATED DESCRIPTION
+ ----------------------
## builtin/merge-tree.c ##
@@ builtin/merge-tree.c: enum mode {
7: 12e2351092a = 7: 4c8f42372dd merge-ort: provide a merge_get_conflicted_files() helper function
8: 5bb7d3725ad ! 8: 7b1ee417f3d merge-tree: provide a list of which files have conflicts
@@ Commit message
Signed-off-by: Elijah Newren <newren@gmail.com>
## Documentation/git-merge-tree.txt ##
-@@ Documentation/git-merge-tree.txt: simply one line:
+@@ Documentation/git-merge-tree.txt: line:
Whereas for a conflicted merge, the output is by default of the form:
<OID of toplevel tree>
@@ Documentation/git-merge-tree.txt: This is a tree object that represents what wou
working tree at the end of `git merge`. If there were conflicts, then
files within this tree may have embedded conflict markers.
++[[CFI]]
+Conflicted file list
+~~~~~~~~~~~~~~~~~~~~
+
@@ Documentation/git-merge-tree.txt: This is a tree object that represents what wou
+as explained for the configuration variable `core.quotePath` (see
+linkgit:git-config[1]).
+
+ [[IM]]
Informational messages
~~~~~~~~~~~~~~~~~~~~~~
-
## builtin/merge-tree.c ##
@@
@@ builtin/merge-tree.c: struct merge_tree_options {
+ const char *prefix)
{
struct commit *parent1, *parent2;
- struct commit_list *common;
+ struct commit_list *merge_bases = NULL;
@@ builtin/merge-tree.c: static int real_merge(struct merge_tree_options *o,
o->show_messages = !result.clean;
9: 3c2ca198cec ! 9: f1231a8fbc8 merge-tree: provide easy access to `ls-files -u` style info
@@ Commit message
Signed-off-by: Elijah Newren <newren@gmail.com>
## Documentation/git-merge-tree.txt ##
-@@ Documentation/git-merge-tree.txt: discuss the first form.
+@@ Documentation/git-merge-tree.txt: After the merge completes, a new toplevel tree object is created. See
OPTIONS
-------
@@ Documentation/git-merge-tree.txt: discuss the first form.
--[no-]messages::
Write any informational messages such as "Auto-merging <path>"
or CONFLICT notices to the end of stdout. If unspecified, the
-@@ Documentation/git-merge-tree.txt: simply one line:
+@@ Documentation/git-merge-tree.txt: line:
Whereas for a conflicted merge, the output is by default of the form:
<OID of toplevel tree>
@@ Documentation/git-merge-tree.txt: simply one line:
<Informational messages>
These are discussed individually below.
-@@ Documentation/git-merge-tree.txt: This is a tree object that represents what would be checked out in the
- working tree at the end of `git merge`. If there were conflicts, then
+@@ Documentation/git-merge-tree.txt: working tree at the end of `git merge`. If there were conflicts, then
files within this tree may have embedded conflict markers.
+ [[CFI]]
-Conflicted file list
+Conflicted file info
~~~~~~~~~~~~~~~~~~~~
@@ Documentation/git-merge-tree.txt: This is a tree object that represents what wou
+the `--name-only` option is passed, the mode, object, and stage will
+be omitted.
+ [[IM]]
Informational messages
~~~~~~~~~~~~~~~~~~~~~~
@@ Documentation/git-merge-tree.txt: This is a tree object that represents what wou
* "Auto-merging <file>"
* "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..."
-@@ Documentation/git-merge-tree.txt: Thus, it could be used as a part of a series of steps such as
- Note that when the exit status is non-zero, NEWTREE in this sequence
+@@ Documentation/git-merge-tree.txt: used as a part of a series of steps such as:
+ Note that when the exit status is non-zero, `NEWTREE` in this sequence
will contain a lot more output than just a tree.
-+git-merge-tree was written to provide users with the same information
-+that they'd have access to if using `git merge`:
-+ * what would be written to the working tree (the <OID of toplevel tree>)
++For conflicts, the output includes the same information that you'd get
++with linkgit:git-merge[1]:
++
++ * what would be written to the working tree (the
++ <<OIDTLT,OID of toplevel tree>>)
+ * the higher order stages that would be written to the index (the
-+ <Conflicted file info>)
-+ * any messages that would have been printed to stdout (the <Informational
-+ messages>)
++ <<CFI,Conflicted file info>>)
++ * any messages that would have been printed to stdout (the
++ <<IM,Informational messages>>)
+
- GIT
- ---
- Part of the linkgit:git[1] suite
+ [[DEPMERGE]]
+ DEPRECATED DESCRIPTION
+ ----------------------
## builtin/merge-tree.c ##
@@ builtin/merge-tree.c: enum mode {
10: 6e89e17693a ! 10: 22297e6ce75 merge-tree: allow `ls-files -u` style info to be NUL terminated
@@ Commit message
Signed-off-by: Elijah Newren <newren@gmail.com>
## Documentation/git-merge-tree.txt ##
-@@ Documentation/git-merge-tree.txt: discuss the first form.
+@@ Documentation/git-merge-tree.txt: After the merge completes, a new toplevel tree object is created. See
OPTIONS
-------
@@ Documentation/git-merge-tree.txt: discuss the first form.
+ Do not quote filenames in the <Conflicted file info> section,
+ and end each filename with a NUL character rather than
+ newline. Also begin the messages section with a NUL character
-+ instead of a newline. See OUTPUT below for more information.
++ instead of a newline. See <<OUTPUT>> below for more information.
+
--name-only::
In the Conflicted file info section, instead of writing a list
@@ Documentation/git-merge-tree.txt: OID of toplevel tree
+files within this tree may have embedded conflict markers. This section
+is always followed by a newline (or NUL if `-z` is passed).
+ [[CFI]]
Conflicted file info
- ~~~~~~~~~~~~~~~~~~~~
@@ Documentation/git-merge-tree.txt: This is a sequence of lines with the format
The filename will be quoted as explained for the configuration
variable `core.quotePath` (see linkgit:git-config[1]). However, if
@@ Documentation/git-merge-tree.txt: This is a sequence of lines with the format
+be omitted. If `-z` is passed, the "lines" are terminated by a NUL
+character instead of a newline character.
+ [[IM]]
Informational messages
~~~~~~~~~~~~~~~~~~~~~~
11: 6ddd5ffde9c ! 11: db73c6dd823 merge-tree: add a --allow-unrelated-histories flag
@@ Documentation/git-merge-tree.txt: OPTIONS
+ share no common history. This flag can be given to override that
+ check and make the merge proceed anyway.
+
+ [[OUTPUT]]
OUTPUT
------
-
## builtin/merge-tree.c ##
@@ builtin/merge-tree.c: enum mode {
@@ builtin/merge-tree.c: enum mode {
@@ builtin/merge-tree.c: static int real_merge(struct merge_tree_options *o,
* merge_incore_recursive in merge-ort.h
*/
- common = get_merge_bases(parent1, parent2);
-- if (!common)
-+ if (!common && !o->allow_unrelated_histories)
+ merge_bases = get_merge_bases(parent1, parent2);
+- if (!merge_bases)
++ if (!merge_bases && !o->allow_unrelated_histories)
die(_("refusing to merge unrelated histories"));
- for (j = common; j; j = j->next)
- commit_list_insert(j->item, &merge_bases);
+ merge_bases = reverse_commit_list(merge_bases);
+
@@ builtin/merge-tree.c: int cmd_merge_tree(int argc, const char **argv, const char *prefix)
&o.name_only,
N_("list filenames without modes/oids/stages"),
12: 7abf633b638 ! 12: d58a7c7a9f6 git-merge-tree.txt: add a section on potentional usage mistakes
@@ Commit message
Signed-off-by: Elijah Newren <newren@gmail.com>
## Documentation/git-merge-tree.txt ##
-@@ Documentation/git-merge-tree.txt: that they'd have access to if using `git merge`:
- * any messages that would have been printed to stdout (the <Informational
- messages>)
+@@ Documentation/git-merge-tree.txt: with linkgit:git-merge[1]:
+ * any messages that would have been printed to stdout (the
+ <<IM,Informational messages>>)
+MISTAKES TO AVOID
+-----------------
+
+Do NOT look through the resulting toplevel tree to try to find which
-+files conflict; parse the <Conflicted file info> section instead. Not
-+only would parsing an entire tree be horrendously slow in large
++files conflict; parse the <<CFI,Conflicted file info>> section instead.
++Not only would parsing an entire tree be horrendously slow in large
+repositories, there are numerous types of conflicts not representable by
+conflict markers (modify/delete, mode conflict, binary file changed on
+both sides, file/directory conflicts, various rename conflict
+permutations, etc.)
+
-+Do NOT interpret an empty <Conflicted file info> list as a clean merge;
-+check the exit status. A merge can have conflicts without having
++Do NOT interpret an empty <<CFI,Conflicted file info>> list as a clean
++merge; check the exit status. A merge can have conflicts without having
+individual files conflict (there are a few types of directory rename
+conflicts that fall into this category, and others might also be added
+in the future).
+
+Do NOT attempt to guess or make the user guess the conflict types from
-+the <Conflicted file info> list. The information there is insufficient
-+to do so. For example: Rename/rename(1to2) conflicts (both sides
-+renamed the same file differently) will result in three different file
-+having higher order stages (but each only has one higher order stage),
-+with no way (short of the <Informational messages> section) to determine
-+which three files are related. File/directory conflicts also result in
-+a file with exactly one higher order stage.
++the <<CFI,Conflicted file info>> list. The information there is
++insufficient to do so. For example: Rename/rename(1to2) conflicts (both
++sides renamed the same file differently) will result in three different
++file having higher order stages (but each only has one higher order
++stage), with no way (short of the <<IM,Informational messages>> section)
++to determine which three files are related. File/directory conflicts
++also result in a file with exactly one higher order stage.
+Possibly-involved-in-directory-rename conflicts (when
+"merge.directoryRenames" is unset or set to "conflicts") also result in
+a file with exactly one higher order stage. In all cases, the
-+<Informational messages> section has the necessary info, though it is
-+not designed to be machine parseable.
++<<IM,Informational messages>> section has the necessary info, though it
++is not designed to be machine parseable.
+
-+Do NOT assume all filenames listed in the <Informational messages>
++Do NOT assume all filenames listed in the <<IM,Informational messages>>
+section had conflicts. Messages can be included for files that have no
+conflicts, such as "Auto-merging <file>".
+
-+AVOID taking the OIDS from the <Conflicted file info> and re-merging
-+them to present the conflicts to the user. This will lose information.
-+Instead, look up the version of the file found within the <OID of
-+toplevel tree> and show that instead. In particular, the latter will
-+have conflict markers annotated with the original branch/commit being
-+merged and, if renames were involved, the original filename. While you
-+could include the original branch/commit in the conflict marker
-+annotations when re-merging, the original filename is not available from
-+the <Conflicted file info> and thus you would be losing information that
-+might help the user resolve the conflict.
++AVOID taking the OIDS from the <<CFI,Conflicted file info>> and
++re-merging them to present the conflicts to the user. This will lose
++information. Instead, look up the version of the file found within the
++<<OIDTLT,OID of toplevel tree>> and show that instead. In particular,
++the latter will have conflict markers annotated with the original
++branch/commit being merged and, if renames were involved, the original
++filename. While you could include the original branch/commit in the
++conflict marker annotations when re-merging, the original filename is
++not available from the <<CFI,Conflicted file info>> and thus you would
++be losing information that might help the user resolve the conflict.
+
- GIT
- ---
- Part of the linkgit:git[1] suite
+ [[DEPMERGE]]
+ DEPRECATED DESCRIPTION
+ ------------------------ gitgitgadget