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

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

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

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:
> > I am actually tempted to suggest rewriting the whole section,
> > starting from the paragraph above and ending at the table, with
> > something like this:
> 
> >     Three different classes of paths are shown in the same format,
> >     but the meaning of `XY` are different:
> 
> >     * For merged paths, `X` shows the status of the index, and `Y`
> >       shows the status of the working tree.
> 
> >     * 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

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