The CodingGuidelines documents stipulates that multi-word placeholders
are to be separated by dashes, not underscores nor spaces.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Stale URLs have been updated to their current counterparts (or
archive.org) and HTTP links are replaced with working HTTPS links.
* js/update-urls-in-doc-and-comment:
doc: refer to internet archive
doc: update links for andre-simon.de
doc: switch links to https
doc: update links to current pages
These sites offer https versions of their content.
Using the https versions provides some protection for users.
Signed-off-by: Josh Soref <jsoref@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The codepath to handle recipient addresses `git send-email
--compose` learns from the user was completely broken, which has
been corrected.
* jk/send-email-fix-addresses-from-composed-messages:
send-email: handle to/cc/bcc from --compose message
Revert "send-email: extract email-parsing code into a subroutine"
doc/send-email: mention handling of "reply-to" with --compose
If the user writes a message via --compose, send-email will pick up
various headers like "From", "Subject", etc and use them for other
patches as if they were specified on the command-line. But we don't
handle "To", "Cc", or "Bcc" this way; we just tell the user "those
aren't interpeted yet" and ignore them.
But it seems like an obvious thing to want, especially as the same
feature exists when the cover letter is generated separately by
format-patch. There it is gated behind the --to-cover option, but I
don't think we'd need the same control here; since we generate the
--compose template ourselves based on the existing input, if the user
leaves the lines unchanged then the behavior remains the same.
So let's fill in the implementation; like those other headers we already
handle, we just need to assign to the initial_* variables. The only
difference in this case is that they are arrays, so we'll feed them
through parse_address_line() to split them (just like we would when
reading a single string via prompting).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for git-send-email lists the headers handled specially
by --compose in a way that implies that this is the complete set of
headers that are special. But one more was added by d11c943c78
(send-email: support separate Reply-To address, 2018-03-04) and never
documented.
Let's add it, and reword the documentation slightly to avoid having to
specify the list of headers twice (as it is growing and will continue to
do so as we add new features).
If you read the code, you may notice that we also handle MIME-Version
specially, in that we'll avoid over-writing user-provided MIME headers.
I don't think this is worth mentioning, as it's what you'd expect to
happen (as opposed to the other headers, which are picked up to be used
in later emails). And certainly this feature existed when the
documentation was expanded in 01d3861217 (git-send-email.txt: describe
--compose better, 2009-03-16), and we chose not to mention it then.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Sometimes, adding a header different than CC or TO is desirable; for
example, when using Debbugs, it is best to use 'X-Debbugs-Cc' headers
to keep people in CC; this is an example use case enabled by the new
'--header-cmd' option.
The header unfolding logic is extracted to a subroutine so that it can
be reused; a test is added for coverage.
Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Support for "less secure apps" ended May 30, 2022.
This effectively reverts 155067a (git-send-email.txt: mention less secure
app access with Gmail, 2021-01-08).
Signed-off-by: Jouke Witteveen <j.witteveen@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We used to write "Message-Id:" and "Message-ID:" pretty much
interchangeably, and the header name is defined to be case
insensitive by the RFCs, but the canonical form "Message-ID:" is
used throughout the RFC documents, so let's imitate it ourselves.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Reviewed-by: Elijah Newren <newren@gmail.com>
New explanation for the difference between these values.
It's hard to understand what they do based only on the names.
New description of used default ports.
Signed-off-by: Sotir Danailov <sndanailov@wired4ever.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
De-duplicate the discussion of "send-email" configuration, such that
the "git-config(1)" manual page becomes the source of truth, and
"git-send-email(1)" includes the relevant part.
Most commands that suffered from such duplication had diverging text
discussing the same variables, but in this case some config was also
only discussed in one or the other.
This is mostly a move-only change, the exception is a minor rewording
of changing wording like "see above" to "see linkgit:git-config[1]",
as well as a clarification about the big section of command-line
option tweaking config being discussed in git-send-email(1)'s main
docs.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Reviewed-by: Matheus Tavares <matheus.bernardino@usp.br>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git-send-email(1) does not mention that "git format-patch" options are
accepted. Augment SYNOPSIS and DESCRIPTION to mention it.
Update git-send-email.perl USAGE to be consistent with
git-send-email(1).
Signed-off-by: Thiago Perrotta <tbperrotta@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The sendemail.smtpServer configuration option and --smtp-server command
line option both support using a sendmail-like program to send emails by
specifying an absolute file path. However, this is not ideal for the
following reasons:
1. It overloads the meaning of smtpServer (now a program is being used
for the server?)
2. It doesn't allow for non-absolute paths, arguments, or arbitrary
scripting
Requiring an absolute path is bad for portability, as the same program
may be in different locations on different systems. If a user wishes to
pass arguments to their program, they have to use the smtpServerOption
option, which is cumbersome (as it must be repeated for each option) and
doesn't adhere to normal git conventions.
Introduce a new configuration option sendemail.sendmailCmd as well as a
command line option --sendmail-cmd that can be used to specify a command
(with or without arguments) or shell expression to run to send email.
The name of this option is consistent with --to-cmd and --cc-cmd. This
invocation honors the user's $PATH so that absolute paths are not
necessary. Arbitrary shell expressions are also supported, allowing
users to do basic scripting.
Give this option a higher precedence over --smtp-server and
sendemail.smtpServer, as the new interface is more flexible. For
backward compatibility, continue to support absolute paths in
--smtp-server and sendemail.smtpServer.
Signed-off-by: Gregory Anders <greg@gpanders.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Google may have changed Gmail security and now less secure app access
needs to be explicitly enabled if two-factor authentication is not in
place, otherwise send-email fails with:
5.7.8 Username and Password not accepted. Learn more at
5.7.8 https://support.google.com/mail/?p=BadCredentials
Document steps required to make this work.
Signed-off-by: Vasyl Vavrychuk <vvavrychuk@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
[dl: Clean up commit message and incorporate suggestions into patch.]
Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ted reported an old typo in the git-commit.txt and merge-options.txt.
Namely, the phrase "Signed-off-by line" was used without either a
definite nor indefinite article.
Upon examination, it seems that the documentation (including items in
Documentation/, but also option help strings) have been quite
inconsistent on usage when referring to `Signed-off-by`.
First, very few places used a definite or indefinite article with the
phrase "Signed-off-by line", but that was the initial typo that led
to this investigation. So, normalize using either an indefinite or
definite article consistently.
The original phrasing, in Commit 3f971fc425 (Documentation updates,
2005-08-14), is "Add Signed-off-by line". Commit 6f855371a5 (Add
--signoff, --check, and long option-names. 2005-12-09) switched to
using "Add `Signed-off-by:` line", but didn't normalize the former
commit to match. Later commits seem to have cut and pasted from one
or the other, which is likely how the usage became so inconsistent.
Junio stated on the git mailing list in
<xmqqy2k1dfoh.fsf@gitster.c.googlers.com> a preference to leave off
the colon. Thus, prefer `Signed-off-by` (with backticks) for the
documentation files and Signed-off-by (without backticks) for option
help strings.
Additionally, Junio argued that "trailer" is now the standard term to
refer to `Signed-off-by`, saying that "becomes plenty clear that we
are not talking about any random line in the log message". As such,
prefer "trailer" over "line" anywhere the former word fits.
However, leave alone those few places in documentation that use
Signed-off-by to refer to the process (rather than the specific
trailer), or in places where mail headers are generally discussed in
comparison with Signed-off-by.
Reported-by: "Theodore Y. Ts'o" <tytso@mit.edu>
Signed-off-by: Bradley M. Kuhn <bkuhn@sfconservancy.org>
Acked-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The indented lines in these example config-file listings are indented
differently by AsciiDoc and Asciidoctor.
Fix this by marking the example config-files as code listings by
wrapping them in "----". Because this gives us some extra indentation,
we can remove the one that we have been carrying explicitly. That is,
drop the first tab of indentation on each line.
With AsciiDoc, this results in identical rendering before and after this
commit. Asciidoctor now renders this the same as AsciiDoc does.
git-config.txt pretty consistently uses twelve dashes rather than the
minimum four to spell "----". Let's stick to the file-local convention
there.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Since "git send-email" learned to take 'auto' as the value for the
transfer-encoding, it by mistake stopped honoring the values given
to the configuration variables sendemail.transferencoding and/or
sendemail.<ident>.transferencoding. This has been corrected to
(finally) redoing the order of setting the default, reading the
configuration and command line options.
* ab/send-email-transferencoding-fix:
send-email: fix regression in sendemail.identity parsing
send-email: document --no-[to|cc|bcc]
send-email: fix broken transferEncoding tests
send-email: remove cargo-culted multi-patch pattern in tests
send-email: do defaults -> config -> getopt in that order
send-email: rename the @bcclist variable for consistency
send-email: move the read_config() function above getopts
Improve and complete the list of required email related Perl modules,
clarifying which are core Perl modules and remove Net::SMTP::SSL.
git-send-email uses the TLS support in the Net::SMTP core module from
recent versions of Perl. Documenting the minimum version is complex
because of separate numbering for Perl (5.21.5~169), Net:SMTP (2.34)
and libnet (3.01). Version numbers from commit:
bfbfc9a953 ("send-email: Net::SMTP::starttls was introduced in v2.34",
2017-05-31).
Users of older Perl versions without Net::SMTP::SSL installed will get a
clear error message.
Signed-off-by: Chris Mayo <aklhfex@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Fix a regression in my recent 3494dfd3ee ("send-email: do defaults ->
config -> getopt in that order", 2019-05-09). I missed that the
$identity variable needs to be extracted from the command-line before
we do the config reading, as it determines which config variable we
should read first. See [1] for the report.
The sendemail.identity feature was added back in
34cc60ce2b ("send-email: Add support for SSL and SMTP-AUTH",
2007-09-03), there were no tests to assert that it worked properly.
So let's fix both the regression, and add some tests to assert that
this is being parsed properly. While I'm at it I'm adding a
--no-identity option to go with --[to|cc|bcc] variable, since the
semantics are similar. It's like to/cc/bcc except that unlike those we
don't support multiple identities, but we could now easily add it
support for it if anyone cares.
In just fixing the --identity command-line parsing bug I discovered
that a narrow fix to that wouldn't do. In read_config() we had a state
machine that would only set config values if they weren't set already,
and thus by proxy we wouldn't e.g. set "to" based on sendemail.to if
we'd seen sendemail.gmail.to before, with --identity=gmail.
I'd modified some of the relevant code in 3494dfd3ee, but just
reverting to that wouldn't do, since it would bring back the
regression fixed in that commit.
Refactor read_config() do what we actually mean here. We don't want to
set a given sendemail.VAR if a sendemail.$identity.VAR previously set
it. The old code was conflating this desire with the hardcoded
defaults for these variables, and as discussed in 3494dfd3ee that was
never going to work. Instead pass along the state of whether an
identity config set something before, as distinguished from the state
of the default just being false, or the default being a non-bool or
true (e.g. --transferencoding).
I'm still not happy with the test coverage here, e.g. there's nothing
testing sendemail.smtpEncryption, but I only have so much time to fix
this code.
1. https://public-inbox.org/git/5cddeb61.1c69fb81.47ed4.e648@mx.google.com/
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
These options added in f434c083a0 ("send-email: add --no-cc, --no-to,
and --no-bcc", 2010-03-07) were never documented.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
"git send-email" learned to disable SMTP authentication via the
"--smtp-auth=none" option, even when the smtp username is given
(which turns the authentication on by default).
* jw/send-email-no-auth:
send-email: explicitly disable authentication
It can be necessary to disable SMTP authentication by a mechanism other
than sendemail.smtpuser being undefined. For example, if the user has
sendemail.smtpuser set globally but wants to disable authentication
locally in one repository.
--smtp-auth and sendemail.smtpauth now understand the value 'none' which
means to disable authentication completely, even if an authentication
user is specified.
The value 'none' is lower case to avoid conflicts with any RFC 4422
authentication mechanisms.
The user may also specify the command line argument --no-smtp-auth as a
shorthand for --smtp-auth=none
Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When rerolling a patch series, including various Reviewed-by etc. that
may have come in, it is quite convenient to have git-send-email
automatically cc those people.
So pick up any *-by lines, with a new suppression category 'misc-by',
but special-case Signed-off-by, since that already has its own
suppression category. It seems natural to make 'misc-by' implied by
'body'.
Based-on-patch-by: Joe Perches <joe@perches.com>
Signed-off-by: Rasmus Villemoes <rv@rasmusvillemoes.dk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
For consistency, add full stops in a few places and outdent a line by
one space.
Signed-off-by: Rasmus Villemoes <rv@rasmusvillemoes.dk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git send-email, when invoked without a --transfer-encoding option, sends
8bit data without a MIME version or a transfer encoding. This has
several downsides.
First, unless the transfer encoding is specified, it defaults to 7bit,
meaning that non-ASCII data isn't allowed. Second, if lines longer than
998 bytes are used, we will send an message that is invalid according to
RFC 5322. The --validate option, which is the default, catches this
issue, but it isn't clear to many people how to resolve this.
To solve these issues, default the transfer encoding to "auto", so that
we explicitly specify 8bit encoding when lines don't exceed 998 bytes
and quoted-printable otherwise. This means that we now always emit
Content-Transfer-Encoding and MIME-Version headers, so remove the
conditionals from this portion of the code.
It is unlikely that the unconditional inclusion of these two headers
will affect the deliverability of messages in anything but a positive
way, since MIME is already widespread and well understood by most email
programs.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The git send-email documentation specifies RFC 2821 (the SMTP RFC) as
providing line length limits, but the specification that restricts line
length to 998 octets is RFC 2822 (the email message format RFC). Since
RFC 2822 has been obsoleted by RFC 5322, update the text to refer to RFC
5322 instead of RFC 2821.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
With --validate (which is the default), we warn about lines exceeding
998 characters due to the limits specified in RFC 5322. However, if
we're using a suitable transfer encoding (quoted-printable or base64),
we're guaranteed not to have lines exceeding 76 characters, so there's
no need to fail in this case. The auto transfer encoding handles this
specific case, so accept it as well.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
For most patches, using a transfer encoding of 8bit provides good
compatibility with most servers and makes it as easy as possible to view
patches. However, there are some patches for which 8bit is not a valid
encoding: RFC 5322 specifies that a message must not have lines
exceeding 998 octets.
Add a transfer encoding value, auto, which indicates that a patch should
use 8bit where allowed and quoted-printable otherwise. Choose
quoted-printable instead of base64, since base64-encoded plain text is
treated as suspicious by some spam filters.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The standard for command documentation synopses appears to be:
[...] means optional
<...> means replaceable
[<...>] means both optional and replaceable
So fix a number of doc pages that use incorrect variations of the
above.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When formatted as a man page, 1st section header is always in upper
case even if we write it otherwise. Make all 1st section headers
uppercase to keep it close to the final output.
This does affect html since case is kept there, but I still think it's
a good idea to maintain a consistent style for 1st section headers.
Some sections perhaps should become second sections instead, where
case is kept, and for better organization. I will update if anyone has
suggestions about this.
While at there I also make some header more consistent (e.g. examples
vs example) and fix a couple minor things here and there.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
There is no need for use to manually call ‘git credential’ especially
as the interface isn’t super user-friendly and a bit confusing. ‘git
send-email’ will do that for them at the first execution and if the
password matches, it will be saved in the store.
Simplify the documentaion so it dosn’t include the ‘git credential’
invocation (which was incorrect anyway as it should use ‘approve’
instead of ‘fill’) and instead just mentions that credentials helper
must be set up.
Signed-off-by: Michał Nazarewicz <mina86@mina86.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In some projects contributions from groups are only accepted from a
common group email address. But every individual may want to receive
replies to her own personal address. That's what we have 'Reply-To'
headers for in SMTP. So introduce an optional '--reply-to' command
line option.
This patch re-uses the $reply_to variable. This could break
out-of-tree patches!
Signed-off-by: Christian Ludwig <chrissicool@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This extends git-send-email to also consider sendmail binaries in $PATH
after checking the (fixed) list of /usr/sbin and /usr/lib, and before
falling back to localhost.
Signed-off-by: Florian Klink <flokli@flokli.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"git send-email" learned to overcome some SMTP server limitation
that does not allow many pieces of e-mails to be sent over a single
session.
* xz/send-email-batch-size:
send-email: --batch-size to work around some SMTP server limit
Some email servers (e.g. smtp.163.com) limit the number emails to be
sent per session (connection) and this will lead to a faliure when
sending many messages.
Teach send-email to disconnect after sending a number of messages
(configurable via the --batch-size=<num> option), wait for a few
seconds (configurable via the --relogin-delay=<seconds> option) and
reconnect, to work around such a limit.
Also add two configuration variables to give these options the default.
Note:
We will use this as a band-aid for now, but in the longer term, we
should look at and react to the SMTP error code from the server;
Xianqiang reports that 450 and 451 are returned by problematic
servers.
cf. https://public-inbox.org/git/7993e188.d18d.15c3560bcaf.Coremail.zxq_yx_007@163.com/
Signed-off-by: xiaoqiang zhao <zxq_yx_007@163.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Currently, send-email has support for rudimentary e-mail validation.
Allow the user to add support for more validation by providing a
sendemail-validate hook.
Helped-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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>
More mark-up updates to typeset strings that are expected to
literally typed by the end user in fixed-width font.
* mm/doc-tt:
doc: typeset HEAD and variants as literal
CodingGuidelines: formatting HEAD in documentation
doc: typeset long options with argument as literal
doc: typeset '--' as literal
doc: typeset long command-line options as literal
doc: typeset short command-line options as literal
Documentation/git-mv.txt: fix whitespace indentation
Similarly to the previous commit, use backquotes instead of
forward-quotes, for long options.
This was obtained with:
perl -pi -e "s/'(--[a-z][a-z=<>-]*)'/\`\$1\`/g" *.txt
and manual tweak to remove false positive in ascii-art (o'--o'--o' to
describe rewritten history).
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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
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>