Skip to main content

Installation

Requirements​

  • Node.js 18 or newer for the CLI package.
  • zsh or bash if you want gji go, gji new, and gji done to change the current shell directory.
  • Git worktree support in your local Git installation.

Install the CLI​

npm install -g @solaqua/gji

What to expect after install​

After the package is installed:

  • gji status works immediately
  • path-printing modes like gji root --print work immediately
  • direct directory handoff still requires shell integration

Run guided setup​

gji can print paths for scripts without shell integration, but interactive navigation is much better once the shell hook is installed. Run the guided setup in a terminal to install shell integration, completions, and an available editor:

gji init
# restart your shell, or source the rc file shown by the wizard
gji doctor

For dotfiles or CI, use the explicit shell command instead:

gji init zsh --write

Verify the setup​

gji status
gji doctor

If shell integration is active, commands like gji new feature/foo and gji go main can hand your shell to the target path directly.

Optional next step: automate setup in each new worktree​

Many users want installs, environment setup, or local configuration files to be ready automatically.

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

gji sync-files add .env.local .npmrc

gji stores that list in your global per-repo config and copies the files before setup hooks run.

Supported dependency adapters run automatically when a lockfile is detected. To permanently opt out for this repository, use:

{
  "dependencyBootstrap": "off"
}

gji new automatically runs the appropriate dependency install command after syncFiles when a supported lockfile is detected. Dependency trees and build caches are never copied. Use gji new --no-install to skip setup, or gji new --dry-run to inspect the commands.

Add an afterCreate hook:

{
  "hooks": {
    "afterCreate": ["pnpm", "install"]
  }
}

Array hooks run without a shell and are the safer default for simple commands. If you need shell features in a string hook, quote context values with "$GJI_PATH", "$GJI_BRANCH", or "$GJI_REPO" instead of leaving template values unquoted.

Script-friendly mode​

Use --print when you want the raw path instead of shell handoff:

path=$(gji go --print feature/dark-mode)
path=$(gji root --print)