89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
# Usage
|
|
|
|
## Environment Requirements
|
|
|
|
- Linux or Unix-like terminal environment with curses support.
|
|
- Python 3 interpreter available as `python3`.
|
|
- Git installed and available in `PATH`.
|
|
- GitHub CLI `gh` installed and authenticated for GitHub repository creation. If using Gitea see below.
|
|
- Gitea API token for Gitea repository creation (read/write permissions for repository and organization) over HTTPS.
|
|
|
|
## Installation
|
|
|
|
1. Make the script executable:
|
|
```bash
|
|
chmod +x git-tui
|
|
```
|
|
2. Install as a memorable command name (example: `gtui`):
|
|
```bash
|
|
sudo install -m 755 git-tui /usr/local/bin/gtui
|
|
```
|
|
|
|
## Running
|
|
|
|
- Run from any project directory:
|
|
```bash
|
|
gtui
|
|
```
|
|
|
|
## Non-Repository Bootstrap Flow
|
|
|
|
- If the current directory is not a Git repository, `git-tui` offers setup actions:
|
|
- Initialize repository only.
|
|
- Initialize, create a new Gitea remote repository, and sync.
|
|
- Initialize, connect an existing Gitea remote repository, and sync.
|
|
- Create and publish flow:
|
|
- Initializes a local Git repository.
|
|
- Stages all current files.
|
|
- Creates an initial commit.
|
|
- Gitea creation uses the HTTPS API token, then configures and pushes `origin` using the separately selected SSH or HTTPS Git transport.
|
|
- Optional Gitea environment variables:
|
|
- `GITEA_URL` or `GITEA_BASE_URL` for instance URL default.
|
|
- `GITEA_OWNER` for default owner or organization.
|
|
- `GITEA_TOKEN` or `GITEA_ACCESS_TOKEN` for API token default.
|
|
- Network Git commands temporarily suspend curses and use the real terminal, allowing normal SSH passphrase, HTTPS credential, and credential-helper prompts.
|
|
|
|
## Existing Repository Without Remote Flow
|
|
|
|
- If the current directory is already a Git repository and has no remotes configured, `git-tui` offers startup actions:
|
|
- Connect to an existing Gitea remote repository and sync.
|
|
- Create a Gitea remote repository and sync (API token required).
|
|
- Continue without remote configuration.
|
|
- Quit.
|
|
- Connect existing remote flow:
|
|
- A full clone URL is used unchanged, preserving custom SSH users, aliases, hosts, and ports.
|
|
- For `owner/name`, uses the Gitea API to obtain the instance's exact `ssh_url` or `clone_url`; private repository lookup requires an API token.
|
|
- Configures remote `origin` to the selected repository URL.
|
|
- Inspects both histories and synchronizes automatically when one side can be fast-forwarded.
|
|
- If histories diverge, offers merge, replace-local-with-backup, and force-push-with-lease choices.
|
|
- Requires existing uncommitted changes to be committed or stashed before synchronization.
|
|
- Repositories with a configured remote expose `Disconnect remote` in the normal operations menu. This removes only the local Git remote configuration.
|
|
|
|
## Key Commands in UI
|
|
|
|
- Main menu:
|
|
- `Up/Down` or `j/k` to move.
|
|
- `Enter` to execute selected action.
|
|
- `q` or `Esc` to quit.
|
|
- File selector:
|
|
- `Space` to toggle file selection.
|
|
- `a` to toggle all files.
|
|
- `Enter` to confirm.
|
|
- `q` or `Esc` to cancel.
|
|
|
|
## Git Operations Covered
|
|
|
|
- Stage all changes (`git add -A`).
|
|
- Stage selected files (`git add -- <paths...>`).
|
|
- Unstage selected files (`git restore --staged -- <paths...>`).
|
|
- Commit staged changes (`git commit -m "<message>"`).
|
|
- Push current branch (`git push`).
|
|
- Pull with rebase (`git pull --rebase`).
|
|
- Fetch all remotes (`git fetch --all --prune`).
|
|
- Show full status (`git status`).
|
|
|
|
## Cross References
|
|
|
|
- Architecture and contracts: [`doc/architecture.md`](architecture.md)
|
|
- Change history: [`CHANGELOG.md`](../CHANGELOG.md)
|