[PATCH v3 0/3] "update-index --show-index-version"

Even though there is "test-tool index-version", there wasn't an officially supported way for end-users to inspect the index version of an on-disk index. Let's have one.

This iteration takes suggestions by Linus Arver; the tests added by [2/3] have been clarified.

Junio C Hamano (3):
  update-index doc: v4 is OK with JGit and libgit2
  update-index: add --show-index-version
  test-tool: retire "index-version"

 Documentation/git-update-index.txt    | 14 ++++++++----
 Makefile                              |  1 -
 builtin/update-index.c                | 19 ++++++++++------
 t/helper/test-index-version.c         | 15 -------------
 t/helper/test-tool.c                  |  1 -
 t/helper/test-tool.h                  |  1 -
 t/t1600-index.sh                      |  2 +-
 t/t1700-split-index.sh                |  2 +-
 t/t2104-update-index-skip-worktree.sh |  6 +++---
 t/t2107-update-index-basic.sh         | 31 +++++++++++++++++++++++++++
 10 files changed, 59 insertions(+), 33 deletions(-)
 delete mode 100644 t/helper/test-index-version.c

Range-diff against v2:
1:  7bc7f7877d ! 1:  224a72529a update-index doc: v4 is OK with JGit and libgit2
    @@ Commit message
         cautious about cross-tool compatibility.
     
         Helped-by: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
    +    Helped-by: Linus Arver <linusa@google.com>
         Signed-off-by: Junio C Hamano <gitster@pobox.com>
     
      ## Documentation/git-update-index.txt ##
    @@ Documentation/git-update-index.txt: you will need to handle the situation manual
     -may not support it yet.
     +time.  Git supports it since version 1.8.0, released in October 2012,
     +and support for it was added to libgit2 in 2016 and to JGit in 2020.
    -+Older editions of this manual page called it "relatively young", but
    ++Older versions of this manual page called it "relatively young", but
     +it should be considered mature technology these days.
     +
      
2:  33c924f893 ! 2:  bd3fc76b3f update-index: add --show-index-version
    @@ Metadata
      ## Commit message ##
         update-index: add --show-index-version
     
    -    "git update-index --version N" is used to set the index format
    +    "git update-index --index-version N" is used to set the index format
         version to a specific version, but there was no way to query the
         current version used in the on-disk index file.
     
    @@ Commit message
         teach the "--index-version N" option to report what the version was
         when run with the "--verbose" option.
     
    +    Helped-by: Linus Arver <linusa@google.com>
         Signed-off-by: Junio C Hamano <gitster@pobox.com>
     
      ## Documentation/git-update-index.txt ##
    @@ Documentation/git-update-index.txt: you will need to handle the situation manual
      	Supported versions are 2, 3 and 4. The current default version is 2
      	or 3, depending on whether extra features are used, such as
     -	`git add -N`.
    -+	`git add -N`.  With `--verbose` option, also reports the
    -+	version the index file uses before and after this command.
    ++	`git add -N`.  With `--verbose`, also report the version the index
    ++	file uses before and after this command.
      +
      Version 4 performs a simple pathname compression that reduces index
      size by 30%-50% on large repositories, which results in faster load
     @@ Documentation/git-update-index.txt: and support for it was added to libgit2 in 2016 and to JGit in 2020.
    - Older editions of this manual page called it "relatively young", but
    + Older versions of this manual page called it "relatively young", but
      it should be considered mature technology these days.
      
     +--show-index-version::
    @@ builtin/update-index.c: int cmd_update_index(int argc, const char **argv, const
      		OPT_INTEGER(0, "index-version", &preferred_index_format,
      			N_("write index in this format")),
     +		OPT_SET_INT(0, "show-index-version", &preferred_index_format,
    -+			    N_("show index format version"), -1),
    ++			    N_("report on-disk index format version"), -1),
      		OPT_BOOL(0, "split-index", &split_index,
      			N_("enable or disable split index")),
      		OPT_BOOL(0, "untracked-cache", &untracked_cache,
    @@ t/t2107-update-index-basic.sh: test_expect_success '--chmod=+x and chmod=-x in t
     +test_expect_success '--index-version' '
     +	git commit --allow-empty -m snap &&
     +	git reset --hard &&
    ++	git rm -f -r --cached . &&
     +
    -+	git update-index --index-version 2 >actual &&
    -+	test_must_be_empty actual &&
    -+
    ++	# The default index version is 2 --- update this test
    ++	# when you change it in the code
     +	git update-index --show-index-version >actual &&
     +	echo 2 >expect &&
     +	test_cmp expect actual &&
     +
    ++	# The next test wants us to be using version 2
    ++	git update-index --index-version 2 &&
    ++
     +	git update-index --index-version 4 --verbose >actual &&
     +	echo "index-version: was 2, set to 4" >expect &&
    -+	test_cmp expect actual
    ++	test_cmp expect actual &&
    ++
    ++	git update-index --index-version 4 --verbose >actual &&
    ++	echo "index-version: was 4, set to 4" >expect &&
    ++	test_cmp expect actual &&
    ++
    ++	git update-index --index-version 2 --verbose >actual &&
    ++	echo "index-version: was 4, set to 2" >expect &&
    ++	test_cmp expect actual &&
    ++
    ++	# non-verbose should be silent
    ++	git update-index --index-version 4 >actual &&
    ++	test_must_be_empty actual
     +'
     +
      test_done
3:  137ec82973 ! 3:  d1144a8240 test-tool: retire "index-version"
    @@ Commit message
         test-tool: retire "index-version"
     
         As "git update-index --show-index-version" can do the same thing,
    -    the test-tool lost its reason to exist.
    +    the 'index-version' subcommand in the test-tool lost its reason to
    +    exist.  Remove it and replace its use with the end-user facing
    +    'git update-index --show-index-version'.
     
    +    Helped-by: Linus Arver <linusa@google.com>
         Signed-off-by: Junio C Hamano <gitster@pobox.com>
     
      ## Makefile ##