Command-Line Help for jj-gh
This document contains the help content for the jj-gh command-line program.
Command Overview:
jj-gh↴jj-gh pr↴jj-gh pr auto-merge↴jj-gh pr create↴jj-gh pr edit↴jj-gh pr fetch↴jj-gh pr log↴jj-gh pr rerun↴jj-gh pr stack↴jj-gh pr url↴jj-gh config↴jj-gh config schema↴jj-gh debug↴jj-gh debug config↴jj-gh debug auth↴jj-gh debug rev↴jj-gh debug pr-lookup↴jj-gh completions↴
jj-gh
Manage GitHub PR Stacks natively with jj
Usage: jj-gh [OPTIONS] <COMMAND>
Subcommands:
pr— Commands to work with PRsconfig— Commands to work with jj-gh’s own configurationdebug— Diagnostic subcommands. Useful for inspecting the resolved config and pre-flight checkscompletions— Generate completions (on stdout) for the specified shell
Options:
-v,--verbose— Increase log verbosity:-visDEBUG,-vvisTRACE(equivalent to--log-level debugand--log-level trace, respectively)-q,--quiet— Drop log level toERROR--log-level <LEVEL>— Set log level explicitly, overrides-vand-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, thendefault_remotein config--upstream-remote <NAME>— Git remote used as the PR target in fork workflows. Precedence: this flag, thenupstream_remotein config, elseupstream--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, andgh_askpassin 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 PRscreate— Open your preferred editor to create a PR from a revisionedit— Edit an existing PR’s title, body, base, labels, reviewers, draft state, and auto-merge settings via the markdown frontmatter editor flowfetch— Fetch a pull request into a local bookmarklog— Likejj log, but injects PR metadata (e.g. number, CI status, URL)rerun— Re-run CI on one or more PRsstack— Make GitHub match the shape of the localjjgraphurl— Lookup the PR by the given number or revision ID and print its full URL. This is useful in pipes such asjj-gh pr url <rev> | pbcopyorjj-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 viaqv::uw)
Options:
-
-m,--method <METHOD>— Merge method used when enabling auto-merge. Overrides configauto_merge_method(defaultmerge)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 jjtrunk(), then to the configureddefault_base_branch. Errors if none resolve -
--draft <DRAFT>— Force the PR to be a draft. Overrides config (default:draft = false). Use--no-draftto 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-mergeto 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 configauto_merge_method(defaultmerge)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-fileand--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 ondefault_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-Tand--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.baseuses the oldest commit (default),headuses the newest. Overrides configdefault_title_sourcePossible 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, theneditorin config, then jj’sui.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. Overridespr_create_show_diffsconfiguration. Use--no-diffsto 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-stackto disable -
--no-stack— Disable automatic stack linking. Overrides config -
--allow-private— Skip the private-commit check and pass--allow-privatetojj git push, pushing commits that match the jjgit.private-commitsrevset
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-ghrefuses 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, theneditorin config, then jj’sui.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. Overridespr_edit_show_diffsconfiguration. Use--no-diffsto 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 againstroot()(no commit context). Default:pr_fetch_bookmark_templatein 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’shtml_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 underlyingjj loginvocation. 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 defaultpr logtemplate. Overrides config. Use--no-nerdfontsto disable--no-nerdfonts— Force the defaultpr logtemplate not to use nerdfont icons. Overrides config-T <TEMPLATE>— Overridepr_log_templatefrom config for this invocation. Sets the body of the defaultpr_logtemplate alias jj-gh injects. Has no effect if you pass your own-T/--templatein forwardedjj logargs (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 modeDefault 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 (likejj-gh pr rerun; a range such asqv::uwexpands bottom-to-top, skipping interior commits of multi-commit PRs) or a PR number. If omitted, every local PR is reconciled against the localjjgraph
Options:
--force— Apply the plan without prompting. Required to apply anything whenSTDINorSTDERRis 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-pushto disable--no-push— Do not push bookmarks, even if their remote target is stale--nerdfonts <NERDFONTS>— Force enable nerdfont icons in thejj logview shown above the plan. Overrides config. Use--no-nerdfontsto disable--no-nerdfonts— Force thejj logview not to use nerdfont icons. Overrides config-T <TEMPLATE>— Template for thejj logview shown above the plan. The same aliases aspr logare injected here. Seejj-gh pr log --help. Defaults topr_log_templatefrom 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, thendefault_remotein config--upstream-remote <NAME>— Git remote used as the PR target in fork workflows. Precedence: this flag, thenupstream_remotein 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 thejj-ghconfig 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 itselfrev— Resolve a revision and print commit info, ancestor bookmark, remote URLs, and the detected default branchpr-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: Bashelvish: Elvishfish: Fishnushell: Nushellpowershell: PowerShellzsh: Zsh
Options:
-
--jj-alias <NAME>— Emit an overlay forjj <NAME> <tab>instead of the standalonejj-ghscript. 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-aliasPossible values:
pr
This document was generated automatically by
clap-markdown.