Frequently asked questions
Do I need to commit or stash before opening another task?
Not for a separate worktree. Your changes stay in the original directory while
gji new or gji pr opens another task elsewhere. gji new --branch-only is
different: it reuses the current worktree and requires it to be clean.
Does navigation move my changes to another branch?
No. go and back change your location; files stay in their worktree. Use
gji new <branch> --take when you deliberately want to move uncommitted changes
into a new task, or add --copy to keep them in both places.
What does each worktree isolate?
Working files, dependency installations, and generated files are in separate directories. Git history and refs are shared. Services, ports, databases, and other external resources still need project-specific configuration.
Can I use my editor or coding agent?
Yes. Enter a worktree and run your usual tool there. gji open can open it in
an installed editor. Give parallel agent tasks separate worktrees when you want
them to work on separate files; gji doesn't manage or coordinate the agents.
Why does gji need shell integration?
A CLI process cannot change the working directory of its parent shell. The
wrapper bridges that gap. Run gji init, restart your shell, and check
gji doctor. See shell integration.
Can I use it without the wrapper?
Yes. Create or inspect worktrees normally, and use gji go --print <branch> or
gji root --print when scripts need a path. Automatic directory changes need
the wrapper.
Where do worktrees live?
By default:
../worktrees/<repo>/<branch>
They sit outside the main checkout, with a predictable path for each branch.
Use gji ls to inspect the directories that already exist.
Do dependencies install for every worktree?
A new worktree needs its own install state. Supported lockfiles trigger
installation automatically; no dependency tree is copied from another
worktree. The first setup can take time. Use --no-install for one creation,
or set dependencyBootstrap to off for the repository. See
dependency bootstrap.
How do new worktrees get .env.local?
gji sync-files add .env.local
Future worktrees copy it from the main worktree, before dependency setup. It isn't kept synchronized afterward. See local file configuration.
Which PR formats work?
gji pr accepts a GitHub PR number, a quoted '#1234', or a full GitHub PR URL.
Use a reference belonging to the repository you are working in.
Where should I put my settings?
Personal defaults go in ~/.config/gji/config.json. Per-repo entries there keep
personal settings out of Git. Use .gji.json for shared project defaults.
See configuration.
Can I rerun setup without recreating a worktree?
Run your project's install command inside that directory for dependency setup.
To rerun a configured hook, use gji run-hook afterCreate. The hook command
doesn't rerun the built-in dependency adapter.
Can undo recover files removed during cleanup?
It restores recorded branch and worktree state, but not uncommitted or
untracked files. Review worktree contents before removal, especially with
--force. See sync and cleanup.