Re: [PATCH] Document git rev-list --first-parent

Avi Kivity [off-list ref] writes:

Junio C Hamano wrote:

quoted

Avi Kivity [off-list ref] writes:

quoted

Document git rev-list's --first-parent option.  Documentation taken from
git log.
...
+--first-parent::
+	Follow only the first parent commit upon seeing a merge
+	commit.  This  option gives a better overview of the
+	evolution of a particular branch.
+

I am afraid that this description is not sufficient.  The
history given by --first-parent is useful only in a very limited
use case, and the user needs to be aware of it.

I don't know which use case you are referring to...

Please read the commit log message you snarfed the description
again.

First-parent is useful only if you are the primary integrator
and do not fast-forward from other people.  Only in that case,
you will see the overview of "the primary integration branch".
Otherwise you will observe the history viewed by whoever
happened to make a merge, which would switch every time you
cross the fast-forward boundary.

Making it sound as if it always will give a better overview is
misleading.