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 remove 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

Enable shell integration​

gji can print paths for scripts without shell integration, but interactive navigation is much better once the shell hook is installed.

zsh​

echo 'eval "$(gji init zsh)"' >> ~/.zshrc
source ~/.zshrc

bash​

echo 'eval "$(gji init bash)"' >> ~/.bashrc
source ~/.bashrc

Verify the setup​

gji status
gji init zsh

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.

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)