earl-warren/docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Clean things up, address review comments

Browse source 
- Improve background information
- Move Caveat information to parameter explanations
- Add <session> example
This commit is contained in:
Panagiotis "Ivory" Vasilopoulos 2024-02-11 14:22:18 +01:00 committed by Earl Warren
parent 389a056329
commit 0cf21c22c5
1 changed files with 36 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
docs/user/agit-support.md
View file

@ -6,13 +6,19 @@ origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f
Forgejo ships with limited support for [AGit-Flow](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/). It was originally introduced in Gitea `1.13`.
Similarly to [Gerrit](https://www.gerritcodereview.com), it is possible to create Pull Requests to a target repository by pushing directly to that said repository, without having to create feature branches or forks.
Similarly to [Gerrit's workflow](https://www.gerritcodereview.com), 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](https://git-scm.com/book/en/v2/Git-Internals-The-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
Creating a new Pull Request can be done by pushing to the branch that you are targeting followed by a specific [refspec](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec) (a location identifier known to Git).
For reasons of clarity, this document will lead with some examples first.
For clarity, 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:
A full list of the parameters, as well as instructions 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:
```shell
git push origin HEAD:refs/for/main -o topic="topic-branch"
@ -24,7 +30,7 @@ The topic branch can also be supplied directly in the refspec:
git push origin HEAD:refs/for/main/topic-branch
```
It is possible to use some additional parameters, such as `topic`, `title` and `description`. Here's another example targeting the `master` branch:
It is also possible to use some additional parameters, such as `topic`, `title` and `description`. Here's another example targeting the `master` branch:
```shell
git push origin HEAD:refs/for/master -o topic="topic-branch" \
@ -34,32 +40,35 @@ 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 wish 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:
```shell
git push origin HEAD:refs/for/remote-branch/local-branch \
-o topic="my-first-contribution" \
-o title="My First Pull Request!"
```
This syntax can be 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.
### Parameters
The following parameters are available:
- `HEAD`: The target branch **(required)**
- `refs/<for|draft|for-review>/<branch>`: The target PR type **(required)**
- `for`: Create a normal PR with `<branch>` as the target branch
- `draft`/ `for-review`: Currently ignored silently
- `<branch>/<session>`: The target branch to open the PR **(required)**
- `-o <topic|title|description>`: Options for the PR
- `title`: The PR title. If left empty, the first line of the first new Git commit will be used instead.
- `topic`: The branch name the PR should be opened for.*
- `description`: The PR description
- `force-push`: confirm force update the target branch
- `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 used by default.
- `-o <topic|title|description>`: Push options
- `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.
- `topic`: Topic. Under the hood, this is just a branch. If you wish to push any further commits to a Pull Request you created using AGit, you **must** use the same topic, as it is used to associate your new commits with your existing Pull Request.
- `force-push`: Necessary when rebasing or amending your previous commits. Otherwise, a new Pull Request will be opened, **even if you supply the same topic value**.
### Caveats
Some caution is required when pushing new changes to an existing Pull Request that was created using AGit. Otherwise, Forgejo may not be able to associate your new changes with your existing Pull Request, resulting in the creation of a new Pull Request.
If you wish to push a second commit to a Pull Request that you previously created using AGit, you **must** use the same topic that you used before.
If you rebase or amend a commit that is already a part of your Pull Request, you **must** push it using the topic that you used before **together** with the `force-push` option.
#### For Gerrit users
Despite the similarites with the Gerrit workflow, AGit does **not** act as a drop-in replacement.
- Submitting new changes will **not** create different "reviews" that can be reviewed individually. Subsequent commits will be appended to the same Pull Request.
- Forgejo does not rely on [Change-Ids](https://gerrit-review.googlesource.com/Documentation/user-changeid.html).
**For Gerrit users:** Forgejo does not support [Change-Ids](https://gerrit-review.googlesource.com/Documentation/user-changeid.html), as it relies on the `topic` parameter instead. Subsequent commits submitted under the same topic will belong to the same Pull Request.