threads / patch / 59170

patchdocs: document zero bits in index "mode"

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

## tl;dr

3 messages between Feb 1, 2023 and Feb 1, 2023. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Glen Choo· Feb 1, 2023, 02:40 UTC · lore

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.

Signed-off-by: Glen Choo <chooglen@google.com>
---

>                 The existing explanation starts with "32-bit mode,
> split into (high to low bits)", followed by "4-bit object type", as
> if the "4-bit object type" occupies bits 29-32, which is not quite
> what we want to say.

If I am understanding you correctly (which I'm not sure, since I am honestly clueless about bit numbering and big endianness and whatnot), you're saying that highest 16 bits are zero, not the lowest? If so, then I genuinely made that mistake, hah.

(We're storing 16 bits as bigendian 32 bits, so they would occupy the lower 16 bits, right..?)

Perhaps something like this would be better. I took the "unused, must be zero" phrasing from elsewhere in the doc. And if I am completely off-base, feel free to patch it without waiting for my reroll if you think that's easier.

 Documentation/gitformat-index.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

Show changes to Documentation/gitformat-index.txt +3 −1

diff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.txt
index 015cb21bdc..0773e5c380 100644
--- a/Documentation/gitformat-index.txt
+++ b/Documentation/gitformat-index.txt
@@ -83,11 +83,13 @@ Git index format
 
   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.

-- 
2.39.1.456.gfc5497dd1b-goog

Glen Choo· Feb 1, 2023, 02:46 UTC · re: Glen Choo · lore

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

Glen Choo <chooglen@google.com> writes:

Show 17 quoted lines

>>                 The existing explanation starts with "32-bit mode,
>> split into (high to low bits)", followed by "4-bit object type", as
>> if the "4-bit object type" occupies bits 29-32, which is not quite
>> what we want to say.
>
> If I am understanding you correctly (which I'm not sure, since I am
> honestly clueless about bit numbering and big endianness and whatnot),
> you're saying that highest 16 bits are zero, not the lowest? If so, then
> I genuinely made that mistake, hah.
>
> (We're storing 16 bits as bigendian 32 bits, so they would occupy the
> lower 16 bits, right..?)
>
> Perhaps something like this would be better. I took the "unused, must be
> zero" phrasing from elsewhere in the doc. And if I am completely
> off-base, feel free to patch it without waiting for my reroll if you
> think that's easier.

Whoops, this was meant to be a reply to https://lore.kernel.org/git/xmqqmt5yy08d.fsf@gitster.g. That's what I get for trying to write the In-Reply-To by hand.

Junio C Hamano· Feb 1, 2023, 16:56 UTC · re: Glen Choo · lore

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

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 ;-)