{"thread":{"id":"13924","subject":"git format-patch documentation anomaly","startedAt":"2008-06-13T00:37:11Z","lastAt":"2008-06-13T00:37:11Z","messageCount":1,"participants":["Jon Loeliger"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"79658","messageId":"E1K6xHz-0002y4-Dv@jdl.com","threadId":"13924","inReplyTo":null,"subject":"git format-patch documentation anomaly","fromName":"Jon Loeliger","fromEmail":"jdl@jdl.com","sentAt":"2008-06-13T00:37:11Z","receivedAt":"2008-06-13T00:37:11Z","isPatch":false,"sender":{"key":"jdl@jdl.com","avatar":"https://gravatar.com/avatar/75ce9a10b151acd2c28ec4ab2136dba7b2ff1634530bd04b155981a749d08a64?d=mp&s=160"},"body":"\nGit-ites,\n\nI noticed that there is a bit of an anomaly with\nthe \"git-format-patch\" documentation.  The option\nfor --ignore-if-in-upstream reads like this:\n\n    --ignore-if-in-upstream::\n        Do not include a patch that matches a commit in\n        <until>..<since>.  This will examine all patches reachable\n        from <since> but not from <until> and compare them with the\n        patches being generated, and any patch that matches is\n        ignored.\n\nFirst, the English on the <until>..<since> is a bit odd,\nand directly opposite the corresponding ordering from git-log:\n\n    <since>..<until>\n        Show only commits between the named two commits. When either\n        <since> or <until> is omitted, it defaults to HEAD, i.e. the tip\n        of the current branch. For a more complete list of ways to spell\n        <since> and <until>, see \"SPECIFYING REVISIONS\" section in\n        git-rev-parse(1).\n\nBut the real issue is that git-format-patch doesn't\neven mention <since>..<until> (or <until>..<since>)\nas its revision range specifier anywhere.  It says\n\n    [ <since> | <revision range> ]\n\nin its synopsis.\n\nAnd I wonder if it is just me or not, but I had to read this\nparagaph about 3 times and compare it to my already-known\nmental model of what format-patch does before I figured out\nwhat it was trying to say:\n\n    A single commit, when interpreted as a <revision range> expression,\n    means \"everything that leads to that commit\", but if you write git\n    format-patch <commit>, the previous rule applies to that command\n    line and you do not get \"everything since the beginning of the\n    time\". If you want to format everything since project inception to\n    one commit, say \"git format-patch --root <commit>\" to make it clear\n    that it is the latter case.\n\nGranted, that is a little out of context (\"the previous rule\" refers\nto this:\n\n    1. A single commit, <since>, specifies that the commits leading to\n       the tip of the current branch that are not in the history that\n       leads to the <since> to be output.\n\nSo, at the risk of complaining and not contributing, I'll\noffer this rewrite or clarification for the confusing paragraph\nand, if needed, followup with a patch unless someone else\nbeats me to it.\n\n    Other Git commands that receive a single commit, <commit>,\n    parameter as part of a range generally mean \"every commit\n    that contributes to and leads up to <commit>\".  However,\n    in the context of git-format-patch, that is generally not\n    the desired behavior; instead a single commit is interpreted\n    as a \"<since>\" parameter as if \"<commit>..HEAD\" were requested,\n    and specifies the commits leading to the tip of the current\n    branch that are not in the history up to and including <commit>.\n    If all commits from the root of the history up to the specified\n    commit are wanted, use \"--root <commit>\".\n\nIs a single commit, in fact, identical to \"<commit>..HEAD\"?\nShould we just state that straight up and be done with it?\n\njdl\n"}]}