From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 2 Apr 2009 05:49:03 +0000 (-0700)
Subject: Merge branch 'tr/maint-1.6.1-doc-format-patch--root'
X-Git-Tag: v1.6.3-rc0~49
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/85b7bd50c47e0f5236cdb93d1be3163a8a1a3be6?hp=-c

Merge branch 'tr/maint-1.6.1-doc-format-patch--root'

* tr/maint-1.6.1-doc-format-patch--root:
Documentation: format-patch --root clarifications
---

85b7bd50c47e0f5236cdb93d1be3163a8a1a3be6
diff --combined Documentation/git-format-patch.txt
index c2eb5fab4c,1f577b8016..c105925df8
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@@ -10,8 -10,7 +10,8 @@@ SYNOPSI
  --------
  [verse]
  'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
 -		   [--attach[=<boundary>] | --inline[=<boundary>]]
 +		   [--attach[=<boundary>] | --inline[=<boundary>] |
 +		     [--no-attach]]
  		   [-s | --signoff] [<common diff options>]
  		   [-n | --numbered | -N | --no-numbered]
  		   [--start-number <n>] [--numbered-files]
@@@ -40,15 -39,11 +40,11 @@@ There are two ways to specify which com
     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
@@@ -97,6 -92,7 +93,6 @@@ include::diff-options.txt[
  --numbered-files::
  	Output file names will be a simple number sequence
  	without the default first line of the commit appended.
 -	Mutually exclusive with the --stdout option.
  
  -k::
  --keep-subject::
@@@ -117,27 -113,15 +113,27 @@@
  	which is the commit message and the patch itself in the
  	second part, with "Content-Disposition: attachment".
  
 +--no-attach::
 +	Disable the creation of an attachment, overriding the
 +	configuration setting.
 +
  --inline[=<boundary>]::
  	Create multipart/mixed attachment, the first part of
  	which is the commit message and the patch itself in the
  	second part, with "Content-Disposition: inline".
  
 ---thread::
 +--thread[=<style>]::
  	Add In-Reply-To and References headers to make the second and
  	subsequent mails appear as replies to the first.  Also generates
  	the Message-Id header to reference.
 ++
 +The optional <style> argument can be either `shallow` or `deep`.
 +'Shallow' threading makes every mail a reply to the head of the
 +series, where the head is chosen from the cover letter, the
 +`\--in-reply-to`, and the first patch mail, in this order.  'Deep'
 +threading makes every mail a reply to the previous one.  If not
 +specified, defaults to the 'format.thread' configuration, or `shallow`
 +if that is not set.
  
  --in-reply-to=Message-Id::
  	Make the first mail (or all the mails with --no-thread) appear as a
@@@ -182,12 -166,18 +178,19 @@@ not add any suffix
  	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
  in the repository configuration, new defaults for the subject prefix
 -and file suffix, and number patches when outputting more than one.
 +and file suffix, control attachements, and number patches when outputting
 +more than one.
  
  ------------
  [format]
@@@ -196,7 -186,6 +199,7 @@@
  	suffix = .txt
  	numbered = auto
  	cc = <email>
 +	attach [ = mime-boundary-string ]
  ------------