Documentation/git-merge-tree.adoc: clarify the --merge-base option
The --merge-base option for merge-tree has a few slightly awkward constructions or omissions: * Split the initial long sentence describing the option into two, making the instructions and the limitations clearer for readers. * Add context to the final sentence that might be obvious to some readers but isn't immediately obvious to all. * The discussion about lack of support for multiple merge bases simply leave folks wondering why that matters and could help or hurt. Separate it out and add a brief explanation. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Elijah Newren committed
Oct 2, 2025 at 22:34 UTC
1c573a34516ab869487ff1212e3244efdc1c402f
1 file changed
+10
-4
Documentation/git-merge-tree.adoc
+10
-4
@@ -78,11 +78,17 @@ OPTIONS
78
79
--merge-base=<tree-ish>::
80
Instead of finding the merge-bases for <branch1> and <branch2>,
81
- specify a merge-base for the merge, and specifying multiple bases is
82
- currently not supported. This option is incompatible with `--stdin`.
81
+ specify a merge-base for the merge. This option is incompatible with
82
+ `--stdin`.
83
+
84
-As the merge-base is provided directly, <branch1> and <branch2> do not need
85
-to specify commits; trees are enough.
84
+Specifying multiple bases is currently not supported, which means that when
85
+merging two branches with more than one merge-base, using this option may
86
+cause merge results to differ from what `git merge` would compute. This
87
+can include potentially losing some changes made on one side of the history
88
+in the resulting merge.
89
++
90
+With this option, since the merge-base is provided directly, <branch1> and
91
+<branch2> do not need to specify commits; trees are enough.
92
93
-X<option>::
94
--strategy-option=<option>::