Update usage and usage documentation.

Author: lettuce-bot[bot]

README.md

@@ -11,6 +11,30 @@ This project uses [GitPython](https://github.com/gitpython-developers/GitPython)
 local commit and recreate it remotely using [PyGitHub](https://github.com/PyGithub/PyGithub).
 
 
+## Usage
+
+### Prerequisites
+
+It is assumed that you have an authorized GitHub app with permissions to write to the contents
+of your target GitHub repository. You will need the `app id` and `private key` of this app
+(and should be sure to keep the `private key` secret throughout any operations using this tool).
+
+It is also assumed that you have a created a single, non-merge commit locally and wish to
+recreate this commit remotely using the bot.
+
+### Invocation
+
+```sh
+write-commit \
+  --app-id <github-app-id> \
+  --private-key <github-app-private-key> \
+  --repo /path/to/repo \
+  --ref <some-local-ref>
+  --branch <some-remote-branch>
+```
+
+Note that the `GITHUB_APP_PRIVATE_KEY` environment variable can be used to pass the private
+key without passing it as a commmand line argument.
 
 ## Docker
 

pyproject.toml

@@ -42,8 +42,8 @@ types = [
 
 [project.scripts]
 
-read-commit = "bot.cli.main:read"
-write-commit = "bot.cli.main:write"
+read-commit = "bot.cli:read"
+write-commit = "bot.cli:write"
 
 [build-system]
 

src/bot/cli/main.py renamed to src/bot/cli.py

@@ -5,9 +5,9 @@
 from click import Path as PathType
 from click import command, option, secho
 
-from ..dtos import Tree
-from ..local import extract_repo_name, read_commit, read_repo
-from ..remote import authenticate_app, write_commit
+from .dtos import Tree
+from .local import extract_repo_name, read_commit, read_repo
+from .remote import authenticate_app, write_commit
 
 
 def print_tree(tree: Tree, parent: Path, depth: int = 0) -> None:
@@ -29,6 +29,7 @@ def print_tree(tree: Tree, parent: Path, depth: int = 0) -> None:
 @option(
     "--repo-path",
     "--repo",
+    help="The path to the local git repository.",
     type=PathType(
         exists=True,
         file_okay=False,
@@ -39,37 +40,26 @@ def print_tree(tree: Tree, parent: Path, depth: int = 0) -> None:
 )
 @option(
     "--ref",
+    help="The local ref to read.",
     required=True,
 )
 def read(
     *,
     repo_path: Path,
-    ref: str,
+    sha: str,
 ) -> None:
     repo = read_repo(repo_path)
-    commit = read_commit(repo, ref)
+    commit = read_commit(repo, sha)
 
     secho(f"Commit: {commit.message}", fg="green")
     print_tree(commit.tree, Path())
 
 
 @command()
-@option(
-    "--application-id",
-    "--app-id",
-    envvar="GITHUB_APP_ID",
-    required=True,
-    type=int,
-)
-@option(
-    "--private-key",
-    hidden=True,
-    envvar="GITHUB_APP_PRIVATE_KEY",
-    required=True,
-)
 @option(
     "--repo-path",
     "--repo",
+    help="The path to the local git repository.",
     type=PathType(
         exists=True,
         file_okay=False,
@@ -78,13 +68,34 @@ def read(
     ),
     required=True,
 )
+@option(
+    "--branch",
+    help="The remote branch on which to add the generated commit.",
+    required=True,
+)
 @option(
     "--ref",
+    help="The local ref to recreate remotely.",
+    required=True,
+)
+@option(
+    "--app-id",
+    envvar="GITHUB_APP_ID",
+    help="The GitHub App's app id.",
+    required=True,
+    type=int,
+)
+@option(
+    "--private-key",
+    hidden=True,
+    help="The GitHub App's private key",
+    envvar="GITHUB_APP_PRIVATE_KEY",
     required=True,
 )
 def write(
     *,
-    application_id: int,
+    app_id: int,
+    branch: str,
     private_key: str,
     repo_path: Path,
     ref: str,
@@ -94,10 +105,10 @@ def write(
     repo = read_repo(repo_path)
     repo_name = extract_repo_name(repo)
 
-    github = authenticate_app(application_id, private_key)
+    github = authenticate_app(app_id, private_key)
     repository = github.get_repo(repo_name)
+    git_ref = repository.get_git_ref(f"heads/{branch}")
 
     commit = read_commit(repo, ref)
     git_commit = write_commit(repository, commit)
-
-    secho(f"Created git commit: {git_commit.sha}", fg="green")
+    git_ref.edit(git_commit.sha)

src/bot/cli/__init__.py

@@ -80,6 +80,7 @@ def iter_blobs(item: Diff) -> Generator[BlobDTO, None, None]:
 
 
 def build_trees(blobs: list[BlobDTO]) -> TreeDTO:
+    """Build the tree structure from a list of blobs."""
     trees: dict[Path, TreeDTO] = {}
 
     # Create the root tree

src/bot/local.py

@@ -1,4 +1,5 @@
 from logging import getLogger as get_logger
+from typing import Generator
 
 from github import Github, GithubIntegration
 from github.Auth import AppAuth
@@ -11,8 +12,8 @@
 from .enums import Mode, Type
 
 
-def authenticate_app(application_id: int, private_key: str) -> Github:
-    auth = AppAuth(application_id, private_key)
+def authenticate_app(app_id: int, private_key: str) -> Github:
+    auth = AppAuth(app_id, private_key)
     integration = GithubIntegration(auth=auth)
     installation = integration.get_installations()[0]
     return installation.get_github_for_installation()  # type: ignore
@@ -36,28 +37,22 @@ def make_tree_blob_element(blob: Blob) -> InputGitTreeElement:
         )
 
 
-def make_tree_tree_element(tree: Tree, git_tree: GitTree) -> InputGitTreeElement:
-    return InputGitTreeElement(
-        path=str(tree.path),
-        mode=Mode.SUBDIRECTORY.value,
-        type=Type.TREE.value,
-        sha=git_tree.sha,
-    )
+def iter_tree_blob_element(tree: Tree) -> Generator[InputGitTreeElement, None, None]:
+    for child in tree.trees:
+        yield from iter_tree_blob_element(child)
+
+    for blob in tree.blobs:
+        yield make_tree_blob_element(blob)
 
 
 def write_tree(repo: Repository, tree: Tree, base_tree: GitTree) -> GitTree:
     logger = get_logger("GitTree")
 
-    child_git_trees = [write_tree(repo, child, base_tree) for child in tree.trees]
-
-    tree_items = [make_tree_blob_element(blob) for blob in tree.blobs] + [
-        make_tree_tree_element(child, child_git_tree)
-        for child, child_git_tree in zip(tree.trees, child_git_trees)
-    ]
+    tree_blob_elements = list(iter_tree_blob_element(tree))
 
-    logger.info(f"Creating git tree with {len(tree_items)} items from: {base_tree}")
+    logger.info("Creating git tree")
     git_tree = repo.create_git_tree(
-        tree=tree_items,
+        tree=tree_blob_elements,
         base_tree=base_tree,
     )
     logger.info(f"Created git tree: {git_tree.sha}")