Subject: Re: git format-patch --range-diff accepts non-quoted arguments (shouldn't it be?)

From: Junio C Hamano <[email-masked]>
Date: Fri, 08 Oct 2021 11:10:35 -0700

Bagas Sanjaya <[email-masked]> writes:

> I think it is rather odd that `git format-patch --range-diff` accepts
> <previous> argument without enclosed in quotes, since it is always 
> multi-word (separated by space). E.g., below works:

What do you mean by "it" in "since it is always"?  If you meant
"<previous>", your may want to re-read "git format-patch --help".

The <previous> will most likely not be a multi-word argument
separated by a space.  It is a way to specify the "previous range",
i.e. one of the two ranges given to the range-diff command to be
compared.  The other range is what the user gave the command to
specify what patches to work on for the latest iteration.

So...

>     $ git format-patch <options> --range-diff=main..previous main..HEAD

This works of course, because <previous> is main..previous (without
any SP anywhere, and needs no quoting), main..HEAD is the range to
take patches from *and* also given to range-diff as the current
range.

> but below returns nothing:
>
>     $ git format-patch <options> --range-diff="main..previous main..HEAD"

This gives an empty range to work on to the command.  The range-diff
argument seems strange, but if we are not emitting a single patch or
cover letter, perhaps there is no place to emit the range-diff so it
may not get any complaint.

> Should the quoted <previous> argument to --range-diff be allowed, and
> forbid the unquoted counterpart?

No, I think the command is fine as-is.

Stepping back a bit, if you have two topics (perhaps related,
perhaps not) forked from the mainline, but you want to present
them as a single unit to the outside world, you may do this:

    $ git format-patch ^master topic-1 topic-2

If two topics share their early commits and their later commits are
independent and do not interact with each other, this command line
should do the right thing to emit shared ones only once.

If these were the second iteration, I would imagine

    $ git format-patch \
	--range-diff='^master@{last.week} topic-1@{last.week} topic-2@{last.week}' \
	^master topic-1 topic-2

would be a good way to include the range-diff for this round
relative to the previous round you sent last week.

So, quoting <previous> may be necessary in a more complex usecase,
but most of the time you should not have to quote.

HTH.