Nanako Shiraishi <nanako3@xxxxxxxxxxx> writes:
> Quoting Junio C Hamano <gitster@xxxxxxxxx>:
>
>> ... I do not think it is a sensible
>> thing to say "let's take as much automerge results as possible to salvage
>> our changes where they do not overlap with what the upstream did, but I
>> would give up our changes to places that the upstream also touched,
>> because I do not understand what they did well enough to be able to
>> resolve the merge conflicts correctly", and "merge -Xtheirs" is exactly
>> that.
>
> I do not know if "I do not understand what they did well enough" is the
> only reason people would want to use that feature. Isn't it better to
> let people decide that for themselves?
We have been saying that we will give long enough rope to people, but at
the same time I believe there are things that the world is better without,
and a feature that would only encourage a bad workflow is one of them.
The way I try to tell such a (mis)feature from a feature that can be
useful to people other than myself is to ask people why they would want
such a feature and what their response to possible downsides of such a
feature.
Don't get me wrong. Choice is good, and it is also good that some people
may choose differently from me. After all, we are different people with
different workflows.
But they should be able to explain the reason why they choose something
clearly, at least well enough to convince themselves to choose it. If
they can't come up with a rational explanation, it becomes an irrational
"because I want to" (and "because I can, now that you have already coded
it"). That leads to feeping creaturism and a bad feature that the world
is better without.
I haven't heard an explanation other than the one I said above, and I do
not think that explanation is rational.
Side note. Even though I invented rerere and it turned out to be a
great ti[mp]esaver, I do want to validate the reused resolution
makes sense in the new context every time rerere does its job.
Recently Ingo wanted the auto resolution to be staged
automatically, and rerere.autoupdate was born. I was initially
very much against it, but his description of the workflow where it
would be useful was convincing enough. This "convincing" does not
have to be "Yeah, it's useful to me as well; thanks for explaining
it to me". Even though my workflow might never be helped with
such a feature, I can see that the different workflow he presented
would be useful to people other than myself, and I could agree
that the new feature would help such a workflow. This was a good
example of "choosing something I initially thought would be
detrimental with a good reason, and with a good explanation making
me realize that my initial thought was too narrow".
> I think such a documentation will help people to decide if 'theirs'
> option makes sense for their workflow.
So here it is.
-- >8 --
[PATCH] Document that merge strategies can now take their own options
Also document the recently added -Xtheirs, -Xours and -Xsubtree[=path]
options to the merge-recursive strategy.
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
---
Documentation/merge-options.txt | 4 ++++
Documentation/merge-strategies.txt | 26 ++++++++++++++++++++++++++
2 files changed, 30 insertions(+), 0 deletions(-)
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index ffbc6e9..96aec48 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -58,3 +58,7 @@
If there is no `-s` option, a built-in list of strategies
is used instead (`git-merge-recursive` when merging a single
head, `git-merge-octopus` otherwise).
+
+-X<option>::
+ Pass merge strategy specific option through to the merge
+ strategy.
diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index 1276f85..39ff0a8 100644
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt
@@ -1,6 +1,11 @@
MERGE STRATEGIES
----------------
+The merge mechanism ('git-merge' and 'git-pull' commands) allows the
+backend 'merge strategies' to be chosen with `-s` option. Some strategies
+can also take their own options, which can be passed by giving `-X<option>`
+arguments to 'git-merge' and/or 'git-pull'.
+
resolve::
This can only resolve two heads (i.e. the current branch
and another branch you pulled from) using 3-way merge
@@ -20,6 +25,27 @@ recursive::
Additionally this can detect and handle merges involving
renames. This is the default merge strategy when
pulling or merging one branch.
++
+The 'recursive' strategy can take the following options:
+
+ours;;
+ This option forces conflicting hunks to be auto-resolved cleanly by
+ favoring 'our' version. Changes from the other tree that do not
+ conflict with our side are reflected to the merge result.
++
+This should not be confused with the 'ours' merge strategy, which does not
+even look at what the other tree contains at all. IOW, it discards everything
+the other tree did, declaring 'our' history contains all that happened in it.
+
+theirs;;
+ This is opposite of 'ours'.
+
+subtree[=path];;
+ This option is a more advanced form of 'subtree' strategy, where
+ the strategy makes a guess on how two trees must be shifted to
+ match with each other when merging. Instead, the specified path
+ is prefixed (or stripped from the beginning) to make the shape of
+ two trees to match.
octopus::
This resolves more than two-head case, but refuses to do
--
1.5.6.3.573.gd2d2
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
