[PATCH 1/2] index-format.txt: mention of v4 is missing in some places

[PATCH 1/2] index-format.txt: mention of v4 is missing in some places

[Nguyễn Thái Ngọc Duy]

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 Documentation/technical/index-format.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 27c716b..0810251 100644
--- a/Documentation/technical/index-format.txt
+++ b/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
 
-- 
1.8.1.2.536.gf441e6d

[PATCH 2/2] read-cache.c: use INDEX_FORMAT_{LB,UB} in verify_hdr()

[Nguyễn Thái Ngọc Duy]

9d22778 (read-cache.c: write prefix-compressed names in the index -
2012-04-04) defined these. Interestingly, they were not used by
read-cache.c, or anywhere in that patch. They were used in
builtin/update-index.c later for checking supported index
versions. Use them here too.

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 read-cache.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/read-cache.c b/read-cache.c
index 827ae55..298161f 100644
--- a/read-cache.c
+++ b/read-cache.c
@@ -1260,7 +1260,8 @@ 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 ||
+	    hdr_version > INDEX_FORMAT_UB)
 		return error("bad index version %d", hdr_version);
 	git_SHA1_Init(&c);
 	git_SHA1_Update(&c, hdr, size - 20);
-- 
1.8.1.2.536.gf441e6d

Re: [PATCH 1/2] index-format.txt: mention of v4 is missing in some places

[Junio C Hamano]

Nguyễn Thái Ngọc Duy  <pclouds@gmail.com> writes:

> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
> ---
>  Documentation/technical/index-format.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
> index 27c716b..0810251 100644
> --- a/Documentation/technical/index-format.txt
> +++ b/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

Depending on how the first later version decides to encode the
additional flag information, "or later" may need to be changed to
"and 4" when it happens.  As we cannot predict the future, I think
"or later" is just as good as "add 4" for now.

Thanks.

Re: [PATCH 2/2] read-cache.c: use INDEX_FORMAT_{LB,UB} in verify_hdr()

[Junio C Hamano]

Nguyễn Thái Ngọc Duy  <pclouds@gmail.com> writes:

> 9d22778 (read-cache.c: write prefix-compressed names in the index -
> 2012-04-04) defined these. Interestingly, they were not used by
> read-cache.c, or anywhere in that patch. They were used in
> builtin/update-index.c later for checking supported index
> versions. Use them here too.

Thanks.

> -	if (hdr_version < 2 || 4 < hdr_version)
> +	if (hdr_version < INDEX_FORMAT_LB ||
> +	    hdr_version > INDEX_FORMAT_UB)
>  		return error("bad index version %d", hdr_version);

[PATCH 3/2] update-index: list supported idx versions and their features

[Nguyễn Thái Ngọc Duy]

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 .. and the user should know (briefly) the differences between index
 versions too.

 Documentation/git-update-index.txt | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 77a912d..e5aaba5 100644
--- a/Documentation/git-update-index.txt
+++ b/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 could
+	reduce index size by 30%-50% on large repositories, which
+	results in faster load time. Version 4 is relatively young
+	(first released in 1.8.0 in October 2012). Other Git
+	implementations may not support it yet.
 
 -z::
 	Only meaningful with `--stdin` or `--index-info`; paths are
-- 
1.8.1.2.536.gf441e6d

[PATCH v2 3/2] update-index: list supported idx versions and their features

[Nguyễn Thái Ngọc Duy]

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 Oops, bogus indentation in the first 3/2

 Documentation/git-update-index.txt | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 77a912d..dbb75f4 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -145,7 +145,14 @@ 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 could reduce
+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 may not support it yet.
 
 -z::
 	Only meaningful with `--stdin` or `--index-info`; paths are
-- 
1.8.1.2.536.gf441e6d

Re: [PATCH 3/2] update-index: list supported idx versions and their features

[Jonathan Nieder]

Nguyễn Thái Ngọc Duy wrote:

> --- a/Documentation/git-update-index.txt
> +++ b/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 could
> +	reduce index size by 30%-50% on large repositories, which
> +	results in faster load time. Version 4 is relatively young
> +	(first released in 1.8.0 in October 2012). Other Git
> +	implementations may not support it yet.

Markup nit: the second paragraph needs to be unindented, or asciidoc
will treat it as literal text, including line breaks.

Usage nit: s/could/can/

Clarity nit: something like "such as JGit and libgit2" after "Other
Git implementations" would make it clearer, at least to my eyes.

Aside from that, this looks like a good change.

Thanks,
Jonathan

Re: [PATCH v2 3/2] update-index: list supported idx versions and their features

[Jonathan Nieder]

Nguyễn Thái Ngọc Duy wrote:

>  Oops, bogus indentation in the first 3/2

Oops, I missed this.  Ok, ignore the comment on indentation on v1. :)

With or without the other changes I suggested,
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Re: [PATCH 3/2] update-index: list supported idx versions and their features

[Junio C Hamano]

Thanks, both.

Jonathan Nieder <jrnieder@gmail.com> writes:

> Nguyễn Thái Ngọc Duy wrote:
> ...
>> +	Version 4 performs a simple pathname compression that could
>> +	reduce index size by 30%-50% on large repositories, which
>> +	results in faster load time. Version 4 is relatively young
>> +	(first released in 1.8.0 in October 2012). Other Git
>> +	implementations may not support it yet.
>
> Usage nit: s/could/can/

I think s/could reduce/reduces/ is even simpler.

Re: [PATCH 3/2] update-index: list supported idx versions and their features

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:
>> Nguyễn Thái Ngọc Duy wrote:

>>> +	Version 4 performs a simple pathname compression that could
>>> +	reduce index size by 30%-50% on large repositories, which
>>> +	results in faster load time. Version 4 is relatively young
>>> +	(first released in 1.8.0 in October 2012). Other Git
>>> +	implementations may not support it yet.
>>
>> Usage nit: s/could/can/
>
> I think s/could reduce/reduces/ is even simpler.

Yes, true.  Thanks.