# pgt TUI

PyGitTools terminal UI for browsing a local git repository.

## Home page

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

- **H** / **Left** or **L** / **Right** — previous or next tab (anywhere except while typing a commit message)
- **K** / **Up** — move selection up (from the changes list, to the actions row, then the branch row, then the project row)
- **J** / **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. On **Tasks**, **Enter** syncs the current board with the default remote. On **Worktrees**, **Enter** opens the add-worktree form.
- **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** or **Ctrl-C** — 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" },
    ]

- **K** / **Up** — move selection up
- **J** / **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
- **K** / **Up** — move selection up
- **J** / **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`.

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

## Tasks tab

Lists boards stored in the repository. The board row shows the current board and its task count. Each status is a collapsible section with a **(+ New Task)** row.

- **J** / **K** — move the selection
- **Enter** on a status header, or **Space** — collapse or expand that status
- **Enter** on **(+ New Task)** — open the task editor for a new task
- **Enter** on a task — open the task editor
- **Branch row** + **Enter** — sync the current board with the default remote (`origin` when it exists)

## Worktrees tab

Lists linked worktrees. The active worktree is marked with `*`.

- **J** / **K** — move the selection
- **Enter** on **(+ Add worktree)**, or **Enter** on the branch row — open the add-worktree form
- **Enter** on another worktree — switch the TUI to that worktree
- **D** — remove the selected worktree. The active worktree cannot be removed.

## Add worktree

- **Type** — path, then an optional branch. Leave the branch empty and git creates a new branch named after the directory, based on `HEAD`. An existing local branch is checked out as-is; an unknown name is created with `-b`.
- **J** / **K** — switch between the path and branch fields
- **Enter** — create the worktree. A relative path is resolved from the current worktree.
- **Esc** / **Q** — return to the home page

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