Skip to main content

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​

CommandOutcome
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 --selectChoose a PR from linked worktrees, then open its hosted page

Creation options​

OptionEffect
--open, --editor <cli>Open the created worktree in an editor; --editor needs --open
--task <description>Record what the new worktree is for
--from-currentBase a new branch on the current worktree's HEAD instead of the main worktree
--detachedCreate scratch space without a branch; incompatible with --from-current
--takeMove current uncommitted changes into the new worktree
--take --copyCopy those changes and leave them in the source too
--branch-onlyCreate a branch in the current worktree; requires it to be clean and creates no new directory
--no-fetchSkip refreshing the remote default branch before creation
--no-installSkip automatic dependency setup for this worktree
--dry-runInspect the plan without Git commands or file writes
--forceRemove and recreate an existing target worktree path; review it before replacing it
--jsonEmit 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.

CommandOutcome
gji go [branch]Enter an existing worktree, or resolve a branch, remote branch, or PR into one
gji go repo/branchDisambiguate a destination across registered repositories
gji go --root or gji rootReturn 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 --selectChoose 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​

CommandOutcome
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​

CommandOutcome
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​

CommandOutcome
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.