| Message ID | YDQ5YIeXGiR5nvLH@coredump.intra.peff.net (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs/format-patch: mention handling of merges | expand |
Jeff King <peff@peff.net> writes: > Subject: [PATCH] docs/format-patch: mention handling of merges > > Format-patch doesn't have a way to format merges in a way that can be > applied by git-am (or any other tool), and so it just omits them. > However, this may be a surprising implication for users who are not well > versed in how the tool works. Let's add a note to the documentation > making this more clear. > ... > +CAVEATS > +------- > + > +Note that `format-patch` cannot represent commits with more than one > +parent (i.e., merges) and will silently omit them entirely from its > +output, even if they are part of the requested range. I think "cannot represent" is a little bit misleading, unless we expect the readers already know what we are trying to say (in which case there is no point in documenting this). Perhaps something like this might clarify a bit, though. Note that `format-patch` omits merge commits from the output, because it is impossible to turn a merge commit into a simple "patch" in such a way that allows receiving end to reproduce the same merge commit.
On Mon, Feb 22, 2021 at 03:31:53PM -0800, Junio C Hamano wrote: > Jeff King <peff@peff.net> writes: > > > Subject: [PATCH] docs/format-patch: mention handling of merges > > > > Format-patch doesn't have a way to format merges in a way that can be > > applied by git-am (or any other tool), and so it just omits them. > > However, this may be a surprising implication for users who are not well > > versed in how the tool works. Let's add a note to the documentation > > making this more clear. > > ... > > +CAVEATS > > +------- > > + > > +Note that `format-patch` cannot represent commits with more than one > > +parent (i.e., merges) and will silently omit them entirely from its > > +output, even if they are part of the requested range. > > > I think "cannot represent" is a little bit misleading, unless we > expect the readers already know what we are trying to say (in which > case there is no point in documenting this). Perhaps something like > this might clarify a bit, though. > > Note that `format-patch` omits merge commits from the output, > because it is impossible to turn a merge commit into a simple > "patch" in such a way that allows receiving end to reproduce the > same merge commit. That seems worse to me, because "it is impossible" implies that this can never be changed. But I don't think that's true. We might one day output something useful for merges. I think one could argue that any merge information (including conflict resolution) works against the root notion of format-patch, which is a set of changes that can be applied on a range of basesa. But even that I would be hesitant to commit to (since --base exists now). And certainly it's more subtlety than I'd want to get in to for this note. :) I almost softened it to "cannot yet represent". Does that read better to your (or worse)? Likewise, I considered adding a note at the end along the lines of "this may change in the future", though I suspect we'd only do so in combination with a command-line option. -Peff
Jeff King <peff@peff.net> writes: > That seems worse to me, because "it is impossible" implies that this > can never be changed. But I don't think that's true. We might one day > output something useful for merges. Fair enough. You are more optimistic than I am ;-) > I think one could argue that any merge information (including conflict > resolution) works against the root notion of format-patch, which is a > set of changes that can be applied on a range of basesa. That's true and it was the primary motive for omiting merges. > But even that I > would be hesitant to commit to (since --base exists now). I am not quite sure what --base has to throw into the equation. The information --base gives is often useful when I want to learn where the patches were taken from, but that does not restrict where the patches are actually applied to in any meaningful way (iow, "on a range of bases" part is not affected).
On Mon, Feb 22, 2021 at 05:24:16PM -0800, Junio C Hamano wrote: > > I think one could argue that any merge information (including conflict > > resolution) works against the root notion of format-patch, which is a > > set of changes that can be applied on a range of basesa. > > That's true and it was the primary motive for omiting merges. > > > But even that I > > would be hesitant to commit to (since --base exists now). > > I am not quite sure what --base has to throw into the equation. The > information --base gives is often useful when I want to learn where > the patches were taken from, but that does not restrict where the > patches are actually applied to in any meaningful way (iow, "on a > range of bases" part is not affected). What I meant is that without "--base", telling somebody "here is the merge you should replay on top of these other patches" is virtually meaningless. You cannot know what the merge base would be! So you might be merging in other random crap, and you might or might not see the same conflicts. But in a world with --base, I can imagine some people recreating whole sequences of the history graph by using "--base" along with some (to be invented) format for representing a merge via email. That mode would certainly not be the default, but at least at that point it is conceivably useful. Sort of like a bundle, but more human-readable (it would also need committer info to recreate the commit ids perfectly, of course). All of which meant only to argue that "it is not possible or not useful to represent a merge in an email" is something that could change in the future. :) -Peff
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 3e49bf2210..33649098ce 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -36,7 +36,7 @@ SYNOPSIS DESCRIPTION ----------- -Prepare each commit with its patch in +Prepare each non-merge commit with its patch in one file per commit, formatted to resemble UNIX mailbox format. The output of this command is convenient for e-mail submission or for use with 'git am'. @@ -718,6 +718,13 @@ use it only when you know the recipient uses Git to apply your patch. $ git format-patch -3 ------------ +CAVEATS +------- + +Note that `format-patch` cannot represent commits with more than one +parent (i.e., merges) and will silently omit them entirely from its +output, even if they are part of the requested range. + SEE ALSO -------- linkgit:git-am[1], linkgit:git-send-email[1]