From: Junio C Hamano <gitster@pobox.com>
Date: Sun, 10 Oct 2021 21:33:28 GMT
Subject: Re: [RFC PATCH] Documentation: better document format-patch options in send-email
Message-ID: <xmqq1r4sftuf.fsf@gitster.g>
In-Reply-To: <CAPUEsphrNMPO_KaAmae02-DsxB9m1tBEK_Gnv29_mLQn0j2MkA@mail.gmail.com>

Carlo Arenas <carenas@gmail.com> writes:

>> > +If you give a single <commit> and nothing else, it is taken as the
>> > +<since> of the first form.  If you want to format everything from the
>> > +beginning of history up until <commit>, use the `--root` option:
>> > +`git format-patch --root <commit>`.
>>
>> Supposed that we have following commit graph:
>>
>> a --- b --- c --- d --- e --- f (main)
>>              \
>>               --- g --- h --- i (mywork, HEAD)
>>
>> According to your edit, `git format-patch <c>` and `git format-patch
>> --root <i>` are equivalent, right?
>
> I didn't change the definition of --root with my edit, but I guess it
> is still confusing.

The explanation you gave Bagas describes what these two variants,
i.e. "<c> alone" and "--root <c>", mean and how they behave very
clearly.  In fact, the 4-line description is designed to encourage
readers to compare a pair of cases like these, using the same commit
in the middle of the history you get two quite different set of
commits with and without "--root".

You can ask for "--root <i>" to get a-b-c-g-h-i but it is not
a good example as there is no useful contrasting example that does
not use "--root", as "git format-patch i" would be showing an empty
set.

The fact that somebody wanted to compare between "<c>" and "--root
<i>" might be a sign that the 4-line description is still somehow
confusing, but I cannot quite figure out what needs to be improved
in the description to avoid such a confusion (IOW, I fail to see how
the description can lead to such a confusion).

Thanks.