How to read the mode field of git-ls-tree's output

Question

$ git ls-tree fb3a8bdd0ce
100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c    .gitignore
100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d    .mailmap
100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3    COPYING
040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745    Documentation
100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200    GIT-VERSION-GEN
100644 blob 289b046a443c0647624607d471289b2c7dcd470b    INSTALL
100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1    Makefile
100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52    README
...

I know the last 3 oct digits are file mode, but what are the first 3 digits for? I can't find it out in git user's manual.

Answer 1

The 6 digits show the file mode using the classical UNIX notations. First two digits show file type, the third one is about set-uid/set-gid/sticky bits, and you know the last three.

Here is how man 2 stat documents it on my GNU/Linux system:

   The following flags are defined for the st_mode field:

       S_IFMT     0170000   bit mask for the file type bit fields
       S_IFSOCK   0140000   socket
       S_IFLNK    0120000   symbolic link
       S_IFREG    0100000   regular file
       S_IFBLK    0060000   block device
       S_IFDIR    0040000   directory
       S_IFCHR    0020000   character device
       S_IFIFO    0010000   FIFO
       S_ISUID    0004000   set UID bit
       S_ISGID    0002000   set-group-ID bit (see below)
       S_ISVTX    0001000   sticky bit (see below)
       S_IRWXU    00700     mask for file owner permissions
       S_IRUSR    00400     owner has read permission
       S_IWUSR    00200     owner has write permission
       S_IXUSR    00100     owner has execute permission
       S_IRWXG    00070     mask for group permissions
       S_IRGRP    00040     group has read permission
       S_IWGRP    00020     group has write permission
       S_IXGRP    00010     group has execute permission
       S_IRWXO    00007     mask for permissions for others (not in group)
       S_IROTH    00004     others have read permission           
       S_IWOTH    00002     others have write permission
       S_IXOTH    00001     others have execute permission

Answer 2

From gitformat-index(5) / the Reference Documentations The Git index file format (¹^, ²), regarding the mode:

32-bit mode, split into (high to low bits)

    4-bit object type
      valid values in binary are 1000 (regular file), 1010 (symbolic link)
      and 1110 (gitlink)

    3-bit unused

    9-bit unix permission. Only 0755 and 0644 are valid for regular files.
    Symbolic links and gitlinks have value 0 in this field.

Also, a directory object type (binary 0100) and group-writeable (0664 permissions) regular file are allowed as indicated by the fsck.c fsck_tree method. The regular non-executable group-writeable file is a non-standard mode that was supported in earlier versions of Git.

This makes valid modes (as binary and octal):

• 0100­000­000000000 (040000): Directory
• 1000­000­110100100 (100644): Regular non-executable file
• 1000­000­110110100 (100664): Regular non-executable group-writeable file
• 1000­000­111101101 (100755): Regular executable file
• 1010­000­000000000 (120000): Symbolic link
• 1110­000­000000000 (160000): Gitlink

---

1. (Source) docs: move index format docs to man section 5 — 00d3e8d
2. (Archived copy on Microsoft Github) docs: move index format docs to man section 5 — 00d3e8d

Answer 3

To add to Go Dan's answer, Git 2.40 (Q1 2023) adds:

See commit 3a2ebae (01 Feb 2023) by Glen Choo (chooglen).
^{(Merged by Junio C Hamano -- gitster -- in commit 2c91b13, 09 Feb 2023)}

docs: document zero bits in index "mode"

^{Signed-off-by: Glen Choo}

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.

gitformat-index now includes in its man page:

16-bit unused, must be zero ... 3-bit unused, must be zero

Which means the format actually is:

• 0(16x) 0100 000 000000000 (040000): Directory
• 0(16x) 1000 000 110100100 (100644): Regular non-executable file
• 0(16x) 1000 000 110110100 (100664): Regular non-executable group-writeable file
• 0(16x) 1000 000 111101101 (100755): Regular executable file
• 0(16x) 1010 000 000000000 (120000): Symbolic link
• 0(16x) 1110 000 000000000 (160000): Gitlink
• ^^^
• always set to 0