Правила репозиторію (.gitcito.json)

Кожен проєкт носить правила, яких із коду не вивести. Ніколи не пушити прямо в release/*. Області комітів — api, web та infra, і жодних інших. Потрібен Node 20, витягнуті підмодулі та .env, скопійований з .env.example, перш ніж щось запуститься. Такі правила живуть у README, який ніхто не перечитує, у падінні CI або в голові того, хто тут найдовше.

.gitcito.json — місце, де репозиторій їх записує, щоб інструмент міг на них спиратися. Файл лежить у корені репозиторію, версіюється як будь-який інший і тому подорожує разом із клоном: усі, хто відкриває проєкт, отримують ті самі правила, а новачок отримує їх у перший день, а не на першому відхиленому push.

Файл цілком необов'язковий. Репозиторій без нього поводиться так само, як завжди.

Писати його вручну не обов'язково: чату репозиторію передають схему цього файла, тож додай посилання на задачі виду JIRA-1234 чи захисти release-гілки повертається як файлова дія, яку можна переглянути.

Де його редагувати

Шестірня поруч з інструментами панелі → Config. Цей редактор пише файл у робоче дерево; більше він ніде не зберігається, тож закомітьте його, щоб поділитися правилами з командою.

Якщо файлу ще немає, Прочитати репозиторій запропонує його з того, що вже є: .nvmrc чи engines.node, .gitmodules, filter=lfs у .gitattributes, .env.example без сусіднього .env, гілки, які ви вже захищаєте локально, і області з останніх 500 заголовків комітів. Нічого не записується, доки ви не збережете. У терміналі те саме робить gitcito config init (див. командний рядок).

Що може бути у файлі

{
  "version": 1,
  "protect": ["main", "release/*"],
  "links": {
    "tickets": [
      { "match": "\\b[A-Z][A-Z0-9]+-\\d+\\b", "url": "https://tracker.example.com/browse/$0", "label": "Jira" }
    ]
  },
  "commit": {
    "scopes": ["api", "web", "infra"],
    "ticketFromBranch": true,
    "trailers": ["Refs: {ticket}"]
  },
  "requires": {
    "node": ">=20",
    "hooksPath": ".husky",
    "submodules": true,
    "lfs": true,
    "files": [{ "path": ".env", "from": ".env.example", "why": "Базова адреса API та токен для розробки" }]
  },
  "checklist": {
    "push": ["Прогнати інтеграційні тести на staging"]
  }
}

Доктор

requires — та частина, що відповідає на «я склонував, і воно не запускається». Gitcito перевіряє її при відкритті репозиторію й показує чип зі стетоскопом у рядку стану, коли щось не так. Клік відкриває вкладку Config на рядках доктора; Перевірити знову запускає їх ще раз.

Два свідомі обмеження. Попередження ніколи не означає «зламано» — воно означає, що доктор не зміг чогось визначити (нечитабельна специфікація Node проходить, замість вигадувати помилку, з якою ви нічого не зробите), і попередження не валять gitcito doctor у CI. І полагодження ніколи не походить із файлу: набір вище — це весь набір, закритий на етапі компіляції. Конфігурація передає йому значення — шлях для копіювання, значення для core.hooksPath — і ніколи команду.

Копіювання ніколи не перезаписує: відсутність файлу — саме та причина, через яку цей рядок тут.

Коміти

Коли оголошено commit.scopes, кнопка області в композиторі пропонує цей список замість вільного поля — різниця між feat(renderer) і feat(rendererr). ticketFromBranch і trailers заповнюють механічні частини повідомлення, а links.tickets повертає ключам вигляд посилань усюди, де показано коміт.

Ті самі правила діють і поза вікном: gitcito commit-check читає цей файл, тож хук commit-msg і CI вимагають рівно того, що пропонує композитор. Див. командний рядок і коміти.

Список перед push

checklist.push показується як підтвердження перед першим push у сесії, по рядку на пункт. Це місце для того, що справді потребує судження — чи хтось попередив підтримку? — бо Gitcito ніколи не перевіряє це за вас. Це нагадування, а не бар'єри: прочитали й запушили або скасували. Показується раз на репозиторій за сесію, бо діалог при кожному push — це діалог, якого ніхто не читає.

Чому він не може вам зашкодити

Файл приходить разом із репозиторієм, тобто від того, хто репозиторій написав. Його вважають недовіреним вмістом, як і повідомлення коміту:

• Ніщо в ньому не виконується. Немає поля, що містить команду, а полагодження доктора — фіксований список.
• Він може лише додавати обмеження. protect об'єднується з вашим локальним списком: репозиторій може захистити більше, ніж обрали ви, але ніколи не відмовить вас щось захищати. Жодне поле не вимикає запобіжник.
• Шляхи не можуть вийти за репозиторій. Абсолютні шляхи, .., ~, літери дисків і все, що торкається .git, відхиляються — і перевіряються ще раз там, де рядок стає справжнім шляхом.
• Посилання мають бути http(s). Нічого іншого системному відкривачу адрес не передається.
• Усе має межу — довжина списків, рядків, шаблонів, — щоб ворожий репозиторій не вставив стіну тексту в діалог і тисячу чипів у панель.

Погане поле відкидається, а не руйнує все. Решта файлу далі діє, а відкинуте перелічено під заголовком Проігноровано Gitcito у вкладці Config із причиною. Єдиний виняток — невалідний JSON або невідома version: там нема чого рятувати.

Чого він свідомо не робить

• Ні команд, ні скриптів, ні хуків. Для цього є хуки, і це рішення, яке ви ухвалюєте для кожного клона.
• Ні правил на гілку, ні на людину. Один файл, один набір правил.
• Він не замінює CI. Список — це текст; доктор перевіряє середовище, а не вашу роботу.
• Він нічого не може послабити. Усі запобіжники Gitcito лишаються вашими.

Див. також: Налаштування репозиторію · Командний рядок · Коміти · Хуки та .gitignore