From 49dcc71f89768f359a53a3409e86a3cb3c0403ad Mon Sep 17 00:00:00 2001
From: MnPX <223180+emnpiex@noreply.gitea.com>
Date: Sun, 2 Aug 2026 17:48:09 +0000
Subject: [PATCH] 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 <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>
---
 docs/usage/issues-prs/agit.md                 | 27 ++++++++++---------
 .../version-1.27/usage/issues-prs/agit.md     | 27 ++++++++++---------
 2 files changed, 30 insertions(+), 24 deletions(-)

diff --git a/docs/usage/issues-prs/agit.md b/docs/usage/issues-prs/agit.md
index 872a98d1..1fc23c0f 100644
--- a/docs/usage/issues-prs/agit.md
+++ b/docs/usage/issues-prs/agit.md
@@ -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"
diff --git a/versioned_docs/version-1.27/usage/issues-prs/agit.md b/versioned_docs/version-1.27/usage/issues-prs/agit.md
index 872a98d1..1fc23c0f 100644
--- a/versioned_docs/version-1.27/usage/issues-prs/agit.md
+++ b/versioned_docs/version-1.27/usage/issues-prs/agit.md
@@ -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"