diff --git a/docs/user/agit-support.md b/docs/user/agit-support.md index 27a1bcbd..85f61d9b 100644 --- a/docs/user/agit-support.md +++ b/docs/user/agit-support.md @@ -24,16 +24,29 @@ Suppose that you cloned a repository and created a new commit on top of the `mai git push origin HEAD:refs/for/main -o topic="agit-typo-fixes" ``` -The topic will be visible in the Pull Request and it will be used to associate further commits to the same Pull Request. Under the hood, it is essentially just a branch. +Note that `HEAD:refs/for/main` is the [Refspec](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec). `HEAD` refers to the [checked out reference](https://git-scm.com/book/en/v2/Git-Internals-Git-References), but can be replaced with any ["local ref"](https://git-scm.com/docs/git-push). `refs/for/main` refers to the destination (**"remote ref"**), with `main` being the "target branch", as in the branch that your submitted change should be applied to. -It can also be supplied directly using the `` parameter in the **Refspec**, which will set the topic as `topic-branch` and push the **currently checked out branch**: +The topic will be visible in the Pull Request. The topic is used to associate further commits with the same Pull Request, instead of creating a new Pull Request. Under the hood, a "topic" is used to create a new branch in the target repository. + +#### Setting a topic using the session parameter. + +Topics can also be defined using the `` parameter in the **Refspec**. In the following example, we create a new pull request using the currently checked out reference (`HEAD`). The target branch will be `main`. The topic will be `topic-branch`. ```shell # topic-branch is the session parameter and the topic git push origin HEAD:refs/for/main/topic-branch ``` -A detailed explanation illustrating the difference between using `-o topic` and `` will follow shortly. +#### Pushing a non-checked-out reference (non-HEAD) + +Suppose you would like to submit a Pull Request meant for a remote branch called `remote-branch` using topic `topic`. +However, the changes that you want to submit reside in a local branch called `local-branch` that you have not checked out. 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`) as follows: + +```shell +git push origin local-branch:refs/for/remote-branch/topic +``` + +#### Setting a title and a description in AGit It is also possible to use some additional parameters, such as `title` and `description`. Here's another example targeting the `main` branch: @@ -45,7 +58,9 @@ This can be **any** markdown content.\n - [x] Ok" ``` -To be able to easily push new commits to your pull request, you first need to switch the [default push method](https://git-scm.com/docs/git-config#Documentation/git-config.txt-pushdefault) to "upstream": +#### Changing the default push method + +To push commits to your Pull Request without having to specify the Refspec, you can modify the [default push method](https://git-scm.com/docs/git-config#Documentation/git-config.txt-pushdefault) to `upstream` in your Git configuration: ```shell # To only set this option for this specific repository @@ -63,17 +78,6 @@ git config branch.local-branch.merge refs/for/main/topic-branch After doing so, you can now simply run `git push` to push commits to your pull request, without having to specify the refspec. This also will allow you to pull, fetch, rebase, etc. from the AGit pull request by default. -#### Pushing a non-checked-out reference (non-HEAD) - -While most users will likely be pushing HEAD most of the time, it is worth noting that AGit flow supports pushing any local reference (just like `push` in general). - -Suppose you would like to submit a Pull Request meant for a remote branch called `remote-branch` using topic `topic`. -However, the changes that you want to submit reside in a local branch called `local-branch` that you have not checked out. 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`) as follows: - -```shell -git push origin local-branch:refs/for/remote-branch/topic -``` - ### Parameters The following parameters are available: @@ -87,8 +91,8 @@ The following parameters are available: - `topic`: Essentially an identifier. **If left empty,** the value of ``, if present, will also be used for the topic. 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 [retroactively modifying](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) your previous commits. Otherwise, a new Pull Request will be opened, **even if you use the same topic**. If used, the value of this parameter should be set to `true`. + - `force-push`: Necessary when rebasing, amending or [retroactively modifying](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) your previous commits. Otherwise, a new Pull Request will be opened. If used, the value of this parameter should be set to `true`. -Forgejo relies on the `topic` parameter and a linear commit history in order to associate new commits with an existing Pull Request. +Forgejo relies on the `topic` parameter and a linear commit history in order to associate new commits with an existing Pull Request. Should you wish to overwrite the contents of an existing pull request, use the `force-push` parameter. **For Gerrit users:** Forgejo does not support [Gerrit's Change-Ids](https://gerrit-review.googlesource.com/Documentation/user-changeid.html).