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, 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.
• Network Git commands temporarily suspend curses and use the real terminal, allowing normal SSH passphrase, HTTPS credential, and credential-helper prompts.

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:
  • A full clone URL is used unchanged, preserving custom SSH users, aliases, hosts, and ports.
  • For owner/name, uses the Gitea API to obtain the instance's exact ssh_url or clone_url; private repository lookup requires an API token.
  • 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
• Change history: CHANGELOG.md