Re: [PATCH] git-send-email.txt: Add EXAMPLES section. Write 1st level sections in uppercase

[Michael J Gruber <git@drmicha.warpmail.net>]

jari.aalto@cante.net venit, vidit, dixit 15.04.2010 17:37:
> 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:

That sentence is linguistically screwed, but...

> +
> +	git send-email \
> +		--from $EMAIL \
> +		--to address@list.example.com \
> +		--suppress-cc=author \
> +		--suppress-from \
> +		--no-chain-reply-to \
> +		--confirm=never \
> +		outgoing/
> +

... 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,
we want one with few options, where the default behaviour is explained.

> +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'. 

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

> 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)..
> +

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
@{upstream} might be a more general option.

> +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
>