Automate the setup you repeat
Use hooks for project commands that should run when you create, enter, or remove a worktree: code generation, local service setup, or project cleanup.
Supported dependency installation already runs automatically. Add an install hook only if your project needs setup the built-in adapters do not cover.
If you only need to copy gitignored local files such as .env.local into new worktrees, use gji sync-files instead of a custom hook. Hooks are best for commands that actually need to run.
Example
{
"hooks": {
"afterCreate": ["pnpm", "run", "generate"],
"afterEnter": ["printf", "switched to %s\n", "{{branch}}"],
"beforeRemove": "pnpm run cleanup"
}
}
Put this in .gji.json for the project, or in global per-repo settings for
your own workflow. Use commands that exist in your project.
Available hooks
| Hook | Event | Triggered by | Runs in |
|---|---|---|---|
afterBranchCreate | A new branch was created. | gji new when it creates a branch, with or without --branch-only | The worktree that holds the new branch |
afterCreate | A linked worktree was created and bootstrapped. | gji new (except --branch-only), gji pr, and gji go when it creates a worktree for an existing branch | The new worktree |
afterEnter | An existing worktree was entered. | gji go and gji back | The entered worktree |
afterSwitch | The current worktree switched to another branch in place. | gji new --branch-only | The current worktree |
beforeRemove | A linked worktree is about to be removed. | gji done and gji clean, once per worktree it attempts to remove | The worktree being removed |
Put project-specific setup in afterCreate: it is
the only hook that runs after gji bootstraps a new worktree directory.
afterBranchCreate and afterSwitch also run for --branch-only, where no
new directory exists, so keep them limited to branch-level work such as
recording a ticket or printing a reminder.
When one command triggers several events, hooks run in this order:
gji new <branch>:afterCreate, thenafterBranchCreate.gji new --branch-only <branch>:afterBranchCreate, thenafterSwitch.
gji new and gji pr do not run afterEnter after creating a worktree.
afterBranchCreate only runs for branches started from a base branch: gji new
skips it when it checks out a branch that already exists, and the local
branches that gji pr and gji go create from pull request or remote refs
only trigger afterCreate. gji go --json skips afterEnter so its output
stays machine-readable.
beforeRemove runs just before gji attempts the removal. If the removal then
fails, or you decline the prompt to force-remove a dirty worktree, the
worktree stays in place after the hook has already run.
In --json mode, hook stdout is discarded so the JSON output stays parseable.
Template values
Hooks receive these template variables:
{{branch}}{{path}}{{repo}}{{slot}}— stable worktree slot number.
The same values are also available as environment variables:
GJI_BRANCHGJI_PATHGJI_REPOGJI_SLOT(for worktrees created by gji; the main worktree uses slot0once gji has created a linked worktree)
Safer hook commands
Prefer argv-array hooks when you do not need shell features:
{
"hooks": {
"afterCreate": ["pnpm", "run", "generate"],
"afterEnter": ["printf", "switched to %s at %s\n", "{{branch}}", "{{path}}"]
}
}
Array hooks run without a shell. Each array item is passed as exactly one argument, so branch names and paths containing spaces or shell metacharacters are not re-parsed as shell syntax.
String hooks are still supported for shell features like &&, pipes, redirects, shell functions, and nvm use. Template values are interpolated before the shell parses the command, so avoid putting {{branch}}, {{path}}, or {{repo}} directly into shell strings.
For shell-string hooks, read the context from environment variables and double-quote each expansion:
{
"hooks": {
"afterCreate": "pnpm run generate && printf 'ready: %s\n' \"$GJI_PATH\""
}
}
Avoid unquoted template values in shell strings, such as echo {{branch}} or cd {{path}}.
Layering behavior
Hooks can come from:
- global config
- per-repo global overrides
- local
.gji.json
Different hook keys merge together. The same hook key is overridden by the highest-precedence layer.
That makes it possible to have a general default like afterEnter, while one repository overrides only afterCreate.
Manual execution
You can rerun any hook from the table above in the current worktree:
gji trigger-hook <hook> # for example: gji trigger-hook afterCreate
This reruns the configured hook, not the built-in dependency adapter. For a failed dependency install, run the project’s install command in that worktree; see troubleshooting.
Practical examples
Generate project files after dependency setup
{
"hooks": {
"afterCreate": ["pnpm", "run", "generate"]
}
}
Print context on entry
{
"hooks": {
"afterEnter": ["printf", "switched to %s at %s\n", "{{branch}}", "{{path}}"]
}
}