[PATCH v3 0/3] Sparse checkout status

["Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com>]

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.
     +
          Signed-off-by: Elijah Newren <newren@gmail.com>
      
       ## 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