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.