forgejo-docs/docs/user/agit-support.md

title	license	origin_url
AGit Workflow Usage	Apache-2.0	abe8fe3527/docs/content/usage/agit-support.en-us.md

Forgejo ships with limited support for AGit-Flow. It was originally introduced in Gitea 1.13.

Similarly to Gerrit's workflow, this workflow provides a way of submitting changes to a remote repository using the git push command alone, without having to create forks or feature branches and then using the web UI to create a Pull Request.

Using Push Options (-o) and a Refspec (a location identifier known to Git), it is possible to supply the information required to open a Pull Request, such as the target branch or the Pull Request's title.

Creating Pull Requests

For clarity reasons, this document will lead with some examples first.

A full list of the parameters, as well as information on avoiding duplicate Pull Requests when rebasing or amending a commit, will follow.

Usage Examples

Suppose that you cloned a repository and created a new commit on top of the main branch. A Pull Request targeting the main branch can be created like this:

git push origin HEAD:refs/for/main -o topic="topic-branch"

The topic branch can also be supplied directly in the refspec:

git push origin HEAD:refs/for/main/topic-branch

It is also possible to use some additional parameters, such as topic, title and description. Here's another example targeting the master branch:

git push origin HEAD:refs/for/master -o topic="topic-branch" \
  -o title="Title of the PR" \
  -o description="# The PR Description
This can be **any** markdown content.\n
- [x] Ok"

A More Complex Example

Suppose that the currently checked out branch in your local repository is main, yet you would like to submit a Pull Request meant for a remote branch called remote-branch.

However, the changes that you want to submit reside in a local branch called local-branch. In order to submit the changes residing in the local-branch branch without checking it out, you can supply the name of the local branch (local-branch) using the <session> parameter:

git push origin HEAD:refs/for/remote-branch/local-branch \
  -o title="My First Pull Request!"

This syntax may be a bit disorienting for users that are accustomed to commands such as git push origin remote-branch or git push origin local-branch:remote-branch.

Just like when using git push origin remote-branch, it is important to reiterate that supplying the local branch name is optional, as long as you checkout local-branch using git checkout local-branch beforehand and use the topic push option:

git checkout local-branch
git push origin HEAD:refs/for/remote-branch \
  -o topic="my-first-agit-pr" \
  -o title="My First Pull Request!"

If you do not use the topic push option, <session> will be used as the topic instead.

Parameters

The following parameters are available:

• HEAD: The target branch (required)
• refs/<for|draft|for-review>/<branch>/<session>: Refspec (required)
  • for/draft``for-review: This parameter describes the Pull Request type. for opens a normal Pull Request. draft and for-review are currently silently ignored.
  • <branch>: The target branch that a Pull Request should be merged against (required)
  • <session>: The local branch that should be submitted remotely. If left empty, the currently checked out branch will be submitted by default, however, you must use topic.
• -o <topic|title|description|force-push>: Push options
  • topic: Topic. Under the hood, this is just a branch. If left empty, <session>, if present, will be used instead. Otherwise, Forgejo will return an error. If you want to push additional commits to a Pull Request that was created using AGit, you must use the same topic.
  • title: Title of the Pull Request. If left empty, the first line of the first new Git commit will be used instead.
  • description: Description of the Pull Request.
  • force-push: Necessary when rebasing, amending or retrospectively modifying your previous commits. Otherwise, a new Pull Request will be opened, even if you use the same topic.

---

Forgejo relies on the topic parameter and a linear commit history in order to associate new commits with an existing Pull Request.

For Gerrit users: Forgejo does not support Gerrit's Change-Ids.