Skip to main content

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​

HookEventTriggered byRuns in
afterBranchCreateA new branch was created.gji new when it creates a branch, with or without --branch-onlyThe worktree that holds the new branch
afterCreateA linked worktree was created and bootstrapped.gji new (except --branch-only), gji pr, and gji go when it creates a worktree for an existing branchThe new worktree
afterEnterAn existing worktree was entered.gji go and gji backThe entered worktree
afterSwitchThe current worktree switched to another branch in place.gji new --branch-onlyThe current worktree
beforeRemoveA linked worktree is about to be removed.gji done and gji clean, once per worktree it attempts to removeThe 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, then afterBranchCreate.
  • gji new --branch-only <branch>: afterBranchCreate, then afterSwitch.

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_BRANCH
  • GJI_PATH
  • GJI_REPO
  • GJI_SLOT (for worktrees created by gji; the main worktree uses slot 0 once 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:

  1. global config
  2. per-repo global overrides
  3. 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}}"]
}
}