Git-ites,
I noticed that there is a bit of an anomaly with
the "git-format-patch" documentation. The option
for --ignore-if-in-upstream reads like this:
--ignore-if-in-upstream::
Do not include a patch that matches a commit in
<until>..<since>. This will examine all patches reachable
from <since> but not from <until> and compare them with the
patches being generated, and any patch that matches is
ignored.
First, the English on the <until>..<since> is a bit odd,
and directly opposite the corresponding ordering from git-log:
<since>..<until>
Show only commits between the named two commits. When either
<since> or <until> is omitted, it defaults to HEAD, i.e. the tip
of the current branch. For a more complete list of ways to spell
<since> and <until>, see "SPECIFYING REVISIONS" section in
git-rev-parse(1).
But the real issue is that git-format-patch doesn't
even mention <since>..<until> (or <until>..<since>)
as its revision range specifier anywhere. It says
[ <since> | <revision range> ]
in its synopsis.
And I wonder if it is just me or not, but I had to read this
paragaph about 3 times and compare it to my already-known
mental model of what format-patch does before I figured out
what it was trying to say:
A single commit, when interpreted as a <revision range> expression,
means "everything that leads to that commit", but if you write git
format-patch <commit>, the previous rule applies to that command
line and you do not get "everything since the beginning of the
time". If you want to format everything since project inception to
one commit, say "git format-patch --root <commit>" to make it clear
that it is the latter case.
Granted, that is a little out of context ("the previous rule" refers
to this:
1. A single commit, <since>, specifies that the commits leading to
the tip of the current branch that are not in the history that
leads to the <since> to be output.
So, at the risk of complaining and not contributing, I'll
offer this rewrite or clarification for the confusing paragraph
and, if needed, followup with a patch unless someone else
beats me to it.
Other Git commands that receive a single commit, <commit>,
parameter as part of a range generally mean "every commit
that contributes to and leads up to <commit>". However,
in the context of git-format-patch, that is generally not
the desired behavior; instead a single commit is interpreted
as a "<since>" parameter as if "<commit>..HEAD" were requested,
and specifies the commits leading to the tip of the current
branch that are not in the history up to and including <commit>.
If all commits from the root of the history up to the specified
commit are wanted, use "--root <commit>".
Is a single commit, in fact, identical to "<commit>..HEAD"?
Should we just state that straight up and be done with it?
jdl
--
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
