git-tui/doc/architecture.md

Architecture

Overview

git-tui is a single executable Python script that provides a terminal UI for common Git commands.

Module Responsibilities

• git-tui:
  • Initializes and runs the curses application loop.
  • Handles startup bootstrap for non-repository directories.
  • Handles startup onboarding for repositories without configured remotes.
  • Renders a menu-driven UI with keyboard navigation.
  • Executes Git subprocess commands and displays command output.
  • Executes provider-specific publication for new remote repositories:
    • GitHub via gh CLI.
    • Gitea via HTTPS API and token-authenticated initial push.
  • Executes provider-specific connection to existing remote repositories:
    • GitHub by resolving owner or URL input to origin.
    • Gitea by resolving owner, base URL, and SSH/HTTPS transport or full URL input to origin.
  • Implements file selection for staged and unstaged operations.

Public API and Contracts

• Command entry point: git-tui executable script.
• Runtime contract:
  • Must be executed in a terminal that supports curses.
  • Must be run from a writable project directory.
  • Requires git to be installed and available in PATH.
  • Requires gh in PATH only for GitHub publication.
  • Requires Gitea API token for Gitea publication.
  • Runs Git subprocesses in non-interactive mode to avoid terminal credential prompt deadlocks.

Data Model

• ChangedFile:
  • index_status: index status marker from git status --short.
  • worktree_status: worktree status marker from git status --short.
  • path: repository-relative file path.

Build and Deployment Rules

• No build step is required.
• Deployment is a direct executable file install (copy or symlink).

Cross References

• Usage and install details: doc/usage.md
• Change tracking: CHANGELOG.md