1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# pgt TUI
PyGitTools terminal UI for browsing a local git repository.
## Modes
Navigation is arrow-key based by default. Press `/` to open the command prompt, then type a command and **Enter**.
- **/help** — open this help page
- **/actions** — open the actions page
- **/quit** — quit
- **/commit** — edit the commit message
- **/status** **/log** **/tasks** **/worktrees** — switch home tabs
- **/projects** — open the projects table
- **/branch** — open the branch picker
- **/vim** — enable vim-style **H**/**J**/**K**/**L** navigation
- **/novim** (or **/arrows**) — restore arrow-only navigation (default)
**Esc** cancels the command prompt. **Q** or **Ctrl-C** still quits from navigation.
## Home page
The top line shows the project name followed by **Status**, **Log**, **Tasks**, and **Worktrees** tabs. The active tab is highlighted in yellow.
- **Left** / **Right** — previous or next tab (anywhere except while typing a commit message or slash command)
- **Up** — move selection up (from the changes list, to the actions row, then the branch row, then the project row)
- **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** — **Enter** opens the multiline commit editor (in **/vim** mode, **i** also works). **/commit** does the same. In the editor, **Enter** inserts a newline; **Tab** / **↓** move to the **[ Commit ]** and **[ Commit (amend) ]** buttons; **Enter** on a button creates or amends the commit (runs git hooks). **Esc** returns to navigation.
- **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** — **Up** / **Down** scroll the commit history (newest first)
- **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" },
]
- **Up** / **Down** — move selection
- **Left** / **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
- **Up** / **Down** — move selection
- **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`.
- **Up** / **Down** — move selection
- **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.
- **Up** / **Down** — move the selection
- **Left** / **Right** on the board row — switch boards
- **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 `*`.
- **Up** / **Down** — 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`.
- **Up** / **Down** — 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** / **Down** — scroll
- **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.