173 lines
7.0 KiB
Markdown
173 lines
7.0 KiB
Markdown
# gh-threads
|
|
|
|
A terminal UI for people receiving GitHub pull-request reviews. It
|
|
shows open PRs and a scrollable PR dashboard with the description, branches,
|
|
review state, checks, people, labels, milestone, activity, change statistics,
|
|
thread totals, submitted reviews, and the PR conversation. Review threads and
|
|
comments are paginated rather than silently stopping at the first page. The
|
|
thread viewer includes highlighted diff hunks and comment authors. Resolved
|
|
threads start folded. GitHub suggestion blocks are shown as
|
|
syntax-highlighted remove/add previews. Comments and PR descriptions render
|
|
GitHub Flavored Markdown, including quoted replies, inline and fenced code,
|
|
lists and tasks, links, tables, emphasis, strikethrough, emoji, and GitHub
|
|
alerts. The current PR is refreshed in the background.
|
|
|
|
## Install and run
|
|
|
|
Requires Go 1.24+ and an authenticated GitHub CLI:
|
|
|
|
```sh
|
|
go install .
|
|
gh auth login
|
|
gh-threads
|
|
```
|
|
|
|
To run directly from a source checkout instead:
|
|
|
|
```sh
|
|
go run .
|
|
```
|
|
|
|
Use `go run .`, not `go run main.go`: the latter compiles only `main.go` and
|
|
omits the other files in the package.
|
|
|
|
For automation, `GH_TOKEN` or `GITHUB_TOKEN` can still be provided and takes
|
|
precedence over the GitHub CLI credential. Enterprise token environment
|
|
variables are also supported.
|
|
|
|
By default the PR picker searches all repositories for open PRs assigned to the
|
|
authenticated user and groups the results by repository. Use `--repo` to limit
|
|
the picker to one repository:
|
|
|
|
```sh
|
|
gh-threads --repo owner/repository
|
|
```
|
|
|
|
With a repository selected, pass `--all` to include every open PR in that
|
|
repository:
|
|
|
|
```sh
|
|
gh-threads --repo owner/repository --all --poll 15s
|
|
```
|
|
|
|
GitHub Enterprise Server can be used after authenticating that host:
|
|
|
|
```sh
|
|
gh auth login --hostname github.example.com
|
|
gh-threads --repo owner/repository \
|
|
--endpoint https://github.example.com/api/graphql
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The optional TOML configuration is loaded from
|
|
`$GH_THREADS_CONFIG`, `$XDG_CONFIG_HOME/gh-threads/config.toml`, or the
|
|
operating system's user configuration directory at `gh-threads/config.toml`.
|
|
On Linux this is normally `~/.config/gh-threads/config.toml`. On macOS,
|
|
`~/Library/Application Support/gh-threads/config.toml` is preferred, with
|
|
`~/.config/gh-threads/config.toml` automatically used as a fallback when it
|
|
exists.
|
|
|
|
```toml
|
|
theme = "dark" # dark, light, high-contrast, or no-color
|
|
refresh_interval = "10s"
|
|
repository = "" # optional owner/repository default
|
|
show_all = false # requires repository
|
|
limit = 50
|
|
endpoint = "https://api.github.com/graphql"
|
|
|
|
[display]
|
|
fold_resolved = true
|
|
thread_list_width_percent = 33 # 20-60
|
|
dashboard_mode = "hotkey" # "hotkey" or "intermediate"
|
|
compact_reviews = true # aggregate submitted review history
|
|
|
|
[paths]
|
|
scroll = false
|
|
scroll_interval = "350ms" # minimum 50ms
|
|
|
|
[threads]
|
|
# Each status must occur exactly once. "outdated" means unresolved and outdated;
|
|
# resolved threads remain in "resolved" even when they are also outdated.
|
|
status_order = ["unresolved", "outdated", "resolved"]
|
|
within_status = "file" # "file" or "timestamp" (oldest first)
|
|
|
|
[cache]
|
|
enabled = true # instant stale view plus offline fallback
|
|
max_age = "168h" # 7 days; 0 means no age limit
|
|
directory = "" # defaults to the OS user cache directory
|
|
```
|
|
|
|
When cached data exists, the picker and PR details are rendered immediately
|
|
from that snapshot while a live GitHub refresh runs in the background. Cached
|
|
screens are labelled with their save time and are replaced automatically when
|
|
fresh data arrives. Check annotations are fetched separately only for failed
|
|
checks so they do not inflate the initial PR query.
|
|
|
|
The cache uses separate JSON files for the picker and each visited PR. Cache
|
|
content is hashed before writing: unchanged responses do not rewrite their
|
|
files. Their modification time is touched at most once per day (or half the
|
|
configured maximum age, when shorter) so recently validated snapshots remain
|
|
usable without writing on every poll. Changed files are replaced atomically.
|
|
|
|
Command-line flags override the configuration. `GH_REPO` overrides the
|
|
configured repository when `--repo` is not provided. The corresponding flags
|
|
include `--config`, `--theme`, `--poll`, `--fold-resolved`,
|
|
`--thread-list-width`, `--dashboard-mode`, `--compact-reviews`,
|
|
`--path-scroll`, and `--path-scroll-interval`, plus `--cache`,
|
|
`--cache-max-age`, and `--cache-dir`.
|
|
Boolean settings can be disabled explicitly, for
|
|
example `--compact-reviews=false`.
|
|
|
|
With the default `dashboard_mode = "hotkey"`, opening a PR goes directly to its
|
|
review threads and `d` opens the dashboard only when requested. Set
|
|
`dashboard_mode = "intermediate"` to follow picker → dashboard → review
|
|
threads instead.
|
|
|
|
Compact reviews aggregate submission counts by state and author. Reviews with
|
|
a written summary retain a compact one-line body, while timestamps and commit
|
|
SHAs are omitted. Set `compact_reviews = false` to restore the complete review
|
|
history and metadata.
|
|
|
|
## Keys
|
|
|
|
| Key | Action |
|
|
| --- | --- |
|
|
| `h` / `l` | Focus the thread list / thread detail |
|
|
| `j` / `k` | Move between items or scroll the dashboard/focused detail |
|
|
| `?` | Show contextual keybinding help |
|
|
| `d` | Open the current pull request dashboard |
|
|
| `/` | Fuzzy-search paths and filter with `status:`, `author:`, `updated:true` |
|
|
| `F` | Clear active thread filters |
|
|
| `n` / `N` | Next / previous thread with a new update |
|
|
| `c` | Compose a reply to the selected thread |
|
|
| `R` | Resolve or unresolve the selected thread |
|
|
| `↑` / `↓` | Choose a fuzzy-search match |
|
|
| `g` / `G` | First / last item |
|
|
| `enter` / `l` | Open the selected PR dashboard or its review threads |
|
|
| `enter` | Toggle the selected review thread |
|
|
| `za` | Toggle the selected thread |
|
|
| `ctrl-d` / `ctrl-u` | Scroll thread detail or page through lists |
|
|
| `tab` | Hide or reveal the thread list |
|
|
| `b` / `esc` | Return to the previous screen |
|
|
| `r` | Refresh now |
|
|
| `q` | Quit |
|
|
|
|
The reply composer appears inline beneath the selected thread so its code and
|
|
comments remain visible while writing. It supports multiple lines: `enter`
|
|
inserts a newline, `ctrl-s` opens the rendered confirmation preview, and `esc`
|
|
cancels. Replies and resolution changes require an explicit `y` confirmation.
|
|
Write keys remain disabled for cached snapshots, during refreshes, and whenever
|
|
GitHub does not grant the corresponding per-thread capability.
|
|
|
|
## Current scope
|
|
|
|
The application can reply to review threads and resolve or unresolve them.
|
|
Other write operations remain disabled. The dashboard shows the capability
|
|
gate, including why each action is unavailable. Read state
|
|
persists beside the configuration, and recent PR data is cached for offline
|
|
fallback. Check contexts and annotations are paginated. GitHub features which depend
|
|
on server-side context, such as unfurling issue references or displaying
|
|
uploaded images, are represented textually in the terminal. See
|
|
[`TODO.md`](TODO.md) for remaining read-only work and write-support preparation.
|