Oldest supported Perl version

Oldest supported Perl version

[Jay Soffian]

On Sun, Apr 19, 2009 at 9:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Sorry, I should have checked myself.  defined-or "//" is 5.8.1 or later.
>
> Now the real question was if we still support anything older, and if so
> what is the bottom version?
>
> I certainly can go with "5.8.1 or later", but I vaguely recall during the
> gitweb discussion we said anything without the utf-8 support is unusable
> for gitweb, but I think we also said that the rest of the git codebase
> should support running with something older (5.6.1, perhaps).

15 minutes of research:

* 2006-06-25 Junio C Hamano: "Tentatively let's say our cut-off point is
  somewhere around 5.6." --
  http://article.gmane.org/gmane.comp.version-control.git/22607

* 2008-05-30 Lea Wiemann: "Gitweb relies on Unicode support (e.g. "use
  Encode") and will continue to be compatible with 5.8 and 5.10 only" --
  http://article.gmane.org/gmane.comp.version-control.git/83339

* 2008-08-13 Lea Wiemann: "This makes Git.pm dependent on Perl 5.6.1. Some
  tests (like t3701-add-interactive.sh) seem to work with pretty much any Perl
  version out there, and requiring File::Spec changes this" --
  http://article.gmane.org/gmane.comp.version-control.git/92260

* 2008-08-15 Marcus Griep: "Git.pm: Make File::Spec and File::Temp requirement
  lazy" -- c14c8ce

* 2008-08-30 Junio C Hamano: "I agree we should say we rely on 5.6 or newer."
  -- http://article.gmane.org/gmane.comp.version-control.git/94399

* 2008-09-01 Junio C Hamano: "I personally think it is probably Ok to declare
  that we do depend on 5.8" --
  http://article.gmane.org/gmane.comp.version-control.git/94523


So here's my take-away. For the *.perl scripts and gitweb, it's 5.8.0. For the
test suite and Git.pm, all Perl versions are theoretically supported, but for
practical purposes, it may be 5.6.0.

Whatever is decided this time, perhaps it should be burned into the tops of
the *.perl scripts (i.e. "require 5.008;"). It should also be added to
CodingGuidelines. You know, so this conversation doesn't keep recurring. :-)

j.

Re: [PATCH RFC3.5 04/12] send-email: Verification for --smtp-server and --smpt-server-port

[Michael Witten]

On Mon, Apr 20, 2009 at 09:59, Jay Soffian <jaysoffian@gmail.com> wrote:
> On Sun, Apr 19, 2009 at 9:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Sorry, I should have checked myself.  defined-or "//" is 5.8.1 or later.

>From what I've read:

	http://perldoc.perl.org/perl581delta.html#Future-Directions

The defined-OR only exists for 5.8.1 in patch form, and it's only directly
supported in 5.10.0:

	http://perldoc.perl.org/perldelta.html#Defined-or-operator

:-(

Oldest supported Perl version

[Michael Witten]

====> Sorry for the repeat; I think I'll go install an MUA now.

On Mon, Apr 20, 2009 at 09:59, Jay Soffian <jaysoffian@gmail.com> wrote:
> On Sun, Apr 19, 2009 at 9:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Sorry, I should have checked myself.  defined-or "//" is 5.8.1 or later.

>From what I've read:

	http://perldoc.perl.org/perl581delta.html#Future-Directions

The defined-OR only exists for 5.8.1 in patch form, and it's only directly
supported in 5.10.0:

	http://perldoc.perl.org/perldelta.html#Defined-or-operator

:-(

Re: Oldest supported Perl version

[Jay Soffian]

On Mon, Apr 20, 2009 at 11:43 AM, Michael Witten <mfwitten@gmail.com> wrote:
> ====> Sorry for the repeat; I think I'll go install an MUA now.
>
> On Mon, Apr 20, 2009 at 09:59, Jay Soffian <jaysoffian@gmail.com> wrote:
>> On Sun, Apr 19, 2009 at 9:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>> Sorry, I should have checked myself.  defined-or "//" is 5.8.1 or later.
>
> From what I've read:
>
>        http://perldoc.perl.org/perl581delta.html#Future-Directions
>
> The defined-OR only exists for 5.8.1 in patch form, and it's only directly
> supported in 5.10.0:
>
>        http://perldoc.perl.org/perldelta.html#Defined-or-operator
>
> :-(

I started this new thread to address Junio's question about the oldest
supported Perl version, so that tidbit isn't really relevant and I
should've trimmed it from the new thread. Nonetheless, thank you for
the correction again again, and enjoy your new MUA. :-)

j.

Re: Oldest supported Perl version

[H.Merijn Brand]

On Mon, 20 Apr 2009 10:59:00 -0400, Jay Soffian <jaysoffian@gmail.com>
wrote:

> On Sun, Apr 19, 2009 at 9:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
> > Sorry, I should have checked myself.  defined-or "//" is 5.8.1 or later.

Being the maintainer of the defined-or patch for perl 5.8, I can
short-circuit this

* defined-or (//) is officially available from perl-5.10.0 and up
  you can be *sure* to have it there. the 'err' keyword that was the
  low-precedence version for // is gone.

* defined-or is available in any version of perl 5.8.x is the binary
  was built with the appropriate patch, which is available on my CPAN
  directory:
  ftp://download.xs4all.nl/pub/mirror/CPAN/authors/id/H/HM/HMBRAND/
  These patches still include the 'err' keyword

* defined-or is definitely NOT available in 5.6.x

All my perl-5.8.x builds include this patch, so all people that use my
perl builds on HP-UX, will have it available.

One major distribution also included it in their perl builds, but I do
not remember which it is.

My personal preference for the lowest usable and reliable perl version
is 5.8.5 (FWIW)

> > Now the real question was if we still support anything older, and if so
> > what is the bottom version?
> >
> > I certainly can go with "5.8.1 or later", but I vaguely recall during the
> > gitweb discussion we said anything without the utf-8 support is unusable
> > for gitweb, but I think we also said that the rest of the git codebase
> > should support running with something older (5.6.1, perhaps).
> 
> 15 minutes of research:
> 
> * 2006-06-25 Junio C Hamano: "Tentatively let's say our cut-off point is
>   somewhere around 5.6." --
>   http://article.gmane.org/gmane.comp.version-control.git/22607
> 
> * 2008-05-30 Lea Wiemann: "Gitweb relies on Unicode support (e.g. "use
>   Encode") and will continue to be compatible with 5.8 and 5.10 only" --
>   http://article.gmane.org/gmane.comp.version-control.git/83339
> 
> * 2008-08-13 Lea Wiemann: "This makes Git.pm dependent on Perl 5.6.1. Some
>   tests (like t3701-add-interactive.sh) seem to work with pretty much any Perl
>   version out there, and requiring File::Spec changes this" --
>   http://article.gmane.org/gmane.comp.version-control.git/92260
> 
> * 2008-08-15 Marcus Griep: "Git.pm: Make File::Spec and File::Temp requirement
>   lazy" -- c14c8ce
> 
> * 2008-08-30 Junio C Hamano: "I agree we should say we rely on 5.6 or newer."
>   -- http://article.gmane.org/gmane.comp.version-control.git/94399
> 
> * 2008-09-01 Junio C Hamano: "I personally think it is probably Ok to declare
>   that we do depend on 5.8" --
>   http://article.gmane.org/gmane.comp.version-control.git/94523
> 
> 
> So here's my take-away. For the *.perl scripts and gitweb, it's 5.8.0. For the
> test suite and Git.pm, all Perl versions are theoretically supported, but for
> practical purposes, it may be 5.6.0.
> 
> Whatever is decided this time, perhaps it should be burned into the tops of
> the *.perl scripts (i.e. "require 5.008;"). It should also be added to
> CodingGuidelines. You know, so this conversation doesn't keep recurring. :-)

-- 
H.Merijn Brand  http://tux.nl      Perl Monger  http://amsterdam.pm.org/
using & porting perl 5.6.2, 5.8.x, 5.10.x, 5.11.x on HP-UX 10.20, 11.00,
11.11, 11.23, and 11.31, OpenSuSE 10.3, 11.0, and 11.1, AIX 5.2 and 5.3.
http://mirrors.develooper.com/hpux/           http://www.test-smoke.org/
http://qa.perl.org      http://www.goldmark.org/jeff/stupid-disclaimers/

Re: Oldest supported Perl version

[Johannes Schindelin]

Hi,

On Mon, 20 Apr 2009, H.Merijn Brand wrote:

> * defined-or is available in any version of perl 5.8.x is the binary
>   was built with the appropriate patch, which is available on my CPAN
>   directory:
>   ftp://download.xs4all.nl/pub/mirror/CPAN/authors/id/H/HM/HMBRAND/
>   These patches still include the 'err' keyword

Do you realize how much _pain_ you cause here?  I just do not have the 
_time_ to recompile Perl 5.8 for msysGit!

Bah,
Dscho "who thinks that a lot of people would not introduce dependencies 
so lightly if they actually felt the pain they cause"

Re: Oldest supported Perl version

[H.Merijn Brand]

On Mon, 20 Apr 2009 19:29:03 +0200 (CEST), Johannes Schindelin
<Johannes.Schindelin@gmx.de> wrote:

> Hi,
> 
> On Mon, 20 Apr 2009, H.Merijn Brand wrote:
> 
> > * defined-or is available in any version of perl 5.8.x is the binary
> >   was built with the appropriate patch, which is available on my CPAN
> >   directory:
> >   ftp://download.xs4all.nl/pub/mirror/CPAN/authors/id/H/HM/HMBRAND/
> >   These patches still include the 'err' keyword
> 
> Do you realize how much _pain_ you cause here?

Me? Why?
I just couldn't line *without* defined-or after I first encountered it,
so I backported it to 5.8.x (after some patch from someone else) and
people thought it would be a good idea to semi-officially allow it to
be available for all.

Officially, defined-or is *NOT* available in perl-5.8.x. End of story.

*ALL* my production code expects defined-or to be available.

> I just do not have the _time_ to recompile Perl 5.8 for msysGit!

Sorry, I can't help you there

> Bah,
> Dscho "who thinks that a lot of people would not introduce dependencies 
> so lightly if they actually felt the pain they cause"

-- 
H.Merijn Brand  http://tux.nl      Perl Monger  http://amsterdam.pm.org/
using & porting perl 5.6.2, 5.8.x, 5.10.x, 5.11.x on HP-UX 10.20, 11.00,
11.11, 11.23, and 11.31, OpenSuSE 10.3, 11.0, and 11.1, AIX 5.2 and 5.3.
http://mirrors.develooper.com/hpux/           http://www.test-smoke.org/
http://qa.perl.org      http://www.goldmark.org/jeff/stupid-disclaimers/

Re: Oldest supported Perl version

[Jakub Narebski]

Jay Soffian <jaysoffian@gmail.com> writes:

> On Sun, Apr 19, 2009 at 9:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Now the real question was if we still support anything older, and if so
> > what is the bottom version?
> >
> > I certainly can go with "5.8.1 or later", but I vaguely recall during the
> > gitweb discussion we said anything without the utf-8 support is unusable
> > for gitweb, but I think we also said that the rest of the git codebase
> > should support running with something older (5.6.1, perhaps).

> So here's my take-away. For the *.perl scripts and gitweb, it's
> 5.8.0. For the test suite and Git.pm, all Perl versions are
> theoretically supported, but for practical purposes, it may be
> 5.6.0.

Errr... no.  For gitweb we require good Unicode support, which means
Perl 5.8.x (IIRC 5.8.1).  For all other: commands (and helpers)
written in Perl like git-svn, fragments of Perl in test suite (because
of incompatibility and corner cases of shell scripting) - with possible
exception of testing gitweb, and Git.pm (which some commands in Perl
use) I think it is reasonable to expect 5.6.0 at least.

> Whatever is decided this time, perhaps it should be burned into the tops of
> the *.perl scripts (i.e. "require 5.008;"). It should also be added to
> CodingGuidelines. You know, so this conversation doesn't keep recurring. :-)
> 
> j.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: Oldest supported Perl version

[Jay Soffian]

On Mon, Apr 20, 2009 at 1:59 PM, Jakub Narebski <jnareb@gmail.com> wrote:
> Jay Soffian <jaysoffian@gmail.com> writes:
>> So here's my take-away. For the *.perl scripts and gitweb, it's
>> 5.8.0. For the test suite and Git.pm, all Perl versions are
>> theoretically supported, but for practical purposes, it may be
>> 5.6.0.
>
> Errr... no.  For gitweb we require good Unicode support, which means
> Perl 5.8.x (IIRC 5.8.1).  For all other: commands (and helpers)
> written in Perl like git-svn, fragments of Perl in test suite (because
> of incompatibility and corner cases of shell scripting) - with possible
> exception of testing gitweb, and Git.pm (which some commands in Perl
> use) I think it is reasonable to expect 5.6.0 at least.

Um, isn't that basically exactly what I said? The only difference is
you're clarifying gitweb to be 5.8.1 instead of 5.8.0. Fine. that's
why this went to the git list.

j.

Re: Oldest supported Perl version

[Jay Soffian]

On Mon, Apr 20, 2009 at 2:27 PM, Jay Soffian <jaysoffian@gmail.com> wrote:
> Um, isn't that basically exactly what I said? The only difference is
> you're clarifying gitweb to be 5.8.1 instead of 5.8.0. Fine. that's
> why this went to the git list.

Oh sorry, I see we differ on the *.perl scripts. You're saying 5.6 for
those. I was suggesting 5.8 for the *.perl scripts based on:

http://article.gmane.org/gmane.comp.version-control.git/94523

Anyway, I see that there are basically a few categories to decide on:

1) gitweb
2) the *.perl scripts
3) Git.pm
4) the parts of the test suite that use perl

I think there is consensus that (1) is 5.8.1 for unicode reasons. (3)
and (4), for all practical purposes, are apparently 5.6.0. So that
leaves (2), which is either 5.6.0 or 5.8.1 depending upon which gmane
thread you consult.

j.

Re: Oldest supported Perl version

[Michael Witten]

On Mon, Apr 20, 2009 at 13:32, Jay Soffian <jaysoffian@gmail.com> wrote:
> Anyway, I see that there are basically a few categories to decide on:
>
> 1) gitweb
> 2) the *.perl scripts
> 3) Git.pm
> 4) the parts of the test suite that use perl
>
> I think there is consensus that (1) is 5.8.1 for unicode reasons. (3)
> and (4), for all practical purposes, are apparently 5.6.0. So that
> leaves (2), which is either 5.6.0 or 5.8.1 depending upon which gmane
> thread you consult.

It looks like 5.6.0 was released a DECADE ago. Drop it.

My advice is to take the advice of Perl hacker H.Merijn Brand:

> My personal preference for the lowest usable and reliable perl version
is 5.8.5 (FWIW)

Re: Oldest supported Perl version

[Johannes Schindelin]

Hi,

On Mon, 20 Apr 2009, Michael Witten wrote:

> It looks like 5.6.0 was released a DECADE ago. Drop it.

What part of "causing others a lot of pain" did you not understand, 
exactly?

Ciao,
Dscho

Re: Oldest supported Perl version

[Michael Witten]

On Mon, Apr 20, 2009 at 14:11, Johannes Schindelin
<Johannes.Schindelin@gmx.de> wrote:
> Hi,
>
> On Mon, 20 Apr 2009, Michael Witten wrote:
>
>> It looks like 5.6.0 was released a DECADE ago. Drop it.
>
> What part of "causing others a lot of pain" did you not understand,
> exactly?

I'd say: Take your own advice.

It's very likely that requiring compatibility with a DECADE old perl
is going to cause others a lot of pain.

At some point, backward compatibility is just stupid; it's meant for TRANSITION.

Re: Oldest supported Perl version

[H.Merijn Brand]

On Mon, 20 Apr 2009 10:59:14 -0700 (PDT), Jakub Narebski
<jnareb@gmail.com> wrote:

> Jay Soffian <jaysoffian@gmail.com> writes:
> 
> > On Sun, Apr 19, 2009 at 9:58 PM, Junio C Hamano <gitster@pobox.com> wrote:
> > >
> > > Now the real question was if we still support anything older, and if so
> > > what is the bottom version?
> > >
> > > I certainly can go with "5.8.1 or later", but I vaguely recall during the
> > > gitweb discussion we said anything without the utf-8 support is unusable
> > > for gitweb, but I think we also said that the rest of the git codebase
> > > should support running with something older (5.6.1, perhaps).
> 
> > So here's my take-away. For the *.perl scripts and gitweb, it's
> > 5.8.0. For the test suite and Git.pm, all Perl versions are
> > theoretically supported, but for practical purposes, it may be
> > 5.6.0.
> 
> Errr... no.  For gitweb we require good Unicode support, which means
> Perl 5.8.x (IIRC 5.8.1).  For all other: commands (and helpers)

Unicode? 5.8.4 or up. Most desirable 5.8.5
5.8.1 is the worst distribution ever.

ask purl on irc :
 <Tux> purl, perl-5.8.1?
<purl> i guess perl-5.8.1 is made from blood, sweat, tears, coffee and single malt

> written in Perl like git-svn, fragments of Perl in test suite (because
> of incompatibility and corner cases of shell scripting) - with possible
> exception of testing gitweb, and Git.pm (which some commands in Perl
> use) I think it is reasonable to expect 5.6.0 at least.

5.6.1 or 5.8.5

> > Whatever is decided this time, perhaps it should be burned into the tops of
> > the *.perl scripts (i.e. "require 5.008;"). It should also be added to
> > CodingGuidelines. You know, so this conversation doesn't keep recurring. :-)

-- 
H.Merijn Brand  http://tux.nl      Perl Monger  http://amsterdam.pm.org/
using & porting perl 5.6.2, 5.8.x, 5.10.x, 5.11.x on HP-UX 10.20, 11.00,
11.11, 11.23, and 11.31, OpenSuSE 10.3, 11.0, and 11.1, AIX 5.2 and 5.3.
http://mirrors.develooper.com/hpux/           http://www.test-smoke.org/
http://qa.perl.org      http://www.goldmark.org/jeff/stupid-disclaimers/

Re: Oldest supported Perl version

[Michael Witten]

On Mon, Apr 20, 2009 at 16:10, H.Merijn Brand <h.m.brand@xs4all.nl> wrote:
> 5.8.1 is the worst distribution ever.

But then you endorse 5.6.1?

Re: Oldest supported Perl version

[Michael Witten]

On Mon, Apr 20, 2009 at 17:38, Michael Witten <mfwitten@gmail.com> wrote:
> On Mon, Apr 20, 2009 at 16:10, H.Merijn Brand <h.m.brand@xs4all.nl> wrote:
>> 5.8.1 is the worst distribution ever.
>
> But then you endorse 5.6.1?

That is:

But then you endorse 5.6.1 if 5.8.5 is not chosen.

Re: Oldest supported Perl version

[H.Merijn Brand]

On Mon, 20 Apr 2009 17:39:34 -0500, Michael Witten <mfwitten@gmail.com>
wrote:

> On Mon, Apr 20, 2009 at 17:38, Michael Witten <mfwitten@gmail.com> wrote:
> > On Mon, Apr 20, 2009 at 16:10, H.Merijn Brand <h.m.brand@xs4all.nl> wrote:
> >> 5.8.1 is the worst distribution ever.
> >
> > But then you endorse 5.6.1?
> 
> That is:
> 
> But then you endorse 5.6.1 if 5.8.5 is not chosen.

5.6.1 and 5.6.2 are fine for non-Unicode environments.

When using Unicode (utf-8) and/or 64bit, I'd strongly advise not to go
below 5.8.5

-- 
H.Merijn Brand  http://tux.nl      Perl Monger  http://amsterdam.pm.org/
using & porting perl 5.6.2, 5.8.x, 5.10.x, 5.11.x on HP-UX 10.20, 11.00,
11.11, 11.23, and 11.31, OpenSuSE 10.3, 11.0, and 11.1, AIX 5.2 and 5.3.
http://mirrors.develooper.com/hpux/           http://www.test-smoke.org/
http://qa.perl.org      http://www.goldmark.org/jeff/stupid-disclaimers/

Re: Oldest supported Perl version

[Jeff King]

On Mon, Apr 20, 2009 at 10:59:00AM -0400, Jay Soffian wrote:

> Whatever is decided this time, perhaps it should be burned into the tops of
> the *.perl scripts (i.e. "require 5.008;"). It should also be added to
> CodingGuidelines. You know, so this conversation doesn't keep recurring. :-)

I have no real comment on _which_ version, but yes, I think a 'require'
for the right version would be very helpful. The error messages you get
when running on a too-old version can be confusing, at best. Saying "you
need a newer perl" would be much nicer.

-Peff

[PATCH RFC3.5 00/12] Introduction to Decreasing send-email Entropy

[Michael Witten]

This patch series introduces some very basic refactorizations and
improvements to send-email. My goal was to keep each patch relatively
small, but it may be better to look at the results of the following
patches:

	[PATCH RFC3.5 06/12] send-email: Cleanup and streamline the SMTP code in send_message
	[PATCH RFC3.5 07/12] send-email: Cleanup send_message 'log' code
	[PATCH RFC3.5 09/12] Docs: send-email: Reorganize the CONFIGURATION section

The overall diffstat:

	Documentation/git-send-email.txt |  201 ++++++++++++++++++++----
	git-send-email.perl              |  317 +++++++++++++++++++++++++-------------
	2 files changed, 376 insertions(+), 142 deletions(-)

The over all patch series:

	[PATCH RFC3.5 01/12] send-email: Cleanup the usage text and docs a bit
	[PATCH RFC3.5 02/12] send-email: No longer repeatedly test if $smtp_server is a command
	[PATCH RFC3.5 03/12] send-email: Interpret --smtp-server "" as "use a default".
	[PATCH RFC3.5 04/12] send-email: Verification for --smtp-server and --smpt-server-port
	[PATCH RFC3.5 05/12] send-email: Improve redability and error-handling in send_message's sendmail code
	[PATCH RFC3.5 06/12] send-email: Cleanup and streamline the SMTP code in send_message
	[PATCH RFC3.5 07/12] send-email: Cleanup send_message 'log' code
	[PATCH RFC3.5 08/12] send-email: Move Subject sanitization from --compose code to send_message
	[PATCH RFC3.5 09/12] Docs: send-email: Reorganize the CONFIGURATION section
	[PATCH RFC3.5 10/12] Docs: Embolden the CONFIGURATION references
	[PATCH RFC3.5 11/12] Docs: send-email: Clarification of sendemail.<identity>
	[PATCH RFC3.5 12/12] Docs: send-email: git send-email -> 'send-email'

Sincerely,
Michael Witten

[PATCH RFC3.5 01/12] send-email: Cleanup the usage text and docs a bit

[Michael Witten]

--chain-reply-to doesn't take an argument.

The here-document quotation that defines the usage
text is now a single-quote form, so that no interpolation
takes place.

All usage text lines should be < 80 characters.

The usage text's option arguments match those of the docs.

The 'host:port' form of argument for --smtp-server was only
working for SSL connections, because the SSL connection code
was relying on undocumented behavior of Net::SMTP::SSL (really,
undocumented behavior of Net::SMTP's new method). Because the
main documentation for send-email doesn't even list it as valid,
<str:int> has been replaced with just <server> and <host | command>
in the usage text; this is only temporary and for purity.

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-send-email.txt |   21 ++++++++-------
 git-send-email.perl              |   49 +++++++++++++++++++++-----------------
 2 files changed, 38 insertions(+), 32 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index f7e428e..071e9bf 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -74,8 +74,9 @@ See the CONFIGURATION section for 'sendemail.multiedit'.
 	the value GIT_COMMITTER_IDENT, as returned by "git var -l".
 	The user will still be prompted to confirm this entry.
 
---in-reply-to=<identifier>::
-	Specify the contents of the first In-Reply-To header.
+--in-reply-to=<message-id>::
+	Specify the contents of the first In-Reply-To header;
+	include the angle brackets `<` and `>`.
 	Subsequent emails will refer to the previous email
 	instead of this if --chain-reply-to is set (the default)
 	Only necessary if --compose is also set.  If --compose
@@ -106,7 +107,7 @@ Sending
 	the 'sendemail.envelopesender' configuration variable; if that is
 	unspecified, choosing the envelope sender is left to your MTA.
 
---smtp-encryption=<encryption>::
+--smtp-encryption=<type>::
 	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
 	value reverts to plain SMTP.  Default is the value of
 	'sendemail.smtpencryption'.
@@ -123,20 +124,20 @@ or on the command line. If a username has been specified (with
 specified (with '--smtp-pass' or 'sendemail.smtppass'), then the
 user is prompted for a password while the input is masked for privacy.
 
---smtp-server=<host>::
+--smtp-server=<server>::
 	If set, specifies the outgoing SMTP server to use (e.g.
 	`smtp.example.com` or a raw IP address).  Alternatively it can
 	specify a full pathname of a sendmail-like program instead;
 	the program must support the `-i` option.  Default value can
 	be specified by the 'sendemail.smtpserver' configuration
-	option; the built-in default is `/usr/sbin/sendmail` or
-	`/usr/lib/sendmail` if such program is available, or
+	variable; the built-in default is `/usr/sbin/sendmail` or
+	`/usr/lib/sendmail` if such a program is available, or
 	`localhost` otherwise.
 
 --smtp-server-port=<port>::
 	Specifies a port different from the default port (SMTP
 	servers typically listen to smtp port 25 and ssmtp port
-	465); symbolic port names (e.g. "submission" instead of 465)
+	465); symbolic service names (e.g. "submission" instead of 587)
 	are also accepted. The port can also be set with the
 	'sendemail.smtpserverport' configuration variable.
 
@@ -158,7 +159,7 @@ Automating
 	Output of this command must be single email address per line.
 	Default is the value of 'sendemail.cccmd' configuration value.
 
---[no-]chain-reply-to=<identifier>::
+--[no-]chain-reply-to::
 	If this is set, each email will be sent as a reply to the previous
 	email sent.  If disabled with "--no-chain-reply-to", all emails after
 	the first will be sent as replies to the first email sent.  When using
@@ -170,7 +171,7 @@ Automating
 	A configuration identity. When given, causes values in the
 	'sendemail.<identity>' subsection to take precedence over
 	values in the 'sendemail' section. The default identity is
-	the value of 'sendemail.identity'.
+	the value of the 'sendemail.identity' configuration variable.
 
 --[no-]signed-off-by-cc::
 	If this is set, add emails found in Signed-off-by: or Cc: lines to the
@@ -214,7 +215,7 @@ specified, as well as 'body' if --no-signed-off-cc is specified.
 Administering
 ~~~~~~~~~~~~~
 
---confirm=<mode>::
+--confirm=<when>::
 	Confirm just before sending:
 +
 --
diff --git a/git-send-email.perl b/git-send-email.perl
index 04267c5..e43342e 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -42,46 +42,51 @@ package main;
 
 
 sub usage {
-	print <<EOT;
+
+	# All printed lines should be less than 80 characters.
+
+	print <<'EOT';
 git send-email [options] <file | directory | rev-list options >
 
   Composing:
-    --from                  <str>  * Email From:
-    --to                    <str>  * Email To:
-    --cc                    <str>  * Email Cc:
-    --bcc                   <str>  * Email Bcc:
-    --subject               <str>  * Email "Subject:"
-    --in-reply-to           <str>  * Email "In-Reply-To:"
-    --annotate                     * Review each patch that will be sent in an editor.
+    --from              <address>  * Email From:
+    --to                <address>  * Email To:
+    --cc                <address>  * Email Cc:
+    --bcc               <address>  * Email Bcc:
+    --subject            <string>  * Email "Subject:"
+    --in-reply-to    <message-id>  * Email "In-Reply-To:"; include '<' and '>'.
+    --annotate                     * Review each patch that will be sent in
+                                     an editor.
     --compose                      * Open an editor for introduction.
 
   Sending:
-    --envelope-sender       <str>  * Email envelope sender.
-    --smtp-server       <str:int>  * Outgoing SMTP server to use. The port
-                                     is optional. Default 'localhost'.
-    --smtp-server-port      <int>  * Outgoing SMTP server port.
-    --smtp-user             <str>  * Username for SMTP-AUTH.
-    --smtp-pass             <str>  * Password for SMTP-AUTH; not necessary.
-    --smtp-encryption       <str>  * tls or ssl; anything else disables.
+    --envelope-sender   <address>  * Email envelope sender.
+    --smtp-server        <server>  * Outgoing SMTP server. <host | command>
+    --smtp-server-port     <port>  * Outgoing SMTP server port; symbolic too.
+    --smtp-user        <username>  * Username for SMTP-AUTH.
+    --smtp-pass       [<password>] * Password for SMTP-AUTH; not necessary.
+    --smtp-encryption      <type>  * tls or ssl; anything else disables.
     --smtp-ssl                     * Deprecated. Use '--smtp-encryption ssl'.
 
   Automating:
-    --identity              <str>  * Use the sendemail.<id> options.
-    --cc-cmd                <str>  * Email Cc: via `<str> \$patch_path`
-    --suppress-cc           <str>  * author, self, sob, cc, cccmd, body, bodycc, all.
-    --[no-]signed-off-by-cc        * Send to Signed-off-by: addresses. Default on.
+    --identity         <identity>  * Use the sendemail.<identity> options.
+    --cc-cmd            <command>  * Email Cc: via `<command> $patch_path`
+    --suppress-cc      <category>  * author, self, sob, cc, cccmd, body,
+                                     bodycc, all.
+    --[no-]signed-off-by-cc        * Send to Signed-off-by: addresses.
+                                     Default on.
     --[no-]suppress-from           * Send to self. Default off.
     --[no-]chain-reply-to          * Chain In-Reply-To: fields. Default on.
     --[no-]thread                  * Use In-Reply-To: field. Default on.
 
   Administering:
-    --confirm               <str>  * Confirm recipients before sending;
+    --confirm              <when>  * Confirm recipients before sending;
                                      auto, cc, compose, always, or never.
     --quiet                        * Output one line of info per email.
     --dry-run                      * Don't actually send the emails.
     --[no-]validate                * Perform patch sanity checks. Default on.
-    --[no-]format-patch            * understand any non optional arguments as
-                                     `git format-patch` ones.
+    --[no-]format-patch            * Understand any non-optional arguments as
+                                     `git format-patch' arguments.
 
 EOT
 	exit(1);
-- 
1.6.2.2.479.g2aec

[PATCH RFC3.5 02/12] send-email: No longer repeatedly test if $smtp_server is a command

[Michael Witten]

This is a minor change, but it's cleaner, and it sets up the
$smtp_server initialization code for future improvements.

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 git-send-email.perl |   19 ++++++++++++++-----
 1 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index e43342e..1a20b2c 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -186,7 +186,8 @@ sub do_edit {
 
 # Variables with corresponding config settings
 my ($thread, $chain_reply_to, $suppress_from, $signed_off_by_cc, $cc_cmd);
-my ($smtp_server, $smtp_server_port, $smtp_authuser, $smtp_encryption);
+my ($smtp_server, $smtp_server_is_a_command);
+my ($smtp_server_port, $smtp_authuser, $smtp_encryption);
 my ($identity, $aliasfiletype, @alias_files, @smtp_host_parts);
 my ($validate, $confirm);
 my (@suppress_cc);
@@ -674,14 +675,22 @@ if (defined $initial_reply_to) {
 	$initial_reply_to = "<$initial_reply_to>" if $initial_reply_to ne '';
 }
 
-if (!defined $smtp_server) {
+if (defined $smtp_server) {
+
+	$smtp_server_is_a_command = ($smtp_server =~ m{^/});
+
+} else { # use a default:
+
 	foreach (qw( /usr/sbin/sendmail /usr/lib/sendmail )) {
 		if (-x $_) {
 			$smtp_server = $_;
+			$smtp_server_is_a_command = 1;
 			last;
 		}
 	}
-	$smtp_server ||= 'localhost'; # could be 127.0.0.1, too... *shrug*
+
+	$smtp_server = 'localhost'; # 127.0.0.1 is not compatible with IPv6
+		unless $smtp_server_is_a_command;
 }
 
 if ($compose && $compose > 0) {
@@ -882,7 +891,7 @@ X-Mailer: git-send-email $gitversion
 
 	if ($dry_run) {
 		# We don't want to send the email.
-	} elsif ($smtp_server =~ m#^/#) {
+	} elsif ($smtp_server_is_a_command) {
 		my $pid = open my $sm, '|-';
 		defined $pid or die $!;
 		if (!$pid) {
@@ -958,7 +967,7 @@ X-Mailer: git-send-email $gitversion
 		printf (($dry_run ? "Dry-" : "")."Sent %s\n", $subject);
 	} else {
 		print (($dry_run ? "Dry-" : "")."OK. Log says:\n");
-		if ($smtp_server !~ m#^/#) {
+		unless ($smtp_server_is_a_command) {
 			print "Server: $smtp_server\n";
 			print "MAIL FROM:<$raw_from>\n";
 			print "RCPT TO:".join(',',(map { "<$_>" } @recipients))."\n";
-- 
1.6.2.2.479.g2aec

[PATCH RFC3.5 03/12] send-email: Interpret --smtp-server "" as "use a default".

[Michael Witten]

Why not? It's at least useful for testing.

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-send-email.txt |    4 +++-
 git-send-email.perl              |    2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 071e9bf..ae01632 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -132,7 +132,9 @@ user is prompted for a password while the input is masked for privacy.
 	be specified by the 'sendemail.smtpserver' configuration
 	variable; the built-in default is `/usr/sbin/sendmail` or
 	`/usr/lib/sendmail` if such a program is available, or
-	`localhost` otherwise.
+	`localhost` otherwise. Also, a built-in default is used if
+	`<host>` or 'sendemail.smtpserver' is the empty string (for
+	example, if '--smtp-server ""' is specified on the command line).
 
 --smtp-server-port=<port>::
 	Specifies a port different from the default port (SMTP
diff --git a/git-send-email.perl b/git-send-email.perl
index 1a20b2c..5e669c7 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -675,7 +675,7 @@ if (defined $initial_reply_to) {
 	$initial_reply_to = "<$initial_reply_to>" if $initial_reply_to ne '';
 }
 
-if (defined $smtp_server) {
+if (defined $smtp_server && $smtp_server ne '') {
 
 	$smtp_server_is_a_command = ($smtp_server =~ m{^/});
 
-- 
1.6.2.2.479.g2aec

[PATCH RFC3.5 04/12] send-email: Verification for --smtp-server and --smpt-server-port

[Michael Witten]

The server URI is verified according to RFCs (including IPv6 support).

The $smtp_server and $smtp_server_port setup code has been moved
higher in the file, so that send-email fails fast if they are bad.

Now, the 'host:port' server URI form is handled regardless of the
documentation deficiencies of Net::SMTP{,::SSL}.

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-send-email.txt |   50 ++++++++++++-----
 git-send-email.perl              |  115 +++++++++++++++++++++++++++++++------
 2 files changed, 131 insertions(+), 34 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index ae01632..92985ee 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -125,23 +125,43 @@ specified (with '--smtp-pass' or 'sendemail.smtppass'), then the
 user is prompted for a password while the input is masked for privacy.
 
 --smtp-server=<server>::
-	If set, specifies the outgoing SMTP server to use (e.g.
-	`smtp.example.com` or a raw IP address).  Alternatively it can
-	specify a full pathname of a sendmail-like program instead;
-	the program must support the `-i` option.  Default value can
-	be specified by the 'sendemail.smtpserver' configuration
-	variable; the built-in default is `/usr/sbin/sendmail` or
-	`/usr/lib/sendmail` if such a program is available, or
-	`localhost` otherwise. Also, a built-in default is used if
-	`<host>` or 'sendemail.smtpserver' is the empty string (for
-	example, if '--smtp-server ""' is specified on the command line).
+	Specifies the outgoing SMTP server to use. The server may be
+	given as a domain name (e.g. `smtp.example.com:587`), raw IP
+	address (e.g. `192.168.0.1`), or absolute path to a command
+	(e.g. `/usr/sbin/sendmail`).
++
+Usually a server is specified with its URI form:
++
+	host[:port]
++
+The optional port, which identifies a particular service at the
+given host, is normally provided as a non-negative integer that
+is representable in 16-bits; however, it is possible to use any
+string composed of some combination of alphanumeric characters, the
+underscore, the hyphen, and punctuation (special) characters, so
+that symbolic service names can be employed (as defined by, say,
+`/etc/services` on Unix systems).
++
+Alternatively the server can be specified as an absolute path to
+a sendmail-like program; in particular, the program must support
+`sendmail's` `-i` option.
++
+Default value can be specified by the 'sendemail.smtpserver'
+configuration variable; the built-in default is `/usr/sbin/sendmail`
+or `/usr/lib/sendmail` if such a program is available, or `localhost`
+otherwise. Also, a built-in default is used if `<server>` or
+'sendemail.smtpserver' is the empty string (for example, if
+'--smtp-server ""' is specified on the command line).
 
 --smtp-server-port=<port>::
-	Specifies a port different from the default port (SMTP
-	servers typically listen to smtp port 25 and ssmtp port
-	465); symbolic service names (e.g. "submission" instead of 587)
-	are also accepted. The port can also be set with the
-	'sendemail.smtpserverport' configuration variable.
+	Specifies a port different from the default port (SMTP servers
+	typically listen to port 25, 587, or even non-standard 465); symbolic
+	service names (e.g. "submission" instead of 587) are also accepted,
+	provided the underlying system handles mappings in something like
+	`/etc/services`; such service names may only be composed of some
+	combination of alphanumeric characters, the underscore, the hyphen,
+	and punctuation (special) characters. The port can also be set with
+	the 'sendemail.smtpserverport' configuration variable.
 
 --smtp-ssl::
 	Legacy alias for '--smtp-encryption ssl'.
diff --git a/git-send-email.perl b/git-send-email.perl
index 5e669c7..e2c7954 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -61,7 +61,7 @@ git send-email [options] <file | directory | rev-list options >
 
   Sending:
     --envelope-sender   <address>  * Email envelope sender.
-    --smtp-server        <server>  * Outgoing SMTP server. <host | command>
+    --smtp-server        <server>  * Outgoing SMTP server: <host[:port] | cmd>.
     --smtp-server-port     <port>  * Outgoing SMTP server port; symbolic too.
     --smtp-user        <username>  * Username for SMTP-AUTH.
     --smtp-pass       [<password>] * Password for SMTP-AUTH; not necessary.
@@ -328,6 +328,101 @@ foreach my $setting (values %config_bool_settings) {
 # 'default' encryption is none -- this only prevents a warning
 $smtp_encryption = '' unless (defined $smtp_encryption);
 
+# Define a function that verifies a server URI and returns
+# its host and port parts:
+
+sub parse_server_URI($) {
+
+	# These regular experssions were derived from:
+	#   * RFC 2373 (Appendix B) : IP Version 6 Addressing Architecture
+	#   * RFC 2732 (Section  3) : Format for Literal IPv6 Addresses in URL's
+	#   * RFC 2396 (Sec. 3.2.2) : Uniform Resource Identifiers (URI): Generic Syntax
+	# Also, ports are allowed to be symbolic, so that /etc/services mappings
+	# can be used.
+
+	# Define a port (RFC 2396 and extension):
+
+	my $port = qr/[\w[:punct:]]+/;
+
+	# Define an IPv4 address (RFC 2373):
+
+	my $dig3        = qr/\d{1,3}/;
+	my $IPv4address = qr/$dig3(?:\.$dig3){3}/;
+
+	# Define an IPv6 address (RFC 2373):
+
+	my $hex4        = qr/[[:xdigit:]]{1,4}/;
+	my $hexseq      = qr/$hex4(?::$hex4)*/;  		# RFC 2373 is really that loose.
+	my $hexpart     = qr/$hexseq|$hexseq?::$hexseq?/;
+	my $IPv6address = qr/$hexpart(?::$IPv4address)?/;
+
+	# Define an IPv6 literal (RFC 2732):
+
+	my $IPv6reference = qr/\[$IPv6address\]/;
+
+	# Define a server URI (RFC 2396 and RFC 2732):
+
+	my $toplabel    = qr/[[:alpha:]](?:(?:[[:alnum:]]|-)*[[:alpha:]])?/;
+	my $domainlabel = qr/[[:alnum:]](?:(?:[[:alnum:]]|-)*[[:alnum:]])?/;
+	my $hostname    = qr/(?:$domainlabel\.)*$toplabel\.?/;
+	my $host        = qr/$hostname|$IPv4address|$IPv6reference/;
+	my $hostport    = qr/^($host)(?::($port))?$/;
+
+	# Phew! Now parse
+
+	return shift =~ $hostport;
+}
+
+# Figure out how to contact the SMTP server.
+# After this code, $smtp_server_port is either
+# valid or undef:
+
+if (defined $smtp_server && $smtp_server ne '') {
+
+	if ($smtp_server_is_a_command = ($smtp_server =~ m{^/})) {
+
+		die "--smtp-server: The SMTP server command does not exist: $smtp_server\n"
+			unless -x $smtp_server;
+
+		print STDERR "--smtp-server: Using command '$smtp_server'; ignoring --smtp-server-port='$smtp_server_port'\n"
+			if defined $smtp_server_port;
+
+	} else {
+
+		($smtp_server, my $port) = parse_server_URI $smtp_server
+			or die "--smtp-server: Not a valid server URI: '$smtp_server'\n";
+
+		if (defined $smtp_server_port) {
+
+			$smtp_server_port =~ /[\w[:punct:]]+/ or die "--smtp-server-port: Invalid port: '$smtp_server_port'\n";
+
+			print STDERR "--smtp-server-port: Using port '$smtp_server_port'; ignoring --smtp-server's port '$port'\n"
+				if defined $port;
+
+		} else {
+
+			$smtp_server_port = $port;
+		}
+	}
+
+} else { # use a default:
+
+	foreach (qw( /usr/sbin/sendmail /usr/lib/sendmail )) {
+		if (-x $_) {
+			$smtp_server = $_;
+			$smtp_server_is_a_command = 1;
+
+			print STDERR "--smtp-server: Using command '$smtp_server'; ignoring --smtp-server-port='$smtp_server_port'\n"
+				if defined $smtp_server_port;
+
+			last;
+		}
+	}
+
+	$smtp_server = 'localhost'; # 127.0.0.1 is not compatible with IPv6
+		unless $smtp_server_is_a_command;
+}
+
 # Set CC suppressions
 my(%suppress_cc);
 if (@suppress_cc) {
@@ -675,24 +770,6 @@ if (defined $initial_reply_to) {
 	$initial_reply_to = "<$initial_reply_to>" if $initial_reply_to ne '';
 }
 
-if (defined $smtp_server && $smtp_server ne '') {
-
-	$smtp_server_is_a_command = ($smtp_server =~ m{^/});
-
-} else { # use a default:
-
-	foreach (qw( /usr/sbin/sendmail /usr/lib/sendmail )) {
-		if (-x $_) {
-			$smtp_server = $_;
-			$smtp_server_is_a_command = 1;
-			last;
-		}
-	}
-
-	$smtp_server = 'localhost'; # 127.0.0.1 is not compatible with IPv6
-		unless $smtp_server_is_a_command;
-}
-
 if ($compose && $compose > 0) {
 	@files = ($compose_filename . ".final", @files);
 }
-- 
1.6.2.2.479.g2aec

Re: [PATCH RFC3.5 04/12] send-email: Verification for --smtp-server and --smpt-server-port

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

> The server URI is verified according to RFCs (including IPv6 support).
>
> The $smtp_server and $smtp_server_port setup code has been moved
> higher in the file, so that send-email fails fast if they are bad.
>
> Now, the 'host:port' server URI form is handled regardless of the
> documentation deficiencies of Net::SMTP{,::SSL}.

You said that in 01/12, too but I do not think there is any problem with
Perl documentation.

My installed copy of /usr/share/perl/5.10.0/Net/SMTP.pm has this:

    B<Host> - SMTP host to connect to. It may be a single scalar, as defined for
    the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
    an array with hosts to try in turn. The L</host> method will return the value
    which was used to connect to the host.

and of course PeerAddr allows host:port.

Please stop placing a false blame on others.  I think it is you who lack
ability to read the documentation correctly in this particular case.

Re: [PATCH RFC3.5 04/12] send-email: Verification for --smtp-server and --smpt-server-port

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Please stop placing a false blame on others.  I think it is you who lack
> ability to read the documentation correctly in this particular case.

Sorry, this came out stronger than I intended.  Your ability has never
been an issue (otherwise there wouldn't have been this patch series).  I
think you just did not read the documentation carefully enough in this
case.

Re: [PATCH RFC3.5 04/12] send-email: Verification for --smtp-server and --smpt-server-port

[Michael Witten]

On Sun, Apr 19, 2009 at 20:42, Junio C Hamano <gitster@pobox.com> wrote:
> Michael Witten <mfwitten@gmail.com> writes:
> ...
>> Now, the 'host:port' server URI form is handled regardless of the
>> documentation deficiencies of Net::SMTP{,::SSL}.
>
> You said that in 01/12, too but I do not think there is any problem with
> Perl documentation.
>
> My installed copy of /usr/share/perl/5.10.0/Net/SMTP.pm has this:
>
>    B<Host> - SMTP host to connect to. It may be a single scalar, as defined for
>    the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
>    an array with hosts to try in turn. The L</host> method will return the value
>    which was used to connect to the host.
>
> and of course PeerAddr allows host:port.
>
> Please stop placing a false blame on others.  I think it is you who lack
> ability to read the documentation correctly in this particular case.

Take a look again at my commit message for 01/12:

	The 'host:port' form of argument for --smtp-server was only
	working for SSL connections, because the SSL connection code
	was relying on undocumented behavior of Net::SMTP::SSL (really,
	undocumented behavior of Net::SMTP's new method)...

Clearly my beef is with Net::SMTP--->::SSL<---

I touch upon this in the commit message for 06/12:

	The code could even be simplified further, because Net::SMTP{,::SSL}
	both take the PORT variable in their new methods (which, as of this
	commit, are actually the same method). Moreover, both take a server
	URI of the form 'host:port' that trumps any value passed to PORT.

	Unfortunately, none of this is documented publicly, so it isn't
	exploited out of purity.

Net::SMTP doesn't document the PORT key, even though it's the one that
implements the constructor for both Net::SMTP and Net::SMTP::SSL. Also,
Net::SMTP:SSL doesn't document whether PORT shadows the ':port' in any
'host:port' input.

So... I remain resolved in my stance: The documentation is poor and
"--smtp-server host:port" only worked because the code relies on the
undocumented behavior of the ':port' taking precedence of over any
PORT specification. 

> I think you just did not read the documentation carefully enough in this
> case.

Actually, I think I read it too carefully and thought about it too much.

On Sun, Apr 19, 2009 at 21:38, Junio C Hamano <gitster@pobox.com> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Please stop placing a false blame on others.  I think it is you who lack
>> ability to read the documentation correctly in this particular case.
>
> Sorry, this came out stronger than I intended.

That's OK. I tend to sound harsher than I want as well.

> Your ability has never been an issue (otherwise there wouldn't have been
> this patch series).

I appreciate that remark; I'm admittedly not important, but I hope that
I'm at least useful.

Now let's get back to work!

Sincerely,
Michael Witten