128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```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.
|