Re: [PATCH] docs: document zero bits in index "mode"

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 1, 2023, 16:56 UTC
Message-ID: <xmqqmt5xwchh.fsf@gitster.g>
In-Reply-To: <20230201024041.29401-1-chooglen@google.com>

Glen Choo <chooglen@google.com> writes:

> Documentation/gitformat-index.txt describes the "mode" as 32 bits, but
> only documents 16 bits. Document the missing 16 bits and specify that
> 'unused' bits must be zero.

I actually think the bottom 16-bit should just be described as allowing only a limited set of possible values and list them all, but this is good as an incremental improvement [*]

Thanks.

Show 13 quoted lines

>    32-bit mode, split into (high to low bits)
>  
> +    16-bit unused, must be zero
> +
>      4-bit object type
>        valid values in binary are 1000 (regular file), 1010 (symbolic link)
>        and 1110 (gitlink)
>  
> -    3-bit unused
> +    3-bit unused, must be zero
>  
>      9-bit unix permission. Only 0755 and 0644 are valid for regular files.
>      Symbolic links and gitlinks have value 0 in this field.

[Footnote]

If I am not mistaken, there are only four possible values allowed. So, instead of "split into...", we could just say

        32-bit "mode", which can be one of

          Regular non-executable file     100644
          Regular executable file         100755
          Symbolic link                   120000
          Git link                        160000

        No other values are allowed.

but we can move one step at a time ;-)