merge-tree: update documentation for differences in -z output
The Informational Messages was updated in de90581141 ("merge-ort: optionally produce machine-readable output", 2022-06-18) to provide more detailed and machine parseable output when `-z` is passed, but the Documentation was not updated to reflect these changes. Update it now. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Elijah Newren committed
Oct 23, 2022 at 01:28 UTC
a9f5bb83e0341a04c46b2dec27e16c793d6447f8
1 file changed
+39
-7
Documentation/git-merge-tree.txt
+39
-7
@@ -108,18 +108,50 @@ character instead of a newline character.
108
Informational messages
109
~~~~~~~~~~~~~~~~~~~~~~
110
111
-This always starts with a blank line (or NUL if `-z` is passed) to
112
-separate it from the previous sections, and then has free-form
113
-messages about the merge, such as:
111
+This section provides informational messages, typically about
112
+conflicts. The format of the section varies significantly depending
113
+on whether `-z` is passed.
114
+
115
+If `-z` is passed:
116
+
117
+The output format is zero or more conflict informational records, each
118
+of the form:
119
+
120
+ <list-of-paths><conflict-type>NUL<conflict-message>NUL
121
+
122
+where <list-of-paths> is of the form
123
+
124
+ <number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL
125
+
126
+and includes paths (or branch names) affected by the conflict or
127
+informational message in <conflict-message>. Also, <conflict-type> is a
128
+stable string explaining the type of conflict, such as
129
+
130
+ * "Auto-merging"
131
+ * "CONFLICT (rename/delete)"
132
+ * "CONFLICT (submodule lacks merge base)"
133
+ * "CONFLICT (binary)"
134
+
135
+and <conflict-message> is a more detailed message about the conflict which often
136
+(but not always) embeds the <stable-short-type-description> within it. These
137
+strings may change in future Git versions. Some examples:
138
139
* "Auto-merging <file>"
140
* "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..."
117
- * "Failed to merge submodule <submodule> (<reason>)"
141
+ * "Failed to merge submodule <submodule> (no merge base)"
142
* "Warning: cannot merge binary files: <filename>"
143
120
-Note that these free-form messages will never have a NUL character
121
-in or between them, even if -z is passed. It is simply a large block
122
-of text taking up the remainder of the output.
144
+If `-z` is NOT passed:
145
+
146
+This section starts with a blank line to separate it from the previous
147
+sections, and then only contains the <conflict-message> information
148
+from the previous section (separated by newlines). These are
149
+non-stable strings that should not be parsed by scripts, and are just
150
+meant for human consumption. Also, note that while <conflict-message>
151
+strings usually do not contain embedded newlines, they sometimes do.
152
+(However, the free-form messages will never have an embedded NUL
153
+character). So, the entire block of information is meant for human
154
+readers as an agglomeration of all conflict messages.
155
156
EXIT STATUS
157
-----------