Re: [RFC PATCH] Documentation: better document format-patch options in send-email

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 10, 2021, 21:33 UTC
Message-ID: <xmqq1r4sftuf.fsf@gitster.g>
In-Reply-To: <CAPUEsphrNMPO_KaAmae02-DsxB9m1tBEK_Gnv29_mLQn0j2MkA@mail.gmail.com>

Carlo Arenas <carenas@gmail.com> writes:

Show 16 quoted lines

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