gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-08-02 21:03:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: AGit docs accurately reflect syntax (#474)

Browse Source 
there was confusing words around this. `HEAD` was mentioned twice and `origin` was used in place of a sensible option

---------

Co-authored-by: MnPX <git@mnpx.dev>
Co-authored-by: lunny <xiaolunwen@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/474
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: MnPX <223180+emnpiex@noreply.gitea.com>
This commit is contained in:
MnPX
2026-08-02 17:48:09 +00:00
committed by Lunny Xiao
parent 42a0f7f45f
commit 49dcc71f89
2 changed files with 30 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/usage/issues-prs/agit.md
View File

@@ -19,30 +19,33 @@ Git version 2.29 or higher is required on the server side for this to work.
## Creating PRs with AGit
AGit allows to create PRs while pushing code to the remote repo.
This can be done by pushing to the branch followed by a specific refspec (a location identifier known to git).
This can be done by pushing to a special refspec (a location identifier known to git) instead of to a branch.
The following example illustrates this:
```shell
git push origin HEAD:refs/for/main
git push origin HEAD:refs/for/main -o topic="topic_of_my_PR"
```
The command has the following structure:
- `HEAD`: The target branch
- `origin`: The target repository (not a fork!)
- `HEAD`: The local branch containing the changes you are proposing
- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
- `for`: Create a normal PR with `<branch>` as the target branch
- `draft`/`for-review`: Currently ignored silently
- `<branch>/`: The branch you want your changes to be merged into
- `-o <topic|title|description>`: Options for the PR
- `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review. This is REQUIRED to trigger a pull request.
```shell
git push <remote> <local-rev>:refs/for/<branch>[/<topic>] [-o <option>[=<value>] ...]
```
- `<remote>`: The remote pointing at the target repository (not a fork!), `origin` in the example above
- `<local-rev>`: The local branch or commit containing the changes you are proposing, `HEAD` in the example above
- `refs/for/<branch>`: The target PR type and configuration
- `for`: Create a normal PR with `<branch>` as the target branch. This is the only prefix supported at the moment, `refs/draft/...` and `refs/for-review/...` are reserved for future use and do not create a PR.
- `<branch>`: The branch you want your changes to be merged into
- `<topic>`: Optional, an alternative to `-o topic=<topic>`. The push is rejected with `topic-branch is not set` if the topic is given in neither place.
- `-o <option>[=<value>]`: Options for the PR
- `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review (prefixed with your user name). This is REQUIRED to trigger a pull request, unless it is already part of the refspec.
- `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
- `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
- `force-push=true`: Specifies whether to force-update the target branch.
- Note: omitting the value and using just `-o force-push` will also work.
Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
Here's another example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
```shell
git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"

27
versioned_docs/version-1.27/usage/issues-prs/agit.md
View File

@@ -19,30 +19,33 @@ Git version 2.29 or higher is required on the server side for this to work.
## Creating PRs with AGit
AGit allows to create PRs while pushing code to the remote repo.
This can be done by pushing to the branch followed by a specific refspec (a location identifier known to git).
This can be done by pushing to a special refspec (a location identifier known to git) instead of to a branch.
The following example illustrates this:
```shell
git push origin HEAD:refs/for/main
git push origin HEAD:refs/for/main -o topic="topic_of_my_PR"
```
The command has the following structure:
- `HEAD`: The target branch
- `origin`: The target repository (not a fork!)
- `HEAD`: The local branch containing the changes you are proposing
- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
- `for`: Create a normal PR with `<branch>` as the target branch
- `draft`/`for-review`: Currently ignored silently
- `<branch>/`: The branch you want your changes to be merged into
- `-o <topic|title|description>`: Options for the PR
- `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review. This is REQUIRED to trigger a pull request.
```shell
git push <remote> <local-rev>:refs/for/<branch>[/<topic>] [-o <option>[=<value>] ...]
```
- `<remote>`: The remote pointing at the target repository (not a fork!), `origin` in the example above
- `<local-rev>`: The local branch or commit containing the changes you are proposing, `HEAD` in the example above
- `refs/for/<branch>`: The target PR type and configuration
- `for`: Create a normal PR with `<branch>` as the target branch. This is the only prefix supported at the moment, `refs/draft/...` and `refs/for-review/...` are reserved for future use and do not create a PR.
- `<branch>`: The branch you want your changes to be merged into
- `<topic>`: Optional, an alternative to `-o topic=<topic>`. The push is rejected with `topic-branch is not set` if the topic is given in neither place.
- `-o <option>[=<value>]`: Options for the PR
- `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review (prefixed with your user name). This is REQUIRED to trigger a pull request, unless it is already part of the refspec.
- `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
- `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
- `force-push=true`: Specifies whether to force-update the target branch.
- Note: omitting the value and using just `-o force-push` will also work.
Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
Here's another example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
```shell
git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"