## Worktrees

Worktree workflow is intentionally **config-driven** so different developers can use different strategies without changing committed files.

### Resolved Configuration

- `worktrees.enabled`: `{{ worktree.enabled }}`
- `worktrees.strategy`: `{{ worktree.strategy }}`
- `worktrees.layout.dir_name`: `{{ worktree.layout_dir_name }}`
- `worktrees.default_branch`: `{{ worktree.default_branch }}`
- `worktrees.apply.integration_mode`: `{{ worktree.integration_mode }}`

### Config Files Consulted (Low -> High)

{% if loaded_from | length == 0 %}
- (none) Using defaults.
{% else %}
{% for p in loaded_from %}
- `{{ p }}`
{% endfor %}
{% endif %}

{% if worktree.ito_root %}
Recommended per-developer override file: `{{ worktree.ito_root }}/config.local.json` (gitignored)
{% else %}
Recommended per-developer override file: `{{ ito_dir_name }}/config.local.json` (gitignored)
{% endif %}

### Guidance

{% if not worktree.enabled %}
Worktrees are not enabled. Do NOT create git worktrees unless the user explicitly asks.

To enable worktrees for *this developer*, create/update {% if worktree.ito_root %}`{{ worktree.ito_root }}/config.local.json`{% else %}`{{ ito_dir_name }}/config.local.json`{% endif %}:

```json
{
  "worktrees": {
    "enabled": true,
    "strategy": "checkout_subdir",
    "default_branch": "main",
    "layout": { "dir_name": "ito-worktrees" },
    "apply": { "integration_mode": "commit_pr" }
  }
}
```
{% else %}
Use the commands below for the configured strategy.

Helpful path commands:

- `ito path project-root` (stable root shared across worktrees)
- `ito path worktree-root` (current working worktree root)
- `ito path worktrees-root` (configured worktrees root)

{% if worktree.strategy == "checkout_subdir" %}
#### Strategy: `checkout_subdir`

Worktrees live in a gitignored subdirectory inside the checkout.
{% if worktree.project_root %}
Project root: `{{ worktree.project_root }}`
{% endif %}
{% if worktree.worktree_root %}
Worktree root: `{{ worktree.worktree_root }}`
{% endif %}

```bash
BRANCH_NAME="<change-name>"
WORKTREE_ROOT="$(ito path worktree-root)"
WORKTREES_ROOT="$(ito path worktrees-root)"
mkdir -p "$WORKTREES_ROOT"

# Ensure the worktree directory is gitignored
GITIGNORE_PATH="$WORKTREE_ROOT/.gitignore"
LAYOUT_DIR_NAME='{{ worktree.layout_dir_name | replace("'", "'\"'\"'") }}'
WORKTREES_IGNORE="${LAYOUT_DIR_NAME%/}/"
grep -qxF "$WORKTREES_IGNORE" "$GITIGNORE_PATH" 2>/dev/null || printf '%s\n' "$WORKTREES_IGNORE" >> "$GITIGNORE_PATH"

git -C "$WORKTREE_ROOT" worktree add "$WORKTREES_ROOT/${BRANCH_NAME}" -b "${BRANCH_NAME}"
```
{% elif worktree.strategy == "checkout_siblings" %}
#### Strategy: `checkout_siblings`

Worktrees live in a sibling directory next to the checkout.
{% if worktree.project_root %}
Project root: `{{ worktree.project_root }}`
{% endif %}
{% if worktree.worktree_root %}
Worktree root: `{{ worktree.worktree_root }}`
{% endif %}

```bash
BRANCH_NAME="<change-name>"
WORKTREE_ROOT="$(ito path worktree-root)"
WORKTREES_ROOT="$(ito path worktrees-root)"
mkdir -p "$WORKTREES_ROOT"

git -C "$WORKTREE_ROOT" worktree add "$WORKTREES_ROOT/${BRANCH_NAME}" -b "${BRANCH_NAME}"
```
{% elif worktree.strategy == "bare_control_siblings" %}
#### Strategy: `bare_control_siblings`

This is a bare/control repo layout with worktrees as siblings.
{% if worktree.project_root %}
Bare repo root: `{{ worktree.project_root }}`
{% endif %}
{% if worktree.worktree_root %}
Worktree root: `{{ worktree.worktree_root }}`
{% endif %}

Run git worktree commands against the bare/control root.

```bash
BRANCH_NAME="<change-name>"
PROJECT_ROOT="$(ito path project-root)"
WORKTREES_ROOT="$(ito path worktrees-root)"
mkdir -p "$WORKTREES_ROOT"

git -C "$PROJECT_ROOT" worktree add "$WORKTREES_ROOT/${BRANCH_NAME}" -b "${BRANCH_NAME}"
```
{% endif %}

#### Integration

{% if worktree.integration_mode == "commit_pr" %}
Commit on the worktree branch, push, and open a PR into `{{ worktree.default_branch }}`.
{% elif worktree.integration_mode == "merge_parent" %}
Commit on the worktree branch, then merge into `{{ worktree.default_branch }}`.
{% endif %}

#### Cleanup

```bash
git worktree remove "<worktree-path>" 2>/dev/null || true
git branch -d "<change-name>" 2>/dev/null || true
git worktree prune
```
{% endif %}
