From: Junio C Hamano Date: Mon, 16 May 2011 23:39:09 +0000 (-0700) Subject: Merge branch 'jn/maint-format-patch-doc' into maint X-Git-Tag: v1.7.5.2~3 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/4bbfd8e3da6d5fde8f1e98900523996fd138d9fc?ds=inline;hp=-c Merge branch 'jn/maint-format-patch-doc' into maint * jn/maint-format-patch-doc: Documentation: describe the format of messages with inline patches --- 4bbfd8e3da6d5fde8f1e98900523996fd138d9fc diff --combined Documentation/git-format-patch.txt index f4e959d662,eebfa5c64a..66aba8a2e9 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@@ -20,7 -20,7 +20,7 @@@ SYNOPSI [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] [--to=] [--cc=] - [--cover-letter] + [--cover-letter] [--quiet] [] [ | ] @@@ -196,9 -196,6 +196,9 @@@ will want to ensure that threading is d Note that the leading character does not have to be a dot; for example, you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. +--quiet:: + Do not print the names of the generated files to standard output. + --no-binary:: Do not output contents of changes in binary files, instead display a notice that those files changed. Patches generated @@@ -232,6 -229,64 +232,64 @@@ attachments, and sign off patches with ------------ + DISCUSSION + ---------- + + The patch produced by 'git format-patch' is in UNIX mailbox format, + with a fixed "magic" time stamp to indicate that the file is output + from format-patch rather than a real mailbox, like so: + + ------------ + From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001 + From: Tony Luck + Date: Tue, 13 Jul 2010 11:42:54 -0700 + Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?= + =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?= + MIME-Version: 1.0 + Content-Type: text/plain; charset=UTF-8 + Content-Transfer-Encoding: 8bit + + arch/arm config files were slimmed down using a python script + (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment) + + Do the same for ia64 so we can have sleek & trim looking + ... + ------------ + + Typically it will be placed in a MUA's drafts folder, edited to add + timely commentary that should not go in the changelog after the three + dashes, and then sent as a message whose body, in our example, starts + with "arch/arm config files were...". On the receiving end, readers + can save interesting patches in a UNIX mailbox and apply them with + linkgit:git-am[1]. + + When a patch is part of an ongoing discussion, the patch generated by + 'git format-patch' can be tweaked to take advantage of the 'git am + --scissors' feature. After your response to the discussion comes a + line that consists solely of "`-- >8 --`" (scissors and perforation), + followed by the patch with unnecessary header fields removed: + + ------------ + ... + > So we should do such-and-such. + + Makes sense to me. How about this patch? + + -- >8 -- + Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet + + arch/arm config files were slimmed down using a python script + ... + ------------ + + When sending a patch this way, most often you are sending your own + patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you + should omit `From:` and `Date:` lines from the patch file. The patch + title is likely to be different from the subject of the discussion the + patch is in response to, so it is likely that you would want to keep + the Subject: line, like the example above. + + EXAMPLES -------- @@@ -281,6 -336,15 +339,6 @@@ SEE ALS -------- linkgit:git-am[1], linkgit:git-send-email[1] - -Author ------- -Written by Junio C Hamano - -Documentation --------------- -Documentation by Junio C Hamano and the git-list . - GIT --- Part of the linkgit:git[1] suite