X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-format-patch.txt;h=7426109f6251b7e4b3b37e0b785157c0d46ee9f7;hb=bf474e2402e51843e8230c064da6ccfdf3a8ff54;hp=5e6d5373ad595d58d2eac53e172099354ca55148;hpb=04b508f22b34e1b7461ab6414e1612547d87f08e;p=git.git diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 5e6d5373a..7426109f6 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -9,13 +9,16 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git-format-patch' [-n | -k] [-o | --stdout] [--thread] - [--attach[=] | --inline[=]] - [-s | --signoff] [] - [--start-number ] [--numbered-files] - [--in-reply-to=Message-Id] [--suffix=.] - [--ignore-if-in-upstream] - [--subject-prefix=Subject-Prefix] +'git format-patch' [-k] [-o | --stdout] [--thread] + [--attach[=] | --inline[=]] + [-s | --signoff] [] + [-n | --numbered | -N | --no-numbered] + [--start-number ] [--numbered-files] + [--in-reply-to=Message-Id] [--suffix=.] + [--ignore-if-in-upstream] + [--subject-prefix=Subject-Prefix] + [--cc=] + [--cover-letter] [ | ] DESCRIPTION @@ -24,7 +27,7 @@ DESCRIPTION Prepare each commit with its patch in one file per commit, formatted to resemble UNIX mailbox format. The output of this command is convenient for e-mail submission or -for use with gitlink:git-am[1]. +for use with 'git-am'. There are two ways to specify which commits to operate on. @@ -33,14 +36,18 @@ There are two ways to specify which commits to operate on. that leads to the to be output. 2. Generic expression (see "SPECIFYING - REVISIONS" section in gitlink:git-rev-parse[1]) means the - commits in the specified range. A single commit, when - interpreted as a expression, means - "everything that leads to that commit", but that is taken as - the special case above. If you want to format everything - since project inception to one commit, say "git format-patch - \--root ", as showing the root commit as patch - requires \--root option anyway. + REVISIONS" section in linkgit:git-rev-parse[1]) means the + commits in the specified range. + +A single commit, when interpreted as a +expression, means "everything that leads to that commit", but +if you write 'git format-patch ', 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 " 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 ". By default, each output file is numbered sequentially from 1, and uses the first line of the commit message (massaged for pathname safety) as @@ -55,25 +62,32 @@ they are created in the current working directory. If -n is specified, instead of "[PATCH] Subject", the first line is formatted as "[PATCH n/m] Subject". -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 as replies to the first mail; this also generates a Message-Id header to reference. OPTIONS ------- +:git-format-patch: 1 include::diff-options.txt[] -:: Limits the number of patches to prepare. --o|--output-directory :: +-o :: +--output-directory :: Use to store the resulting files, instead of the current working directory. --n|--numbered:: +-n:: +--numbered:: Name output in '[PATCH n/m]' format. +-N:: +--no-numbered:: + Name output in '[PATCH]' format. + --start-number :: Start numbering the patches at instead of 1. @@ -82,11 +96,13 @@ include::diff-options.txt[] without the default first line of the commit appended. Mutually exclusive with the --stdout option. --k|--keep-subject:: +-k:: +--keep-subject:: Do not strip/add '[PATCH]' from the first line of the commit log message. --s|--signoff:: +-s:: +--signoff:: Add `Signed-off-by:` line to the commit message, using the committer identity of yourself. @@ -127,6 +143,15 @@ include::diff-options.txt[] allows for useful naming of a patch series, and can be combined with the --numbered option. +--cc=:: + Add a "Cc:" header to the email headers. This is in addition + to any configured headers, and may be used multiple times. + +--cover-letter:: + In addition to the patches, generate a cover letter file + containing the shortlog and the overall diffstat. You can + fill in a description in the file before sending it out. + --suffix=.:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is @@ -137,58 +162,81 @@ want a filename like `0001-description-of-my-change.patch`, and the first letter does not have to be a dot. Leaving it empty would not add any suffix. +--no-binary:: + Don't output contents of changes in binary files, just take note + that they differ. Note that this disable the patch to be properly + applied. By default the contents of changes in those files are + encoded in the patch. + CONFIGURATION ------------- -You can specify extra mail header lines to be added to each -message in the repository configuration. You can also specify -new defaults for the subject prefix and file suffix. +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. ------------ [format] - headers = "Organization: git-foo\n" - subjectprefix = CHANGE - suffix = .txt + headers = "Organization: git-foo\n" + subjectprefix = CHANGE + suffix = .txt + numbered = auto + cc = ------------ EXAMPLES -------- -git-format-patch -k --stdout R1..R2 | git-am -3 -k:: - Extract commits between revisions R1 and R2, and apply - them on top of the current branch using `git-am` to - cherry-pick them. - -git-format-patch origin:: - Extract all commits which are in the current branch but - not in the origin branch. For each commit a separate file - is created in the current directory. - -git-format-patch \--root origin:: - Extract all commits which that leads to 'origin' since the - inception of the project. - -git-format-patch -M -B origin:: - The same as the previous one. Additionally, it detects - and handles renames and complete rewrites intelligently to - produce a renaming patch. A renaming patch reduces the - amount of text output, and generally makes it easier to - review it. Note that the "patch" program does not - understand renaming patches, so use it only when you know - the recipient uses git to apply your patch. - -git-format-patch -3:: - Extract three topmost commits from the current branch - and format them as e-mailable patches. - -See Also +* Extract commits between revisions R1 and R2, and apply them on top of +the current branch using 'git-am' to cherry-pick them: ++ +------------ +$ git format-patch -k --stdout R1..R2 | git am -3 -k +------------ + +* Extract all commits which are in the current branch but not in the +origin branch: ++ +------------ +$ git format-patch origin +------------ ++ +For each commit a separate file is created in the current directory. + +* Extract all commits that lead to 'origin' since the inception of the +project: ++ +------------ +$ git format-patch --root origin +------------ + +* The same as the previous one: ++ +------------ +$ git format-patch -M -B origin +------------ ++ +Additionally, it detects and handles renames and complete rewrites +intelligently to produce a renaming patch. A renaming patch reduces +the amount of text output, and generally makes it easier to review it. +Note that the "patch" program does not understand renaming patches, so +use it only when you know the recipient uses git to apply your patch. + +* Extract three topmost commits from the current branch and format them +as e-mailable patches: ++ +------------ +$ git format-patch -3 +------------ + +SEE ALSO -------- -gitlink:git-am[1], gitlink:git-send-email[1] +linkgit:git-am[1], linkgit:git-send-email[1] Author ------ -Written by Junio C Hamano +Written by Junio C Hamano Documentation -------------- @@ -196,4 +244,4 @@ Documentation by Junio C Hamano and the git-list . GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[1] suite