From e82255b9bf11bc03e74d16cbb68977d40b111b61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rados=C5=82aw=20Piliszek?= Date: Thu, 15 Aug 2024 11:53:59 +0200 Subject: [PATCH] agit: replace the "complex" example There was a lot of false information in that section and the examples did not do what was described in the text. This change extracts the perhaps-useful reminder that push still behaves like push and allows to specify arbitrary local references. Some points to note (which were wronged previously): * refspec for push has the dst part optional, not the other way around (and it's thus either `src` or `src:dest` in syntax) * HEAD always points to the checked-out reference, so all examples were still pushing the checked-out reference --- docs/user/agit-support.md | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/docs/user/agit-support.md b/docs/user/agit-support.md index 58ff08e7..68e179d0 100644 --- a/docs/user/agit-support.md +++ b/docs/user/agit-support.md @@ -63,30 +63,17 @@ 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. -#### A More Complex Example +#### Pushing a non-checked-out reference (non-HEAD) -Suppose that the currently checked out branch in your local repository is `main`, yet you would like to submit a Pull Request meant for a remote branch called `remote-branch`. +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). -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 `` parameter: +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 HEAD:refs/for/remote-branch/local-branch \ - -o title="My First Pull Request!" +git push origin local-branch:refs/for/remote-branch/topic ``` -This syntax may be a bit 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`, supplying the local branch name is optional, as long as you checkout `local-branch` using `git checkout local-branch` beforehand and **use the `topic` push option**: - -```shell -git checkout local-branch -git push origin HEAD:refs/for/remote-branch \ - -o topic="my-first-agit-pr" \ - -o title="My First Pull Request!" -``` - -**If you do not use the `topic` push option,** `` will be used as the topic instead. - ### Parameters The following parameters are available: