git-tui/README.md

git-tui

A single-file terminal UI for common Git workflows.

git-tui gives you a keyboard-driven interface for staging, committing, syncing, and bootstrapping repositories without leaving the terminal.

Highlights

• Single-file executable (git-tui)
• Curses-based terminal UI
• Stage all or select individual files
• Commit with message prompt
• Push, pull (rebase), fetch, status
• Non-repo bootstrap flow:
  • Initialize local repository
  • Optionally create and publish a new remote repository
  • Supports GitHub and Gitea
• Existing local repo without remote:
  • Offers connection to an existing GitHub or Gitea remote repository
  • Can continue without remote setup if preferred

Requirements

• Linux or Unix-like terminal with curses support
• Python 3
• Git
• GitHub CLI gh only if you choose GitHub publish flow
• Gitea personal access token only if you choose Gitea publish flow

Installation

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

Quick Start

Run from any project directory:

gtui

If the directory is not a Git repository, git-tui offers:

• Initialize repository only
• Initialize and publish to a new remote repository

If the directory is already a Git repository but has no remote configured, git-tui offers:

• Connect to an existing remote repository
• Continue without remote

Gitea Setup

For Gitea publish flow, you can provide values interactively in the TUI or pre-set environment variables:

export GITEA_URL="https://git.example.com"
export GITEA_OWNER="your-user-or-org"
export GITEA_TOKEN="your-token"

Supported variable names:

• GITEA_URL or GITEA_BASE_URL
• GITEA_OWNER
• GITEA_TOKEN or GITEA_ACCESS_TOKEN
• GITEA_SSH_USER (defaults to git)
• GITEA_SSH_PORT (only needed for a non-default SSH port)

Token handling behavior:

• Token is read from environment when present
• Otherwise token is requested in the TUI
• Token is not persisted by git-tui

When connecting an existing Gitea repository by owner/name, choose SSH to use an SSH key already configured on the machine, or HTTPS to use a configured Git credential helper. You can also paste a complete clone URL to use it unchanged.

Keybindings

• Main menu:
  • Up/Down or j/k move
  • Enter run action
  • q or Esc quit
• File picker:
  • Space toggle
  • a toggle all
  • Enter confirm
  • q or Esc cancel

Documentation

• doc/README.md
• doc/usage.md
• doc/architecture.md
• CHANGELOG.md

License

No license file is currently included in this repository.