Sparse checkout status

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.

(As per discussion on v1, a "git sparse-checkout [status|info|status]" might supplement the changes from this series later; this is just aimed at giving users a simple reminder that they are in a sparse checkout.)

Changes since v2:

* Added an extra commit to document how git-prompt works with in-progress state of operations (rebase/merge/cherry-pick/revert/bisect), since I want to refer to it for comparison later in the docs.
* As requested by SZEDER, added the ability to shorten or remove the information relating to sparsity state in the git-prompt.
* Since there are now three options for whether and how to show information related to sparsity state, I put a fair amount of effort into reasoning among the options about what is a good default and why; I included this in the final commit message. (While I suspect that we can easily change the default for the prompt in the future based on the big warning at the top of git-sparse-checkout.txt, having the rationale up-front for the original decision may help us out in the future.)

Elijah Newren (3):
wt-status: show sparse checkout status as well
git-prompt: document how in-progress operations affect the prompt
git-prompt: include sparsity state as well

 contrib/completion/git-prompt.sh | 26 ++++++++++++++++++--
 wt-status.c                      | 41 ++++++++++++++++++++++++++++++++
 wt-status.h                      |  2 ++
 3 files changed, 67 insertions(+), 2 deletions(-)

base-commit: b3d7a52fac39193503a0b6728771d1bf6a161464
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-808%2Fnewren%2Fsparse-checkout-status-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-808/newren/sparse-checkout-status-v3
Pull-Request: https://github.com/git/git/pull/808

Range-diff vs v2:

 1:  e266bc39d99 = 1:  e266bc39d99 wt-status: show sparse checkout status as well
 -:  ----------- > 2:  1fd1b919684 git-prompt: document how in-progress operations affect the prompt
 2:  17254b30a5b ! 3:  d99202f8e14 git-prompt: include sparsity state as well

@@ Metadata
## Commit message ##
git-prompt: include sparsity state as well

- The current git prompt includes a lot of possible state information from
- cherry-picks, merges, bisects, and various flavors of rebases. Add
- sparsity as another state flavor (though one which can be present
- simultaneously with any of rebase/cherry-pick/merge/bisect). This extra
- state is shown with an extra
+ git-prompt includes the current branch, a bunch of single character
+ mini-state displayers, and some much longer in-progress state
+ notifications. The current branch is always shown. The single
+ character mini-state displayers are all off by default (they are not
+ self explanatory) but each has an environment variable for turning it
+ on. The in-progress state notifications provide no configuration
+ options for turning them off, and can be up to 15 characters long (e.g.
+ "|REBASE (12/18)" or "|CHERRY-PICKING").
+
+ The single character mini-state tends to be used for things like "Do you
+ have any stashes in refs/stash?" or "Are you ahead or behind of
+ upstream?". These are things which users can take advantage of but do
+ not affect most normal git operations. The in-progress states, by
+ contrast, suggest the user needs to interact differently and may also
+ prevent some normal operations from succeeding (e.g. git switch may show
+ an error instead of switching branches).
+
+ Sparsity is like the in-progress states in that it suggests a
+ fundamental different interaction with the repository (many of the files
+ from the repository are not present in your working copy!). A few
+ commits ago added sparsity information to wt_longstatus_print_state(),
+ grouping it with other in-progress state displays. We do similarly here
+ with the prompt and show the extra state, by default, with an extra
|SPARSE
- substring before the other states, providing a prompt that looks like:
+ This state can be present simultaneously with the in-progress states, in
+ which case it will appear before the other states; for example,
(branchname|SPARSE|REBASE 6/10)

The reason for showing the "|SPARSE" substring before other states is to
@@ Commit message
make them appear closer to where the user types and make them more likely to be noticed.

+ The fact that sparsity isn't just cached metadata or additional
+ information is what leads us to show it more similarly to the
+ in-progress states, but the fact that sparsity is not transient like the
+ in-progress states might cause some users to want an abbreviated
+ notification of sparsity state or perhaps even be able to turn it off.
+ Allow GIT_PS1_COMPRESSSPARSESTATE to be set to request that it be
+ shortened to a single character ('?'), and GIT_PS1_OMITSPARSESTATE to be
+ set to request that sparsity state be omitted from the prompt entirely.
+

## contrib/completion/git-prompt.sh ##
+@@
+ # revert, cherry-pick, or bisect, the prompt will include information
+ # related to the operation, often in the form "|<OPERATION-NAME>".
+ #
++# When the repository has a sparse-checkout, a notification of the form ++# "|SPARSE" will be included in the prompt. This can be shortened to a ++# single '?' character by setting GIT_PS1_COMPRESSSPARSESTATE, or omitted ++# by setting GIT_PS1_OMITSPARSESTATE.
++#
+ # By default, __git_ps1 will compare HEAD to your SVN upstream if it can
+ # find one, or @{upstream} otherwise. Once you have set
+ # GIT_PS1_SHOWUPSTREAM, you can override it on a per-repository basis by @@ contrib/completion/git-prompt.sh: __git_ps1 ()
return $exit
fi

+ local sparse=""
-+ if [ "$(git config --bool core.sparseCheckout)" == "true" ]; then
-+ sparse="|SPARSE"
++ if [ -z "${GIT_PS1_COMPRESSSPARSESTATE}" ] &&
++ [ -z "${GIT_PS1_OMITSPARSESTATE}" ] &&
++ [ "$(git config --bool core.sparseCheckout)" == "true" ]; then
++ sparse="|SPARSE"
+ fi
+
local r=""
local b=""
local step=""
@@ contrib/completion/git-prompt.sh: __git_ps1 ()
+ local i=""
+ local s=""
+ local u=""
++ local h=""
+ local c=""
+ local p=""
+
+@@ contrib/completion/git-prompt.sh: __git_ps1 ()
+ u="%${ZSH_VERSION+%}"
+ fi
+
++ if [ -n "${GIT_PS1_COMPRESSSPARSESTATE}" ] &&
++ [ "$(git config --bool core.sparseCheckout)" == "true" ]; then
++ h="?"
++ fi
++
+ if [ -n "${GIT_PS1_SHOWUPSTREAM-}" ]; then
+ __git_ps1_show_upstream
+ fi
+@@ contrib/completion/git-prompt.sh: __git_ps1 ()
+ b="\${__git_ps1_branch_name}"
fi

- local f="$w$i$s$u"
+- local f="$w$i$s$u"
- local gitstring="$c$b${f:+$z$f}$r$p"
++ local f="$h$w$i$s$u"
+ local gitstring="$c$b${f:+$z$f}${sparse}$r$p"

if [ $pcmode = yes ]; then

gitgitgadget