# [PATCH] Amend git-push refspec documentation 3 messages from 2008-04-21 to 2008-04-22. Participants: Sam Vilain, Junio C Hamano. Thread: https://gitlist.dev/t/13193 ## Sam Vilain, 2008-04-21 03:31 Subject: [PATCH] Amend git-push refspec documentation Message-ID: <1208748684-28253-1-git-send-email-sam.vilain@catalyst.net.nz> URL: https://gitlist.dev/e/1208748684-28253-1-git-send-email-sam.vilain%40catalyst.net.nz ``` These paragraphs are a little confusing. Also, make it clearer when you have to specify the full name for Signed-off-by: Sam Vilain --- Documentation/git-push.txt | 22 ++++++++++++---------- 1 files changed, 12 insertions(+), 10 deletions(-) diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 3128170..b3d164e 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -35,14 +35,14 @@ OPTIONS by the source ref, followed by a colon `:`, followed by the destination ref. + -The side can be an -arbitrary "SHA1 expression" that can be used as an -argument to `git-cat-file -t`. E.g. `master~4` (push -four parents before the current master head). +The side represents the source branch (or arbitrary +"SHA1 expression"; see linkgit:git-rev-parse[1]) that you want to +push. The side represents the destination location. + The local ref that matches is used -to fast forward the remote ref that matches . If -the optional plus `+` is used, the remote ref is updated +to fast forward the remote ref that matches (or, if no was +specified, the same ref that referred to locally). If +the optional leading plus `+` is used, the remote ref is updated even if it does not result in a fast forward update. + Note: If no explicit refspec is found, (that is neither @@ -165,7 +165,8 @@ git push origin master:: Find a ref that matches `master` in the source repository (most likely, it would find `refs/heads/master`), and update the same ref (e.g. `refs/heads/master`) in `origin` repository - with it. + with it. If `master` did not exist remotely, it would be + created. git push origin :experimental:: Find a ref that matches `experimental` in the `origin` repository @@ -179,9 +180,10 @@ git push origin master:satellite/master:: git push origin master:refs/heads/experimental:: Create the branch `experimental` in the `origin` repository - by copying the current `master` branch. This form is usually - needed to create a new branch in the remote repository as - there is no `experimental` branch to match. + by copying the current `master` branch. This form is only + needed to create a new branch in the remote repository when + the local name and the remote name are different; otherwise, + the branch name on its own will work. Author ------ -- 1.5.5.1.50.g1d36.dirty ``` ## Junio C Hamano, 2008-04-22 05:48 Subject: Re: [PATCH] Amend git-push refspec documentation Message-ID: <7vk5iq5tj2.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vk5iq5tj2.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1208748684-28253-1-git-send-email-sam.vilain@catalyst.net.nz> ``` Sam Vilain writes: > These paragraphs are a little confusing. Also, make it clearer when > you have to specify the full name for > > Signed-off-by: Sam Vilain > --- > Documentation/git-push.txt | 22 ++++++++++++---------- > 1 files changed, 12 insertions(+), 10 deletions(-) > > diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt > index 3128170..b3d164e 100644 > --- a/Documentation/git-push.txt > +++ b/Documentation/git-push.txt > @@ -35,14 +35,14 @@ OPTIONS > by the source ref, followed by a colon `:`, followed by > the destination ref. > + > -The side can be an > -arbitrary "SHA1 expression" that can be used as an > -argument to `git-cat-file -t`. E.g. `master~4` (push > -four parents before the current master head). > +The side represents the source branch (or arbitrary > +"SHA1 expression"; see linkgit:git-rev-parse[1]) that you want to > +push. The side represents the destination location. > + Hmm. We lost an example but refer to a more authoritative information, which is probably Ok. > The local ref that matches is used > -to fast forward the remote ref that matches . If > -the optional plus `+` is used, the remote ref is updated > +to fast forward the remote ref that matches (or, if no was > +specified, the same ref that referred to locally). If > +the optional leading plus `+` is used, the remote ref is updated > even if it does not result in a fast forward update. > + That's an improvement. > @@ -179,9 +180,10 @@ git push origin master:satellite/master:: > > git push origin master:refs/heads/experimental:: > Create the branch `experimental` in the `origin` repository > - by copying the current `master` branch. This form is usually > - needed to create a new branch in the remote repository as > - there is no `experimental` branch to match. > + by copying the current `master` branch. This form is only > + needed to create a new branch in the remote repository when > + the local name and the remote name are different; otherwise, > + the branch name on its own will work. Note that writing "refs/tags/xprm" instead would allow you to create a lightweight tag over there. ``` ## Sam Vilain, 2008-04-22 08:27 Subject: Re: [PATCH] Amend git-push refspec documentation Message-ID: <480DA161.3070107@catalyst.net.nz> URL: https://gitlist.dev/e/480DA161.3070107%40catalyst.net.nz In-Reply-To: <7vk5iq5tj2.fsf@gitster.siamese.dyndns.org> ``` Junio C Hamano wrote: >> -The side can be an >> -arbitrary "SHA1 expression" that can be used as an >> -argument to `git-cat-file -t`. E.g. `master~4` (push >> -four parents before the current master head). >> +The side represents the source branch (or arbitrary >> +"SHA1 expression"; see linkgit:git-rev-parse[1]) that you want to >> +push. The side represents the destination location. >> + > > Hmm. We lost an example but refer to a more authoritative information, > which is probably Ok. Well, the example I think was quite confusing to people who have never seen `master~4` before. >> @@ -179,9 +180,10 @@ git push origin master:satellite/master:: >> >> git push origin master:refs/heads/experimental:: >> Create the branch `experimental` in the `origin` repository >> - by copying the current `master` branch. This form is usually >> - needed to create a new branch in the remote repository as >> - there is no `experimental` branch to match. >> + by copying the current `master` branch. This form is only >> + needed to create a new branch in the remote repository when >> + the local name and the remote name are different; otherwise, >> + the branch name on its own will work. > > Note that writing "refs/tags/xprm" instead would allow you to create a > lightweight tag over there. True. You could probably replace 'branch' with 'ref' in the two places it occurs in the last sentence to encompass that meaning, too. Cheers, Sam. ```