git-tui/doc/usage.md

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:

   chmod +x git-tui
   

2. Install as a memorable command name (example: gtui):

   sudo install -m 755 git-tui /usr/local/bin/gtui
   

Running

• Run from any project directory:

  gtui
  

Non-Repository Bootstrap Flow

• If the current directory is not a Git repository, git-tui offers setup actions:
  • Initialize repository only.
  • Initialize and publish to a new remote repository.
• Initialize and publish flow:
  • Chooses publishing provider: GitHub or Gitea.
  • Initializes a local Git repository.
  • Stages all current files.
  • Creates an initial commit.
  • GitHub option creates and pushes via gh repo create --source=. --remote=origin --push.
  • Gitea option creates via HTTPS API, configures origin, and pushes with HTTPS authentication using the provided token.
• 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 remote repository.
  • Continue without remote configuration.
  • Quit.
• Connect existing remote flow:
  • Chooses provider: GitHub or Gitea.
  • GitHub accepts owner/name or full clone URL input.
  • 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.
  • Optionally pushes current branch with upstream tracking (git push -u origin <branch>).

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
• Change history: CHANGELOG.md