Make new worktrees fit your project
Start with the defaults. Add configuration when you find yourself repeating a setup step, choosing the same editor, or copying the same local files.
Choose where a setting belongs
| Location | Use it for |
|---|---|
~/.config/gji/config.json | Personal defaults across repositories |
repos entries in that global file | Personal settings for one repository, including private local file names |
.gji.json in a repository | Shared project defaults |
Configuration is resolved in that order: global defaults, global per-repo
settings, then local .gji.json. The later layer overrides the earlier value.
Hooks merge by event key; the same event is overridden by the later layer.
Save an editor or branch prefix
gji open --editor cursor --save
gji config set branchPrefix feature/
Use your installed editor CLI. config edits global defaults:
gji config get
gji config get branchPrefix
gji config unset branchPrefix
Sync private local files
Run this in the repository whose future worktrees need the files:
gji sync-files add .env.local .npmrc
gji sync-files list
gji sync-files remove .npmrc
The list is saved under that repository in your global config. New worktrees copy the files from the main worktree before dependency setup. Missing source files are skipped; existing files in the destination aren't overwritten. This is a copy at creation time, not continuous synchronization.
For shared project files, put syncFiles in .gji.json instead:
{
"syncFiles": [".env.example", ".nvmrc"]
}
Dependency bootstrap
A new worktree gets its own dependencies. When gji new or gji pr detects a
supported lockfile, it runs the appropriate project-local setup:
| Project | Setup |
|---|---|
| pnpm, Yarn, Bun, npm | Install JavaScript dependencies |
| uv, Poetry, Pipenv | Install Python environments |
| Bundler | Install into vendor/bundle |
| Composer | Install into vendor |
| Go | go mod download |
| Cargo | cargo check, or your dependencyBuildCommand |
Dependency trees and build caches aren't copied between worktrees. Setup can
take time and needs the relevant tools and remote access. Configured local
files are copied first; afterCreate hooks run after setup succeeds.
To skip installation once:
gji new feature/search --no-install
gji pr 1234 --no-install
To disable it for a repository, put this in .gji.json:
{
"dependencyBootstrap": "off"
}
Use gji new feature/search --dry-run to inspect the creation plan. JSON and
headless commands use the same dependency setup unless disabled. If setup
fails, use the reported worktree path to recover rather than creating the task
again; see troubleshooting.
Choose a worktree directory
The default is ../worktrees/<repo>/<branch>. For a repository that needs a
different base directory, set worktreePath in its .gji.json or global
per-repo settings:
{
"worktreePath": "~/worktrees/my-repo"
}
Branches are placed under that base: feature/search becomes
~/worktrees/my-repo/feature/search. Use an absolute path or a ~/ path;
relative values are ignored with a warning. This setting controls future
creation, not the location of existing worktrees.
Use a different sync target
{
"syncRemote": "upstream",
"syncDefaultBranch": "main"
}
These control the target used by gji sync and the remote default branch used
by gji new --branch-only. See sync and cleanup.
Keep personal per-repo settings out of Git
In ~/.config/gji/config.json:
{
"repos": {
"/home/me/code/my-repo": {
"editor": "zed",
"syncFiles": [".env.local"],
"hooks": {
"afterCreate": ["pnpm", "run", "generate"]
}
}
}
}
Use an absolute path for the repository entry. Only the named repository gets those overrides.
Key reference
| Key | Purpose |
|---|---|
branchPrefix | Prefix for new branch names, such as feature/ |
editor | Default editor CLI for open and new --open |
worktreePath | Base directory for new worktrees; absolute or ~/ path |
syncRemote | Remote used for sync |
syncDefaultBranch | Default branch used as the sync target |
syncFiles | Files copied from the main worktree on creation |
dependencyBootstrap | Set to off to disable automatic dependency setup |
dependencyBuildCommand | Optional Cargo setup command; defaults to cargo check |
shellIntegration | Saved shell setup choice from the wizard |
installSaveTarget | Whether setup wizard settings are saved locally or globally |
hooks | Lifecycle commands for creation, entry, switching, and removal |
repos | Per-repository overrides in global configuration |