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 <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The standard reference for this information is the article
"Plain text e-mail - Thunderbird#Completely_plain_email" at
kb.mozillazine.org, 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 <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <jim@meyering.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
Improved-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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.
* 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
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 <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <artagnon@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <bebarino@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Has the same functionality as the '--cc' option and 'format.cc'
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 <sdrake@xnet.co.nz>
Signed-off-by: Stephen Boyd <bebarino@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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.
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 <bgustavsson@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This hopefully makes the relationship between threading options of
format-patch and send-email easier to grasp.
Signed-off-by: Yann Dirson <ydirson@altern.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <bebarino@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Even when a sentence is started with 'shallow' or 'deep' use the
lowercase version to maintain consistency.
Signed-off-by: Stephen Boyd <bebarino@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <hvoigt@hvoigt.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <michael@ndrix.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <bebarino@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* 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
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 <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <gitster@pobox.com>
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 <benji@silverinsanity.com>
Test-updates-by: Jeff King <peff@peff.net>
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <s-beyer@gmx.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* mv/format-cc:
Add tests for sendemail.cc configuration variable
git-send-email: add a new sendemail.cc configuration variable
git-format-patch: add a new format.cc configuration variable
Add a new option --no-binary to git-format-patch so that no binary
changes are included in the generated patches, only notices that those
files changed. This generate patches that cannot be applied, but still
is useful for generating mails for code review purposes.
See also: commit e47f306d4b, where --binary
option was turned on by default.
Signed-off-by: Caio Marcelo de Oliveira Filho <cmarcelo@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Before this patch in "git-add.txt" and "git-format-patch.txt", the
commands used in the examples were "git-CMD" instead of "git CMD".
This patch fixes that.
In "git-pull.txt" only the last example had the code sample in an
asciidoc "Listing Block", and in the other two files, none.
This patch fixes that by putting all code samples in listing
blocks.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Some projects prefer to always CC patches to a given mailing list. In
these cases, it's handy to configure that address once.
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When you have particular reviewers you want to sent particular series
to, it's nice to be able to generate the whole series with them as
additional recipients, without configuring them into your general
headers or adding them by hand afterwards.
Signed-off-by: Daniel Barkalow <barkalow@iabervon.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If --cover-letter is provided, generate a cover letter message before
the patches, numbered 0.
Original patch thanks to Johannes Schindelin
Signed-off-by: Daniel Barkalow <barkalow@iabervon.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock
Asciidoc configuration:
@@ -149,7 +153,10 @@
# Inline macros.
# Backslash prefix required for escape processing.
# (?s) re flag for line spanning.
-(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
+# Explicit so they can be nested.
+(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
# Anchor: [[[id]]]. Bibliographic anchor.
(?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3
# Anchor: [[id,xreflabel]]
This default regex now matches explicit values, and unfortunately in this
case gitlink was being matched by just 'link', causing the wrong inline
macro template to be applied. By renaming the macro, we can avoid being
matched by the wrong regex.
Signed-off-by: Dan McGee <dpmcgee@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
