On 2021-01-10 at 01:41:23, Junio C Hamano wrote: > "brian m. carlson" <sandals@xxxxxxxxxxxxxxxxxxxx> 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:
signature.asc
Description: PGP signature
