Subject: git format-patch documentation anomaly

From: Jon Loeliger <[email-masked]>
Date: Thu, 12 Jun 2008 19:37:11 -0500

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