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
This commit is contained in:
Junio C Hamano 2009-11-20 23:47:10 -08:00
commit 1a02a85d63
4 changed files with 99 additions and 50 deletions

View File

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

View File

@ -43,28 +43,28 @@ There are two ways to specify which commits to operate on.
The first rule takes precedence in the case of a single <commit>. To 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 apply the second rule, i.e., format everything since the beginning of
history up until <commit>, use the '\--root' option: "git format-patch history up until <commit>, use the '\--root' option: `git format-patch
\--root <commit>". If you want to format only <commit> itself, you \--root <commit>`. If you want to format only <commit> itself, you
can do this with "git format-patch -1 <commit>". can do this with `git format-patch -1 <commit>`.
By default, each output file is numbered sequentially from 1, and uses the By default, each output file is numbered sequentially from 1, and uses the
first line of the commit message (massaged for pathname safety) as first line of the commit message (massaged for pathname safety) as
the filename. With the --numbered-files option, the output file names the filename. With the `--numbered-files` option, the output file names
will only be numbers, without the first line of the commit appended. will only be numbers, without the first line of the commit appended.
The names of the output files are printed to standard The names of the output files are printed to standard
output, unless the --stdout option is specified. output, unless the `--stdout` option is specified.
If -o is specified, output files are created in <dir>. Otherwise If `-o` is specified, output files are created in <dir>. Otherwise
they are created in the current working directory. they are created in the current working directory.
By default, the subject of a single patch is "[PATCH] First Line" and By default, the subject of a single patch is "[PATCH] First Line" and
the subject when multiple patches are output is "[PATCH n/m] First the subject when multiple patches are output is "[PATCH n/m] First
Line". To force 1/1 to be added for a single patch, use -n. To omit Line". To force 1/1 to be added for a single patch, use `-n`. To omit
patch numbers from the subject, use -N patch numbers from the subject, use `-N`.
If given --thread, 'git-format-patch' will generate In-Reply-To and If given `--thread`, `git-format-patch` will generate `In-Reply-To` and
References headers to make the second and subsequent patch mails appear `References` headers to make the second and subsequent patch mails appear
as replies to the first mail; this also generates a Message-Id header to as replies to the first mail; this also generates a `Message-Id` header to
reference. reference.
OPTIONS OPTIONS
@ -112,7 +112,7 @@ include::diff-options.txt[]
--attach[=<boundary>]:: --attach[=<boundary>]::
Create multipart/mixed attachment, the first part of Create multipart/mixed attachment, the first part of
which is the commit message and the patch itself in the which is the commit message and the patch itself in the
second part, with "Content-Disposition: attachment". second part, with `Content-Disposition: attachment`.
--no-attach:: --no-attach::
Disable the creation of an attachment, overriding the Disable the creation of an attachment, overriding the
@ -121,13 +121,13 @@ include::diff-options.txt[]
--inline[=<boundary>]:: --inline[=<boundary>]::
Create multipart/mixed attachment, the first part of Create multipart/mixed attachment, the first part of
which is the commit message and the patch itself in the which is the commit message and the patch itself in the
second part, with "Content-Disposition: inline". second part, with `Content-Disposition: inline`.
--thread[=<style>]:: --thread[=<style>]::
--no-thread:: --no-thread::
Controls addition of In-Reply-To and References headers to Controls addition of `In-Reply-To` and `References` headers to
make the second and subsequent mails appear as replies to the make the second and subsequent mails appear as replies to the
first. Also controls generation of the Message-Id header to first. Also controls generation of the `Message-Id` header to
reference. reference.
+ +
The optional <style> argument can be either `shallow` or `deep`. The optional <style> argument can be either `shallow` or `deep`.
@ -136,16 +136,16 @@ series, where the head is chosen from the cover letter, the
`\--in-reply-to`, and the first patch mail, in this order. 'deep' `\--in-reply-to`, and the first patch mail, in this order. 'deep'
threading makes every mail a reply to the previous one. threading makes every mail a reply to the previous one.
+ +
The default is --no-thread, unless the 'format.thread' configuration The default is `--no-thread`, unless the 'format.thread' configuration
is set. If --thread is specified without a style, it defaults to the is set. If `--thread` is specified without a style, it defaults to the
style specified by 'format.thread' if any, or else `shallow`. style specified by 'format.thread' if any, or else `shallow`.
+ +
Beware that the default for 'git send-email' is to thread emails Beware that the default for 'git send-email' is to thread emails
itself. If you want 'git format-patch' to take care of hreading, you itself. If you want `git format-patch` to take care of threading, you
will want to ensure that threading is disabled for 'git send-email'. will want to ensure that threading is disabled for `git send-email`.
--in-reply-to=Message-Id:: --in-reply-to=Message-Id::
Make the first mail (or all the mails with --no-thread) appear as a Make the first mail (or all the mails with `--no-thread`) appear as a
reply to the given Message-Id, which avoids breaking threads to reply to the given Message-Id, which avoids breaking threads to
provide a new patch series. provide a new patch series.
@ -160,16 +160,16 @@ will want to ensure that threading is disabled for 'git send-email'.
Instead of the standard '[PATCH]' prefix in the subject Instead of the standard '[PATCH]' prefix in the subject
line, instead use '[<Subject-Prefix>]'. This line, instead use '[<Subject-Prefix>]'. This
allows for useful naming of a patch series, and can be allows for useful naming of a patch series, and can be
combined with the --numbered option. combined with the `--numbered` option.
--cc=<email>:: --cc=<email>::
Add a "Cc:" header to the email headers. This is in addition Add a `Cc:` header to the email headers. This is in addition
to any configured headers, and may be used multiple times. to any configured headers, and may be used multiple times.
--add-header=<header>:: --add-header=<header>::
Add an arbitrary header to the email headers. This is in addition Add an arbitrary header to the email headers. This is in addition
to any configured headers, and may be used multiple times. to any configured headers, and may be used multiple times.
For example, --add-header="Organization: git-foo" For example, `--add-header="Organization: git-foo"`
--cover-letter:: --cover-letter::
In addition to the patches, generate a cover letter file In addition to the patches, generate a cover letter file

View File

@ -927,10 +927,11 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)
PARSE_OPT_NOARG | PARSE_OPT_NONEG, keep_callback }, PARSE_OPT_NOARG | PARSE_OPT_NONEG, keep_callback },
OPT_BOOLEAN(0, "no-binary", &no_binary_diff, OPT_BOOLEAN(0, "no-binary", &no_binary_diff,
"don't output binary diffs"), "don't output binary diffs"),
OPT_BOOLEAN('p', NULL, &use_patch_format,
"show patch format instead of default (patch + stat)"),
OPT_BOOLEAN(0, "ignore-if-in-upstream", &ignore_if_in_upstream, OPT_BOOLEAN(0, "ignore-if-in-upstream", &ignore_if_in_upstream,
"don't include a patch matching a commit upstream"), "don't include a patch matching a commit upstream"),
{ OPTION_BOOLEAN, 'p', "no-stat", &use_patch_format, NULL,
"show patch format instead of default (patch + stat)",
PARSE_OPT_NONEG | PARSE_OPT_NOARG },
OPT_GROUP("Messaging"), OPT_GROUP("Messaging"),
{ OPTION_CALLBACK, 0, "add-header", NULL, "header", { OPTION_CALLBACK, 0, "add-header", NULL, "header",
"add email header", PARSE_OPT_NONEG, "add email header", PARSE_OPT_NONEG,
@ -1036,11 +1037,20 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)
if (argc > 1) if (argc > 1)
die ("unrecognized argument: %s", argv[1]); die ("unrecognized argument: %s", argv[1]);
if (use_patch_format) if (rev.diffopt.output_format & DIFF_FORMAT_NAME)
rev.diffopt.output_format |= DIFF_FORMAT_PATCH; die("--name-only does not make sense");
else if (!rev.diffopt.output_format || if (rev.diffopt.output_format & DIFF_FORMAT_NAME_STATUS)
rev.diffopt.output_format == DIFF_FORMAT_PATCH) die("--name-status does not make sense");
rev.diffopt.output_format = DIFF_FORMAT_DIFFSTAT | DIFF_FORMAT_SUMMARY | DIFF_FORMAT_PATCH; if (rev.diffopt.output_format & DIFF_FORMAT_CHECKDIFF)
die("--check does not make sense");
if (!use_patch_format &&
(!rev.diffopt.output_format ||
rev.diffopt.output_format == DIFF_FORMAT_PATCH))
rev.diffopt.output_format = DIFF_FORMAT_DIFFSTAT | DIFF_FORMAT_SUMMARY;
/* Always generate a patch */
rev.diffopt.output_format |= DIFF_FORMAT_PATCH;
if (!DIFF_OPT_TST(&rev.diffopt, TEXT) && !no_binary_diff) if (!DIFF_OPT_TST(&rev.diffopt, TEXT) && !no_binary_diff)
DIFF_OPT_SET(&rev.diffopt, BINARY); DIFF_OPT_SET(&rev.diffopt, BINARY);

View File

@ -536,4 +536,22 @@ test_expect_success 'format-patch --signoff' '
grep "^Signed-off-by: $GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>" grep "^Signed-off-by: $GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>"
' '
echo "fatal: --name-only does not make sense" > expect.name-only
echo "fatal: --name-status does not make sense" > expect.name-status
echo "fatal: --check does not make sense" > expect.check
test_expect_success 'options no longer allowed for format-patch' '
test_must_fail git format-patch --name-only 2> output &&
test_cmp expect.name-only output &&
test_must_fail git format-patch --name-status 2> output &&
test_cmp expect.name-status output &&
test_must_fail git format-patch --check 2> output &&
test_cmp expect.check output'
test_expect_success 'format-patch --numstat should produce a patch' '
git format-patch --numstat --stdout master..side |
grep "^diff --git a/" |
wc -l |
xargs test 6 = '
test_done test_done