From: "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Elijah Newren <newren@gmail.com>, Elijah Newren <newren@gmail.com>
Subject: [PATCH] Documentation/git-merge-tree.adoc: clarify the --merge-base option
Date: Thu, 02 Oct 2025 22:34:47 +0000 [thread overview]
Message-ID: <pull.1980.git.1759444487406.gitgitgadget@gmail.com> (raw)
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
reply other threads:[~2025-10-02 22:34 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=pull.1980.git.1759444487406.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=git@vger.kernel.org \
--cc=newren@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).