* [PATCH] docs: document zero bits in index "mode"
@ 2023-02-01 2:40 Glen Choo
2023-02-01 2:46 ` Glen Choo
2023-02-01 16:56 ` Junio C Hamano
0 siblings, 2 replies; 3+ messages in thread
From: Glen Choo @ 2023-02-01 2:40 UTC (permalink / raw)
To: git; +Cc: Glen Choo, Junio C Hamano
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(-)
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
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] docs: document zero bits in index "mode"
2023-02-01 2:40 [PATCH] docs: document zero bits in index "mode" Glen Choo
@ 2023-02-01 2:46 ` Glen Choo
2023-02-01 16:56 ` Junio C Hamano
1 sibling, 0 replies; 3+ messages in thread
From: Glen Choo @ 2023-02-01 2:46 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano
Glen Choo <chooglen@google.com> writes:
>> 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.
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] docs: document zero bits in index "mode"
2023-02-01 2:40 [PATCH] docs: document zero bits in index "mode" Glen Choo
2023-02-01 2:46 ` Glen Choo
@ 2023-02-01 16:56 ` Junio C Hamano
1 sibling, 0 replies; 3+ messages in thread
From: Junio C Hamano @ 2023-02-01 16:56 UTC (permalink / raw)
To: Glen Choo; +Cc: git
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.
> 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 ;-)
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2023-02-01 16:56 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-02-01 2:40 [PATCH] docs: document zero bits in index "mode" Glen Choo
2023-02-01 2:46 ` Glen Choo
2023-02-01 16:56 ` Junio C Hamano
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).