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

On 2021-01-10 at 12:28:40, Alan Mackenzie wrote:

On Sat, Jan 09, 2021 at 17:41:23 -0800, Junio C Hamano wrote:

quoted

I am actually tempted to suggest rewriting the whole section,
starting from the paragraph above and ending at the table, with
something like this:

quoted

    Three different classes of paths are shown in the same format,
    but the meaning of `XY` are different:

quoted

    * For merged paths, `X` shows the status of the index, and `Y`
      shows the status of the working tree.

quoted

    * For unmerged paths, `X` and `Y` show the modification states
      of each side of the merge, relative to the common ancestor.

Also missing from the current doc, I think, is a description of which
"side" of the difference is represented by X, and which by Y.  In my use
case (having conflicts after doing a git stash pop) those "sides" would
be the work tree and the repository.  In other scenarios (say a merge
conflict after git pull) I think they would be something else (though my
head is hurting a bit, here).

The two sides are the two heads that are being merged and don't include
the working tree at all.  I think the answer about which side is which
in a merge depends on whether you're merging or rebasing.  Rebases do
things the opposite way of how merges do them.

In your case, you're interested in the fact that there _is_ an
unresolved conflict, which means you'll either get DD, AA, or something
with a U in it.  That will happen regardless of how you do it, with git
pull, git merge, git rebase -m, or git cherry-pick, and it indicates
that the working tree is "broken" (i.e., has conflict markers) and the
index is in a conflicted state.  Since the state of the working tree and
the index are known, we use this field for listing the two heads
instead.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US