55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
# 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`](usage.md)
|
|
- Change tracking: [`CHANGELOG.md`](../CHANGELOG.md)
|