Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command-Line Help for jj-gh

This document contains the help content for the jj-gh command-line program.

Command Overview:

jj-gh

Manage GitHub PR Stacks natively with jj

Usage: jj-gh [OPTIONS] <COMMAND>

Subcommands:
  • pr — Commands to work with PRs
  • config — Commands to work with jj-gh’s own configuration
  • debug — Diagnostic subcommands. Useful for inspecting the resolved config and pre-flight checks
  • completions — Generate completions (on stdout) for the specified shell
Options:
  • -v, --verbose — Increase log verbosity: -v is DEBUG, -vv is TRACE (equivalent to --log-level debug and --log-level trace, respectively)
  • -q, --quiet — Drop log level to ERROR
  • --log-level <LEVEL> — Set log level explicitly, overrides -v and -q
  • --remote <NAME> — Git remote used for the user’s own pushes and PR head lookups. Precedence: this flag, then git’s auto-detected default push remote, then default_remote in config
  • --upstream-remote <NAME> — Git remote used as the PR target in fork workflows. Precedence: this flag, then upstream_remote in config, else upstream
  • --gh-askpass <CMD> — Askpass helper command that prints a GitHub token on stdout; e.g. --gh-askpass "op read op://Vault/gh/token". Highest-priority token source; outranks $GH_ASKPASS, the token env vars, and gh_askpass in config
  • --askpass-timeout <SECS> — Timeout in seconds for the askpass helper. Default: 20

jj-gh pr

Commands to work with PRs

Usage: jj-gh pr <COMMAND>

Subcommands:
  • auto-merge — Enable auto-merge on one or more PRs
  • create — Open your preferred editor to create a PR from a revision
  • edit — Edit an existing PR’s title, body, base, labels, reviewers, draft state, and auto-merge settings via the markdown frontmatter editor flow
  • fetch — Fetch a pull request into a local bookmark
  • log — Like jj log, but injects PR metadata (e.g. number, CI status, URL)
  • rerun — Re-run CI on one or more PRs
  • stack — Make GitHub match the shape of the local jj graph
  • url — Lookup the PR by the given number or revision ID and print its full URL. This is useful in pipes such as jj-gh pr url <rev> | pbcopy or jj-gh pr url <rev> | wl-copy

jj-gh pr auto-merge

Enable auto-merge on one or more PRs.

Accepts PR numbers and/or jj revsets (which may match multiple commits, e.g. a whole stack via qv::uw); revision targets are looked up by their local bookmarks. When several PRs are targeted, a failure on one PR does not stop the others; a summary error is reported at the end. Fails if the repo does not allow auto-merge.

Usage: jj-gh pr auto-merge [OPTIONS] <PR_NUM|REVSET>...

Command Alias: am

Arguments:
  • <PR_NUM|REVSET> — PR numbers and/or jj revsets to look up PRs from. A numeric argument is treated as a PR number; anything else is resolved as a revset, which may match multiple commits (e.g. a whole stack via qv::uw)
Options:
  • -m, --method <METHOD> — Merge method used when enabling auto-merge. Overrides config auto_merge_method (default merge)

    Possible values: merge, squash, rebase

jj-gh pr create

Open your preferred editor to create a PR from a revision.

Opens your editor to a markdown file where you can write the PR description, and set PR metadata like title, labels, auto-merge, etc. via the markdown frontmatter. This supports stacked PRs; by default the base branch is set to the closest ancestor bookmark if one exists, otherwise trunk().

Usage: jj-gh pr create [OPTIONS] <REV>...

Command Alias: c

Arguments:
  • <REV> — Revision(s) to create PR(s) from. Pass multiple revisions to create a stack
Options:
  • --base <BRANCH> — Override the base bookmark. Default: closest ancestor bookmark on the stack, falling back to jj trunk(), then to the configured default_base_branch. Errors if none resolve

  • --draft <DRAFT> — Force the PR to be a draft. Overrides config (default: draft = false). Use --no-draft to force non-draft

  • --no-draft — Force the PR to be non-draft. Overrides config

  • --auto-merge <AUTO_MERGE> — Enable auto-merge on the PR after creation (merges once required checks pass). Overrides config (default: auto_merge = false). Use --no-auto-merge to force no auto-merge

  • --no-auto-merge — Disable auto-merge on the created PR. Overrides config

  • --auto-merge-method <METHOD> — Merge method used when auto-merge is enabled. Overrides config auto_merge_method (default merge)

    Possible values: merge, squash, rebase

  • -T, --template <TEMPLATE> — jj template string used to render the PR body. Evaluated against the revset being PR’d in chronological order (--reversed), so a multi-commit stack renders bottom-up.

    Mutually exclusive with --template-file and --no-template.

    All standard jj template builtins are available (description, commit_id, author, etc.). The following template aliases are also injected:

    • pr_title: default title (first-line description of the oldest or newest commit, depending on default_title_source).

    • pr_base: resolved base branch; owner-qualified (owner:branch) for cross-fork PRs.

    • pr_head_branch: existing local bookmark on the rev, or empty if the rev is unpushed.

    • pr_oldest_rev_id: 40-char hex commit SHA of the oldest commit in the revset.

  • --template-file <PATH_OR_NAME> — Path or name (under .github/PULL_REQUEST_TEMPLATE/) of a markdown template file to use as the PR body. Mutually exclusive with -T and --no-template

  • --no-template — Skip body templating entirely

  • --pick-title — Interactively choose which commit supplies the PR title

  • --title-template <TEMPLATE> — jj template string used to render candidate PR titles. Evaluated once per commit in the PR revset

  • --title-source <SOURCE> — Which commit’s description to use as the default PR title. base uses the oldest commit (default), head uses the newest. Overrides config default_title_source

    Possible values:

    • base: Use the oldest commit in the PR (closest to the base branch)
    • head: Use the newest commit in the PR (the head/top of the stack)
  • -e, --editor <CMD> — Editor command, e.g. --editor "nvim +7". Precedence: this flag, then editor in config, then jj’s ui.editor (which jj itself resolves from $JJ_EDITOR, $VISUAL, and $EDITOR)

  • --no-edit — Create the PR without opening an editor. Useful when combined with --draft

  • --diffs <SHOW_DIFFS> — Show a preview of the PR diffs while creating the PR body. Overrides pr_create_show_diffs configuration. Use --no-diffs to disable

  • --no-diffs — Hide the PR diff preview while creating the PR body. Overrides config

  • --stack <AUTO_STACK> — Automatically link created PRs into a GitHub stack when stacked. Default: true. Use --no-stack to disable

  • --no-stack — Disable automatic stack linking. Overrides config

  • --allow-private — Skip the private-commit check and pass --allow-private to jj git push, pushing commits that match the jj git.private-commits revset

jj-gh pr edit

Edit an existing PR’s title, body, base, labels, reviewers, draft state, and auto-merge settings via the markdown frontmatter editor flow.

Resolves the PR from a revision (via its local bookmark) or a PR number, fetches its current state, and opens your editor. By default, the editor includes a read-only preview of the PR diff. Applies only metadata you change: labels you didn’t touch keep whatever others (CI bots, etc.) set.

Usage: jj-gh pr edit [OPTIONS] <PR_NUM|REV>

Command Alias: e

Arguments:
  • <PR_NUM|REV> — PR number, or revision ID to look up a PR from
Options:
  • -f, --force — Edit even if the PR body is empty. By default, jj-gh refuses to edit an empty body to avoid clobbering one that exists but failed to load
  • -e, --editor <CMD> — Editor command, e.g. --editor "nvim +7". Precedence: this flag, then editor in config, then jj’s ui.editor (which jj itself resolves from $JJ_EDITOR, $VISUAL, and $EDITOR)
  • --diffs <SHOW_DIFFS> — Show a preview of the PR diffs while editing the PR. Overrides pr_edit_show_diffs configuration. Use --no-diffs to disable
  • --no-diffs — Hide the PR diff preview while editing the PR. Overrides config

jj-gh pr fetch

Fetch a pull request into a local bookmark.

Accepts a PR number. The special refs/pull/123/head ref is fetched via gix because jj cannot yet fetch arbitrary refs.

See: https://github.com/jj-vcs/jj/issues/4388

Usage: jj-gh pr fetch [OPTIONS] <PR_NUM>

Command Alias: f

Arguments:
  • <PR_NUM> — PR number to fetch
Options:
  • -T, --template <TEMPLATE> — Override the bookmark template. The argument is a jj template string evaluated once against root() (no commit context). Default: pr_fetch_bookmark_template in config, else "pr-" ++ pr_number ++ "/" ++ pr_branch.

    All standard jj template builtins are available (description, commit_id, author, etc.). The following template aliases are also injected:

    • pr_number: PR number as a decimal string.

    • pr_title: PR title.

    • pr_branch: head ref name (the source branch on the PR’s fork).

    • pr_url: PR’s html_url.

    • pr_head_sha: 40-char hex commit SHA of the PR’s head.

    • pr_head_user: PR’s head fork owner login, or empty if the fork was deleted.

    • pr_head_repo: PR’s head fork repository name, or empty if the fork was deleted.

    • pr_slug: sanitized lowercase ASCII slug of the title (max 50 chars), suitable for embedding in a bookmark name.

  • -f, --force — Replace an existing local bookmark of the same name

jj-gh pr log

Like jj log, but injects PR metadata (e.g. number, CI status, URL).

This works by injecting template aliases keyed by commit_id and renders inline PR info in a temporary config file added via jj’s --config-file argument. Any arguments after -- are forwarded to the underlying jj log invocation, e.g. jj-gh pr log -- -r 'mine()'. A default template that mirrors jj’s default template is provided, but you may provide your own with the -T|--template argument and use the injected template aliases.

Usage: jj-gh pr log [OPTIONS] [-- <JJ_LOG_ARGS>...]

Command Alias: l

Arguments:
  • <JJ_LOG_ARGS> — Arguments forwarded verbatim to the underlying jj log invocation. Pass after --, e.g. jj-gh pr log -- -r 'mine()' -T builtin_log_compact. If you pass -T / --template, the default PR-aware template is not applied.

    All standard jj template builtins are available (description, commit_id, author, etc.). The following template aliases are also injected:

    • pr_number: PR number as a string, or empty for commits without a PR.

    • pr_url: PR URL, or empty.

    • pr_ci_status: SUCCESS, FAILED, PENDING, or empty.

    • pr_merge_status: merged / in-merge-queue / auto-merge label, or empty.

    • pr_meta: pre-formatted hyperlinked PR number plus colored CI icon plus merge status.

Options:
  • --nerdfonts <NERDFONTS> — Force enable the use of nerdfont icons in the default pr log template. Overrides config. Use --no-nerdfonts to disable
  • --no-nerdfonts — Force the default pr log template not to use nerdfont icons. Overrides config
  • -T <TEMPLATE> — Override pr_log_template from config for this invocation. Sets the body of the default pr_log template alias jj-gh injects. Has no effect if you pass your own -T / --template in forwarded jj log args (after --)

jj-gh pr rerun

Re-run CI on one or more PRs.

Accepts PR numbers and/or jj revsets (which may match multiple commits, e.g. qn::ps); revision targets are looked up via their local bookmarks. Pass --all to target every local PR instead.

By default, failed jobs are re-run on each PR’s completed workflow runs with a retryable failure; runs still in progress are skipped with a note, because GitHub refuses to re-run a workflow run until it reaches the completed state. With --all-jobs, every completed run is fully restarted, even successful ones (not to be confused with --all, which targets all local PRs rather than all jobs). With --cancel, in-progress runs that already contain a failed job are cancelled first and retried once they finalize; combined with --all-jobs, ALL in-progress runs are cancelled and the entire pipeline is restarted.

When several PRs are targeted, a failure on one PR does not stop the others; the command reports a summary error at the end instead.

With --watch, instead of a one-shot retry the selected PRs are polled continuously and retryable failures are retried as they happen (optionally capped per run with --max-retries), until you quit. A bare --watch implies --all and, unlike one-shot --all, also watches currently-green PRs since they can go red later. On a terminal this shows an inline list with one row per PR (j/k to move, p to pause retrying the selected PR, R to force a cancel-and-retry of it, q to quit); without one it prints plain log lines per event instead.

Usage: jj-gh pr rerun [OPTIONS] <PR_NUM|REVSET|--all|--watch>

Arguments:
  • <PR_NUM|REVSET> — PR numbers and/or jj revsets to look up PRs from. A numeric argument is treated as a PR number; anything else is resolved as a revset, which may match multiple commits
Options:
  • --all — Rerun CI on all local PRs (the default/–cancel/–all-jobs rules still apply to each PR)

  • --cancel — Cancel in-progress runs that already contain at least one failed job, wait for them to finalize, then retry. With –all-jobs, cancels ALL in-progress runs and restarts the entire pipeline

  • --all-jobs — Re-run ALL jobs in the targeted workflow runs, even successful ones, instead of only failed jobs. Not to be confused with --all, which targets all local PRs rather than all jobs

  • --cancel-timeout <SECS> — Seconds to wait for cancelled runs to finalize before re-running. Only meaningful with –cancel (ignored in watch mode, which never blocks on a cancelled run)

    Default value: 30

  • --watch — Keep watching the selected PRs and retry failures as they happen, until you quit. With no other selection, watches every local open PR, including currently-green ones (they can go red later). New PRs matching the selection are picked up while running; merged and closed PRs stay listed with a checkmark

  • --poll-interval <SECS> — Seconds between CI status polls in watch mode

    Default value: 15

  • --max-retries <N> — Watch mode retry budget per workflow run: a run that keeps failing after this many automatic retries is marked given-up and left alone (press R on the PR to force another retry). Unlimited when not set

jj-gh pr stack

Make GitHub match the shape of the local jj graph.

Pushes bookmarks whose remote target has fallen behind, moves each PR’s base branch onto its closest stacked ancestor bookmark, then creates, reshapes, or dissolves GitHub stacks to match the local chains. The jj graph is never rewritten: shape it yourself (e.g. via jj rebase), then run this.

Without arguments it reconciles every local PR, printing the jj log it is working from and the proposed plan before touching anything. Given revsets or PR numbers it asserts exactly that stack, bottom to top, which is the escape hatch for when detection gets it wrong. A revset range like qv::uw expands bottom-to-top, so a whole stack can be asserted with a single argument.

Without arguments, applying needs a confirmation: answer the prompt, or pass --force. Outside a terminal there is nobody to prompt, so the plan is printed and --force is required to apply it. Naming the PRs explicitly is itself the confirmation, so that form does not prompt.

Use --dry-run or --json to print the plan and stop either way.

Usage: jj-gh pr stack [OPTIONS] [REVSET_OR_PR_NUM]...

Command Alias: s

Arguments:
  • <REVSET_OR_PR_NUM> — Revisions or PR numbers to stack, in order from bottom to top. Each argument can be a jj revset (like jj-gh pr rerun; a range such as qv::uw expands bottom-to-top, skipping interior commits of multi-commit PRs) or a PR number. If omitted, every local PR is reconciled against the local jj graph
Options:
  • --force — Apply the plan without prompting. Required to apply anything when STDIN or STDERR is not a terminal, where the default is a dry run. Also unstacks PRs that are already in a different stack; answering the interactive prompt does the same
  • --dry-run — Print the proposed plan and exit without touching GitHub
  • --json — Emit the proposed plan as JSON. Implies --dry-run
  • --push <AUTO_PUSH> — Push bookmarks whose remote target has fallen behind before stacking. Default: true. Use --no-push to disable
  • --no-push — Do not push bookmarks, even if their remote target is stale
  • --nerdfonts <NERDFONTS> — Force enable nerdfont icons in the jj log view shown above the plan. Overrides config. Use --no-nerdfonts to disable
  • --no-nerdfonts — Force the jj log view not to use nerdfont icons. Overrides config
  • -T <TEMPLATE> — Template for the jj log view shown above the plan. The same aliases as pr log are injected here. See jj-gh pr log --help. Defaults to pr_log_template from configuration

jj-gh pr url

Lookup the PR by the given number or revision ID and print its full URL. This is useful in pipes such as jj-gh pr url <rev> | pbcopy or jj-gh pr url <rev> | wl-copy

Usage: jj-gh pr url [OPTIONS] <PR_NUM|REV>

Arguments:
  • <PR_NUM|REV> — PR number or revision ID to lookup PR from
Options:
  • --remote <NAME> — Git remote used for the user’s own pushes and PR head lookups. Precedence: this flag, then git’s auto-detected default push remote, then default_remote in config
  • --upstream-remote <NAME> — Git remote used as the PR target in fork workflows. Precedence: this flag, then upstream_remote in config, else the default upstream

jj-gh config

Commands to work with jj-gh’s own configuration

Usage: jj-gh config <COMMAND>

Subcommands:
  • schema — Print the JSON Schema for the jj-gh config table on stdout

jj-gh config schema

Print the JSON Schema for the jj-gh config table on stdout.

Point an editor’s JSON-schema support at the output to get completion and validation for the [jj-gh] table in your jj config.

Usage: jj-gh config schema

jj-gh debug

Diagnostic subcommands. Useful for inspecting the resolved config and pre-flight checks

Usage: jj-gh debug <COMMAND>

Subcommands:
  • config — Print the merged config with the token rendered as ***
  • auth — Resolve the GitHub token and report success or failure. Never prints the token itself
  • rev — Resolve a revision and print commit info, ancestor bookmark, remote URLs, and the detected default branch
  • pr-lookup — Pre-flight lookup for a PR: resolve the target, check if a PR is already open for the head, and confirm the base branch exists on the remote

jj-gh debug config

Print the merged config with the token rendered as ***

Usage: jj-gh debug config

jj-gh debug auth

Resolve the GitHub token and report success or failure. Never prints the token itself

Usage: jj-gh debug auth

jj-gh debug rev

Resolve a revision and print commit info, ancestor bookmark, remote URLs, and the detected default branch

Usage: jj-gh debug rev <REV>

Arguments:
  • <REV>

jj-gh debug pr-lookup

Pre-flight lookup for a PR: resolve the target, check if a PR is already open for the head, and confirm the base branch exists on the remote

Usage: jj-gh debug pr-lookup <REV>

Arguments:
  • <REV>

jj-gh completions

Generate completions (on stdout) for the specified shell.

Without flags, emits a standalone completion script for the jj-gh binary. With --jj-alias <NAME> --subcommand <NAME> (both required together), emits an overlay that adds completions for jj <jj-alias> <tab> on top of jj’s own completion script (source the overlay after jj util completion <shell>).

Usage: jj-gh completions [OPTIONS] <SHELL>

Arguments:
  • <SHELL>

    Possible values:

    • bash: Bash
    • elvish: Elvish
    • fish: Fish
    • nushell: Nushell
    • powershell: PowerShell
    • zsh: Zsh
Options:
  • --jj-alias <NAME> — Emit an overlay for jj <NAME> <tab> instead of the standalone jj-gh script. Pass the jj alias name (e.g. pr). Must be paired with --subcommand

  • --subcommand <NAME> — jj-gh top-level subcommand whose tree the overlay describes (e.g. pr). Must be paired with --jj-alias

    Possible values: pr


This document was generated automatically by clap-markdown.