Cleaned code and doc-string

- The CLI for commit, add, rm is still missing or incomplete
- The `shortify_sha1` or `abbrev=<n>` function should be added
- The CLI for checkout, tag, log should be updated to reflect recent
  changes
- There are still alot of TODO's in the repo, especially re-add the
  cat-file for commits and tags and trees
- Rewriting README to better reflect new changes and bug-fixes in ngit
  and calc

Author: nyx-4

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added a `ngit ls-files` to parse and show `.git/index`
 - Added a `ngit check-ignore` to debug .gitignore and exclude file from `git add`
 - Added a semi-complete .gitignore parser (incomplete support for Slash `/` as directory separator)
+- Added missing doc-strings and cleaned some code
 
 
 ### Changed

microprojects/ngit/libngit.py

@@ -1,25 +1,16 @@
-import argparse  # ngit is CLI tool, so we need to parse CLI args
-
-# import configparser  # ngit's config file uses INI format
-# from datetime import datetime  # to store time of each commit
-# import grp, pwd  # because ngit saves numerical owner/group ID of files author
-# from fnmatch import fnmatch  # to match .gitignore patterns like *.txt
-# import hashlib  # ngit uses SHA-1 hash extensively
-# import math
-import os  # os and os.path provide some nice filesystem abstraction routines
-
-# import re  # just a little-bit of RegEx
-import sys  # to access `sys.argv`
-# import zlib  # to compress & decompress files
+import argparse
+import os
+import sys
 
 from microprojects.ngit.object import GitObject, GitCommit, GitTree
 from microprojects.ngit.repository import GitRepository, repo_file, repo_find_f
-from microprojects.ngit.repository import resolve_ref, ref_list, tag_list, GitIgnore
+from microprojects.ngit.repository import GitIgnore, resolve_ref, ref_list, tag_list
 from microprojects.ngit.object_utils import object_find_f, object_read, tag_create
 from microprojects.ngit.object_utils import gitignore_read, get_obj_type, get_obj_size
 from microprojects.ngit.ngit_utils import cat_file, ls_tree, object_hash, repo_create
 from microprojects.ngit.ngit_utils import checkout, show_ref, ls_files, check_ignore
 from microprojects.ngit.log import print_logs
+from microprojects.ngit.status import filter_paths
 
 
 def ngit_main() -> None:
@@ -41,6 +32,39 @@ def ngit_main() -> None:
     arg_subparser.required = True
 
     # ArgParser for ngit add
+    argsp_add = arg_subparser.add_parser(  # add
+        "add",
+        prog="ngit add",
+        description="Add file contents to the index",
+        help="Add file contents to the index",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    argsp_add.add_argument(  # -f --force
+        "-f",
+        "--force",
+        dest="force",
+        action="store_true",
+        help="Allow adding otherwise ignored files",
+    )
+    argsp_add.add_argument(  # -A --all --no-ignore-removal
+        "-A",
+        "--all",
+        "--no-ignore-removal",
+        dest="all",
+        action="store_true",
+        help="All files in entire worktree will be added to GitIndex",
+    )
+    argsp_add.add_argument(  # --ignore-errors
+        "--ignore-errors",
+        dest="no_errors",
+        action="store_true",
+        help="If some files could not be added, do not abort the operation, but continue adding the others",
+    )
+    argsp_add.add_argument(  # paths
+        "paths",
+        nargs="*",
+        help="Files to add content from",
+    )
 
     # ArgParser for ngit cat-file
     argsp_cat_file = arg_subparser.add_parser(  # cat-file
@@ -480,6 +504,54 @@ def ngit_main() -> None:
     )
 
     # ArgParser for ngit rm
+    argsp_rm = arg_subparser.add_parser(  # rm
+        "rm",
+        prog="ngit rm",
+        description="Remove files from the working tree and from the index",
+        help="Remove files from the working tree and from the index",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    argsp_rm.add_argument(  # -f --force
+        "-f",
+        "--force",
+        dest="force",
+        action="store_true",
+        help="Override the up-to-date check",
+    )
+    argsp_rm.add_argument(  # -q --quiet
+        "-q",
+        "--quiet",
+        dest="quiet",
+        action="store_true",
+        help="Suppress all output except errors and warnings",
+    )
+    argsp_rm.add_argument(  # -r --recursive
+        "-r",
+        "--recursice",
+        dest="recursive",
+        action="store_true",
+        help="Allow recursive removal when a leading directory name is given",
+    )
+    argsp_rm.add_argument(  # --cached
+        "--cached",
+        dest="cached",
+        action="store_true",
+        help="Use this option to unstage and remove paths only from the index. "
+        "Working tree files, whether modified or not, will be left alone",
+    )
+    argsp_rm.add_argument(  # -i --stdin --pathspec-from-file
+        "-i",
+        "--stdin",
+        "--pathspec-from-file",
+        dest="stdin",
+        metavar="<path>",
+        help="Pathspec is passed in <file> instead of args, if <file> is exactly - then standard input is used",
+    )
+    argsp_rm.add_argument(  # paths
+        "paths",
+        nargs="*",
+        help="Files to add content from",
+    )
 
     # ArgParser for ngit show-ref
     argsp_show_ref = arg_subparser.add_parser(  # show-ref
@@ -563,6 +635,55 @@ def ngit_main() -> None:
     )
 
     # ArgParser for ngit status
+    argsp_staus = arg_subparser.add_parser(
+        "status",
+        prog="ngit status",
+        description="Show the working tree status",
+        help="Show the working tree status",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    argsp_staus.add_argument(  # -s --short
+        "-s",
+        "--short",
+        dest="short",
+        action="store_true",
+        help="Give the output in the short-format",
+    )
+    argsp_staus.add_argument(  # -b --branch
+        "-b",
+        "--branch",
+        dest="branch",
+        action="store_true",
+        help="Show the branch and tracking info even in short-format",
+    )
+    argsp_staus.add_argument(  # --porcelain
+        "--porcelain",
+        dest="porcelain",
+        action="store_true",
+        help="Give the output in an easy-to-parse format for scripts",
+    )
+    argsp_staus.add_argument(  # --long
+        "--long",
+        dest="long",
+        action="store_true",
+        help="Give the output in the long-format (default)",
+    )
+    argsp_staus.add_argument(  # -u --untracked-files
+        "-u",
+        "--untracked-files",
+        dest="untracked",
+        choices=["all", "normal", "no"],
+        default="all",
+        const="all",
+        nargs="?",
+        help="Show untracked files",
+    )
+    argsp_staus.add_argument(  # paths
+        "paths",
+        nargs="*",
+        help="Files to add content from",
+    )
+
     # ArgParser for ngit tag
     argsp_tag = arg_subparser.add_parser(
         "tag",

microprojects/ngit/log.py

@@ -28,7 +28,7 @@ def print_logs(
         date_fmt (str): The format to use for dates in `ngit log`.
 
     Returns:
-        None (None): print_log just has side-effects, no return value
+        None (None): have side-effect (prints on screen), so returns `None` to enforce this behavior
     """
     obj: GitObject = object_read(repo, sha1)
 
@@ -123,13 +123,13 @@ def prettify(
 
     Parameters:
         kvlm (dict): The dict with required information to put in `format_str`
-        format_str (str): The str containing the required format
+        format_str (str): The str containing the desired format
         shortify: A function that takes in object's ref and returns a shortified sha1 of minimum len 7
         commit_sha1 (str): The SHA1 of current commit, as it's not in KVLM
         date_fmt (str): The date format to use for dates
 
     Returns:
-        format_str (str): The format_str, with supported formats replaced by respective value
+        format_str (str): The format_str, with supported formats replaced by respective values
     """
 
     # Git escape character
@@ -248,8 +248,6 @@ def _ftime(fmt: str) -> str:
     """Convert human-readable/standard time formats to one used by `strftime`"""
     fmt = fmt.lower()
     match fmt:
-        case "local":
-            return ""
         case "iso" | "iso8601":
             return "%Y-%m-%d %H:%M:%S %z"
         case "iso-strict" | "iso8601-strict":
@@ -258,7 +256,7 @@ def _ftime(fmt: str) -> str:
             return "%a, %-d %b %Y %H:%M:%S %z"
         case "short":
             return "%Y-%m-%d"
-        case "default":
+        case "default" | "local":
             return "%c %z"
         case _:
             return fmt

microprojects/ngit/ngit_utils.py

@@ -6,8 +6,8 @@
 from microprojects.ngit.repository import GitIndex, GitIndexEntry
 from microprojects.ngit.repository import GitIgnore, gitignore_check_rule
 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, index_read
+from microprojects.ngit.object_utils import object_read, object_pick, object_write
+from microprojects.ngit.object_utils import shortify_hash, index_read
 
 
 def repo_default_config() -> configparser.ConfigParser:
@@ -181,35 +181,58 @@ def prettify(leaf, format_str: str, obj_fmt: str, _prefix: str) -> str:
 
 
 def ls_files(repo: GitRepository, fmt: str, endl: str = "\n") -> None:
-    """"""
+    """Show information about files in the index and the working tree in desired `fmt`
+
+    Parameters:
+        repo (GitRepository): The current working git repository
+        fmt (str): Pretty-print the contents of the tree in this format
+        endl (str): The separater after each entry
+
+    Returns:
+        None (None): have side-effect (prints on screen), so returns `None` to enforce this behavior
+    """
 
     def prettify(entry: GitIndexEntry, format_str: str) -> str:
+        """Returns a formatted version of `format_str` using substitutions from entry
+
+        Parameters:
+            entry (GitIndexEntry): The GitIndexEntry to use for filling the `format_str`
+            format_str (str): The str containing the desired format
+
+        Returns:
+            format_str (str): The format_str, with supported formats replaced by respective values
+        """
+
+        def to_iso(timestamp: int) -> str:
+            return datetime.isoformat(datetime.fromtimestamp(timestamp))
+
         obj_type: str = {0o10: "blob", 0o12: "symlink", 0o16: "commit"}[entry.mode_type]
+        obj_mode: str = f"{entry.mode_type:02o}{entry.mode_perms:04o}"
+        flags: str = f"{entry.flag_assume_valid}{entry.flag_stage}"
 
-        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}")
+        format_str = format_str.replace("%(objectmode)", obj_mode)
+        format_str = format_str.replace("%(objecttype)", obj_type)
+        format_str = format_str.replace("%(objectname)", entry.sha1)
+        format_str = format_str.replace("%(objectsize)", str(entry.file_size))
+        format_str = format_str.replace("%(stage)", str(entry.flag_stage))
+        format_str = format_str.replace("%(path)", 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
+        format_str = format_str.replace("%(ctime:iso)", to_iso(entry.ctime_s))
+        format_str = format_str.replace("%(mtime:iso)", to_iso(entry.mtime_s))
+        format_str = format_str.replace("%(dev)", str(entry.dev))
+        format_str = format_str.replace("%(ino)", str(entry.ino))
+        format_str = format_str.replace("%(uid)", str(entry.uid))
+        format_str = format_str.replace("%(gid)", str(entry.gid))
+        format_str = format_str.replace("%(gid)", str(entry.gid))
+        format_str = format_str.replace("%(flags)", flags)
 
         return format_str
 
-    index: GitIndex = index_read(repo)
-    for entry in index.entries:
-        print(prettify(entry, fmt))
+    for entry in index_read(repo).entries:
+        print(prettify(entry, fmt), end=endl)
 
 
 def checkout(repo: GitRepository, tree: GitTree, path: str, quiet: bool) -> None:
@@ -259,7 +282,15 @@ def show_ref(repo: GitRepository, refs: list, only_sha1: bool, deref: bool, pref
 
 
 def check_ignore(rules: GitIgnore, path: str) -> bool:
-    """"""
+    """Check whether the `path` should be ignored under given GitIgnore `rules`
+
+    Parameters:
+        rules (GitIgnore): The parsed GitIgnore rules to ckeck against
+        path (str): Relative path to file of which we want to check ignore status of
+
+    Returns:
+        status (bool): True if the path will be ignored, False otherwise
+    """
 
     if os.path.isabs(path):
         raise ValueError(f"{path=} should be relative, not absolute")

microprojects/ngit/object.py

@@ -68,10 +68,10 @@ def deserialize(self, data: bytes) -> None:
 
 
 class GitCommit(GitObject):
-    """TODO: Add description here
+    """GitCommits are represented as key-value pairs (RFC2822)
 
     Attributes:
-        data (dict):
+        data (dict[None | bytes, list[bytes] | bytes]): key-value pairs (list[bytes] is preferred)
         fmt (bytes): GitCommit uses "commit" in header format
     """
 
@@ -89,14 +89,15 @@ def init(self) -> None:
 
 
 class GitTag(GitCommit):
-    """Tags are similar to commits
+    """Like GitCommit, GitTag are also key-value pairs (RFC2822)
 
     Attributes:
-        data (dict):
+        data (dict[None | bytes, list[bytes] | bytes]): key-value pairs (list[bytes] is preferred)
         fmt (bytes): GitTag uses "tag" in header format
     """
 
     fmt: bytes = b"tag"
+    # all other stuff is same as GitCommit
 
 
 class GitTree(GitObject):