summaryrefslogtreecommitdiff
path: root/Documentation/git-format-patch.txt
AgeCommit message (Collapse)AuthorFilesLines
2019-09-05Doc: add more detail for git-format-patchLibravatar Denton Liu1-10/+13
In git-format-patch.txt, we were missing some key user information. First of all, document the special value of `--base=auto`. Next, while we're at it, surround option arguments with <> and change existing names such as "Message-Id" to "message id", which conforms with how existing documentation is written. Finally, document the `format.outputDirectory` config and change `format.coverletter` to use camel case. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-07-09Merge branch 'nd/switch-and-restore'Libravatar Junio C Hamano1-2/+2
Two new commands "git switch" and "git restore" are introduced to split "checking out a branch to work on advancing its history" and "checking out paths out of the index and/or a tree-ish to work on advancing the current history" out of the single "git checkout" command. * nd/switch-and-restore: (46 commits) completion: disable dwim on "git switch -d" switch: allow to switch in the middle of bisect t2027: use test_must_be_empty Declare both git-switch and git-restore experimental help: move git-diff and git-reset to different groups doc: promote "git restore" user-manual.txt: prefer 'merge --abort' over 'reset --hard' completion: support restore t: add tests for restore restore: support --patch restore: replace --force with --ignore-unmerged restore: default to --source=HEAD when only --staged is specified restore: reject invalid combinations with --staged restore: add --worktree and --staged checkout: factor out worktree checkout code restore: disable overlay mode by default restore: make pathspec mandatory restore: take tree-ish from --source option instead checkout: split part of it to new command 'restore' doc: promote "git switch" ...
2019-05-17format-patch: teach format.notes config optionLibravatar Denton Liu1-0/+3
In git-format-patch, notes can be appended with the `--notes` option. However, this must be specified by the user on an invocation-by-invocation basis. If a user is not careful, it's possible that they may forget to include it and generate a patch series without notes. Teach git-format-patch the `format.notes` config option. Its value is a notes ref that will be automatically appended. The special value of "standard" can be used to specify the standard notes. This option is overridable with the `--no-notes` option in case a user wishes not to append notes. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-13git-format-patch.txt: document --no-notes optionLibravatar Denton Liu1-1/+3
Internally, git-format-patch uses the `handle_revision_opt` parser. The parser handles the `--no-notes` option to negate an earlier `--notes` option, but it isn't documented. Document this option so that users are aware of it. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-07doc: promote "git restore"Libravatar Nguyễn Thái Ngọc Duy1-1/+1
The new command "git restore" (together with "git switch") are added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguous context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands. One nice thing about git-restore is the ability to restore "everything", so it can be used in "git status" advice instead of both "git checkout" and "git reset". The three commands suggested by "git status" are add, rm and restore. "git checkout" is also removed from "git help" (i.e. it's no longer considered a commonly used command) Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-02doc: promote "git switch"Libravatar Nguyễn Thái Ngọc Duy1-1/+1
The new command "git switch" is added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguation context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands... The "Checking out files" progress line in unpack-trees.c is also updated to "Updating files" to be neutral to both git-checkout and git-switch. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-23doc: tidy asciidoc styleLibravatar Jean-Noël Avila1-7/+7
This mainly refers to enforcing indentation on additional lines of items of lists. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-11-30format-patch: do not let its diff-options affect --range-diffLibravatar Junio C Hamano1-0/+5
Stop leaking how the primary output of format-patch is customized to the range-diff machinery and instead let the latter use its own "reasonable default", in order to correct the breakage introduced by a5170794 ("Merge branch 'ab/range-diff-no-patch'", 2018-11-18) on the 'master' front. "git format-patch --range-diff..." without any weird diff option started to include the "range-diff --stat" output, which is rather useless right now, that made the whole thing unusable and this is probably the least disruptive way to whip the codebase into a shippable shape. We may want to later make the range-diff driven by format-patch more configurable, but that would have to wait until we have a good design. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-14format-patch: allow --range-diff to apply to a lone-patchLibravatar Eric Sunshine1-1/+2
When submitting a revised version of a patch or series, it can be helpful (to reviewers) to include a summary of changes since the previous attempt in the form of a range-diff, typically in the cover letter. However, it is occasionally useful, despite making for a noisy read, to insert a range-diff into the commentary section of the lone patch of a 1-patch series. Therefore, extend "git format-patch --range-diff=<refspec>" to insert a range-diff into the commentary section of a lone patch rather than requiring a cover letter. Implementation note: Generating a range-diff for insertion into the commentary section of a patch which itself is currently being generated requires invoking the diffing machinery recursively. However, the machinery does not (presently) support this since it uses global state. Consequently, we need to take care to stash away the state of the in-progress operation while generating the range-diff, and restore it after. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-14format-patch: add --creation-factor tweak for --range-diffLibravatar Eric Sunshine1-1/+7
When generating a range-diff, matching up commits between two version of a patch series involves heuristics, thus may give unexpected results. git-range-diff allows tweaking the heuristic via --creation-factor. Follow suit by accepting --creation-factor in combination with --range-diff when generating a range-diff for a cover-letter. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-14format-patch: extend --range-diff to accept revision rangeLibravatar Eric Sunshine1-3/+5
When submitting a revised a patch series, the --range-diff option embeds a range-diff in the cover letter showing changes since the previous version of the patch series. The argument to --range-diff is a simple revision naming the tip of the previous series, which works fine if the previous and current versions of the patch series share a common base. However, it fails if the revision ranges of the old and new versions of the series are disjoint. To address this shortcoming, extend --range-diff to also accept an explicit revision range for the previous series. For example: git format-patch --cover-letter --range-diff=v1~3..v1 -3 v2 Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-14format-patch: add --range-diff option to embed diff in cover letterLibravatar Eric Sunshine1-0/+10
When submitting a revised version of a patch series, it can be helpful (to reviewers) to include a summary of changes since the previous attempt in the form of a range-diff, however, doing so involves manually copy/pasting the diff into the cover letter. Add a --range-diff option to automate this process. The argument to --range-diff specifies the tip of the previous attempt against which to generate the range-diff. For example: git format-patch --cover-letter --range-diff=v1 -3 v2 (At this stage, the previous attempt and the patch series being formatted must share a common base, however, a subsequent enhancement will make it possible to specify an explicit revision range for the previous attempt.) Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-07-23format-patch: allow --interdiff to apply to a lone-patchLibravatar Eric Sunshine1-1/+2
When submitting a revised version of a patch or series, it can be helpful (to reviewers) to include a summary of changes since the previous attempt in the form of an interdiff, typically in the cover letter. However, it is occasionally useful, despite making for a noisy read, to insert an interdiff into the commentary section of the lone patch of a 1-patch series. Therefore, extend "git format-patch --interdiff=<prev>" to insert an interdiff into the commentary section of a lone patch rather than requiring a cover letter. The interdiff is indented to avoid confusing git-am and human readers into considering it part of the patch proper. Implementation note: Generating an interdiff for insertion into the commentary section of a patch which itself is currently being generated requires invoking the diffing machinery recursively. However, the machinery does not (presently) support this since it uses global state. Consequently, we need to take care to stash away the state of the in-progress operation while generating the interdiff, and restore it after. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-07-23format-patch: add --interdiff option to embed diff in cover letterLibravatar Eric Sunshine1-0/+9
When submitting a revised version of a patch series, it can be helpful (to reviewers) to include a summary of changes since the previous attempt in the form of an interdiff, however, doing so involves manually copy/pasting the diff into the cover letter. Add an --interdiff option to automate this process. The argument to --interdiff specifies the tip of the previous attempt against which to generate the interdiff. For example: git format-patch --cover-letter --interdiff=v1 -3 v2 The previous attempt and the patch series being formatted must share a common base. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-04-18doc: convert \--option to --optionLibravatar Martin Ågren1-1/+1
Rather than using a backslash in \--foo, with or without ''-quoting, write `--foo` for better rendering. As explained in commit 1c262bb7b (doc: convert \--option to --option, 2015-05-13), the backslash is not needed for the versions of AsciiDoc that we support, but is rendered literally by Asciidoctor. Signed-off-by: Martin Ågren <martin.agren@gmail.com>
2017-08-14format-patch: have progress option while generating patchesLibravatar Kevin Willford1-0/+4
When generating patches for the rebase command, if the user does not realize the branch they are rebasing onto is thousands of commits different, there is no progress indication after initial rewinding message. The progress meter as presented in this patch assumes the thousands of patches to have a fine granularity as well as assuming to require all the same amount of work/time for each, such that a steady progress bar is achieved. We do not want to estimate the time for each patch based e.g. on their size or number of touched files (or parents) as that is too expensive for just a progress meter. This patch allows a progress option to be passed to format-patch so that the user can be informed the progress of generating the patch. This option is then used by the rebase command when calling format-patch. Signed-off-by: Kevin Willford <kewillf@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-04-23Merge branch 'xy/format-patch-base'Libravatar Junio C Hamano1-1/+1
Doc cleanup. * xy/format-patch-base: doc: trivial typo in git-format-patch.txt
2017-04-17doc: trivial typo in git-format-patch.txtLibravatar Giuseppe Bilotta1-1/+1
Signed-off-by: Giuseppe Bilotta <giuseppe.bilotta@gmail.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-20doc: change erroneous --[no]-whatever into --[no-]whateverLibravatar Ævar Arnfjörð Bjarmason1-1/+1
Change these two obvious typos to be in line with the rest of the documentation, which uses the correct --[no-]whatever form. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-09-21format-patch: add "--rfc" for the common case of [RFC PATCH]Libravatar Josh Triplett1-1/+7
Add an alias for --subject-prefix='RFC PATCH', which is used commonly in some development communities to deserve such a short-hand. Signed-off-by: Josh Triplett <josh@joshtriplett.org> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-27Merge branch 'tr/doc-tt'Libravatar Junio C Hamano1-3/+3
The documentation set has been updated so that literal commands, configuration variables and environment variables are consistently typeset in fixed-width font and bold in manpages. * tr/doc-tt: doc: change configuration variables format doc: more consistency in environment variables format doc: change environment variables format doc: clearer rule about formatting literals
2016-06-08doc: change configuration variables formatLibravatar Tom Russello1-3/+3
This change configuration variables that where in italic style to monospace font according to the guideline. It was obtained with grep '[[:alpha:]]*\.[[:alpha:]]*::$' config.txt | \ sed -e 's/::$//' -e 's/\./\\\\./' | \ xargs -iP perl -pi -e "s/\'P\'/\`P\`/g" ./*.txt Signed-off-by: Tom Russello <tom.russello@grenoble-inp.org> Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org> Signed-off-by: Samuel Groot <samuel.groot@grenoble-inp.org> Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr> Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-04-26format-patch: introduce --base=auto optionLibravatar Xiaolong Ye1-0/+6
Introduce --base=auto to record the base commit info automatically, the base_commit will be the merge base of tip commit of the upstream branch and revision-range specified in cmdline. Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Wu Fengguang <fengguang.wu@intel.com> Signed-off-by: Xiaolong Ye <xiaolong.ye@intel.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-04-26format-patch: add '--base' option to record base tree infoLibravatar Xiaolong Ye1-0/+54
Maintainers or third party testers may want to know the exact base tree the patch series applies to. Teach git format-patch a '--base' option to record the base tree info and append it at the end of the first message (either the cover letter or the first patch in the series). The base tree info consists of the "base commit", which is a well-known commit that is part of the stable part of the project history everybody else works off of, and zero or more "prerequisite patches", which are well-known patches in flight that is not yet part of the "base commit" that need to be applied on top of "base commit" in topological order before the patches can be applied. The "base commit" is shown as "base-commit: " followed by the 40-hex of the commit object name. A "prerequisite patch" is shown as "prerequisite-patch-id: " followed by the 40-hex "patch id", which can be obtained by passing the patch through the "git patch-id --stable" command. Imagine that on top of the public commit P, you applied well-known patches X, Y and Z from somebody else, and then built your three-patch series A, B, C, the history would be like: ---P---X---Y---Z---A---B---C With "git format-patch --base=P -3 C" (or variants thereof, e.g. with "--cover-letter" of using "Z..C" instead of "-3 C" to specify the range), the base tree information block is shown at the end of the first message the command outputs (either the first patch, or the cover letter), like this: base-commit: P prerequisite-patch-id: X prerequisite-patch-id: Y prerequisite-patch-id: Z Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Wu Fengguang <fengguang.wu@intel.com> Signed-off-by: Xiaolong Ye <xiaolong.ye@intel.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-01-26Merge branch 'ak/format-patch-odir-config'Libravatar Junio C Hamano1-1/+5
"git format-patch" learned to notice format.outputDirectory configuration variable. This allows "-o <dir>" option to be omitted on the command line if you always use the same directory in your workflow. * ak/format-patch-odir-config: format-patch: introduce format.outputDirectory configuration
2016-01-20Merge branch 'dw/signoff-doc'Libravatar Junio C Hamano1-0/+1
The documentation has been updated to hint the connection between the '--signoff' option and DCO. * dw/signoff-doc: Expand documentation describing --signoff
2016-01-13format-patch: introduce format.outputDirectory configurationLibravatar Alexander Kuleshov1-1/+5
We can pass -o/--output-directory to the format-patch command to store patches in some place other than the working directory. This patch introduces format.outputDirectory configuration option for same purpose. The case of usage of this configuration option can be convenience to not pass every time -o/--output-directory if an user has pattern to store all patches in the /patches directory for example. The format.outputDirectory has lower priority than command line option, so if user will set format.outputDirectory and pass the command line option, a result will be stored in a directory that passed to command line option. Signed-off-by: Alexander Kuleshov <kuleshovmail@gmail.com> Signed-off-by: Stephen P. Smith <ischis2@cox.net> Reviewed-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-01-05Expand documentation describing --signoffLibravatar David A. Wheeler1-0/+1
Modify various document (man page) files to explain in more detail what --signoff means. This was inspired by https://lwn.net/Articles/669976/ where paulj noted, "adding [the] '-s' argument to [a] git commit doesn't really mean you have even heard of the DCO...". Extending git's documentation will make it easier to argue that developers understood --signoff when they use it. Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-12-15format-patch: add an option to suppress commit hashLibravatar brian m. carlson1-0/+4
Oftentimes, patches created by git format-patch will be stored in version control or compared with diff. In these cases, two otherwise identical patches can have different commit hashes, leading to diff noise. Teach git format-patch a --zero-commit option that instead produces an all-zero hash to avoid this diff noise. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-09-17Merge branch 'po/doc-branch-desc'Libravatar Junio C Hamano1-1/+1
The branch descriptions that are set with "git branch --edit-description" option were used in many places but they weren't clearly documented. * po/doc-branch-desc: doc: show usage of branch description
2015-09-14doc: show usage of branch descriptionLibravatar Philip Oakley1-1/+1
The branch description will be included in 'git format-patch --cover-letter' and in 'git pull-request' emails. It can also be used in the automatic merge message. Tell the reader. While here, clarify that the description may be a multi-line explanation of the purpose of the branch's patch series. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-06-24Merge branch 'fk/doc-format-patch-vn'Libravatar Junio C Hamano1-1/+1
Docfix. * fk/doc-format-patch-vn: doc: format-patch: fix typo
2015-06-10doc: format-patch: fix typoLibravatar Frans Klaver1-1/+1
reroll count documentation states that v<n> will be pretended to the filename. Judging by the examples that should have been 'prepended'. Signed-off-by: Frans Klaver <fransklaver@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-13*config.txt: stick to camelCase naming conventionLibravatar Nguyễn Thái Ngọc Duy1-2/+2
This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-27format-patch: add "--signature-file=<file>" optionLibravatar Jeremiah Mahler1-0/+4
Add an option to format-patch for reading a signature from a file. $ git format-patch -1 --signature-file=$HOME/.signature The config variable `format.signaturefile` can also be used to make this the default. $ git config format.signaturefile $HOME/.signature $ git format-patch -1 Signed-off-by: Jeremiah Mahler <jmmahler@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-10-14format-patch doc: Thunderbird wraps lines unless mailnews.wraplength=0Libravatar Ramsay Jones1-1/+2
The Thunderbird section of the 'MUA-specific hints' contains three different approaches to setting up the mail client to leave patch emails unmolested. The second approach (configuration) has a step missing when configuring the composition window not to wrap. In particular, the "mailnews.wraplength" configuration variable needs to be set to zero. Update the documentation to add the missing setting. Signed-off-by: Ramsay Jones <ramsay@ramsay1.demon.co.uk> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
2013-08-05log, format-patch: parsing uses OPT__QUIETLibravatar Stefan Beller1-0/+1
This patch allows users to use the short form -q on log and format-patch, which was non possible before. Also the documentation of format-patch mentions -q now. The documentation of log doesn't even talk about --quiet, so I'll leave that for more experienced git contributors. ;) It doesn't seem to change the default behavior, but in combination with --stat for example it suppresses the actual stats. however the only relevant code in log is if (quiet) rev->diffopt.output_format |= DIFF_FORMAT_NO_OUTPUT; Signed-off-by: Stefan Beller <stefanbeller@googlemail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-03teach format-patch to place other authors into in-body "From"Libravatar Jeff King1-0/+15
Format-patch generates emails with the "From" address set to the author of each patch. If you are going to send the emails, however, you would want to replace the author identity with yours (if they are not the same), and bump the author identity to an in-body header. Normally this is handled by git-send-email, which does the transformation before sending out the emails. However, some workflows may not use send-email (e.g., imap-send, or a custom script which feeds the mbox to a non-git MUA). They could each implement this feature themselves, but getting it right is non-trivial (one must canonicalize the identities by reversing any RFC2047 encoding or RFC822 quoting of the headers, which has caused many bugs in send-email over the years). This patch takes a different approach: it teaches format-patch a "--from" option which handles the ident check and in-body header while it is writing out the email. It's much simpler to do at this level (because we haven't done any quoting yet), and any workflow based on format-patch can easily turn it on. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-07format-patch: add format.coverLetter configuration variableLibravatar Felipe Contreras1-2/+3
Also, add a new option: 'auto', so if there's more than one patch, the cover letter is generated, otherwise it's not. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-5/+5
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-11Merge branch 'jc/format-patch-reroll'Libravatar Junio C Hamano1-1/+10
Teach "format-patch" to prefix v4- to its output files for the fourth iteration of a patch series, to make it easier for the submitter to keep separate copies for iterations. * jc/format-patch-reroll: format-patch: give --reroll-count a short synonym -v format-patch: document and test --reroll-count format-patch: add --reroll-count=$N option get_patch_filename(): split into two functions get_patch_filename(): drop "just-numbers" hack get_patch_filename(): simplify function signature builtin/log.c: stop using global patch_suffix builtin/log.c: drop redundant "numbered_files" parameter from make_cover_letter() builtin/log.c: drop unused "numbered" parameter from make_cover_letter()
2013-01-03format-patch: give --reroll-count a short synonym -vLibravatar Junio C Hamano1-1/+2
Accept "-v" as a synonym to "--reroll-count", so that users can say "git format-patch -v4 master", instead of having to fully spell it out as "git format-patch --reroll-count=4 master". As I do not think of a reason why users would want to tell the command to be "verbose", I think this should be OK. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-02format-patch: document and test --reroll-countLibravatar Junio C Hamano1-1/+9
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-10-26Doc format-patch: clarify --notes use caseLibravatar Philip Oakley1-7/+6
Remove double negative, and include the repeat usage across versions of a patch series. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Jeff King <peff@peff.net>
2012-10-19Documentation: decribe format-patch --notesLibravatar Junio C Hamano1-1/+14
Even though I coded this, I am not sure what use scenarios would benefit from this option, so the description is unnecessarily negative at this moment. People who do want to use this feature need to come up with a more plausible use case and replace it. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-13Documentation: describe subject more preciselyLibravatar Jeremy White1-4/+7
The discussion of email subject throughout the documentation is misleading; it indicates that the first line will always become the subject. In fact, the subject is generally all lines up until the first full blank line. This patch refines that, and makes more use of the concept of a commit title, with the title being all text up to the first blank line. Signed-off-by: Jeremy White <jwhite@codeweavers.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26docs: stop using asciidoc no-inline-literalLibravatar Jeff King1-2/+2
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 <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - 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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-29Document negated forms of format-patch --to --cc --add-headersLibravatar Thomas Rast1-1/+8
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 <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-05-04Merge branch 'jn/format-patch-doc'Libravatar Junio C Hamano1-0/+169
* 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'Libravatar Junio C Hamano1-0/+58
* jn/maint-format-patch-doc: Documentation: describe the format of messages with inline patches