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

Carlo Arenas [off-list ref] writes:

quoted

quoted

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