foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-12-25 22:40:42 -05:00
Code Issues Activity

agit: replace the "complex" example

Browse source 
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
This commit is contained in:
Radosław Piliszek 2024-08-15 11:53:59 +02:00 committed by Otto
parent f0374b28fe
commit e82255b9bf
1 changed files with 5 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
docs/user/agit-support.md
View file

@ -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 `<session>` 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,** `<session>` will be used as the topic instead.
### Parameters
The following parameters are available: