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, create a Gitea remote, and sync local commits to it
• Initialize, connect an existing Gitea remote, and synchronize both sides

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

• Create a Gitea remote and sync
• Connect an existing Gitea remote and sync
• Continue without remote

When a remote is configured, the normal operations menu includes an action to disconnect it. Disconnecting removes only the local remote configuration; it does not delete the Gitea repository.

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.

Creating a Gitea repository still uses an API token, because Git/SSH cannot create repositories. The Git remote transport is selected separately; choosing SSH leaves the new origin configured with Gitea's SSH clone URL.

Synchronization compares local and remote commit history. It fast-forwards or pushes automatically when one side is ahead. If the histories diverge, the UI offers to merge, replace local history after creating a backup branch, or force-push local history with --force-with-lease. Uncommitted changes must be committed or stashed first and are never silently discarded.

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.