# pgt TUI

PyGitTools terminal UI for browsing a local git repository.

## Home page

The top line shows the project name followed by **Status** and **Log** tabs. The active tab is highlighted in yellow.

- **H** / **Left** or **L** / **Right** — switch between **Status** and **Log** (anywhere except while typing a commit message)
- **J** / **Up** — move selection up (from the changes list, to the actions row, then the branch row, then the project row)
- **K** / **Down** — move selection down
- **Project row** — **Enter** opens the projects table (PyGitWeb `PROJECTROOT`)
- **Branch row** — **Enter** opens a filterable list of local branches to check out
- **Actions row** — always on **Status**. **Enter** opens the actions page when the project has action sets; otherwise the row reads **No Action Groups**
- **Commit row** — type a message, then **Enter** to commit staged changes (runs git hooks); **Enter** with an empty message starts typing
- **Space** — collapse or expand a section header
- **Enter** on a section header — stage or unstage every file in that section (on **Staged**, Enter stages all unstaged and untracked files when nothing is staged)
- **Enter** on a file — stage (unstaged / untracked) or unstage (staged)
- **Log tab** — **J** / **K** scroll the commit history (newest first)
- **?** — open this help page
- **!** — open the actions page (scripts from ``pyproject.toml`` or ``actions.toml``)
- **Q** — quit

Commit or hook failures appear in the status bar.

## Actions page

Lists project actions from ``pyproject.toml`` and a top-level ``actions.toml``.
``[tool.pgt].actions`` is the ``default`` set (rename it with ``[tool.pgt].name``).
More sets live in ``[tool.pgt.sets.<name>]`` or as tables in ``actions.toml``.
Each action is ``{ name = "...", script = "..." }`` and may include ``args = ["..."]``.
Scripts run inside the
project's ``.venv``. An ``actions.toml`` set looks like this:

    [quality]
    actions = [
      { name = "lint", script = "scripts/lint.py" },
    ]

- **J** / **Up** — move selection up
- **K** / **Down** — move selection down
- **H** / **Left** or **L** / **Right** — previous or next action set
- **Tab** / **Shift-Tab** — next or previous action set
- **Enter** — run the selected action (or **Run all**)
- **A** — run all actions in the current set, stopping at the first failure
- **Esc** / **Q** — return to the home page

While an action runs, its row shows an animated spinner. Completed actions use the
staged (success) or unstaged (failure) theme colors.

## Branch picker

- **Type** — filter branches by name
- **J** / **Up** — move selection up
- **K** / **Down** — move selection down
- **Enter** — check out the selected branch (`*` marks current), or create a new branch from the current branch when the filter matches nothing
- **Esc** / **Q** — return to the home page

Checkout failures appear in the status bar.

## Projects page

Lists git repositories under the PyGitWeb project directory. Settings are read from
`~/.pygitweb/settings.json` and `PYGITWEB_*` environment variables (same as PyGitWeb):
`PYGITWEB_PROJECTROOT`, `PYGITWEB_PROJECTS_LIST`, `PYGITWEB_PROJECT_MAXDEPTH`, and
`PYGITWEB_LIST_ALL`.

- **J** / **Up** — move selection up
- **K** / **Down** — move selection down
- **Enter** — open the selected project and return to the home page
- **Esc** / **Q** — return without switching

## Help page

- **Up** / **K** — scroll up
- **Down** / **J** — scroll down
- **Q** / **Esc** — return to the previous page

## Command line

Run `pgt` with no arguments to start the TUI from the current directory.
Use `pgt --repo PATH` to open a specific repository.
Run `pgt --help` for full CLI options.