Skip to main content

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.