[PATCH] Documentation/git-merge-tree.adoc: clarify the --merge-base option

From: Elijah Newren via GitGitGadget <gitgitgadget@gmail.com>
Date: Oct 2, 2025, 22:34 UTC
Message-ID: <pull.1980.git.1759444487406.gitgitgadget@gmail.com>

From: Elijah Newren <newren@gmail.com>

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>
---
    Documentation/git-merge-tree.adoc: clarify the --merge-base option

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1980%2Fnewren%2Fmerge-tree-merge-base-clarifications-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1980/newren/merge-tree-merge-base-clarifications-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1980

 Documentation/git-merge-tree.adoc | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc
index f824eea61f..4e13ed33d6 100644
--- a/Documentation/git-merge-tree.adoc
+++ b/Documentation/git-merge-tree.adoc
@@ -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>::

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0

-- 
gitgitgadget