Commands

Running gji without a subcommand opens the action-oriented repository hub. It shows the current worktree, recommends a next worktree, separates worktrees needing attention, and collapses quiet worktrees. Use gji --json for dashboard, IDE, fzf, and other ecosystem integrations; the JSON projection remains additive to the existing ls --json and status --json contracts.

Everyday commands

Command	What it does
gji [--json]	Show the action-oriented repository/worktree hub, optionally as structured JSON.
gji new [branch] [--from-current] [--detached] [--take] [--copy] [--task <description>] [--force] [--open] [--editor <cli>] [--dry-run] [--json]	Create a branch and worktree, optionally carrying uncommitted changes and recording a task.
gji done [branch] [--force] [--keep-branch] [--json]	Safely finish a linked worktree and return.
gji undo [id] [--list] [--json]	Restore a journaled cleanup without overwriting work.
gji pr <ref> [--json]	Fetch a pull request ref and open it in a dedicated worktree.
`gji pr open [branch	#N] [--select]`
gji go [branch] [--root] [--print] [--json]	Resolve and jump to a worktree, branch, remote, or PR.
gji warp [branch] [--print] [--json]	Deprecated compatibility command; use gji go.
gji open [branch] [--select] [--editor <cli>] [--save] [--workspace]	Open the current or selected 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 task [description] [--clear] [--json]	Show, set, or clear the current worktree task.
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] [--dry-run] [--json]	Interactively prune linked worktrees.
gji remove [branch] [--force] [--dry-run] [--json] (rm)	Deprecated; use gji done for one worktree or gji clean for bulk cleanup.
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]	Interactively set up shell integration, completion, and an editor; with a shell argument, print or install the wrapper.
gji doctor [--json] [--fix] [--yes]	Check installation and configuration health; optionally remove stale repository entries.
gji completion [shell]	Print shell completion definitions.

Command groups

Creation and entry

• gji new
• gji pr
• gji go
• 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
• gji doctor

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

Maintenance

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

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

gji remove and rm remain available during the deprecation window for compatibility. They print a migration warning in human-readable mode; use gji done <branch> to finish one worktree or gji clean for bulk cleanup.

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

By default, gji new starts the branch from the main worktree. Use --from-current when the new branch should include the current worktree's HEAD instead. It cannot be combined with --detached:

gji new feature/auth-tests --from-current

Open the current worktree directly, choose another interactively, or target a branch:

gji open                    # open the current worktree in an editor
gji open --select           # 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

# Open the web page for an existing open PR
gji pr open
gji pr open --select
gji pr open feature/auth-refactor
gji pr open '#1234'

Navigate across repositories

With no branch argument, gji go opens a chooser scoped to the current repository. Press Tab to switch to all registered repositories; the chooser loads the global scope only when requested. A branch argument still resolves the current repository first, then other registered repositories, an existing local branch, a fetched remote branch, and finally a pull-request reference.

gji go teammate-branch
gji go origin-only-branch
gji go 1234
gji go -                         # return to the previous worktree
gji go --root                    # return to the main repository checkout
gji go --json feature/auth-refactor

Use --json only for already-existing destinations; it never creates a worktree or fetches a PR. Navigation JSON includes repository.name and the canonical repository.root. Use gji new when you want to create a worktree explicitly:

gji new fix/copy-regression

gji warp is deprecated. Use gji go <branch> for direct navigation, or run gji go and press Tab when you want to browse all registered repositories. repo/branch still disambiguates across repositories, and --print/--json remain available for scripts:

gji go feature/auth-refactor
gji go repo-a/main
gji go feature/auth-refactor --json

The navigation-only warp command remains available as a compatibility path during the deprecation window. It prints a warning in human-readable mode; JSON mode remains machine-readable. Use gji new for worktree creation.

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 done --json
• gji sync --json
• gji sync-files --json
• gji go --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.

When a supported lockfile is detected, gji new and gji pr automatically install dependencies before running after-create. Pass --no-install or set dependencyBootstrap to off to skip setup. Dependency setup never copies an existing tree or falls back to ordinary copying. Keep after-create hooks for project-specific commands such as generation and local-service setup. JSON bootstrap events include structured reasons, and failed setup reports the created worktree path for recovery. See the configuration guide for adapter behavior, JSON output, and dry-run behavior.