Re: [PATCH v2 0/2] Sparse checkout status

[Elijah Newren <newren@gmail.com>]

On Thu, Jun 18, 2020 at 4:18 PM Elijah Newren <newren@gmail.com> wrote:
>
> On Thu, Jun 18, 2020 at 2:46 PM Junio C Hamano <gitster@pobox.com> wrote:
> >
> > "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
> >
> > > Some of the feedback of folks trying out sparse-checkouts at $dayjob is that
> > > sparse checkouts can sometimes be disorienting; users can forget that they
> > > had a sparse-checkout and then wonder where files went. This series adds
> > > some output to 'git status' and modifies git-prompt slightly as an attempt
> > > to help.
> > >
> > > Note that as per discussion on v1, we may want to later add a git
> > > sparse-checkout subcommand named something like 'stats' or 'info' or
> > > 'status' that provides more detailed information for users to dig deeper.
> > > That would be an additional improvement for helping users find out more
> > > information once they realize or remember they are in a sparse checkout,
> > > this is just aimed at giving them a simple reminder.
> > >
> > > Changes since v1:
> > >
> > >  * Replaced the -1 magic constant with SPARSE_CHECKOUT_DISABLED
> > >  * Fixed a possible division by 0 (when there are no entries in the index
> > >    AND sparse checkout is enabled; not sure when that'd ever happen but
> > >    still better to guard against...)
> > >  * Slight wording tweaks for the git-prompt commit message
> > >  * Removed the RFC label
> > >
> > > Elijah Newren (2):
> > >   wt-status: show sparse checkout status as well
> > >   git-prompt: include sparsity state as well
> > >
> > >  contrib/completion/git-prompt.sh |  7 +++++-
> > >  wt-status.c                      | 41 ++++++++++++++++++++++++++++++++
> > >  wt-status.h                      |  2 ++
> > >  3 files changed, 49 insertions(+), 1 deletion(-)
> >
> > Any change to Documentation/git-status.txt?
>
> Reasonable question; I didn't think of it.  But on a related note, in
> the eight years we've had status output for various other forms of
> state (in-progress operations like merge, cherry-pick, rebase, or
> bisect), these haven't been documented either.  Was that also
> oversight, or was there a reason it was left out?
>
> If oversight, should I just document all those others while I'm at it?

So, I went to look at this.  Documentation/git-status.txt documents in
detail the short status format, the porcelain V1 format, and the
porcelain V2 format.  There are two side comments that the long format
is the default, and that status.submoduleSummary affects the long
output, but the only thing it says to document the contents of the
long format is:
"""
The default, long format, is designed to be human readable,
verbose and descriptive.  Its contents and format are subject to change
at any time.
"""
It would thus feel odd to mention the sparsity status within the long
format when nothing else within that format is documented.  I suspect
that's why it was never added when rebase/merge/cherry-pick/bisect
state notifications were added to the long format.