Command reference
Start with the task you want to do. For the complete option list of any command,
run gji <command> --help. If you're trying gji for the first time, follow the
quick start instead.
Start and review
| Command | Outcome |
|---|---|
gji new [branch] | Create a branch and linked worktree; omit the branch for an interactive flow |
gji pr <ref> | Fetch a GitHub pull request into a dedicated worktree; accepts a number, #number, or URL |
gji pr open [branch|#N] | Open the hosted PR page for the current or named worktree |
gji pr open --select | Choose a PR from linked worktrees, then open its hosted page |
Creation options
| Option | Effect |
|---|---|
--open, --editor <cli> | Open the created worktree in an editor; --editor needs --open |
--task <description> | Record what the new worktree is for |
--from-current | Base a new branch on the current worktree's HEAD instead of the main worktree |
--detached | Create scratch space without a branch; incompatible with --from-current |
--take | Move current uncommitted changes into the new worktree |
--take --copy | Copy those changes and leave them in the source too |
--branch-only | Create a branch in the current worktree; requires it to be clean and creates no new directory |
--no-fetch | Skip refreshing the remote default branch before creation |
--no-install | Skip automatic dependency setup for this worktree |
--dry-run | Inspect the plan without Git commands or file writes |
--force | Remove and recreate an existing target worktree path; review it before replacing it |
--json | Emit structured success or error output |
These options describe new. pr supports --no-install, --dry-run, and
--json. Project-specific setup follows the built-in dependency adapter; see
configuration.
gji new feature/search --open --editor cursor
gji new feature/search-tests --from-current
gji pr 1234 --dry-run
--branch-only refreshes the configured default branch and creates the branch
in place without dependency setup. Use --no-fetch to use the local default
branch. Choose a separate worktree when the task you leave needs to stay open.
Navigate and open editors
| Command | Outcome |
|---|---|
gji go [branch] | Enter an existing worktree, or resolve a branch, remote branch, or PR into one |
gji go repo/branch | Disambiguate a destination across registered repositories |
gji go --root or gji root | Return to the main repository checkout |
gji back [n] or gji go - | Return to the previously visited worktree; back n goes farther into history |
gji history [--json] | Show where you've been |
gji open [branch] | Open the current or named worktree in an editor |
gji open --select | Choose a worktree and editor interactively |
With no destination, go opens a chooser for the current repository. Press
Tab for all registered repositories. Press / to search branch, path, PR,
or task text.
A branch argument resolves the current repository first, then other registered
repositories, an existing local branch, a fetched remote branch, and a PR ref.
go --json only resolves existing destinations: it doesn't fetch or create one.
gji go feature/payments
gji go api/main
gji back 2
gji open --editor cursor --save
gji open feature/payments --workspace
open --save remembers the editor CLI. --workspace generates a
.code-workspace file for VS Code, Cursor, or Windsurf. go --quiet suppresses
the context card. Navigation changes your current shell directory only when
shell integration is loaded.
Inspect and label work
| Command | Outcome |
|---|---|
gji [--json] | Open the repository hub with current work, suggested destinations, and worktrees needing attention |
gji status [--json] | Check repository/worktree health and ahead/behind counts |
gji ls [--compact] [--json] | List worktrees; compact mode shows branch and path |
gji task [description] [--clear] [--json] | Read, set, or clear the current worktree's task description |
gji doctor [--json] | Diagnose shell, Git, configuration, and registry setup |
Use gji doctor --fix to review removal of missing repository registry entries.
It doesn't repair Git or shell configuration automatically. --yes applies
that fix without prompting.
Maintenance
| Command | Outcome |
|---|---|
gji sync [--all] [--json] | Fetch and rebase one or all worktrees onto the default branch |
gji done [branch] [--keep-branch] [--force] [--json] | Remove a finished linked worktree and, unless kept, its branch |
gji clean [--stale] [--path <pattern>] [--dry-run] [--force] [--json] | Select and remove several linked worktrees |
gji undo [id] [--list] [--json] | Restore recorded state from a journaled cleanup without overwriting existing work |
gji sync-files [list|add|remove] [paths...] [--json] | Manage files copied from the main worktree into future worktrees |
gji run-hook <hook> | Run a configured lifecycle hook in the current worktree; trigger-hook is an alias |
sync can require rebase conflict resolution. done and clean can delete
branches. --force can discard uncommitted files and delete unmerged branches;
undo cannot recover those files. Read sync and cleanup
before automating removal.
gji clean --stale --dry-run
gji done feature/search --keep-branch
gji undo --list
gji sync-files add .env.local
gji run-hook afterCreate
--stale selects clean worktrees with a missing upstream and changes already
merged into the default branch. Repeat --path to match any of several
locations; path filters search all registered repositories. See
path filtering.
Setup and defaults
| Command | Outcome |
|---|---|
gji init [shell] [--write] | Run guided setup, or print/install a specific shell wrapper |
gji completion [shell] | Print shell completions |
gji config get [key] | Read global defaults or one value |
gji config set <key> <value> | Save a global default |
gji config unset <key> | Remove a global default |
See installation, configuration, and hooks for setup choices.
Paths and JSON for scripts
Use --print with go, back, or root when you only need the destination:
feature_path=$(gji go --print feature/payments)
--json is available on the hub, new, pr, go, status, ls, task,
history, sync, sync-files, clean, done, undo, and doctor.
Navigation JSON includes repository.name and canonical repository.root.
gji --json
gji go feature/payments --json
gji new feature/search --json
JSON doesn't mean read-only: creation still runs dependency setup unless you
skip it. Use --dry-run where supported to inspect a plan. In headless cleanup,
--force is required for removal; use --dry-run to review candidates first.