Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 20, 2015, 19:59 UTC
Message-ID: <xmqqoaj6y50b.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1437416790-5792-5-git-send-email-philipoakley@iee.org>

Philip Oakley <philipoakley@iee.org> writes:

Show 6 quoted lines

> +git-send-email invokes the cc-cmd like this:
> +
> +	$cc-cmd $patchfilename
> +
> +Thus the patch itself can be processed to locate appropriate email address
> +information if required.

That's not even a valid command line (cc-cmd cannot be a shell variable name), so why bother writing it that way? Rather

    The program that is specified by `cc-cmd` is invoked by `git
    send-email` with the name of the patch file as an argument;
    the program can read from it and customize its output based on
    what the patch file contains.
    
or something like that, perhaps.

> +
> +A simple solution for a basic address list is to create a 'cc-cmd' file
> +(executable) which provides a list of addressees:

There is no "problem" stated here that requires your "solution". In fact, what problem are you solving?

Show 5 quoted lines

> +	#!/bin/sh
> +	echo <<\EOF
> +	person1@example.com
> +	person2@example.com
> +	EOF

That is one simple and denegerate use case; if the program does not need any information from the patch file, it surely has an option not to look at it. But it is not an interesting usage.

If you want to add a single example to illustrate how cc-cmd (or to-cmd, or anything that goes thru recipients_cmd()), you should have an example that reads the input and then adds a few hardcoded one.

	#!/bin/sh
	# always send it to the logger service
        echo "patchlog@example.com"
	# tell the bug tracker as necessary
	if fixes=$(sed -ne 's/^Fixes bug#\([0-9]*\)/\1/p' "$1")
        then
		echo "bugs+$fixes@example.com"
	fi

or something silly like that.

And this ...

Show 5 quoted lines

> +Simply, using `cat cc-cmd` as the --cc-cmd (with cc-cmd as the text file
> +of email addresses), does not work as expected as the invocation becomes:
> +
> +	$cat cc-cmd $patchfilename
> +

... and the rest of the patch is unnecessary noise to a reader who read that the single argument to the program is the name of the patchfile, I think. You were trying to avoid the same confusion caused by the sketchy documentaiton, and you already "solved" that problem by telling the reader what the command takes as its input.

> +    --cc-cmd='cat cc-cmd #'

This heavily depends on the current implementation that happens to pass the command line string to a shell.