GitUM
GitUm (Git Upstream Manager) — средство для разработки параллельно внешнему апстриму и синхронизации с ним.
Эта страница описывает gitum 2 (сейчас версия 2.1). Старый gitum 1 с ветками upstream/rebased/mainline/patches и командами create/merge/update больше не поддерживается, а его репозитории не переводятся на новый формат.
Сайт проекта с руководством: https://gitum.ru
Общее описание gitum
Представим, что есть проект с публичным git-репозиторием. Иногда вы передаёте в него свои коммиты, и их включают в общее дерево. Но бывает, что у вас много изменений, которые по каким-то причинам не приняты или ещё не отправлены. Тогда вы держите свой репозиторий со своими добавлениями.
Как обновлять его до новой версии апстрима?
- merge: ваши изменения уходят глубоко в историю и постепенно размазываются по merge-коммитам из-за конфликтов, а «свои» коммиты теряются среди тысяч коммитов апстрима;
- rebase: ваши изменения всегда лежат поверх кода апстрима — это наглядно и удобно, но теряется история изменений, и переписанной веткой нельзя безопасно делиться.
Хочется получить всё сразу:
- прямую историю без merge;
- все свои изменения сверху;
- историю того, как эти изменения менялись;
- целостность коммитов-патчей;
- возможность работать с каждым коммитом отдельно;
- историю, пригодную для git bisect.
gitum этого и добивается. Кроме того, в любой момент видно, где каждое ваше изменение находится относительно апстрима: только у нас, отправлено, принято (как есть или с правками), исправлено апстримом иначе, только для дистрибутива.
Это полезно для форков с сотнями своих патчей (например, wine-rebased), для пакетов дистрибутивов, обросших патчами, и для серий изменений, которые ждут приёма в апстрим.
Основные идеи
- Слои. Ваши изменения живут в обычных git-ветках, сложенных стопкой поверх апстрима, например winehq → rebased (wine-staging) → rebased-basealt → rebased-etersoft. Работаете с ними обычным git.
- Синхронизация одним проходом. gitum sync переносит весь стек на новый релиз апстрима сразу.
- Работа идёт в приватном рабочем дереве, а все ваши ветки двигаются одним атомарным шагом в конце.
- Конфликт останавливает прогон, ничего не меняя; вы разрешаете его и продолжаете.
- Учёт каждого изменения. Каждое изменение классифицируется: применилось чисто; разрешено (и кем: rerere, ваши правила, агент, человек); уже есть в апстриме; выброшено как бэкпорт; выброшено по известной судьбе; схлопнуто как пара «патч + revert».
- Журнал. Ветка gitum/journal только дописывается: по коммиту на каждое опубликованное состояние.
- В ней базы и вершины слоёв, идентификаторы и судьбы изменений, серии, отчёты синхронизаций и общий rerere-кеш.
- Ветки слоёв переписываются, а журнал и ветки истории gitum/history/СЛОЙ только растут. Поэтому ими можно безопасно делиться (без force-push), а git log -p и git bisect работают между вашими состояниями.
- Любое прежнее состояние можно вернуть командой gitum restore; возврат записывается как новое состояние.
- Идентичность и судьба изменения. gitum прослеживает изменение через все ребейзы, не переписывая коммиты. Судьба бывает: только наше, отправлено (MR), принято как такой-то коммит, принято с правками, исправлено иначе, только для дистрибутива, бэкпорт, отключено.
- Серии. Серия — именованный набор изменений в своей ветке, с зависимостями, багами в трекерах, merge request'ами, текстом MR с картинками и состоянием. Журнал хранит серии в раскладке wine-staging (patches/СЕРИЯ/definition и *.patch).
Как это устроено
Стек слоёв до и после синхронизации:
до: после gitum sync --next-release: rebased-etersoft 156 патчей rebased-etersoft перенесён rebased-basealt 15 патчей rebased-basealt перенесён rebased wine-staging rebased собран из wine-staging v11.20 winehq wine-11.19 winehq wine-11.20
Слой переносится только после успешного переноса слоя под ним. Пока весь стек не готов, ни одна ваша ветка не меняется.
Что происходит с каждым изменением при sync:
| Проверка | Результат |
|---|---|
| пара «патч + Revert патч» (annihilate-reverts) | annihilated — обе выброшены |
| судьба велит выбросить (принято, исправлено иначе, отключено) | dropped-marked |
| коммит из Origin: уже в новой базе | dropped-backport |
| такой же патч (patch-id) уже в апстриме | dropped-upstream |
| cherry-pick чисто | picked |
| после cherry-pick ничего не осталось | emptied — вероятно, принято с правками |
| конфликт: rerere → ваши правила → агент | resolved, записано, кто разрешил |
| никто не разрешил | остановка с кодом 2: человек разрешает, gitum continue или gitum skip |
Результаты резолверов, которым вы ещё не доверяете (например, агента), сначала уходят на ревью в ветки candidate/*; после проверки — gitum accept (или gitum reject). Ручное разрешение человеком считается доверенным.
Что переписывается, а что только растёт:
| Ветки | Поведение |
|---|---|
| ветки слоёв (rebased, rebased-basealt, rebased-etersoft) | переписываются при каждом sync, публикуются с lease |
| gitum/journal | коммит на каждое состояние: gitum.toml, слои, изменения, серии, отчёты, rr-cache; публикуется без force |
| gitum/history/СЛОЙ | коммит на каждое состояние с деревом слоя: для git log -p и bisect; публикуется без force |
Коммиты, которые коллега тем временем запушил в ветку слоя, при публикации встают сверху. Журналы двух сессий сливаются при gitum pull, если те меняли разные серии или изменения.
Установка
Требуются Python 3.11 или новее и git 2.45 или новее. Других зависимостей нет.
В ALT Linux:
epm install gitum
Пакет собирается из gitum.spec с помощью gear, в %check выполняются все тесты. Из исходников:
pip install ./gitum
Быстрый старт
cd wine-rebased
gitum init --upstream winehq=winehq/master --release-tags 'wine-*' \
--layer rebased=rebased:winehq \
--layer basealt=rebased-basealt:rebased \
--layer etersoft=rebased-etersoft:basealt
gitum status
gitum sync --next-release # следующий тег wine-X.Y, все слои
# при конфликте: исправить файлы в указанном рабочем дереве, git add, затем
gitum continue # или gitum skip / gitum abort
gitum publish # опубликовать слои, историю и журнал
gitum init берёт базу каждого слоя из тега ВЕТКА-START, вершины родительского слоя или общей базы с апстримом. Слои необязательны: для работы только с сериями достаточно апстримов.
Конфигурация
Конфигурация — файл gitum.toml в журнале. Посмотреть: gitum config show; заменить: gitum config load ФАЙЛ. Неизвестные ключи (опечатки, устаревшие настройки) не принимаются.
version = 2
[upstream.winehq]
remote = "winehq"
ref = "winehq/master"
release-tags = "wine-*"
[layer.rebased] # собирается из wine-staging, а не переносится
base = "upstream:winehq"
branch = "rebased"
generator = "staging"
staging-repo = "../wine-staging"
staging-ref = "v{version}"
post-command = "autoreconf -f && tools/make_requests"
[layer.basealt]
base = "layer:rebased"
branch = "rebased-basealt"
compat-start-tag = "rebased-basealt-START"
[layer.etersoft]
base = "layer:basealt"
branch = "rebased-etersoft"
annihilate-reverts = true
[resolve]
chain = ["rerere", "rules", "agent"]
rules = "tools/conflict-resolve.py"
agent = "tools/conflict-agent.sh"
review-unless = ["rerere"] # прочие — через candidate/*; человеку (manual) доверие всегда
[publish]
remote = "origin"
check = "./build.sh" # должна пройти до того, как двинутся ветки
[series]
subject-lint = '^[a-z0-9_./-]+: [A-Z].*\.$'
pr-forge = "winehq"
internal-mr-forge = "eterfund"
bug-tracker = "etersoft" # голый номер бага относится к нему
fixes-tracker = "winehq" # его баги — строки Fixes: в definition
[forge.winehq]
type = "gitlab"
url = "https://gitlab.winehq.org"
[forge.eterfund]
type = "gitlab"
url = "https://gitlab.eterfund.ru"
mr-url = "{url}/{project}/merge_requests/{n}"
[tracker.etersoft]
url = "https://bugs.etersoft.ru/show_bug.cgi?id={n}"
[tracker.winehq]
url = "https://bugs.winehq.org/show_bug.cgi?id={n}"
[hooks] # получают JSON-события на stdin
change = "tools/notify-bugs.py"
run = "tools/notify-chat.sh"
publish = "tools/set-version-branches.sh"
series = "tools/comment-in-bugs.py" # серия сменила состояние
Параметры апстрима:
- rewritten = true — апстрим пересоздаётся, а не продолжается (как ветка, собранная patchinstall);
- prefix = "third-party/lib" — апстрим вложен в ваше дерево (vendored).
Команды
Все команды принимают --json и --repo ПУТЬ (в любом месте командной строки) и никогда ничего не спрашивают интерактивно. Коды возврата: 0 — успех, 1 — ошибка (в том числе ошибка в параметрах), 2 — нужен человек (конфликт, ревью, разошедшаяся история), 10 — что-то обновлено (с --detailed-exitcode), 75 — репозиторий занят. Опции, которые без другой опции ничего не значат, отвергаются, а не игнорируются.
| Команда | Что делает |
|---|---|
| init | Создать журнал из существующих веток. |
| status [--changes [--all]] [--series [--variants] [--bug Б]] | Апстримы, слои, незавершённые операции, блокировки; таблица «изменение → судьба → действие»; серии деревом по зависимостям. |
| sync [--to REF | --next-release] [--step] [--candidate auto|always|never] [--publish] [--find-culprit] [--allow-rewrite] | Перенести стек на новый апстрим. --step — по одному коммиту апстрима (для bisect), --find-culprit — найти коммит апстрима, сломавший патч. |
| continue, skip, abort | Продолжить, выбросить конфликтующее изменение или отменить остановленную (или прерванную) операцию. |
| accept [--publish], reject | Опубликовать или выбросить результат, ждущий ревью в candidate/*. |
| save [СЛОЙ...] [-m СООБЩЕНИЕ] | Записать работу, сделанную в ветках слоёв обычным git. |
| restore СОСТОЯНИЕ | Вернуть весь стек (ветки, базы, теги START, точки синхронизации) к прежнему состоянию журнала из gitum log. Возврат — новое состояние, ничего не теряется. |
| publish, pull | Обмен состоянием через общий remote. |
| change list, change show ID, change set ID КЛЮЧ=ЗНАЧЕНИЕ..., change confirm ID [SHA] | Изменения и их судьбы, например gitum change set ID fate=distro-only reason="..."; confirm подтверждает подозрительное совпадение с апстримом. |
| check-upstream [layer:X|series:Y] [--since REF] [--apply] | Найти наши изменения в апстриме: по patch-id, затем по сходству заголовка и диффа. «Принято с правками» засчитывается, только если содержимое подтверждено (наше изменение поверх апстрима ничего не меняет). |
| series add|save|list|show|set|remove|checkout|claim|release|export-json|import-json | Серии изменений. Состояния: draft → review (внутреннее ревью) → queued → sent → approved → merged, rejected или superseded. claim отмечает, что серией занимается сессия (GITUM_SESSION). Если ветка серии стоит на апстриме новее локального ref, gitum предупреждает и просит сделать fetch. |
| mr set|import|render|record | Текст merge request серии с картинками: внутренняя часть для ревью не уходит в апстрим; import забирает публичный MR (например, ещё не принятый в gitlab.winehq); render ставит заглушки вместо картинок, а record запоминает адреса картинок, загруженных тем, кто открывает MR. gitum сам ничего не загружает и не работает с токенами. |
| bugs [ТРЕКЕР:N] [--format md] | Индекс багов: баг (ссылкой) → серии → состояние и версия → MR → релиз. Баги серии записываются как etersoft:19979, winehq:60741; series list --bug и status --series --bug показывают серии одного бага. |
| port СЕРИЯ --onto БАЗА, variants СЕРИЯ | Серия на другой базе (например, на слое etersoft) и чем её варианты отличаются. |
| queue [list [--format md]], queue next, queue add СЕРИЯ, queue pause, queue resume | Очереди отправки в апстрим: по одной серии, пока её не одобрят или не примут; сначала зависимости. Генерирует UPSTREAM-QUEUE.md с настраиваемыми разделами и колонками. |
| prepare СЕРИЯ [--push ФОРК] | Серия в виде для апстрима: свежая база, новые даты, без Co-Authored-By, проверка заголовков, range-diff с сохранённой серией. Merge request открывает человек. |
| backport SHA|URL --into СЛОЙ | Взять коммит апстрима с Origin:; он выбрасывается сам, когда база его содержит. |
| branches [--remote ФОРК] [--prune] | Ветки серий; устаревшие после merge. |
| forge refresh, forge import-json, forge export-json | Состояния публичных merge request'ов из GitHub, GitLab или Forgejo (без токенов) либо в виде JSON от ваших скриптов. |
| export ЧТО --format quilt|spec|staging --dir КАТАЛОГ, import ИСТОЧНИК [--format ...] | Наборы патчей: spec-файлы RPM (строки Patch между «# BEGIN gitum patches» и «# END gitum patches») и quilt для слоя или серии; каталоги wine-staging для серий (export series пишет все). --dep3 записывает судьбу изменений в патчи полями DEP-3, import читает их обратно; --verify проверяет, что патчи в точности дают слой; --clean удаляет только патчи, записанные gitum. |
| log, diff, report [--format html] | История журнала, изменения или серии; range-diff между состояниями; отчёт прогона. |
| mirror ИМЯ | Общее зеркало апстрима в ~/.cache/gitum вместо разовых клонов. |
Сценарии
Робот: обновление форка на каждый новый релиз
Робот по cron выполняет
gitum sync --next-release --candidate auto --publish
- Слой staging пересобирается из wine-staging нужной версии; остальные слои переносятся.
- Конфликты, которые узнал rerere, разрешаются сами. Разрешения агента уходят на ревью в candidate/* и публикуются после gitum accept.
- Неразрешённый конфликт даёт код 2: человек разрешает его в приватном дереве и запускает gitum continue.
- Хуки получают JSON-события: по каждому изменённому или выброшенному патчу (для отчётов в баги), о смене состояния серии и о публикации (тег, версия, старые и новые вершины слоёв).
На wine-rebased gitum воспроизвёл результат прежнего робота: слой staging для 11.20 совпал с rebased-11.20, а все 158 патчей etersoft при переносе на 11.21 совпали с результатом робота.
Серия изменений на пути в апстрим
git checkout -b series/ntdll-fix winehq/master # работа над серией gitum series add ntdll-fix --base upstream:winehq gitum series set ntdll-fix bugs=19979,winehq:60741 gitum port ntdll-fix --onto layer:etersoft # вариант для наших сборок gitum mr set ntdll-fix mr.md # текст MR и его картинки gitum queue add ntdll-fix gitum queue next # что отправлять следующим gitum prepare ntdll-fix --push fork # ветка в форке на свежем master gitum mr render ntdll-fix --forge winehq # текст для MR в апстрим gitum series set ntdll-fix state=sent pr=wine/wine!12345 gitum forge refresh # одобрено, принято gitum check-upstream series:ntdll-fix --apply # подтвердить принятие по содержимому
Когда серия принята, её изменения выбрасываются из слоёв при следующем sync, а очередь переходит к следующей серии.
Пакет дистрибутива
Изменения пакета ведутся коммитами в слое поверх настоящей истории апстрима:
gitum export layer:pkg --format spec --dir ГИР-РЕПО --spec пакет.spec --dep3 --verify
пишет патчи с полями DEP-3 (Forwarded, Applied-Upstream, Origin, Bug), обновляет строки Patch в spec-файле и проверяет, что патчи в точности дают слой, а
gitum import пакет.spec --into pkg
забирает существующие патчи пакета в слой (судьбы берутся из полей DEP-3).
Команды, которые запускает gitum
gitum запускает ваши команды для разрешения конфликтов, проверок, генерируемых слоёв и хуков. Все они получают окружение GITUM_*: GITUM_REPO, GITUM_WORKTREE, GITUM_LAYER, GITUM_RUN, GITUM_TARGET_TAG, GITUM_VERSION (wine-11.20 → 11.20), GITUM_LOCK_FILE, GITUM_LOCK_HELD и другие.
Блокировка — flock на $GIT_COMMON_DIR/gitum/lock, в файле JSON владельца. Команды, запущенные gitum, получают GITUM_LOCK_HELD, и запущенный из них gitum не берёт блокировку повторно. Подробная таблица — в руководстве: https://gitum.ru/manual/
Надёжность
gitum можно прервать в любой момент (kill, нехватка памяти, отключение питания), и ничего не потеряется и не останется сделанным наполовину:
- ваши ветки двигаются только в конце, одной атомарной транзакцией, или не двигаются вовсе;
- каждый шаг sync записывается до выполнения: после падения gitum continue возвращается к началу прерванного шага и продолжает, gitum abort отменяет операцию;
- следующая команда gitum доделывает успевшую произойти фиксацию или откатывает не произошедшую и убирает брошенные приватные деревья;
- чистое рабочее дерево, в котором открыта переносимая ветка, следует за ней, а при локальных изменениях операция останавливается.
Тесты убивают gitum во многих точках и проверяют, что gitum continue приходит ровно к результату непрерванного прогона.
Исходный код
Руководство и устройство с принятыми решениями и сравнением с похожими решениями (git-debrebase, dgit, gbp pq, rdopkg, StGit, b4): https://gitum.ru/manual/ и https://gitum.ru/design/ (в репозитории — docs/manual.ru.md и docs/design.ru.md).
Ссылки
- Файл:Презентация Gitum на Протве 2012.odp — доклад о gitum 1
- https://habr.com/ru/sandbox/60279/ — статья о gitum 1 (2013)
Почему не merge
- http://gitready.com/advanced/2009/02/11/pull-with-rebase.html
- http://randyfay.com/node/103 : git config --global branch.autosetuprebase always
- http://gitevangelism.blogspot.com/2011/02/git-push-force-and-merging-without.html
- http://libav.org/git-howto.html (Проект libav: «merge commits are forbidden»)
- http://www.kerrybuckley.org/2008/06/18/avoiding-merge-commits-in-git/
- http://yannesposito.com/Scratch/en/blog/2010-03-23-Encapsulate-git/
- Git Rebase: руководство по использованию
Обратная точка зрения: