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
      +'

gitgitgadget