---
docgen:
  source: npm/scripts/lib/worktree.mjs
  crc: ffcdbca5
---

# worktree.mjs

## Огляд

Файл містить детерміновану логіку для обробки гілок у `worktree-tool`, забезпечуючи безпечне перетворення імен гілок та створення описових файлів для `worktree`. Він використовується для генерації структури `.worktrees/` та ідентифікації неактивних описових файлів, що необхідно для операцій з видаленням. Це ключовий компонент для забезпечення консистентності та зручності роботи з `worktree-tool` безпосередньо з файловою системою.

## Поведінка

sanitizeBranch: Перетворює ім’я git-гілки на безпечне ім’я каталогу/файла для `.worktrees/`, замінюючи небезпечні символи на дефіс.
firstFreeBranch: Знаходить першу вільну назву гілки, починаючи з заданої, і повертає її.
worktreePaths: Створює абсолютні шляхи до checkout і файла-опису для заданої гілки.
buildDescription: Генерує markdown-вміст файла-опису `.worktrees/<name>.md` на основі наданих параметрів.
buildDirtyNotice: Створює повідомлення про незакомічені зміни основного дерева, якщо їх є, обмежуючи кількість відображених файлів.
findOrphanDescFiles: Знаходить `.md`-описи, які не мають відповідного зареєстрованого worktree-checkout.

## Публічний API

- sanitizeBranch — Перетворює ім'я гілки на безпечне ім'я для каталогу/файлу.
- firstFreeBranch — Знаходить першу вільну назву гілки, використовуючи суфікси `base`, `base2`, `base3` тощо.
- worktreePaths — Визначає шляхи для checkout гілки та файлу опису.
- buildDescription — Генерує текст опису для файлу опису worktree.
- buildDirtyNotice — Виводить повідомлення про незакомічені зміни, які не включені у worktree.
- findOrphanDescFiles — Знаходить `.md`-описи, що не мають відповідного worktree-checkout.

## Гарантії поведінки

- `sanitizeBranch` повертає строку, безпечну для використання в шляхах файлової системи.
- `sanitizeBranch` не змінює вхідну строку.
- `worktreePaths` повертає масив з двох строк, що представляють шлях до checkout та файлу опису.
- `worktreePaths` гарантує, що обидва шляхи є дійсними.
- `buildDescription` повертає строку, що відповідає конвенції `worktree.mdc`.
- `buildDescription` не змінює вхідну строку.
- `findOrphanDescFiles` повертає масив з рядків, що представляють шляхи до файлів опису.
- `findOrphanDescFiles` гарантує, що всі рядки в масиві є дійсними шляхами файлів.
- Функції не викликають жодних побічних ефектів, що впливають на стан файлової системи.
- Функції не взаємодіють з Git або будь-якими іншими системами контролю версій.
- Результат роботи функцій не залежить від будь-яких зовнішніх факторів.
- Функції не використовують жодного кешу.
