Skip to main content

Get back to your task

Start with a diagnosis inside the affected repository:

gji doctor

Follow the hints for Git, your shell, and configuration. The sections below cover the common symptoms.

gji go prints a path instead of changing directories​

The shell wrapper isn't loaded in this session. For zsh:

eval "$(gji init zsh)"

For bash, replace zsh with bash. In fish, run gji init fish | source. Retry gji go. To make it persistent, run gji init, restart your shell, and verify again with gji doctor.

See shell integration for explicit installation and script-only usage.

The worktree exists but dependencies are missing​

Creation can finish before dependency setup fails. Use the path reported in the error to enter the created worktree; don't remove and recreate it just to retry an install.

Run your project's normal install command there, for example:

pnpm install

Check that the package manager is available and registry access works. If afterCreate didn't run because installation failed, rerun the configured hook when appropriate:

gji run-hook afterCreate

Only rerun commands you intend to repeat. Hooks may have side effects. The hook command itself doesn't rerun automatic dependency installation.

If no supported lockfile is present, configure a project-specific setup hook or install manually. See dependency bootstrap for supported tools.

I want to skip dependency setup​

For one task:

gji new feature/search --no-install
gji pr 1234 --no-install

For a repository, set dependencyBootstrap to off in .gji.json.

Local setup files weren't copied​

Check the configured list:

gji sync-files list

Source files must exist in the main worktree, not just the worktree you're currently in. Missing sources are skipped and existing destination files aren't overwritten. Changes to the list apply to future worktrees; copying isn't continuous. See local files.

sync refuses to run, or a rebase stops​

gji status
git status --short

The worktree may have local changes or a detached HEAD. Resolve local changes or move to a branch-backed worktree before syncing. If a rebase is already in progress, resolve it with your usual Git workflow (git rebase --continue or git rebase --abort) before retrying.

A PR won't open locally​

Check that its number or URL belongs to the current repository and that the Git remote is reachable with your current credentials. gji pr fetches PR refs; it doesn't grant access to private repositories.

For a plan without creating files:

gji pr 1234 --dry-run

A repository in the registry no longer exists​

Review the stale entries:

gji doctor --fix

Interactive mode asks before removing missing repository entries. Use gji doctor --fix --yes for an already-reviewed headless fix. This doesn't repair Git, editor, or shell configuration automatically.

Cleanup refuses to remove a worktree​

Check for local changes, an unmerged branch, and whether the worktree is current or primary. Keep the branch with gji done <branch> --keep-branch if you only want to remove the directory.

Don't use --force just to suppress a warning: it can discard uncommitted files and delete unmerged branches. Read cleanup and recovery first. gji undo --list shows recoverable recorded operations; undo doesn't recover uncommitted files.

I only need paths for a script​

gji go --print feature/payments
gji root --print

These don't require the shell wrapper. For structured state, use the relevant command's --json option; see commands.