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