Re: [PATCH] docs: add description of status output table

["brian m. carlson" <sandals@crustytoothpaste.net>]

[-- Attachment #1: Type: text/plain, Size: 1855 bytes --]

On 2021-01-10 at 01:41:23, Junio C Hamano wrote:
> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
> 
> > The table describing the porcelain format in git-status(1) is helpful,
> > but it's not completely clear what the three sections mean, even to
> > some contributors.  As a result, users are unable to find how to detect
> > common cases like merge conflicts programmatically.
> 
> I agree that the addition clarifies, but it is a bit sad that we
> already have a beginning of the explanation; I wonder if we should
> improve the existing description in addition, even if it may not be
> sufficient to eliminate the need for this new paragraph.  Here is
> what we already have:
> 
>     For paths with merge conflicts, `X` and `Y` show the modification
>     states of each side of the merge. For paths that do not have merge
>     conflicts, `X` shows the status of the index, and `Y` shows the status
>     of the work tree.  For untracked paths, `XY` are `??`.  Other status
>     codes can be interpreted as follows:
> 
> This introductory text does sort-of hint that there are three
> classes (merged paths, unmerged paths and untracked paths), but (1)
> the order the three classes are described do not match that of the
> table, and (2) the explanation of the untracked paths predates the
> addition of ignored ones to the untracked class, so the description
> is added after the legends as if an afterthought.
> 
> I am actually tempted to suggest rewriting the whole section,
> starting from the paragraph above and ending at the table, with
> something like this:

Sure, I can reroll with that.  I noticed that we're using a text diagram
instead of a table, so maybe I can fix that up as well in v2, depending
how the output looks.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]