fix: AGit docs accurately reflect syntax (#474)

there was confusing words around this. `HEAD` was mentioned twice and `origin` was used in place of a sensible option --------- Co-authored-by: MnPX <[email protected]> Co-authored-by: lunny <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/474 Reviewed-by: Lunny Xiao <[email protected]> Co-authored-by: MnPX <[email protected]>
2026-09-17 19:55:34 +00:00 · 2026-08-02 17:48:09 +00:00
parent 42a0f7f45f
commit 49dcc71f89
2 changed files with 30 additions and 24 deletions
@@ -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
+```shell
- `origin`: The target repository (not a fork!)
+git push <remote> <local-rev>:refs/for/<branch>[/<topic>] [-o <option>[=<value>] ...]
- `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
+- `<remote>`: The remote pointing at the target repository (not a fork!), `origin` in the example above
-  - `draft`/`for-review`: Currently ignored silently
+- `<local-rev>`: The local branch or commit containing the changes you are proposing, `HEAD` in the example above
-  - `<branch>/`: The branch you want your changes to be merged into
+- `refs/for/<branch>`: The target PR type and configuration
- `-o <topic|title|description>`: Options for the PR
+  - `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.
-  - `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.
+  - `<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"
@@ -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
+```shell
- `origin`: The target repository (not a fork!)
+git push <remote> <local-rev>:refs/for/<branch>[/<topic>] [-o <option>[=<value>] ...]
- `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
+- `<remote>`: The remote pointing at the target repository (not a fork!), `origin` in the example above
-  - `draft`/`for-review`: Currently ignored silently
+- `<local-rev>`: The local branch or commit containing the changes you are proposing, `HEAD` in the example above
-  - `<branch>/`: The branch you want your changes to be merged into
+- `refs/for/<branch>`: The target PR type and configuration
- `-o <topic|title|description>`: Options for the PR
+  - `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.
-  - `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.
+  - `<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"