123 lines
4.1 KiB
Markdown
123 lines
4.1 KiB
Markdown
# gh-threads
|
|
|
|
A read-only terminal UI for people receiving GitHub pull-request reviews. It
|
|
shows open PRs, review threads with highlighted diff hunks and comment authors,
|
|
reviewer/assignee state, and the latest commit's check rollup. Resolved threads
|
|
start folded. GitHub suggestion blocks are shown as syntax-highlighted
|
|
remove/add previews. Comments 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" or "light"
|
|
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
|
|
|
|
[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)
|
|
```
|
|
|
|
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`, `--path-scroll`, and `--path-scroll-interval`. Boolean
|
|
settings can be disabled explicitly, for example `--path-scroll=false`.
|
|
|
|
## Keys
|
|
|
|
| Key | Action |
|
|
| --- | --- |
|
|
| `h` / `l` | Focus the thread list / thread detail |
|
|
| `j` / `k` | Move between threads or scroll the focused detail |
|
|
| `?` | Show contextual keybinding help |
|
|
| `/` | Fuzzy-search thread file paths |
|
|
| `↑` / `↓` | Choose a fuzzy-search match |
|
|
| `g` / `G` | First / last item |
|
|
| `enter` / `l` | Open a PR |
|
|
| `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 PR picker |
|
|
| `r` | Refresh now |
|
|
| `q` | Quit |
|
|
|
|
## Current scope
|
|
|
|
The application is intentionally read-only. GitHub's GraphQL API currently
|
|
limits this client to the first 100 review threads and first 100 comments per
|
|
thread; the UI warns when the thread list is truncated. GitHub features which
|
|
depend on server-side context, such as unfurling issue references or displaying
|
|
uploaded images, are represented textually in the terminal.
|