Note

Цей документ містить практичний довідник з використання Fossil SCM, вирішення конфліктів при злитті бінарних файлів, управління гілками та налаштування локальної та серверної embedded-документації.

1. Основні CLI-команди для щоденного флоу

Перевірка змінених файлів:
```
fossil status       # Або коротка форма: fossil stat
```
Показує поточний стан робочої копії (змінені, додані, видалені або невідстежувані файли).

Перегляд доданих/невідстежуваних файлів:

fossil extras       # Список локальних файлів, які ще не додані до VCS
fossil changeset    # Зміни у фіксованих ревізіях

Перегляд різниці (diffs):

fossil diff         # Порівняння робочої копії з останнім комітом
fossil gdiff        # Відкрити diff у графічній утиліті (якщо налаштовано)

Фіксація змін та Push:
```
fossil commit -m "Comment"   # Або коротка форма: fossil ci
```
Примітка (Autosync): За замовчуванням у Fossil увімкнено режим Autosync. Під час виконання fossil commit зміни автоматично відправляються (push) на сервер. Якщо Autosync вимкнено, відправка виконується вручну:
```
fossil push
```

Запуск веб-інтерфейсу:

fossil ui           # Відкриває локальний веб-сервер у браузері
fossil server       # Запуск веб-сервера без автоматичного відкриття браузера

2. Гілки (Branching) та Злиття (Merging)

У Fossil гілка — це мітка (tag), прив'язана до коміту на DAG-графі.

Створення та перемикання гілок

Створити нову гілку та перейти на неї:
```
fossil branch new <branch-name> <target-commit/trunk>
```
Створити коміт безпосередньо в нову гілку:
```
fossil commit --branch <branch-name> -m "Commit text"
```

Переключитися між гілками:

fossil checkout <branch-name>    # Або: fossil co <branch-name>

Список усіх гілок:
```
fossil branch list
```

Злиття (Merge)

Перейти у цільову гілку (наприклад, trunk):
```
fossil checkout trunk
```
Виконати злиття з іншою гілкою:
```
fossil merge <branch-name>
```
(Команда застосовує зміни до робочої копії, але НЕ робить автоматичний коміт).
Закомітити результат злиття:
```
fossil commit -m "Merged <branch-name> into trunk"
```

Закриття гілки після злиття

Щоб закрити гілку (щоб вона не показувалася як активна в графіку):

fossil commit --close -m "Closing feature branch"

3. Злиття бінарних файлів (Binary Merge Issues)

Якщо при злитті виникає помилка:

MERGE public/android-chrome-192x192.png
***** Cannot merge binary file public/android-chrome-192x192.png

Варіанти вирішення:

Залишити версію з поточної гілки:
```
fossil revert public/android-chrome-192x192.png
```

Взяти версію з гілки, яку зливаєте:

fossil artifact <branch-name>:public/android-chrome-192x192.png public/android-chrome-192x192.png

Автоматичний вибір версії через gmerge-command:
- Завжди вибирати свою версію:
```
fossil setting gmerge "cp %b %output"
```
- Завжди вибирати версію з гілки, що вливається:
```
fossil setting gmerge "cp %other %output"
```

4. Embedded Documentation & Робота з Markdown без постійних комітів

Чому локальні `.md` файли в UI показують старі версії?

Fossil зберігає все у базі SQLite. Команда fossil ui за замовчуванням читає файли документації з репозиторію (з коміту), а не з вашої робочої файлової системи (Uncommitted Changes).

Як читати локальні незакомічені `.md` файли напряму з диска:

Використовуйте спеціальний псевдонім ревізії ckout (робоча копія):

URL у браузері: http://localhost:8081/doc/ckout/docs/index.md

Важливо: Прапорець --localdoc не є параметром CLI. Для гарантованого зчитування файлів з диска запускайте сервер з прапорцем --localauth:
fossil ui --localauth

5. Налаштування головного меню (`mainmenu`) та локальні settings

У Fossil налаштування (fossil settings) не передаються через коміти (Unversioned / Local database settings). Це дозволяє мати різну конфігурацію меню на локальній машині та на сервері.

Структура елемента `mainmenu`

Формат рядка:

Label /URL Capability Class

Розшифровка 3-го параметра (Capability / Права доступу):

* — Доступно для всіх (включно з гостями/анонімами).
o — Потрібні права на перегляд коду/файлів (Read/Check-out).
{o r j} — Логічне OR: наявність хоча б одного з прав (o=Read, r=Tickets, j=Wiki).
{@2 3 4 5 6} — Права доступу до Форуму.
C — Доступ до Чату.
{a s} — Адміністративні права (a=Admin, s=Setup).
L — Лише для залогінених користувачів.
!L — Лише для НЕзалогінених відвідувачів (наприклад, кнопка Login).

Налаштування для локального середовища

На локальній машині вказуємо шлях до робочої копії (ckout):

fossil settings mainmenu '
  Home      /home         *              {}
  Doc       /doc/ckout/docs/index.md  o   {}
  Timeline  /timeline     {o r j}        {}
  Files     /dir?ci=tip   oh             desktoponly
  Branches  /brlist       o              wideonly
  Tags      /taglist      o              wideonly
  Forum     /forum        {@2 3 4 5 6}   wideonly
  Chat      /chat         C              wideonly
  Tickets   /ticket       r              wideonly
  Wiki      /wiki         j              wideonly
  Admin     /setup        {a s}          desktoponly
  Logout    /logout       L              wideonly
  Login     /login        !L             wideonly
'

Налаштування для віддаленого сервера

На сервері вказуємо шлях до конкретної гілки (наприклад, DEV):

fossil settings mainmenu '
  Home      /home         *              {}
  Doc       /doc/DEV/docs/index.md    o   {}
  Timeline  /timeline     {o r j}        {}
  Files     /dir?ci=tip   oh             desktoponly
  Branches  /brlist       o              wideonly
  Tags      /taglist      o              wideonly
  Forum     /forum        {@2 3 4 5 6}   wideonly
  Chat      /chat         C              wideonly
  Tickets   /ticket       r              wideonly
  Wiki      /wiki         j              wideonly
  Admin     /setup        {a s}          desktoponly
  Logout    /logout       L              wideonly
  Login     /login        !L             wideonly
'

Завдяки тому, що fossil settings зберігаються локально в базі кожного вузла, виконання fossil commit та fossil push не перезапише конфігурацію меню на сервері.

Fossil SCM Workflow & Documentation Cheat Sheet