From: Jari Aalto <jari.aalto@cante.net>


Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-send-email.txt |   36 ++++++++++++++++++++++++++++++++++--
 1 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index ced35b2..8b33eb0 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -299,8 +299,40 @@ sendemail.confirm::
 	one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
 	in the previous section for the meaning of these values.
 
+EXAMPLES
+--------
 
-Author
+To batch send all patches to a mailig list, no copies to oneself,
+messages in a relaxed single thread format (no nesting) and don't ask
+any confirmations:
+
+	git send-email \
+		--from $EMAIL \
+		--to address@list.example.com \
+		--suppress-cc=author \
+		--suppress-from \
+		--no-chain-reply-to \
+		--confirm=never \
+		outgoing/
+
+Tip: in case the patches in a branch need rework, you might consider
+adjusting the subjects of each patch to "[PATCH v<number>]" with
+options '--subject-prefix'. The 'merge-base' inside command
+substitution is there to find out the initial commit of the branch:
+
+	git checkout BRANCH
+
+	git format-patch \
+		--subject-prefix="PATCH v2" \
+		--signoff \
+		-M \
+		--output-directory outgoing/
+		$(git merge-base HEAD master)..
+
+Then proceed as in in the first example the send the patches out
+again.
+
+AUTHOR
 ------
 Written by Ryan Anderson <ryan@michonline.com>
 
@@ -308,7 +340,7 @@ git-send-email is originally based upon
 send_lots_of_email.pl by Greg Kroah-Hartman.
 
 
-Documentation
+DOCUMENTATION
 --------------
 Documentation by Ryan Anderson
 
-- 
1.7.0

--

[ message continues ]

... I don't think this is a good example at all. All options are
explained in the man page, so what is the point in listing and
explaining some of them here? If we really want an introductory example,

That is a git.git convention, and it applies to format-patch, not

This is a useful example (although it mixes several issues), but one for
format-patch, not send-email. You assume you branched off master. Using

--

[ message continues ]

Please improve. How would you explain the options and their explanations


I don't agree.

We need examples that use most of the options in combination so that the
examples can practically "copy pasted / sliced off". The user can eaily
reduce options he may not find useful from the examples.

    With too few options presented, he needs to skim through the whole
    of 31 option explanations above and pray he finds what he needs.

Please suggest another example to be accompanied with this one. How do
you use the git-send-email? What options? What you have configured in
~/.gitconfig?

Jari
--

[ message continues ]

By "but..." and the paragraph below I meant to say that there is no need
to pick on individual typos and such, because I don't favour the
approach anyways.

Looking at the send-email man page, I definitely agree with you that
there is room for improvement. For example, in the end there is a
configuration section listing only very few of the config options. The
reader could easily think these are the only ones. We tend to list them

I don't use any options besides --dry-run and --cc, which is the point
of the config options ;) In config I have to, smtpserver (pointing to an
msmtp-script), bcc, suppresscc, aliasesfile, aliastype, but that depends
on the project, of course (git.git here).

I just think that using all these options on the command line is very
atypical. It would be helpful to see the defaults in one place:

"Without any options, send-email will send patches (using
/usr/sbin/sendmail or /usr/lib/sendmail or localhost) using any from, cc
and subject lines contained in the patch files; you have to specify at
least --to, or else you will be prompted for it.

All defaults pertaining to composing and sending of the patch mails and
to automating this process can be changed with config options, see the
corresponding sections below."

I liked your format-patch example with merge-base, I just liked it
better in format-patch's man page ;)

Michael
--

[ message continues ]

Now, think this:

    You have 30 servers.

    You notice a problem.

    You need that command, whatever that is.

    Consult manual page, yay (Wow, or "Ugh")

    <blink> there is EXMAPLE, options and - Hurray: Copy/Paste and use.

You don't necessarily have full blown "environment" in front of you, so
we need both

    * Full command line exmaples. They are commadn line options after
      all
    * And configuration examples

The more copy/paste ready, the better. The more FAQ like, the better.
Let's make FAQs obsolete.

Thansk for the examples, I'll be revising the patch
Jari
--

[ message continues ]

Having to give too many options from the command line all the time is a
sure sign that the defaults for unconfigured case are bad (which may well
be true but is is hard to change without a good plan) and that it is not
clearly explained how to configure the defaults for the repository.

I do not think it is productive to give an overwhelming list that you
would rarely use (i.e. until you figure out a good set of defaults for the


Likewise.
--

[ message continues ]