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>
next
Elijah Newren 2025-10-02 22:34:47 +00:00 committed by Junio C Hamano
parent c44beea485
commit 1c573a3451
1 changed files with 10 additions and 4 deletions

View File

@ -78,11 +78,17 @@ OPTIONS

--merge-base=<tree-ish>::
Instead of finding the merge-bases for <branch1> and <branch2>,
specify a merge-base for the merge, and specifying multiple bases is
currently not supported. This option is incompatible with `--stdin`.
specify a merge-base for the merge. This option is incompatible with
`--stdin`.
+
As the merge-base is provided directly, <branch1> and <branch2> do not need
to specify commits; trees are enough.
Specifying multiple bases is currently not supported, which means that when
merging two branches with more than one merge-base, using this option may
cause merge results to differ from what `git merge` would compute. This
can include potentially losing some changes made on one side of the history
in the resulting merge.
+
With this option, since the merge-base is provided directly, <branch1> and
<branch2> do not need to specify commits; trees are enough.

-X<option>::
--strategy-option=<option>::