path: root/Documentation/git-format-patch.txt
AgeCommit message (Collapse)Author
2012-04-26docs: stop using asciidoc no-inline-literalJeff King
In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <>` used to erroneously auto-generate a mailto footnote for - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2011-08-29Document negated forms of format-patch --to --cc --add-headersThomas Rast
The negated forms introduced in c426003 (format-patch: add --no-cc, --no-to, and --no-add-headers, 2010-03-07) were not documented anywhere. Add them to the descriptions of the positive forms. Signed-off-by: Thomas Rast <> Signed-off-by: Junio C Hamano <>
2011-05-04Merge branch 'jn/format-patch-doc'Junio C Hamano
* jn/format-patch-doc: Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird Documentation: publicize hints for sending patches with GMail Documentation: publicize KMail hints for sending patches inline Documentation: hints for sending patches inline with Thunderbird Documentation: explain how to check for patch corruption
2011-05-04Merge branch 'jn/maint-format-patch-doc'Junio C Hamano
* jn/maint-format-patch-doc: Documentation: describe the format of messages with inline patches
2011-04-19Documentation/format-patch: suggest Toggle Word Wrap add-on for ThunderbirdJohannes Sixt
Of the (now) three methods to send unmangled patches using Thunderbird, this method is listed first because it provides a single-click on-demand option rather than a permanent change of configuration like the other two methods. Signed-off-by: Johannes Sixt <> Signed-off-by: Junio C Hamano <>
2011-04-15Documentation: publicize hints for sending patches with GMailJonathan Nieder
The hints in SubmittingPatches about stopping GMail from clobbering patches are widely useful both as examples of "git send-email" and "git imap-send" usage. Move the documentation to the appropriate places. While at it, don't encourage storing passwords in config files. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2011-04-15Documentation: publicize KMail hints for sending patches inlineJonathan Nieder
These hints are in git's private SubmittingPatches document but a wider audience might be interested. Move them to the "git format-patch" manpage. I'm not sure what gotchas these hints are meant to work around. They might be completely false. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2011-04-15Documentation: hints for sending patches inline with ThunderbirdJonathan Nieder
The standard reference for this information is the article "Plain text e-mail - Thunderbird#Completely_plain_email" at, but the hints hidden away in git's SubmittingPatches file are more complete. Move them to the "git format-patch" manual so they can be installed with git and read by a wide audience. While at it, make some tweaks: - update "Approach #1" so it might work with Thunderbird 3; - remove ancient version numbers from the descriptions of both approaches so current readers might have more reason to complain if they don't work. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2011-04-15Documentation: explain how to check for patch corruptionJonathan Nieder
SubmittingPatches has some excellent advice about how to check a patch for corruption before sending it off. Move it to the format-patch manual so it can be installed with git's documentation for use by people not necessarily interested in the git project's practices. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2011-04-15Merge v1.7.5-rc2 into jn/format-patch-docJunio C Hamano
This is to sync with the recent updates in Documentation/SubmittingPatches and Documentation/format-patch.txt
2011-04-15Documentation: describe the format of messages with inline patchesJonathan Nieder
Add a DISCUSSION section to the "git format-patch" manual to encourage people to send patches in a form that can be applied by "git am" automatically. There are two such forms: 1. The default form in which most metadata goes in the mail header and the message body starts with the patch description; 2. The snipsnip form in which a message starts with pertinent discussion and ends with a patch after a "scissors" mark. The example requires QP encoding in the "Subject:" header intended for the mailer to give the reader a chance to reflect on that, rather than being startled by it later. By contrast, in-body "From:" and "Subject:" lines should be human-readable and not QP encoded. Inspired-by: Jim Meyering <> Signed-off-by: Jonathan Nieder <> Improved-by: Junio C Hamano <> Improved-by: Drew Northup <> Signed-off-by: Junio C Hamano <>
2011-04-12format-patch: document --quiet optionCarlos Martín Nieto
Signed-off-by: Carlos Martín Nieto <> Signed-off-by: Junio C Hamano <>
2011-03-11doc: drop author/documentation sections from most pagesJeff King
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2010-10-14Merge branch 'maint'Junio C Hamano
* maint: Better advice on using topic branches for kernel development Documentation: update implicit "--no-index" behavior in "git diff" Documentation: expand 'git diff' SEE ALSO section Documentation: diff can compare blobs Documentation: gitrevisions is in section 7 shell portability: no "export VAR=VAL" CodingGuidelines: reword parameter expansion section Documentation: update-index: -z applies also to --index-info Documentation: No argument of ALLOC_GROW should have side-effects
2010-10-14Documentation: gitrevisions is in section 7Jonathan Nieder
Fix references to gitrevisions(1) in the manual pages and HTML documentation. In practice, this will not matter much unless someone tries to use a hard copy of the git reference manual. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-09-29Merge branch 'rr/format-patch-count-without-merges'Junio C Hamano
* rr/format-patch-count-without-merges: format-patch: Don't go over merge commits t4014-format-patch: Call test_tick before committing
2010-08-27format-patch: Don't go over merge commitsRamkumar Ramachandra
If the topmost three commits in a branch were merge commits, 'git format-patch -3' used to output nothing. Since Git can't prepare patches out of merge commits anyway, don't go over them in the first place. 'git format-patch -3' now prepares three patches from the topmost three commits without counting merge commits. Also add a corresponding test in t4014-format-patch and update documentation. Signed-off-by: Ramkumar Ramachandra <> Signed-off-by: Junio C Hamano <>
2010-07-05Documentation: link to gitrevisions rather than git-rev-parseMichael J Gruber
Currently, whenever we need documentation for revisions and ranges, we link to the git-rev-parse man page, i.e. a plumbing man page, which has this along with the documentation of all rev-parse modes. Link to the new gitrevisions man page instead in all cases except - when the actual git-rev-parse command is referred to or - in very technical context (git-send-pack). Signed-off-by: Michael J Gruber <> Signed-off-by: Junio C Hamano <>
2010-06-16format-patch: Add a signature option (--signature)Stephen Boyd
By default, git uses the version string as the signature for all patches output by format-patch. Many employers (mine included) require the use of a signature on all outgoing mails. In a format-patch | send-email workflow there isn't an easy way to modify the signature without breaking the pipe and manually replacing the version string with the signature required. Instead of doing all that work, add an option (--signature) and a config variable (format.signature) to replace the default git version signature when formatting patches. This does modify the original behavior of format-patch a bit. First off the version string is now placed in the cover letter by default. Secondly, once the configuration variable format.signature is added to the .config file there is no way to revert back to the default git version signature. Instead, specifying the --no-signature option will remove the signature from the patches entirely. Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2010-03-07Add 'git format-patch --to=' option and '' configuration variable.Steven Drake
Has the same functionality as the '--cc' option and '' configuration variable but for the "To:" email header. Half of the code to support this was already there. With email the To: header usually more important than the Cc: header. [jc: tests are by Stephen Boyd] Signed-off-by: Steven Drake <> Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2010-01-10Documentation: spell 'git cmd' without dash throughoutThomas Rast
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2009-11-10format-patch documentation: Fix formattingBjörn Gustavsson
Format git commands and options consistently using back quotes (i.e. a fixed font in the resulting HTML document). Signed-off-by: Björn Gustavsson <> Signed-off-by: Junio C Hamano <>
2009-07-23Improve doc for format-patch threading options.Yann Dirson
This hopefully makes the relationship between threading options of format-patch and send-email easier to grasp. Signed-off-by: Yann Dirson <> Signed-off-by: Junio C Hamano <>
2009-04-23git-format-patch.txt: general rewordings and cleanupsStephen Boyd
Clarify --no-binary description using some words from the original commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix description. Add --thread style option to synopsis and reorganize it a bit. Clarify renaming patches example and the configuration paragraph. Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2009-04-23Documentation: use lowercase for shallow and deep threadingStephen Boyd
Even when a sentence is started with 'shallow' or 'deep' use the lowercase version to maintain consistency. Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2009-04-20Documentation: fix typos / spelling mistakesMike Ralphson
Signed-off-by: Mike Ralphson <> Signed-off-by: Junio C Hamano <>
2009-04-06Add configuration variable for sign-off to format-patchHeiko Voigt
If you regularly create patches which require a Signed-off: line you may want to make it your default to add that line. It also helps you not to forget to add the -s/--signoff switch. Signed-off-by: Heiko Voigt <> Signed-off-by: Junio C Hamano <>
2009-04-02Merge branch 'mh/format-patch-add-header'Junio C Hamano
* mh/format-patch-add-header: format-patch: add arbitrary email headers
2009-04-02Merge branch 'tr/maint-1.6.1-doc-format-patch--root'Junio C Hamano
* tr/maint-1.6.1-doc-format-patch--root: Documentation: format-patch --root clarifications
2009-03-28format-patch: add arbitrary email headersMichael Hendricks
format-patch supports the format.headers configuration for adding arbitrary email headers to the patches it outputs. This patch adds support for an --add-header argument which makes the same feature available from the command line. This is useful when the content of custom email headers must change from branch to branch. This patch has been sponsored by Grant Street Group Signed-off-by: Michael Hendricks <> Signed-off-by: Junio C Hamano <>
2009-03-27Documentation: format-patch --root clarificationsThomas Rast
Users were confused about the meaning and use of the --root option. Notably, since 68c2ec7 (format-patch: show patch text for the root commit, 2009-01-10), --root has nothing to do with showing the patch text for the root commit any more. Shorten and clarify the corresponding paragraph in the DESCRIPTION section, document --root under OPTIONS, and add an explicit note that root commits are formatted regardless. Signed-off-by: Thomas Rast <> Signed-off-by: Junio C Hamano <>
2009-03-22Sync with maintJunio C Hamano
Signed-off-by: Junio C Hamano <>
2009-03-22format-patch: --numbered-files and --stdout aren't mutually exclusiveStephen Boyd
For example: git format-patch --numbered-files --stdout --attach HEAD~~ will create two messages with files 1 and 2 attached respectively. Without --attach/--inline but with --stdout, --numbered-files option can be simply ignored, because we are not creating any file ourselves. Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2009-03-11Merge branch 'tr/format-patch-thread'Junio C Hamano
* tr/format-patch-thread: format-patch: support deep threading format-patch: thread as reply to cover letter even with in-reply-to format-patch: track several references format-patch: threading test reactivation Conflicts: builtin-log.c
2009-02-22format-patch: support deep threadingThomas Rast
For deep threading mode, i.e., the mode that gives a thread structured like + [PATCH 0/n] Cover letter `-+ [PATCH 1/n] First patch `-+ [PATCH 2/n] Second patch `-+ ... we currently have to use 'git send-email --thread' (the default). On the other hand, format-patch also has a --thread option which gives shallow mode, i.e., + [PATCH 0/n] Cover letter |-+ [PATCH 1/n] First patch |-+ [PATCH 2/n] Second patch ... To reduce the confusion resulting from having two indentically named features in different tools giving different results, let format-patch take an optional argument '--thread=deep' that gives the same output as 'send-mail --thread'. With no argument, or 'shallow', behave as before. Also add a configuration variable format.thread with the same semantics. Signed-off-by: Thomas Rast <> Signed-off-by: Junio C Hamano <>
2009-02-12Enable setting attach as the default in .gitconfig for git-format-patch.Jeremy White
Signed-off-by: Jeremy White <> Signed-off-by: Junio C Hamano <>
2008-11-04Merge branch 'maint'Junio C Hamano
* maint: format-patch documentation: mention the special case of showing a single commit
2008-11-03format-patch documentation: mention the special case of showing a single commitJunio C Hamano
Even long timers seem to have missed that "format-patch -1 $commit" is a much simpler and more obvious way to say "format-patch $commit^..$commit" from the current documentation (and an example "format-patch -3 $commit" to get three patches). Add an explicit instruction in a much earlier part of the documentation to make it easier to find. Signed-off-by: Junio C Hamano <>
2008-10-18format-patch: autonumber by defaultBrian Gernhardt
format-patch is most commonly used for multiple patches at once when sending a patchset, in which case we want to number the patches; on the other hand, single patches are not usually expected to be numbered. In other words, the typical behavior expected from format-patch is the one obtained by enabling autonumber, so we set it to be the default. Users that want to disable numbering for a particular patchset can do so with the existing -N command-line switch. Users that want to change the default behavior can use the format.numbering config key. Signed-off-by: Brian Gernhardt <> Test-updates-by: Jeff King <> Signed-off-by: Shawn O. Pearce <> Signed-off-by: Junio C Hamano <>
2008-08-15git format-patch documentation: clarify what --cover-letter doesMatt McCutchen
Signed-off-by: Matt McCutchen <> Signed-off-by: Junio C Hamano <>
2008-07-21Update my e-mail addressJunio C Hamano
The old address is still getting mails from gitters. Signed-off-by: Junio C Hamano <>
2008-07-05manpages: italicize git command names (which were in teletype font)Jonathan Nieder
The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-05Documentation: more "git-" versus "git " changesJonathan Nieder
With git-commands moving out of $(bindir), it is useful to make a clearer distinction between the git subcommand 'git-whatever' and the command you type, `git whatever <options>`. So we use a dash after "git" when referring to the former and not the latter. I already sent a patch doing this same thing, but I missed some spots. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-05manpages: fix bogus whitespaceJonathan Nieder
It's distracting. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-05git-format-patch(1): fix stray \ in outputJonathan Nieder
In listing blocks (set off by rows of dashes), the usual formatting characters of asciidoc are instead rendered verbatim. When the escaped double-hyphen of olden days is moved into such a block along with other formatting improvements, it becomes backslash-dash-dash. So we remove the backslash. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-02Documentation formatting and cleanupJonathan Nieder
Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-02Documentation: be consistent about "git-" versus "git "Jonathan Nieder
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-06-08Docs: Use "-l::\n--long\n" format in OPTIONS sectionsStephan Beyer
The OPTIONS section of a documentation file contains a list of the options a git command accepts. Currently there are several variants to describe the case that different options (almost) do the same in the OPTIONS section. Some are: -f, --foo:: -f|--foo:: -f | --foo:: But AsciiDoc has the special form: -f:: --foo:: This patch applies this form to the documentation of the whole git suite, and removes useless em-dash prevention, so \--foo becomes --foo. Signed-off-by: Stephan Beyer <> Signed-off-by: Junio C Hamano <>
2008-06-06documentation: move git(7) to git(1)Christian Couder
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <> Signed-off-by: Junio C Hamano <>
2008-05-28Manual subsection to refer to other pages is SEE ALSOJunio C Hamano
Consistently say so in all caps as it is customary to do so. Signed-off-by: Junio C Hamano <>