Documentation: format-patch --root clarifications

Users were confused about the meaning and use of the --root option.
Notably, since 68c2ec7 (format-patch: show patch text for the root
commit, 2009-01-10), --root has nothing to do with showing the patch
text for the root commit any more.

Shorten and clarify the corresponding paragraph in the DESCRIPTION
section, document --root under OPTIONS, and add an explicit note that
root commits are formatted regardless.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 11a7d772618f48b961d41fb5fe1cb269d7ae7cd1..1f577b8016156871debcbb17fc32af9f7a6082f4 100644 (file)
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -39,15 +39,11 @@ There are two ways to specify which commits to operate on.
    REVISIONS" section in linkgit:git-rev-parse[1]) means the
    commits in the specified range.
 
    REVISIONS" section in linkgit:git-rev-parse[1]) means the
    commits in the specified range.
 

-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.  If you want to format a single commit, you can do
-this with "git format-patch -1 <commit>".
+The first rule takes precedence in the case of a single <commit>.  To
+apply the second rule, i.e., format everything since the beginning of
+history up until <commit>, use the '\--root' option: "git format-patch
+\--root <commit>".  If you want to format only <commit> itself, you
+can do this with "git format-patch -1 <commit>".

 
 By default, each output file is numbered sequentially from 1, and uses the
 first line of the commit message (massaged for pathname safety) as
 
 By default, each output file is numbered sequentially from 1, and uses the
 first line of the commit message (massaged for pathname safety) as


@@ -170,6 +166,13 @@ not add any suffix.
        applied.  By default the contents of changes in those files are
        encoded in the patch.
 
        applied.  By default the contents of changes in those files are
        encoded in the patch.
 

+--root::
+       Treat the revision argument as a <revision range>, even if it
+       is just a single commit (that would normally be treated as a
+       <since>).  Note that root commits included in the specified
+       range are always formatted as creation patches, independently
+       of this flag.
+

 CONFIGURATION
 -------------
 You can specify extra mail header lines to be added to each message
 CONFIGURATION
 -------------
 You can specify extra mail header lines to be added to each message