[PATCH v3 0/2] ls-files: add %(skipworktree) atom to format option

Add a %(skipworktree) atom git ls-files --format to indicate whether the file in the index match the sparse specification.

v1: add %(skipworktree) atom to git ls-files format option. v2:

 1. no longer mentioned git ls-files -t.
 2. change %(skipworktree) output from "true"/"false" to "1"/"".
 3. fix the sparse-checkout docs link. v3:
 4. fixed numbering of paragraphs in documentation by using ".".
 5. revised little test style.

ZheNing Hu (2):
  docs: fix sparse-checkout docs link
  ls-files: add %(skipworktree) atom to format option

 Documentation/Makefile                      |  1 +
 Documentation/git-ls-files.txt              |  4 ++
 Documentation/technical/sparse-checkout.txt | 55 +++++++++++++--------
 builtin/ls-files.c                          |  3 ++
 t/t3013-ls-files-format.sh                  | 16 ++++++
 5 files changed, 59 insertions(+), 20 deletions(-)

base-commit: a7caae2729742fc80147bca1c02ae848cb55921a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1458%2Fadlternative%2Fzh%2Fls-file-format-skipworktree-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1458/adlternative/zh/ls-file-format-skipworktree-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1458

Range-diff vs v2:

 1:  cde4827da13 ! 1:  3bdd3ceb16c docs: fix sparse-checkout docs link
     @@ Documentation/technical/sparse-checkout.txt: operate full-tree.
       
      -0. Behavior A is not well supported in Git.  (Behavior B didn't used to
      -   be either, but was the easier of the two to implement.)
     -+Behavior A is not well supported in Git.  (Behavior B didn't used to
     ++. Behavior A is not well supported in Git.  (Behavior B didn't used to
      +be either, but was the easier of the two to implement.)
       
     - 1. am and apply:
     +-1. am and apply:
     ++. am and apply:
       
     +    apply, without `--index` or `--cached`, relies on files being present
     +    in the working copy, and also writes to them unconditionally.  As
      @@ Documentation/technical/sparse-checkout.txt: been working on it.
     +    files and then complain that those vivified files would be
     +    overwritten by merge.
     + 
     +-2. reset --hard:
     ++. reset --hard:
     + 
     +    reset --hard provides confusing error message (works correctly, but
     +    misleads the user into believing it didn't):
     +@@ Documentation/technical/sparse-checkout.txt: been working on it.
     +     `git reset --hard` DID remove addme from the index and the working tree, contrary
     +     to the error message, but in line with how reset --hard should behave.
     + 
     +-3. read-tree
     ++. read-tree
     + 
     +    `read-tree` doesn't apply the 'SKIP_WORKTREE' bit to *any* of the
     +    entries it reads into the index, resulting in all your files suddenly
     +    appearing to be "deleted".
     + 
     +-4. Checkout, restore:
     ++. Checkout, restore:
     + 
     +    These command do not handle path & revision arguments appropriately:
     + 
     +@@ Documentation/technical/sparse-checkout.txt: been working on it.
     +     S tracked
     +     H tracked-but-maybe-skipped
     + 
     +-5. checkout and restore --staged, continued:
     ++. checkout and restore --staged, continued:
     + 
     +    These commands do not correctly scope operations to the sparse
     +    specification, and make it worse by not setting important SKIP_WORKTREE
     +@@ Documentation/technical/sparse-checkout.txt: been working on it.
     +    the sparse specification, but then it will be important to set the
     +    SKIP_WORKTREE bits appropriately.
     + 
     +-6. Performance issues; see:
     ++. Performance issues; see:
           https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/
       
       
 2:  9ebd6b77a69 ! 2:  15e77743f7f ls-files: add %(skipworktree) atom to format option
     @@ Documentation/git-ls-files.txt: eolattr::
       path::
       	The pathname of the file which is recorded in the index.
      +skipworktree::
     -+	If the file in the index marked with SKIP_WORKTREE bit.
     -+	It means the file do not match the sparse specification.
     ++	Whether the file in the index has the SKIP_WORKTREE bit set.
      +	See link:technical/sparse-checkout.txt[sparse-checkout]
      +	for more information.
       
     @@ t/t3013-ls-files-format.sh: test_expect_success 'git ls-files --format with --de
      +	git add dir1 dir2 &&
      +	git commit -m skipworktree &&
      +	git sparse-checkout set dir1 &&
     -+	git ls-files --format="%(path)%(skipworktree)" >actual &&
     ++	git ls-files --format="%(skipworktree) %(path)" "dir*" >actual &&
      +	cat >expect <<-\EOF &&
     -+	dir1/file1.txt
     -+	dir2/file2.txt1
     -+	o1.txt
     -+	o2.txt
     -+	o3.txt
     -+	o4.txt
     -+	o5.txt
     -+	o6.txt
     -+	o7.txt
     ++	 dir1/file1.txt
     ++	1 dir2/file2.txt
      +	EOF
      +	test_cmp expect actual
      +'