Added a GitIndex parser

Two things in @todo right now:
- CLI flags like -cdkmosu (will be added after git status)
- docstrings (will be populated in next commit)

Author: nyx-4

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `ngit show-ref` that list references stored in `.git/refs`
 - Added `ngit tag` that can create, delete and list tags, and is based on `show-ref`'s backend
 - Added a stupid `ngit rev-parse` de-reference tags, branches, short-hashes etc
+- Added a `ngit ls-files` to parse and show `.git/index`
 
 
 ### Changed

microprojects/ngit/libngit.py

@@ -17,7 +17,7 @@
 from microprojects.ngit.repository import resolve_ref, ref_list, tag_list
 from microprojects.ngit.object_utils import object_find_f, object_read, tag_create
 from microprojects.ngit.ngit_utils import cat_file, ls_tree, object_hash, repo_create
-from microprojects.ngit.ngit_utils import checkout, show_ref
+from microprojects.ngit.ngit_utils import checkout, show_ref, ls_files
 from microprojects.ngit.log import print_logs
 
 
@@ -306,6 +306,54 @@ def ngit_main() -> None:
     )
 
     # ArgParser for ngit ls-files
+    argsp_ls_files = arg_subparser.add_parser(  # ls-files
+        "ls-files",
+        prog="ngit ls-files",
+        description="Show information about files in the index and the working tree",
+        help="Show information about files in the index and the working tree",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    argsp_ls_files.add_argument(  # -z
+        "-z",
+        dest="null_terminator",
+        action="store_true",
+        help="\\0 line termination on output and do not quote filenames",
+    )
+    argsp_ls_files.add_argument(  # --format
+        "--format",
+        default="",  # TODO: Use a sensible default for format
+        dest="format",
+        help="A string that interpolates %%(fieldname) from the result being shown",
+    )
+    argsp_ls_files.add_argument(  # --verbose
+        "--verbose",
+        action="store_const",
+        const="""\
+%(path) @%(objectname) <%(stage)>
+  ctime: %(ctime:iso)
+  mtime: %(mtime:iso)
+  mode: %(objectmode)\ttype: %(objecttype)
+  dev: %(dev)\tino: %(ino)
+  uid: %(uid)\tgid: %(gid)
+  size: %(objectsize)\tflags: %(flags)
+""",
+        dest="format",
+        help="show all information about GitIndex",
+    )
+    argsp_ls_files.add_argument(  # --debug
+        "--debug",
+        action="store_const",
+        const="""\
+%(path)
+  ctime: %(ctime)
+  mtime: %(mtime)
+  dev: %(dev)\tino: %(ino)
+  uid: %(uid)\tgid: %(gid)
+  size: %(objectsize)\tflags: %(flags)
+""",
+        dest="format",
+        help="After each line that describes a file, add more data about its cache entry",
+    )
 
     # ArgParser for ngit ls-tree
     argsp_ls_tree = arg_subparser.add_parser(  # ls-tree
@@ -606,14 +654,12 @@ def cmd_add(args: argparse.Namespace) -> None:
 def cmd_cat_file(args: argparse.Namespace) -> None:
     repo: GitRepository = repo_find_f()
 
-    # fmt: off
     flag: int = (
         1 if args.only_error else
         2 if args.only_type else
         3 if args.only_size else
         4 # default flag is 4
-    )
-    # fmt: on
+    )  # fmt: skip
 
     cat_file(repo, args.object, fmt=args.type, flag=flag)
 
@@ -704,7 +750,10 @@ def cmd_log(args: argparse.Namespace) -> None:
 
 
 def cmd_ls_files(args: argparse.Namespace) -> None:
-    pass
+    # TODO: Some args depends on `git status`, add them after status implemented
+    repo: GitRepository = repo_find_f()
+    endl: str = "\0" if args.null_terminator else "\n"
+    ls_files(repo, args.format, endl)
 
 
 def cmd_ls_tree(args: argparse.Namespace) -> None:

microprojects/ngit/log.py

@@ -7,20 +7,10 @@
 
 
 def print_logs(
-    repo: GitRepository,
-    sha1: str,
-    *,
-    decorate: str,
-    log_size: bool,
-    max_count: int,
-    skip: int,
-    after: str,
-    before: str,
-    min_parents: int,
-    max_parents: int,
-    format_str: str,
-    date_fmt: str,
-) -> None:
+        repo: GitRepository, sha1: str, *, decorate: str, log_size: bool,
+        max_count: int, skip: int, after: str, before: str, min_parents: int,
+        max_parents: int, format_str: str, date_fmt: str
+) -> None:  # fmt: skip
     """Show commit logs, according to specified flags
 
     Parameters:

microprojects/ngit/ngit_utils.py

@@ -1,10 +1,12 @@
 import os
 import configparser
+from datetime import datetime
 
 from microprojects.ngit.repository import GitRepository, repo_dir, repo_file, ref_list
+from microprojects.ngit.repository import GitIndex, GitIndexEntry
 from microprojects.ngit.object import GitObject, GitCommit, GitBlob, GitTag, GitTree
 from microprojects.ngit.object_utils import object_read, object_find, object_write
-from microprojects.ngit.object_utils import object_pick, shortify_hash
+from microprojects.ngit.object_utils import object_pick, shortify_hash, index_read
 
 
 def repo_default_config() -> configparser.ConfigParser:
@@ -122,15 +124,9 @@ def object_hash(repo: GitRepository | None, file, fmt: bytes) -> str:
 
 
 def ls_tree(
-    repo: GitRepository,
-    sha1: str,
-    only_trees: bool,
-    recurse_trees: bool,
-    always_trees: bool,
-    null_terminator: bool,
-    format_str: str,
-    _prefix: str = "",
-) -> None:
+        repo: GitRepository, sha1: str, only_trees: bool, recurse_trees: bool,
+        always_trees: bool, null_terminator: bool, format_str: str, _prefix: str = "",
+) -> None:  # fmt: skip
     """List the contents of a tree object
 
     Parameters:
@@ -162,7 +158,7 @@ def prettify(leaf, format_str: str, obj_fmt: str, _prefix: str) -> str:
     if type(obj) is not GitTree:
         raise TypeError(f"fatal: {sha1} do not point to valid GitTree")
 
-    if not any([recurse_trees, always_trees, only_trees]):
+    if not any([only_trees, recurse_trees, always_trees]):
         always_trees = True  # set always_trees, if no
 
     for leaf in obj.data:
@@ -183,20 +179,45 @@ def prettify(leaf, format_str: str, obj_fmt: str, _prefix: str) -> str:
             if always_trees or only_trees:
                 print(prettify(leaf, format_str, obj_fmt, _prefix), end=endl)
             if recurse_trees:
-                ls_tree(
-                    repo,
-                    leaf.sha1,
-                    only_trees,
-                    recurse_trees,
-                    always_trees,
-                    null_terminator,
-                    format_str,
-                    _prefix=os.path.join(_prefix, leaf.path),
-                )
+                ls_tree(repo, leaf.sha1, only_trees, recurse_trees, always_trees,
+                    null_terminator, format_str, _prefix=os.path.join(_prefix, leaf.path))  # fmt: skip
+
         elif not only_trees:
             print(prettify(leaf, format_str, obj_fmt, _prefix), end=endl)
 
 
+def ls_files(repo: GitRepository, fmt: str, endl: str = "\n") -> None:
+    """"""
+
+    def prettify(entry: GitIndexEntry, format_str: str) -> str:
+        obj_type: str = {0o10: "blob", 0o12: "symlink", 0o16: "commit"}[entry.mode_type]
+
+        format_str = format_str.replace("%(objectmode)", f"{entry.mode_type:02o}{entry.mode_perms:04o}")  # fmt: skip
+        format_str = format_str.replace("%(objecttype)", f"{obj_type}")
+        format_str = format_str.replace("%(objectname)", f"{entry.sha1}")
+        format_str = format_str.replace("%(objectsize)", f"{entry.file_size}")
+        format_str = format_str.replace("%(stage)", f"{entry.flag_stage}")
+        format_str = format_str.replace("%(path)", f"{entry.name}")
+
+        # Extras
+        format_str = format_str.replace("%(ctime)", f"{entry.ctime_s}:{entry.ctime_n}")
+        format_str = format_str.replace("%(mtime)", f"{entry.mtime_s}:{entry.mtime_n}")
+        format_str = format_str.replace("%(ctime:iso)", f"{datetime.fromtimestamp(entry.ctime_s)}")  # fmt: skip
+        format_str = format_str.replace("%(mtime:iso)", f"{datetime.fromtimestamp(entry.mtime_s)}")  # fmt: skip
+        format_str = format_str.replace("%(dev)", f"{entry.dev}")
+        format_str = format_str.replace("%(ino)", f"{entry.ino}")
+        format_str = format_str.replace("%(uid)", f"{entry.uid}")
+        format_str = format_str.replace("%(gid)", f"{entry.gid}")
+        format_str = format_str.replace("%(gid)", f"{entry.gid}")
+        format_str = format_str.replace("%(flags)", f"{entry.flag_assume_valid}{entry.flag_stage}")  # fmt: skip
+
+        return format_str
+
+    index: GitIndex = index_read(repo)
+    for entry in index.entries:
+        print(prettify(entry, fmt))
+
+
 def checkout(repo: GitRepository, tree: GitTree, path: str, quiet: bool) -> None:
     """Switch branches or restore working tree files
 
@@ -222,9 +243,7 @@ def checkout(repo: GitRepository, tree: GitTree, path: str, quiet: bool) -> None
                 file.write(obj.data)
 
 
-def show_ref(
-    repo: GitRepository, refs: list, only_sha1: bool, deref: bool, prefx="refs"
-) -> None:
+def show_ref(repo: GitRepository, refs: list, only_sha1: bool, deref: bool, prefx="refs") -> None:  # fmt: skip
     """List references in repo under ref, verify them, and print relevant information
 
     Parameters:

microprojects/ngit/object_utils.py

@@ -2,10 +2,11 @@
 import os  # os and os.path provide some nice filesystem abstraction routines
 import zlib  # to compress & decompress files
 import re
+import math
 
 
 from microprojects.ngit.repository import GitRepository, repo_file, resolve_ref
-from microprojects.ngit.repository import repo_dir
+from microprojects.ngit.repository import repo_dir, GitIndex, GitIndexEntry
 from microprojects.ngit.object import GitObject, GitBlob, GitCommit, GitTag, GitTree
 
 
@@ -195,6 +196,7 @@ def shortify_hash(repo: GitRepository, sha1: str) -> str:
 
     """
     # TODO: implement shortify hash properly
+    # TODO: add `--abbrev=[n]` in ngit sub-commands that supports it
     return sha1[:7]
 
 
@@ -232,3 +234,68 @@ def tag_create(
         tag_file.write(sha1 + "\n")
 
     return sha1
+
+
+def index_read(repo) -> GitIndex:
+    """"""
+
+    def bin_read(raw_data: bytes) -> int:
+        """A helper function to converts big-endian bytes to int"""
+        return int.from_bytes(raw_data, byteorder="big")
+
+    index_file: str = repo_file(repo, "index")
+
+    # New repositories do not have .git/index file
+    if not os.path.exists(index_file):
+        return GitIndex()
+
+    with open(index_file, "rb") as file:
+        raw_idx: bytes = file.read()
+
+    signature: bytes = raw_idx[:4]
+    assert signature == b"DIRC", f"signature should be b'DIRC', got {signature=}"
+    version: int = bin_read(raw_idx[4:8])
+    assert version == 2, f"Only version 2 GitIndex is supported, got {version=}"
+
+    len_entries: int = bin_read(raw_idx[8:12])
+    entries: list[GitIndexEntry] = []
+
+    idx: int = 0
+    raw_idx = raw_idx[12:]  # 12 bytes are already read
+
+    for _ in range(len_entries):
+        flags: int = bin_read(raw_idx[idx + 60 : idx + 62])
+
+        kwargs: dict[str, int] = {  # some kwargs to pass to GitIndexEntry()
+            "ctime_s": bin_read(raw_idx[idx + 0 : idx + 4]),
+            "ctime_n": bin_read(raw_idx[idx + 4 : idx + 8]),
+            "mtime_s": bin_read(raw_idx[idx + 8 : idx + 12]),
+            "mtime_n": bin_read(raw_idx[idx + 12 : idx + 16]),
+            "dev": bin_read(raw_idx[idx + 16 : idx + 20]),
+            "ino": bin_read(raw_idx[idx + 20 : idx + 24]),
+            "mode_type": bin_read(raw_idx[idx + 26 : idx + 28]) >> 12,
+            "mode_perms": bin_read(raw_idx[idx + 26 : idx + 28]) & 0x1FF,
+            "uid": bin_read(raw_idx[idx + 28 : idx + 32]),
+            "gid": bin_read(raw_idx[idx + 32 : idx + 36]),
+            "file_size": bin_read(raw_idx[idx + 36 : idx + 40]),
+            "flag_assume_valid": flags & 0x8000,
+            "flag_stage": flags & 0x3000,
+        }
+        sha1: str = format(bin_read(raw_idx[idx + 40 : idx + 60]), "040x")
+
+        idx += 62  # read 62 bytes thus far
+        len_name: int = flags & 0xFFF
+
+        if len_name < 0xFFF:  # normal case, len(name) is given
+            assert raw_idx[idx + len_name] == 0x00, f"No NULL at {idx + len_name=}"
+            raw_name: bytes = raw_idx[idx : idx + len_name]
+            idx += len_name + 1
+        else:
+            idx_null: int = raw_idx.find(b"\x00", idx + 0xFFF)
+            raw_name = raw_idx[idx:idx_null]
+            idx += idx_null + 1
+
+        idx = (idx + 7) & ~7  # ceil to next multiple of 8
+
+        entries.append(GitIndexEntry(**kwargs, sha1=sha1, name=raw_name.decode()))
+    return GitIndex(version=version, entries=entries)

microprojects/ngit/repository.py

@@ -45,6 +45,46 @@ def __init__(self, path: str, force: bool = False) -> None:
                 raise NotImplementedError(f"unsupported repositoryformatversion: {ver}")
 
 
+class GitIndexEntry(object):
+    """"""
+
+    def __init__(
+        self, ctime_s: int, ctime_n: int, mtime_s: int, mtime_n: int, dev: int, ino: int,
+        mode_type: int, mode_perms: int, uid: int, gid: int, file_size: int, sha1: str,
+        flag_assume_valid: int, flag_stage: int, name: str
+    ) -> None:  # fmt: skip
+        """"""
+
+        self.ctime_s: int = ctime_s
+        self.ctime_n: int = ctime_n
+        self.mtime_s: int = mtime_s
+        self.mtime_n: int = mtime_n
+        self.dev: int = dev
+        self.ino: int = ino
+        self.mode_type: int = mode_type
+        self.mode_perms: int = mode_perms
+        self.uid: int = uid
+        self.gid: int = gid
+        self.file_size: int = file_size
+        self.sha1: str = sha1
+        self.flag_assume_valid: int = flag_assume_valid
+        self.flag_stage: int = flag_stage
+        self.name: str = name
+
+
+class GitIndex(object):
+    """"""
+
+    version: int = 2
+    entries: list[GitIndexEntry]
+    # ext  # NotImplemented
+    # sha1: str  # ignored
+
+    def __init__(self, version: int = 2, entries: list[GitIndexEntry] = []) -> None:
+        self.version = version
+        self.entries = entries or []  # `or []` is important part
+
+
 def repo_path(repo: GitRepository, *path: str) -> str:
     """Compute path under repo's git/ directory