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

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Jan 10, 2021, 18:32 UTC
Message-ID: <X/tIWgzANq7e71X7@camp.crustytoothpaste.net>
In-Reply-To: <X/ry+ApdWMFs5l/+@ACM>

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

Show 20 quoted lines

> 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