Skip to main content

Commands

Everyday commands​

CommandWhat it does
gji new [branch] [--detached] [--open] [--editor <cli>] [--json]Create a branch and worktree, then enter it.
gji pr <ref> [--json]Fetch a pull request ref and open it in a dedicated worktree.
gji go [branch] [--print]Jump to a worktree or print its path for scripting.
gji warp [branch] [--new [branch]] [--print] [--json]Jump to any known repo worktree, or create a new one from the same entry point.
gji open [branch] [--editor <cli>] [--save] [--workspace]Open a worktree in an editor.
gji back [n] [--print]Return to the previously visited worktree, optionally N steps back.
gji history [--json]Show navigation history.
gji root [--print]Jump back to the main repo root.
gji status [--json]Show repo health, active worktrees, and ahead/behind counts.
gji ls [--compact] [--json]Show detailed or compact worktree lists.
gji sync [--all]Fetch and rebase worktrees onto the default branch.
gji sync-files [--json] [list|add|remove] [paths...]Manage local files copied into new worktrees.
gji clean [--stale] [--force] [--json]Interactively prune linked worktrees.
gji remove [branch] [--force] [--json]Remove a worktree and its branch.
gji trigger-hook <hook>Re-run a configured hook in the current worktree.
gji config [get|set|unset] [key] [value]Read and update configuration values.
gji init [shell]Print or install shell integration.

Command groups​

Creation and entry​

  • gji new
  • gji pr
  • gji go
  • gji warp
  • gji open
  • gji back [n]
  • gji root

These are the commands you use for opening or switching context.

Inspection​

  • gji status
  • gji ls
  • gji ls --compact

Use these when you need to understand the current set of worktrees and their state.

Maintenance​

  • gji sync
  • gji sync-files
  • gji clean
  • gji remove
  • gji trigger-hook

These are the commands that keep the worktree set healthy over time.

Configuration and shell setup​

  • gji config
  • gji init

Use these to shape default behavior and shell handoff.

Common patterns​

Start feature work and open it in an editor​

gji new feature/auth-refactor --open --editor cursor

Or open an existing worktree interactively from anywhere:

gji open                    # pick a worktree, then an editor
gji open feature/auth-refactor --editor code
gji open --editor cursor --save   # save cursor as your default editor

--workspace generates a .code-workspace file before opening, enabling per-workspace settings in VS Code, Cursor, and Windsurf.

Open a pull request for review​

gji pr 1234

Warp across registered repos​

gji warp feature/auth-refactor
gji warp repo-a/main
gji warp --new fix/copy-regression
gji warp feature/auth-refactor --json

Use gji warp when branch intent matters more than the repo directory you happen to be inside. repo/branch disambiguates across registered repos, and --new lets you create the next worktree from the same command surface.

Re-run your setup hook​

gji trigger-hook afterCreate

Sync local files into future worktrees​

gji sync-files add .env.local .npmrc
gji sync-files list
gji sync-files remove .npmrc

Use sync-files for gitignored or machine-local files that new worktrees need before install hooks run. The command writes to your global per-repo config, so private file names do not need to be committed to .gji.json.

Return to the last worktree​

gji back       # one step back
gji back 2     # two steps back
gji back 3     # three steps back

gji back behaves like cd - for worktrees. Run it once to return to wherever you were before. Run it again to toggle back. Pass a number to jump further into history. Use gji history to see where you've been:

gji history
gji history --json

Script against printed paths​

repo_root=$(gji root --print)
feature_path=$(gji go --print feature/auth-refactor)

JSON output​

Several commands support --json so shell scripts and tools can consume structured output directly:

  • gji new --json
  • gji pr --json
  • gji status --json
  • gji ls --json
  • gji clean --json
  • gji remove --json
  • gji sync --json
  • gji sync-files --json
  • gji warp --json

gji clean --stale limits cleanup to clean branch worktrees whose upstream is gone and whose branch is already merged into the configured or remote default branch.