{"thread":{"id":"59170","subject":"[PATCH] docs: document zero bits in index \"mode\"","startedAt":"2023-02-01T02:40:49Z","lastAt":"2023-02-01T16:56:56Z","messageCount":3,"participants":["Glen Choo","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"471214","messageId":"20230201024041.29401-1-chooglen@google.com","threadId":"59170","inReplyTo":null,"subject":"[PATCH] docs: document zero bits in index \"mode\"","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2023-02-01T02:40:41Z","receivedAt":"2023-02-01T02:40:49Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Documentation/gitformat-index.txt describes the \"mode\" as 32 bits, but\nonly documents 16 bits. Document the missing 16 bits and specify that\n'unused' bits must be zero.\n\nSigned-off-by: Glen Choo <chooglen@google.com>\n---\n>                 The existing explanation starts with \"32-bit mode,\n> split into (high to low bits)\", followed by \"4-bit object type\", as\n> if the \"4-bit object type\" occupies bits 29-32, which is not quite\n> what we want to say.\n\nIf I am understanding you correctly (which I'm not sure, since I am\nhonestly clueless about bit numbering and big endianness and whatnot),\nyou're saying that highest 16 bits are zero, not the lowest? If so, then\nI genuinely made that mistake, hah.\n\n(We're storing 16 bits as bigendian 32 bits, so they would occupy the\nlower 16 bits, right..?)\n\nPerhaps something like this would be better. I took the \"unused, must be\nzero\" phrasing from elsewhere in the doc. And if I am completely\noff-base, feel free to patch it without waiting for my reroll if you\nthink that's easier.\n\n Documentation/gitformat-index.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.txt\nindex 015cb21bdc..0773e5c380 100644\n--- a/Documentation/gitformat-index.txt\n+++ b/Documentation/gitformat-index.txt\n@@ -83,11 +83,13 @@ Git index format\n \n   32-bit mode, split into (high to low bits)\n \n+    16-bit unused, must be zero\n+\n     4-bit object type\n       valid values in binary are 1000 (regular file), 1010 (symbolic link)\n       and 1110 (gitlink)\n \n-    3-bit unused\n+    3-bit unused, must be zero\n \n     9-bit unix permission. Only 0755 and 0644 are valid for regular files.\n     Symbolic links and gitlinks have value 0 in this field.\n-- \n2.39.1.456.gfc5497dd1b-goog\n\n"},{"id":"471215","messageId":"kl6lzg9yw19a.fsf@chooglen-macbookpro.roam.corp.google.com","threadId":"59170","inReplyTo":"20230201024041.29401-1-chooglen@google.com","subject":"Re: [PATCH] docs: document zero bits in index \"mode\"","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2023-02-01T02:46:57Z","receivedAt":"2023-02-01T02:47:04Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Glen Choo <chooglen@google.com> writes:\n\n>>                 The existing explanation starts with \"32-bit mode,\n>> split into (high to low bits)\", followed by \"4-bit object type\", as\n>> if the \"4-bit object type\" occupies bits 29-32, which is not quite\n>> what we want to say.\n>\n> If I am understanding you correctly (which I'm not sure, since I am\n> honestly clueless about bit numbering and big endianness and whatnot),\n> you're saying that highest 16 bits are zero, not the lowest? If so, then\n> I genuinely made that mistake, hah.\n>\n> (We're storing 16 bits as bigendian 32 bits, so they would occupy the\n> lower 16 bits, right..?)\n>\n> Perhaps something like this would be better. I took the \"unused, must be\n> zero\" phrasing from elsewhere in the doc. And if I am completely\n> off-base, feel free to patch it without waiting for my reroll if you\n> think that's easier.\n\nWhoops, this was meant to be a reply to\nhttps://lore.kernel.org/git/xmqqmt5yy08d.fsf@gitster.g. That's what I\nget for trying to write the In-Reply-To by hand.\n"},{"id":"471252","messageId":"xmqqmt5xwchh.fsf@gitster.g","threadId":"59170","inReplyTo":"20230201024041.29401-1-chooglen@google.com","subject":"Re: [PATCH] docs: document zero bits in index \"mode\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-01T16:56:42Z","receivedAt":"2023-02-01T16:56:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Glen Choo <chooglen@google.com> writes:\n\n> Documentation/gitformat-index.txt describes the \"mode\" as 32 bits, but\n> only documents 16 bits. Document the missing 16 bits and specify that\n> 'unused' bits must be zero.\n\nI actually think the bottom 16-bit should just be described as\nallowing only a limited set of possible values and list them all,\nbut this is good as an incremental improvement [*]\n\nThanks.\n\n\n>    32-bit mode, split into (high to low bits)\n>  \n> +    16-bit unused, must be zero\n> +\n>      4-bit object type\n>        valid values in binary are 1000 (regular file), 1010 (symbolic link)\n>        and 1110 (gitlink)\n>  \n> -    3-bit unused\n> +    3-bit unused, must be zero\n>  \n>      9-bit unix permission. Only 0755 and 0644 are valid for regular files.\n>      Symbolic links and gitlinks have value 0 in this field.\n\n\n[Footnote]\n\nIf I am not mistaken, there are only four possible values allowed.\nSo, instead of \"split into...\", we could just say\n\n        32-bit \"mode\", which can be one of\n\n          Regular non-executable file     100644\n          Regular executable file         100755\n          Symbolic link                   120000\n          Git link                        160000\n\n        No other values are allowed.\n\nbut we can move one step at a time ;-)\n\n"}]}