Merge branch 'nd/doc-index-format' into maint-1.8.1

The v4 index format was not documented.

* nd/doc-index-format:
  update-index: list supported idx versions and their features
  read-cache.c: use INDEX_FORMAT_{LB,UB} in verify_hdr()
  index-format.txt: mention of v4 is missing in some places

Author: gitster

Documentation/git-update-index.txt

@@ -145,7 +145,15 @@ you will need to handle the situation manually.
 
 --index-version <n>::
 	Write the resulting index out in the named on-disk format version.
-	The current default version is 2.
+	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`.
++
+Version 4 performs a simple pathname compression that reduces index
+size by 30%-50% on large repositories, which results in faster load
+time. Version 4 is relatively young (first released in in 1.8.0 in
+October 2012). Other Git implementations such as JGit and libgit2
+may not support it yet.
 
 -z::
 	Only meaningful with `--stdin` or `--index-info`; paths are

Documentation/technical/index-format.txt

@@ -12,7 +12,7 @@ GIT index format
        The signature is { 'D', 'I', 'R', 'C' } (stands for "dircache")
 
      4-byte version number:
-       The current supported versions are 2 and 3.
+       The current supported versions are 2, 3 and 4.
 
      32-bit number of index entries.
 
@@ -93,8 +93,8 @@ GIT index format
     12-bit name length if the length is less than 0xFFF; otherwise 0xFFF
     is stored in this field.
 
-  (Version 3) A 16-bit field, only applicable if the "extended flag"
-  above is 1, split into (high to low bits).
+  (Version 3 or later) A 16-bit field, only applicable if the
+  "extended flag" above is 1, split into (high to low bits).
 
     1-bit reserved for future
 

read-cache.c

@@ -1256,7 +1256,7 @@ static int verify_hdr(struct cache_header *hdr, unsigned long size)
 	if (hdr->hdr_signature != htonl(CACHE_SIGNATURE))
 		return error("bad signature");
 	hdr_version = ntohl(hdr->hdr_version);
-	if (hdr_version < 2 || 4 < hdr_version)
+	if (hdr_version < INDEX_FORMAT_LB || INDEX_FORMAT_UB < hdr_version)
 		return error("bad index version %d", hdr_version);
 	git_SHA1_Init(&c);
 	git_SHA1_Update(&c, hdr, size - 20);