worktree-plus Configuration

Manage worktree-plus settings. All settings live in git config under the worktreeplus.* namespace (plugin-custom) plus one worktree.guessRemote (git-native). No env vars.

Settings

Key	Default	Scope guidance
worktreeplus.baseBranch	HEAD	Per-repo typical (different repos have different default branches)
worktreeplus.branchPrefix	worktree-	Global typical (personal naming convention); per-repo for team rules
worktreeplus.dirBase	.claude/worktrees	Per-repo typical
worktree.guessRemote	true (plugin override; git default is false)	Global typical

View current settings

Always start by showing what's active. Run:

git config --get-regexp '^worktreeplus\.|^worktree\.guessRemote'

If nothing prints, the user is on defaults. State that explicitly — don't leave them guessing.

For layered view (local vs global vs system):

git config --local  --get-regexp worktreeplus
git config --global --get-regexp worktreeplus

Change a setting

Ask scope before writing. "Just this repo" (--local, default) vs "all repos for me" (--global).

git config [--local|--global] worktreeplus.baseBranch develop
git config [--local|--global] worktreeplus.branchPrefix "feat-"
git config [--local|--global] worktreeplus.dirBase ".worktrees"
git config [--local|--global] worktree.guessRemote false

Writes take effect on the next EnterWorktree / claude -w. Existing worktrees are not affected.

Reset / unset

Destructive. Confirm with the user first before running — name exactly what will be removed.

Single key:

git config [--local|--global] --unset worktreeplus.baseBranch

All plugin settings at once:

git config [--local|--global] --remove-section worktreeplus

Value validation

Before writing, sanity-check the value:

• branchPrefix: literal — "feat-" produces feat-name, "feat" produces featname. If user says "use feat prefix" they almost certainly want the -. Ask.
• dirBase: no tilde expansion (~/foo stays literal). Relative paths resolve against the repo root. Trailing slash is stripped automatically. Empty value falls back to default.
• baseBranch: must be a resolvable ref. git rev-parse --verify <value> works? If not, warn.

Migration check

If the user mentions WORKTREE_BASE_BRANCH / WORKTREE_BRANCH_PREFIX env vars:

1. These were removed in v3.0.0. SessionStart migrated them to --global git config on first run.
2. Check migration ran and inspect its record:

   ls  "${CLAUDE_PLUGIN_DATA}/migrated-envvars"
   cat "${CLAUDE_PLUGIN_DATA}/migrated-envvars"   # shows migration version + timestamp
   

3. Verify current global config captured the old values:

   git config --global --get-regexp worktreeplus
   

4. Tell the user to remove the env vars from their shell profile — they're now dead weight.

If the flag file is missing but env vars are still set (shouldn't happen in normal flow), run the migration manually by re-triggering SessionStart (restart Claude Code).

Gotchas

• Changing dirBase does not move existing worktrees. New worktrees go to the new location; old ones stay at the old path. Both still appear in git worktree list and can be removed normally, but the mixed layout is confusing. Tell the user to finish/remove pending worktrees before changing dirBase.
• git config --remove-section errors if the section doesn't exist. Check first: git config --get-regexp '^worktreeplus\.' — if empty, skip remove.
• --global writes go to ~/.gitconfig. If the user wants truly project-scoped, use --local (writes to .git/config). Local overrides global.
• worktree.guessRemote=true is the plugin's non-default. Setting it explicitly to false disables auto-tracking of remote branches — user gets pure HEAD branch creation. Git's own default is false; the plugin flips it for better UX but respects explicit user config.
• branchPrefix is literal (no auto-separator). Different from the pre-v3 env var which inserted - automatically. The migration adds the - for you when converting, but fresh writes don't.
• Narrow allowed-tools scope. Only git config, git worktree list, git rev-parse, ls, and Read are pre-approved here. If you reach for another command (e.g., git worktree remove, file edits), the user will see a permission prompt — that's intentional. This skill is read/write on config only; actual worktree lifecycle belongs to the worktree-plus hooks.