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, followed by an SSH or token-authenticated HTTPS push.
  • Executes provider-specific connection to existing remote repositories:
    • GitHub by resolving owner or URL input to origin.
    • Gitea by preserving a full clone URL or retrieving exact SSH/HTTPS clone endpoints through the repository API.
  • Synchronizes Gitea connections by inspecting ancestry, fast-forwarding the side that is behind, or asking the user how to resolve divergent histories.
  • Preserves local history on a backup branch before a user-confirmed local replacement and uses --force-with-lease for remote replacement.
  • Removes local remote configuration through a conditional disconnect action.
  • 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.
  • Temporarily suspends curses for network Git subprocesses so terminal authentication and credential helpers remain available.

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