# 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.

![git-tui avatar](assets/logo-avatar.png)

## 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

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

## Quick Start

Run from any project directory:

```bash
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:

```bash
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`

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, paste the complete clone URL or
provide `owner/name` and ask the Gitea API to return its exact clone endpoints.
The app does not derive an SSH endpoint from the web URL because the SSH user,
host, and port can differ. Private API lookups require a token; pasting the
clone URL does not.

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.

Network Git commands temporarily leave the curses screen and use the real
terminal. SSH passphrase prompts, HTTPS username/token prompts, and interactive
credential helpers therefore behave as they do for Git commands run directly
from the shell.

## 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.