Skip to main content

Troubleshooting

Start with a diagnostic report whenever setup or configuration is unclear:

gji doctor

If the report says that registered repository paths are missing, review and remove those stale entries with:

gji doctor --fix

Interactive terminals ask for confirmation. Use --yes when running headlessly or when the fix has already been reviewed:

gji doctor --fix --yes

Only missing repository registry entries are fixed automatically. Git, shell, configuration, and editor problems still include a manual hint.

gji go prints a path instead of changing directories​

Shell integration is not installed or not loaded in the current shell session.

eval "$(gji init zsh)"

Then retry the command.

The worktree exists but dependencies are missing​

Each worktree is a separate directory. If your project requires its own install state per directory, run installs there or configure an afterCreate hook.

{
  "hooks": {
    "afterCreate": "pnpm install"
  }
}

I want raw paths for scripts​

Use --print:

gji go --print feature/foo
gji root --print

sync refuses to run​

The current worktree may be dirty or detached.

Check:

gji status
git status --short

Then either clean the working tree or switch to a branch-backed worktree.

Pull request checkout is not behaving as expected​

Make sure the PR reference is valid and that the repository remote is reachable. gji pr accepts either a numeric PR or a full GitHub PR URL.

Cleanup prompts feel too repetitive​

Use --force when you have already reviewed what should be removed:

gji clean --force
gji done feature/foo --force

Dependency installation is not what I want​

Dependency installation is automatic when a supported lockfile is detected. To skip it for one worktree:

gji new feature/foo --no-install
gji pr 123 --no-install

To disable it for a repository, set dependencyBootstrap to off in .gji.json.