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.
skipInstallPrompt	Disable the automatic install prompt permanently.
installSaveTarget	Persist install prompt choices 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"]
}

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.

CLI helpers

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