Перейти к содержанию

GitUM

Материал из Etersoft wiki

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).

Ссылки

Почему не merge

Обратная точка зрения: