Использование рабочего процесса AGit

Forgejo поставляется с ограниченной поддержкой AGit-Flow, который был изначально представлен в Gitea версии 1.13.

Аналогично рабочему процессу Gerrit, этот подход позволяет отправлять изменения в репозитории, размещённые на экземплярах Forgejo, используя только команду git push, без необходимости создавать форки, ветки фич и затем использовать веб-интерфейс для создания Pull Request’а.

С помощью Push-опций (-o) и Refspec (идентификатор места назначения в Git) можно передать всю необходимую информацию для открытия Pull Request’а, такую как целевая ветка или заголовок Pull Request’а.

Создание Pull Request’ов

Для наглядности начнём с примеров.

Полный список параметров, а также информация об избежании дубликатов Pull Request’ов при ребейзе или изменении коммитов, будет приведён далее.

Примеры использования

Предположим, что вы клонировали репозиторий и создали новый коммит поверх ветки main. Pull Request, нацеленный на ветку main, с использованием текущей ветки можно создать так:

git push origin HEAD:refs/for/main -o topic="agit-typo-fixes"

Обратите внимание, что HEAD:refs/for/main — это Refspec. HEAD указывает на текущую ветку, но может быть заменён на любую "локальную ссылку". refs/for/main — это место назначения ("удалённая ссылка"), где main — "целевая ветка", то есть ветка, в которую предлагается применить изменение.

Topic будет виден в Pull Request’е и используется для связи последующих коммитов с тем же Pull Request’ом.

Указание topic через параметр сессии

Topic можно также задать через параметр <session> в Refspec. В следующем примере мы создаём новый Pull Request, используя текущую ветку (HEAD). Целевая ветка — main, topic — topic-branch.

# topic-branch — это и session, и topic
git push origin HEAD:refs/for/main/topic-branch

Отправка ссылки, отличной от текущей (не HEAD)

Предположим, вы хотите создать Pull Request для удалённой ветки remote-branch с topic topic, но изменения находятся в локальной ветке local-branch, которую вы не хотите переключать. В этом случае можно выполнить:

git push origin local-branch:refs/for/remote-branch/topic

Установка заголовка и описания в AGit

Также можно использовать дополнительные параметры, такие как title и description. Пример для ветки main:

git push origin HEAD:refs/for/main -o topic="topic-branch" \
  -o title="Заголовок PR" \
  -o description="# Описание PR
Это может быть **любой** markdown.\n
- [x] Всё ОК"

Изменение метода отправки по умолчанию

Чтобы отправлять коммиты в Pull Request без указания Refspec, можно изменить метод push по умолчанию на upstream:

# Только для текущего репозитория
git config push.default upstream
# Или глобально
git config --global push.default upstream

Затем выполните:

git config branch.local-branch.merge refs/for/main/topic-branch

После этого можно просто запускать git push для отправки коммитов в Pull Request без указания Refspec. Также это позволит использовать pull, fetch, rebase и другие команды по умолчанию с этим Pull Request’ом.

---

Параметры

git push <имя-удалённого> <локальная-ссылка>:refs/for[draft|for-review]/<ветка>/<сессия> [-o <topic|title|description|force-push>]

Доступные параметры:

• <имя-удалённого>: имя удалённого репозитория (например, origin) (обязательно)

• <локальная-ссылка>: ссылка на локальный объект (например, HEAD, my-branch, хеш коммита) (обязательно)

• refs/<for|draft|for-review>/<ветка>/<сессия>: Refspec (обязательно)

  • for/draft/for-review: Тип Pull Request’а. for открывает обычный Pull Request. draft и for-review пока игнорируются.
  • <ветка>: целевая ветка для Pull Request’а (обязательно)
  • <сессия>: идентификатор сессии или topic для Pull Request’а. Если не указан, параметр -o topic обязателен.

• -o <topic|title|description|force-push>: Опции Push

  • topic: Идентификатор. Если не указан, будет использовано значение <сессия>. Если ни того, ни другого нет, Forgejo вернёт ошибку. Для добавления новых коммитов в уже созданный Pull Request необходимо использовать тот же topic.
  • title: Заголовок Pull Request’а. Если не указан, будет использована первая строка первого нового коммита.
  • description: Описание Pull Request’а.
  • force-push: Необходимо при ребейзе, изменении коммитов или ретроактивном редактировании истории. Иначе будет создан новый Pull Request, даже при том же topic. Если используется, значение должно быть true.

Forgejo полагается на параметр topic и линейную историю коммитов, чтобы связать новые коммиты с существующим Pull Request’ом. Если вы хотите перезаписать содержимое уже созданного PR, используйте параметр force-push.

Для пользователей Gerrit: Forgejo не поддерживает Change-Id из Gerrit.