X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-format-patch.txt;h=84eabebe0bc767112805d2d35c68ad000d8e1003;hb=f45fa2a073da591f3ac0b63900e07afa2dccee44;hp=7a3abec02e5b07533d11322b2ab9a3a89d2bd0d6;hpb=72e5890b68e7199d92620d3bba91fa36dd259404;p=git.git diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 7a3abec02..84eabebe0 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -3,61 +3,114 @@ git-format-patch(1) NAME ---- -git-format-patch - Prepare patches for e-mail submission. +git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- -'git-format-patch' [-n][-o |--stdout][-k][--mbox][--diff-options] [] +[verse] +'git-format-patch' [] [-n | -k] [-o | --stdout] + [--attach] [--thread] [-s | --signoff] [--start-number ] + [--in-reply-to=Message-Id] [--suffix=.] + [--ignore-if-in-upstream] + [..] DESCRIPTION ----------- -Prepare each commit with its patch since head forked from - head, one file per patch, for e-mail submission. Each -output file is numbered sequentially from 1, and uses the first -line of the commit message (massaged for pathname safety) as the -filename. -When -o is specified, output files are created in that -directory; otherwise in the current working directory. +Prepare each commit between and with its patch in +one file per commit, formatted to resemble UNIX mailbox format. +If .. is not specified, the head of the current working +tree is implied. For a more complete list of ways to spell + and , see "SPECIFYING REVISIONS" section in +gitlink:git-rev-parse[1]. -When -n is specified, instead of "[PATCH] Subject", the first -line is formatted as "[PATCH N/M] Subject", unless you have only -one patch. +The output of this command is convenient for e-mail submission or +for use with gitlink:git-am[1]. -When --mbox is specified, the output is formatted to resemble -UNIX mailbox format, and can be concatenated together for -processing with applymbox. +Each output file is numbered sequentially from 1, and uses the +first line of the commit message (massaged for pathname safety) as +the filename. The names of the output files are printed to standard +output, unless the --stdout option is specified. +If -o is specified, output files are created in . Otherwise +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 +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 ------- --o :: +include::diff-options.txt[] + +-o|--output-directory :: Use to store the resulting files, instead of the current working directory. --n:: +-n|--numbered:: Name output in '[PATCH n/m]' format. --k:: +--start-number :: + Start numbering the patches at instead of 1. + +-k|--keep-subject:: Do not strip/add '[PATCH]' from the first line of the commit log message. ---author, --date:: - Output From: and Date: headers for commits made by - yourself as well. Usually these are output only for - commits made by people other than yourself. - ---mbox:: - Format the output files for closer to mbox format by - adding a phony Unix "From " line, so they can be - concatenated together and fed to `git-applymbox`. - Implies --author and --date. +-s|--signoff:: + Add `Signed-off-by:` line to the commit message, using + the committer identity of yourself. --stdout:: - This flag generates the mbox formatted output to the - standard output, instead of saving them into a file per - patch and implies --mbox. + Print all commits to the standard output in mbox format, + instead of creating a file for each one. + +--attach:: + Create attachments instead of inlining patches. + +--thread:: + 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. + +--in-reply-to=Message-Id:: + 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 + provide a new patch series. + +--ignore-if-in-upstream:: + Do not include a patch that matches a commit in + ... This will examine all patches reachable + from but not from and compare them with the + patches being generated, and any patch that matches is + ignored. + +--suffix=.:: + Instead of using `.patch` as the suffix for generated + filenames, use specifed suffix. A common alternative is + `--suffix=.txt`. ++ +Note that you would need to include the leading dot `.` if you +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. + +CONFIGURATION +------------- +You can specify extra mail header lines to be added to each +message in the repository configuration. Also you can specify +the default suffix different from the built-in one: + +------------ +[format] + headers = "Organization: git-foo\n" + suffix = .txt +------------ EXAMPLES @@ -69,14 +122,26 @@ git-format-patch -k --stdout R1..R2 | git-am -3 -k:: cherry-pick them. git-format-patch origin:: - Extract commits the current branch accumulated since it - pulled from origin the last time in a patch form for - e-mail submission. - + 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 -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 -------- -gitlink:git-am[1], gitlink:git-send-email +gitlink:git-am[1], gitlink:git-send-email[1] Author