---
description: Конвенція git-worktree у цьому репо — створення, інвентаризація та прибирання через native CLI `mt worktree`.
globs:
alwaysApply: true
---

# Worktree-конвенція

Усі git-worktree створюй і прибирай через native CLI `mt worktree` — він кладе їх у
`.worktrees/` (gitignored, checkout `<name>/`), створює власну гілку `mt/<name>` і
зберігає опис у локальній Git-конфігурації цієї гілки.

## Розташування

```
.worktrees/
  feat-skill-meta/        ← checkout гілки mt/feat-skill-meta
```

`<name>` має бути пласким: слеш у похідній назві перетворюй на дефіс, наприклад
`feat/skill-meta` → `feat-skill-meta`. Git-гілка, яку створює CLI, завжди має префікс
`mt/`: `mt/feat-skill-meta`. Опис належить цій гілці (`branch.mt/feat-skill-meta.description`),
тому немає sidecar-файлів у `.worktrees/`.

## Налаштування редакторів

Worktree-каталоги — це вкладені копії всього дерева. Якщо редактор індексує їх,
пошук дає дублі, а file-watcher вантажить диск. Тому редактор має **виключити**
`.worktrees/` (а для Zed ще й приватний `.claude/worktrees/`) з пошуку та сканування.

Канон перевіряється **лише** якщо файл налаштувань уже є — проєктам без VS Code / Zed
нічого не нав'язується.

### VS Code

У `.vscode/settings.json` обовʼязково виключи `**/.worktrees/**` з пошуку і з дерева
файлів. `node_modules` додавати не треба — VS Code виключає його з пошуку дефолтно.

```json title=".vscode/settings.json"
{
  "search.exclude": {
    "**/.worktrees/**": true
  },
  "files.exclude": {
    "**/.worktrees/**": true
  }
}
```

Канон (subset — інші ключі дозволені): [settings.json.snippet.json](./vscode_settings/template/settings.json.snippet.json)

### Zed

Zed **замінює** масив `file_scan_exclusions` цілком (не зливає з дефолтами), тому в
`.zed/settings.json` перелічуй і дефолти Zed, і `**/.worktrees`, і `**/.claude/worktrees`.
Перевірка вимагає **всі** записи канону (бо інакше дефолти губляться).

```json title=".zed/settings.json"
{
  "file_scan_exclusions": [
    "**/.git",
    "**/.svn",
    "**/.hg",
    "**/.DS_Store",
    "**/Thumbs.db",
    "**/node_modules",
    "**/.worktrees",
    "**/.claude/worktrees"
  ]
}
```

Канон (усі елементи обовʼязкові, зайві дозволені): [settings.json.snippet.json](./zed_settings/template/settings.json.snippet.json)

`.zed/settings.json` без стабільної схеми в Schema Store — додай його до `.v8rignore` (як `.vscode/*`, див. **text.mdc**).

## Команди

- **Створити** (опис обовʼязковий): `mt worktree create <name> --description "<навіщо>"`
- **Від базової гілки/рефа**: `mt worktree create <name> --base <ref> --description "<навіщо>"`
- **Інвентаризація**: `mt worktree list` (людино-) або `mt worktree inventory` (JSON; містить `description`)
- **Прибрати**: `mt worktree remove <name>`; за наявності незакомічених змін — додай `--force`. Команда прибирає checkout і лише власну гілку `mt/<name>`.
- **Прибрати осиротілі Git-записи**: `mt worktree prune`

## Завершення гілки worktree

Коли робота у worktree завершена і її треба влити в базову гілку — **за замовчуванням пропонуй
squash-merge** (уся гілка одним комітом), а не fast-forward чи merge-комітом. Worktree — це одна
логічна задача, тож в історії базової гілки їй відповідає **один** коміт; проміжні TDD-коміти
(«додав парсер», «видалив auto.md» тощо) у базовій гілці не потрібні. Реліз і `CHANGELOG`
агрегуються за change-файлом, не за кількістю комітів, тож squash нічого не ламає.

```bash
git checkout <base> && git merge --squash <branch> && git commit
```

Якщо користувач явно просить зберегти поетапну історію — лише тоді fast-forward / merge-коміт.

## Заборони

- Не клади worktree в `.claude/worktrees/` — це приватна директорія харнесу Claude Code.
- Не клади worktree в батьківський каталог `../cursor-<name>` — ускладнює інвентаризацію.
- Не створюй worktree вручну (`git worktree add`) повз `mt worktree create` — інакше не буде branch description в інвентаризації та безпечного lifecycle.