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>
Thomas Rast committed
Mar 26, 2009 at 18:29 UTC
2d266f9d623625e0a28fbe3c3615707500e9448f
1 file changed
+12
-9
Documentation/git-format-patch.txt
+12
-9
@@ -39,15 +39,11 @@ There are two ways to specify which commits to operate on.
39
REVISIONS" section in linkgit:git-rev-parse[1]) means the
40
commits in the specified range.
41
42
-A single commit, when interpreted as a <revision range>
43
-expression, means "everything that leads to that commit", but
44
-if you write 'git format-patch <commit>', the previous rule
45
-applies to that command line and you do not get "everything
46
-since the beginning of the time". If you want to format
47
-everything since project inception to one commit, say "git
48
-format-patch \--root <commit>" to make it clear that it is the
49
-latter case. If you want to format a single commit, you can do
50
-this with "git format-patch -1 <commit>".
42
+The first rule takes precedence in the case of a single <commit>. To
43
+apply the second rule, i.e., format everything since the beginning of
44
+history up until <commit>, use the '\--root' option: "git format-patch
45
+\--root <commit>". If you want to format only <commit> itself, you
46
+can do this with "git format-patch -1 <commit>".
47
48
By default, each output file is numbered sequentially from 1, and uses the
49
first line of the commit message (massaged for pathname safety) as
@@ -170,6 +166,13 @@ not add any suffix.
166
applied. By default the contents of changes in those files are
167
encoded in the patch.
168
169
+--root::
170
+ Treat the revision argument as a <revision range>, even if it
171
+ is just a single commit (that would normally be treated as a
172
+ <since>). Note that root commits included in the specified
173
+ range are always formatted as creation patches, independently
174
+ of this flag.
175
+
176
CONFIGURATION
177
-------------
178
You can specify extra mail header lines to be added to each message