Skip to main content

Install gji

Install the CLI, then enable shell integration once. The integration lets gji new, gji go, and gji back change the directory of your current shell.

Requirements​

  • Node.js 20+ to run the npm package.
  • Git with worktree support and a local repository to work in.
  • zsh, bash, or fish for automatic directory changes.
  • Access to your Git remote for fetching branches or pull requests.

New worktrees install dependencies when a supported lockfile is detected. Your project's package manager must be available; the first install may take time and uses additional disk space. You can skip it with --no-install.

Install and set up your shell​

npm install -g @solaqua/gji
gji init

The wizard installs shell integration and completions, and lets you choose an available editor. Restart your shell, or load the configuration file shown by the wizard, before continuing.

Inside a repository, check the result:

gji doctor

Follow any hints for your shell, Git, or configuration. Then create your first worktree.

Set up a specific shell​

For dotfiles or non-interactive setup:

gji init zsh --write
# Or use your shell:
gji init bash --write
gji init fish --write

Use just the command for your shell. To inspect the wrapper without writing it:

gji init zsh

See shell integration for session-only setup and scripts. Without it, worktree commands can still create or resolve directories, but they cannot move the parent shell for you.

Optional: prepare local project files​

If a new worktree needs private files from your main worktree, register them:

gji sync-files add .env.local .npmrc

The file list is saved in global per-repository configuration. New worktrees receive those files before dependency setup; existing target files aren't overwritten. See local files.

Keep hooks for additional project setup, such as code generation. Don't add a second install hook if the built-in adapter already installs your dependencies.

Update​

npm install -g @solaqua/gji

Restart your shell to reload integration, then run gji doctor again. If navigation prints a path instead of moving your shell, follow the navigation troubleshooting steps.