Re: [PATCH v4 06/13] commit-graph: implement git commit-graph read

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 22, 2018, 18:25 UTC
Message-ID: <xmqqo9kgx4op.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <xmqq371uyufx.fsf@gitster-ct.c.googlers.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 15 quoted lines

> Derrick Stolee <stolee@gmail.com> writes:
>
>> +'read'::
>> +
>> +Read a graph file given by the graph-head file and output basic
>> +details about the graph file.
>> ++
>> +With `--file=<name>` option, consider the graph stored in the file at
>> +the path  <object-dir>/info/<name>.
>> +
>
> A sample reader confusion after reading the above twice:
>
>     What is "the graph-head file" and how does the user specify it?  Is
>     it given by  the value for the "--file=<name>" command line option?

This confusion is somewhat lightened with s/graph-head/graph-latest/ (I just saw 07/13 to realize that the file is renamed).

Perhaps describe it as "Read the graph file currently active (i.e. the one pointed at by graph-latest file in the object/info directory) and output blah" + "With --file parameter, read the graph file specified with that parameter instead"?