Merge branch 'bg/format-patch-doc-update'

* bg/format-patch-doc-update:
  format-patch: Add "--no-stat" as a synonym for "-p"
  format-patch documentation: Fix formatting
  format-patch documentation: Remove diff options that are not useful
  format-patch: Always generate a patch

1 files changed, 41 insertions, 20 deletions

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index e26b84706f..2b37193a37 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -14,7 +14,8 @@ endif::git-format-patch[]
 
 ifdef::git-format-patch[]
 -p::
-	Generate patches without diffstat.
+--no-stat::
+	Generate plain patches without any diffstats.
 endif::git-format-patch[]
 
 ifndef::git-format-patch[]
@@ -27,33 +28,40 @@ endif::git-format-patch[]
 -U<n>::
 --unified=<n>::
 	Generate diffs with <n> lines of context instead of
-	the usual three. Implies "-p".
+	the usual three.
+ifndef::git-format-patch[]
+	Implies `-p`.
+endif::git-format-patch[]
 
+ifndef::git-format-patch[]
 --raw::
 	Generate the raw format.
 	{git-diff-core? This is the default.}
+endif::git-format-patch[]
 
+ifndef::git-format-patch[]
 --patch-with-raw::
-	Synonym for "-p --raw".
+	Synonym for `-p --raw`.
+endif::git-format-patch[]
 
 --patience::
 	Generate a diff using the "patience diff" algorithm.
 
 --stat[=width[,name-width]]::
 	Generate a diffstat.  You can override the default
-	output width for 80-column terminal by "--stat=width".
+	output width for 80-column terminal by `--stat=width`.
 	The width of the filename part can be controlled by
 	giving another width to it separated by a comma.
 
 --numstat::
-	Similar to \--stat, but shows number of added and
+	Similar to `\--stat`, but shows number of added and
 	deleted lines in decimal notation and pathname without
 	abbreviation, to make it more machine friendly.  For
 	binary files, outputs two `-` instead of saying
 	`0 0`.
 
 --shortstat::
-	Output only the last line of the --stat format containing total
+	Output only the last line of the `--stat` format containing total
 	number of modified files, as well as number of added and deleted
 	lines.
 
@@ -61,24 +69,26 @@ endif::git-format-patch[]
 	Output the distribution of relative amount of changes (number of lines added or
 	removed) for each sub-directory. Directories with changes below
 	a cut-off percent (3% by default) are not shown. The cut-off percent
-	can be set with "--dirstat=limit". Changes in a child directory is not
-	counted for the parent directory, unless "--cumulative" is used.
+	can be set with `--dirstat=limit`. Changes in a child directory is not
+	counted for the parent directory, unless `--cumulative` is used.
 
 --dirstat-by-file[=limit]::
-	Same as --dirstat, but counts changed files instead of lines.
+	Same as `--dirstat`, but counts changed files instead of lines.
 
 --summary::
 	Output a condensed summary of extended header information
 	such as creations, renames and mode changes.
 
+ifndef::git-format-patch[]
 --patch-with-stat::
-	Synonym for "-p --stat".
-	{git-format-patch? This is the default.}
+	Synonym for `-p --stat`.
+endif::git-format-patch[]
 
+ifndef::git-format-patch[]
 -z::
-	NUL-line termination on output.  This affects the --raw
+	NUL-line termination on output.  This affects the `--raw`
 	output field terminator.  Also output from commands such
-	as "git-log" will be delimited with NUL between commits.
+	as `git-log` will be delimited with NUL between commits.
 
 --name-only::
 	Show only names of changed files.
@@ -117,16 +127,19 @@ The regex can also be set via a diff driver or configuration option, see
 linkgit:gitattributes[1] or linkgit:git-config[1].  Giving it explicitly
 overrides any diff driver or configuration setting.  Diff drivers
 override configuration settings.
+endif::git-format-patch[]
 
 --no-renames::
 	Turn off rename detection, even when the configuration
 	file gives the default to do so.
 
+ifndef::git-format-patch[]
 --check::
 	Warn if changes introduce trailing whitespace
 	or an indent that uses a space before a tab. Exits with
 	non-zero status if problems are found. Not compatible with
 	--exit-code.
+endif::git-format-patch[]
 
 --full-index::
 	Instead of the first handful of characters, show the full
@@ -134,16 +147,16 @@ override configuration settings.
 	line when generating patch format output.
 
 --binary::
-	In addition to --full-index, output "binary diff" that
-	can be applied with "git apply".
+	In addition to `--full-index`, output a binary diff that
+	can be applied with `git-apply`.
 
 --abbrev[=<n>]::
 	Instead of showing the full 40-byte hexadecimal object
 	name in diff-raw format output and diff-tree header
 	lines, show only a partial prefix.  This is
-	independent of --full-index option above, which controls
+	independent of the `--full-index` option above, which controls
 	the diff-patch output format.  Non default number of
-	digits can be specified with --abbrev=<n>.
+	digits can be specified with `--abbrev=<n>`.
 
 -B::
 	Break complete rewrite changes into pairs of delete and create.
@@ -154,6 +167,7 @@ override configuration settings.
 -C::
 	Detect copies as well as renames.  See also `--find-copies-harder`.
 
+ifndef::git-format-patch[]
 --diff-filter=[ACDMRTUXB*]::
 	Select only files that are Added (`A`), Copied (`C`),
 	Deleted (`D`), Modified (`M`), Renamed (`R`), have their
@@ -165,6 +179,7 @@ override configuration settings.
 	paths are selected if there is any file that matches
 	other criteria in the comparison; if there is no file
 	that matches other criteria, nothing is selected.
+endif::git-format-patch[]
 
 --find-copies-harder::
 	For performance reasons, by default, `-C` option finds copies only
@@ -176,12 +191,13 @@ override configuration settings.
 	`-C` option has the same effect.
 
 -l<num>::
-	-M and -C options require O(n^2) processing time where n
+	The `-M` and `-C` options require O(n^2) processing time where n
 	is the number of potential rename/copy targets.  This
 	option prevents rename/copy detection from running if
 	the number of rename/copy targets exceeds the specified
 	number.
 
+ifndef::git-format-patch[]
 -S<string>::
 	Look for differences that introduce or remove an instance of
 	<string>. Note that this is different than the string simply
@@ -189,18 +205,20 @@ override configuration settings.
 	linkgit:gitdiffcore[7] for more details.
 
 --pickaxe-all::
-	When -S finds a change, show all the changes in that
+	When `-S` finds a change, show all the changes in that
 	changeset, not just the files that contain the change
 	in <string>.
 
 --pickaxe-regex::
 	Make the <string> not a plain string but an extended POSIX
 	regex to match.
+endif::git-format-patch[]
 
 -O<orderfile>::
 	Output the patch in the order specified in the
 	<orderfile>, which has one shell glob pattern per line.
 
+ifndef::git-format-patch[]
 -R::
 	Swap two inputs; that is, show differences from index or
 	on-disk file to tree contents.
@@ -212,6 +230,7 @@ override configuration settings.
 	not in a subdirectory (e.g. in a bare repository), you
 	can name which subdirectory to make the output relative
 	to by giving a <path> as an argument.
+endif::git-format-patch[]
 
 -a::
 --text::
@@ -236,13 +255,15 @@ override configuration settings.
 	Show the context between diff hunks, up to the specified number
 	of lines, thereby fusing hunks that are close to each other.
 
+ifndef::git-format-patch[]
 --exit-code::
 	Make the program exit with codes similar to diff(1).
 	That is, it exits with 1 if there were differences and
 	0 means no differences.
 
 --quiet::
-	Disable all output of the program. Implies --exit-code.
+	Disable all output of the program. Implies `--exit-code`.
+endif::git-format-patch[]
 
 --ext-diff::
 	Allow an external diff helper to be executed. If you set an