Skip to main content

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​

LocationUse it for
~/.config/gji/config.jsonPersonal defaults across repositories
repos entries in that global filePersonal settings for one repository, including private local file names
.gji.json in a repositoryShared 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:

ProjectSetup
pnpm, Yarn, Bun, npmInstall JavaScript dependencies
uv, Poetry, PipenvInstall Python environments
BundlerInstall into vendor/bundle
ComposerInstall into vendor
Gogo mod download
Cargocargo 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​

KeyPurpose
branchPrefixPrefix for new branch names, such as feature/
editorDefault editor CLI for open and new --open
worktreePathBase directory for new worktrees; absolute or ~/ path
syncRemoteRemote used for sync
syncDefaultBranchDefault branch used as the sync target
syncFilesFiles copied from the main worktree on creation
dependencyBootstrapSet to off to disable automatic dependency setup
dependencyBuildCommandOptional Cargo setup command; defaults to cargo check
shellIntegrationSaved shell setup choice from the wizard
installSaveTargetWhether setup wizard settings are saved locally or globally
hooksLifecycle commands for creation, entry, switching, and removal
reposPer-repository overrides in global configuration