From b7f4d97852f706f1f0cd6e3ea8dbe25637042103 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Wed, 1 Oct 2025 15:57:09 -0700 Subject: [PATCH] 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 --- 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 f824eea61f1e06..4e13ed33d6152f 100644 --- a/Documentation/git-merge-tree.adoc +++ b/Documentation/git-merge-tree.adoc @@ -78,11 +78,17 @@ OPTIONS --merge-base=:: Instead of finding the merge-bases for and , - 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, and 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, and + do not need to specify commits; trees are enough. -X