# Usage

## Environment Requirements

- Linux or Unix-like terminal environment with curses support.
- Python 3 interpreter available as `python3`.
- Git installed and available in `PATH`.
- GitHub CLI `gh` installed and authenticated for GitHub repository creation. If using Gitea see below.
- Gitea API token for Gitea repository creation (read/write permissions for repository and organization) over HTTPS.

## Installation

1. Make the script executable:
   ```bash
   chmod +x git-tui
   ```
2. Install as a memorable command name (example: `gtui`):
   ```bash
   sudo install -m 755 git-tui /usr/local/bin/gtui
   ```

## Running

- Run from any project directory:
  ```bash
  gtui
  ```

## Non-Repository Bootstrap Flow

- If the current directory is not a Git repository, `git-tui` offers setup actions:
  - Initialize repository only.
  - Initialize, create a new Gitea remote repository, and sync.
  - Initialize, connect an existing Gitea remote repository, and sync.
- Create and publish flow:
  - Initializes a local Git repository.
  - Stages all current files.
  - Creates an initial commit.
  - Gitea creation uses the HTTPS API token, then configures and pushes `origin` using the separately selected SSH or HTTPS Git transport.
- Optional Gitea environment variables:
  - `GITEA_URL` or `GITEA_BASE_URL` for instance URL default.
  - `GITEA_OWNER` for default owner or organization.
  - `GITEA_TOKEN` or `GITEA_ACCESS_TOKEN` for API token default.
- Git credential prompts are disabled inside `git-tui`; authentication issues are reported in the UI instead of opening an interactive terminal prompt.

## Existing Repository Without Remote Flow

- If the current directory is already a Git repository and has no remotes configured, `git-tui` offers startup actions:
  - Connect to an existing Gitea remote repository and sync.
  - Create a Gitea remote repository and sync (API token required).
  - Continue without remote configuration.
  - Quit.
- Connect existing remote flow:
  - Gitea accepts `owner/name` or full clone URL input, and uses `GITEA_URL` or `GITEA_BASE_URL` defaults when a base URL is needed.
  - For Gitea `owner/name` input, chooses SSH (the default) or HTTPS transport. SSH uses `GITEA_SSH_USER` (default `git`) and optional `GITEA_SSH_PORT`; HTTPS uses the configured Git credential helper.
  - Configures remote `origin` to the selected repository URL.
  - Inspects both histories and synchronizes automatically when one side can be fast-forwarded.
  - If histories diverge, offers merge, replace-local-with-backup, and force-push-with-lease choices.
  - Requires existing uncommitted changes to be committed or stashed before synchronization.
- Repositories with a configured remote expose `Disconnect remote` in the normal operations menu. This removes only the local Git remote configuration.

## Key Commands in UI

- Main menu:
  - `Up/Down` or `j/k` to move.
  - `Enter` to execute selected action.
  - `q` or `Esc` to quit.
- File selector:
  - `Space` to toggle file selection.
  - `a` to toggle all files.
  - `Enter` to confirm.
  - `q` or `Esc` to cancel.

## Git Operations Covered

- Stage all changes (`git add -A`).
- Stage selected files (`git add -- <paths...>`).
- Unstage selected files (`git restore --staged -- <paths...>`).
- Commit staged changes (`git commit -m "<message>"`).
- Push current branch (`git push`).
- Pull with rebase (`git pull --rebase`).
- Fetch all remotes (`git fetch --all --prune`).
- Show full status (`git status`).

## Cross References

- Architecture and contracts: [`doc/architecture.md`](architecture.md)
- Change history: [`CHANGELOG.md`](../CHANGELOG.md)