Configuration

No setup is required to start using gji, but optional configuration makes repeated workflows faster.

Config files

• ~/.config/gji/config.json for global defaults.
• .gji.json in a repository for repo-local overrides.

Use the global file for defaults you want everywhere. Use .gji.json when one repository needs a different workflow.

Available keys

Key	Meaning
branchPrefix	Prefix added to new branch names, such as feature/.
editor	Default editor CLI for gji open and gji new --open (e.g. cursor, code, zed). Set with gji open --save.
syncRemote	Remote used by gji sync.
syncDefaultBranch	Branch used as the rebase target.
syncFiles	Files copied from the main worktree into new worktrees. Use global per-repo config for private files.
dependencyBootstrap	Persistent opt-out for automatic dependency setup: off.
dependencyBuildCommand	Optional Cargo build command used by dependencyBootstrap; defaults to cargo check.
installSaveTarget	Choose whether gji init --write saves wizard settings locally or globally.
hooks	Lifecycle commands for create, enter, and remove events. String hooks run through a shell; array hooks run as argv without a shell.
repos	Per-repository overrides inside the global config.

Example

{
  "branchPrefix": "feature/",
  "syncRemote": "origin",
  "syncDefaultBranch": "main",
  "syncFiles": [".env.example", ".nvmrc"],
  "dependencyBootstrap": "off"
}

Per-repo overrides in global config

If you work across many repositories, you can scope config inside the global file without adding a .gji.json to each repo:

{
  "branchPrefix": "feature/",
  "repos": {
    "/home/me/code/my-repo": {
      "branchPrefix": "fix/",
      "hooks": {
        "afterCreate": ["npm", "install"]
      }
    }
  }
}

Precedence

Configuration is resolved in this order:

1. Global defaults
2. Per-repo overrides inside the global config
3. Local .gji.json

Hooks merge by key across those layers, while normal scalar values are overridden by the highest-precedence layer.

Common patterns

Prefix all new branches

gji config set branchPrefix feature/

Rebase onto a non-default remote branch

{
  "syncRemote": "upstream",
  "syncDefaultBranch": "main"
}

Copy bootstrap files into each new worktree

{
  "syncFiles": [".env.example", ".nvmrc"]
}

Sync private local files

Use sync-files for gitignored or machine-local files such as .env.local and .npmrc:

gji sync-files add .env.local .npmrc
gji sync-files list
gji sync-files remove .npmrc

The command stores the list under the current repository inside your global config:

{
  "repos": {
    "/home/me/code/my-repo": {
      "syncFiles": [".env.local"]
    }
  }
}

gji new copies configured files from the main worktree before install hooks run, skips missing source files, and never overwrites a file that already exists in the new worktree.

Dependency bootstrap

Dependency setup is automatic by default. Set dependencyBootstrap to off to disable it, or use gji new --no-install / gji pr --no-install for one worktree. Adapters discover project-local targets from lockfiles: pnpm, Yarn, Bun, and npm install JavaScript dependencies; uv, Poetry, and Pipenv install Python environments; Bundler uses vendor/bundle; Composer uses vendor; Go runs go mod download; and Cargo runs cargo check.

No dependency tree or build cache is copied between worktrees. CoW is not supported, and a failed install is reported directly without an ordinary-copy fallback or an automatic retry. syncFiles still runs before dependency setup, and after-create hooks run only after setup succeeds. Use --no-install for a one-off opt-out; JSON and headless modes run the same automatic adapter commands unless setup is disabled.

CLI helpers

gji config get
gji config get branchPrefix
gji config set branchPrefix feature/
gji config unset branchPrefix