* [PATCH 0/3] Documentation: refine refspec description @ 2009-01-25 23:45 Anders Melchiorsen 2009-01-25 23:45 ` [PATCH 1/3] Documentation: simplify refspec format description Anders Melchiorsen 0 siblings, 1 reply; 5+ messages in thread From: Anders Melchiorsen @ 2009-01-25 23:45 UTC (permalink / raw) To: gitster; +Cc: git, Anders Melchiorsen These are the remaining parts of my git-push refspec updates. I recall having a hard time making sense of the existing documentation, due to a lot of small questions that popped up. With these patches, I try to reword things to make them clearer. It is, however, getting to the point where I have looked at this so much that I can no longer tell whether I am actually improving things. Thus, this will be my last submission for this particular itch. Cheers, Anders. ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH 1/3] Documentation: simplify refspec format description 2009-01-25 23:45 [PATCH 0/3] Documentation: refine refspec description Anders Melchiorsen @ 2009-01-25 23:45 ` Anders Melchiorsen 2009-01-25 23:45 ` [PATCH 2/3] Documentation: more git push examples Anders Melchiorsen 2009-01-26 6:24 ` [PATCH 1/3] Documentation: simplify refspec format description Junio C Hamano 0 siblings, 2 replies; 5+ messages in thread From: Anders Melchiorsen @ 2009-01-25 23:45 UTC (permalink / raw) To: gitster; +Cc: git, Anders Melchiorsen The refspec format description was a mix of regexp and BNF, making it very difficult to read. The format was also wrong: it did not show that each part of a refspec is optional in different situations. Rather than having a confusing grammar, just present the format in informal prose. Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk> --- This is a rework of http://article.gmane.org/gmane.comp.version-control.git/99552/ Documentation/git-push.txt | 8 ++++---- Documentation/pull-fetch-param.txt | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 7b27dc6..3fd4bbb 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -33,10 +33,10 @@ OPTIONS of a remote (see the section <<REMOTES,REMOTES>> below). <refspec>...:: - The canonical format of a <refspec> parameter is - `+?<src>:<dst>`; that is, an optional plus `{plus}`, followed - by the source ref, followed by a colon `:`, followed by - the destination ref. + The format of a <refspec> parameter is an optional plus + `{plus}`, followed by the source ref <src>, followed + by a colon `:`, followed by the destination ref <dst>. + Find various forms of refspecs in examples section. + The <src> side represents the source branch (or arbitrary "SHA1 expression", such as `master~4` (four parents before the diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index ebdd948..820c140 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -5,10 +5,10 @@ of a remote (see the section <<REMOTES,REMOTES>> below). <refspec>:: - The canonical format of a <refspec> parameter is - `+?<src>:<dst>`; that is, an optional plus `{plus}`, followed - by the source ref, followed by a colon `:`, followed by - the destination ref. + The format of a <refspec> parameter is an optional plus + `{plus}`, followed by the source ref <src>, followed + by a colon `:`, followed by the destination ref <dst>. + Find various forms of refspecs in examples section. + The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local -- 1.6.0.2.514.g23abd3 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH 2/3] Documentation: more git push examples 2009-01-25 23:45 ` [PATCH 1/3] Documentation: simplify refspec format description Anders Melchiorsen @ 2009-01-25 23:45 ` Anders Melchiorsen 2009-01-25 23:45 ` [PATCH 3/3] Documentation: rework src/dst description in git push Anders Melchiorsen 2009-01-26 6:24 ` [PATCH 1/3] Documentation: simplify refspec format description Junio C Hamano 1 sibling, 1 reply; 5+ messages in thread From: Anders Melchiorsen @ 2009-01-25 23:45 UTC (permalink / raw) To: gitster; +Cc: git, Anders Melchiorsen Include examples of using HEAD. The order of examples introduces new concepts one by one. This pushes the example of deleting a ref to the end of the list. --- Documentation/git-push.txt | 16 +++++++++++++--- 1 files changed, 13 insertions(+), 3 deletions(-) diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 3fd4bbb..6d478c5 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -190,9 +190,9 @@ git push origin master:: 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 - (e.g. `refs/heads/experimental`), and delete it. +git push origin HEAD:: + A handy way to push the current branch to the same name on the + remote. git push origin master:satellite/master dev:satellite/dev:: Use the source ref that matches `master` (e.g. `refs/heads/master`) @@ -200,6 +200,11 @@ git push origin master:satellite/master dev:satellite/dev:: `refs/remotes/satellite/master`) in the `origin` repository, then do the same for `dev` and `satellite/dev`. +git push origin HEAD:master:: + Push the current branch to the remote ref matching `master` in the + `origin` repository. This form is convenient to push the current + branch without thinking about its local name. + git push origin master:refs/heads/experimental:: Create the branch `experimental` in the `origin` repository by copying the current `master` branch. This form is only @@ -207,6 +212,11 @@ git push origin master:refs/heads/experimental:: the local name and the remote name are different; otherwise, the ref name on its own will work. +git push origin :experimental:: + Find a ref that matches `experimental` in the `origin` repository + (e.g. `refs/heads/experimental`), and delete it. + + Author ------ Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C -- 1.6.0.2.514.g23abd3 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH 3/3] Documentation: rework src/dst description in git push 2009-01-25 23:45 ` [PATCH 2/3] Documentation: more git push examples Anders Melchiorsen @ 2009-01-25 23:45 ` Anders Melchiorsen 0 siblings, 0 replies; 5+ messages in thread From: Anders Melchiorsen @ 2009-01-25 23:45 UTC (permalink / raw) To: gitster; +Cc: git, Anders Melchiorsen This tries to make the description of ref matching in git push easier to read. Beauty is in the eye of the beholder, though. Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk> --- This is a followup to http://article.gmane.org/gmane.comp.version-control.git/99553/ Documentation/git-push.txt | 23 ++++++++++++----------- 1 files changed, 12 insertions(+), 11 deletions(-) diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 6d478c5..1b3de4f 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -38,20 +38,21 @@ OPTIONS by a colon `:`, followed by the destination ref <dst>. Find various forms of refspecs in examples section. + -The <src> side represents the source branch (or arbitrary -"SHA1 expression", such as `master~4` (four parents before the -tip of `master` branch); see linkgit:git-rev-parse[1]) that you -want to push. The <dst> side represents the destination location. +The <src> is often the name of the branch you would want to push, but +it can be any arbitrary "SHA-1 expression", such as `master~4` or +`HEAD` (see linkgit:git-rev-parse[1]). + -The local ref that matches <src> is used -to fast forward the remote ref that matches <dst>. If -the optional leading plus `+` is used, the remote ref is updated -even if it does not result in a fast forward update. +The <dst> tells which ref on the remote side is updated with this +push. Arbitrary expressions cannot be used here, an actual ref must +be named. If `:`<dst> is omitted, the same ref as <src> will be +updated. + -`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. +The object referenced by <src> is used to fast forward the ref <dst> +on the remote side. If the optional leading plus `{plus}` is used, the +remote ref is updated even if it does not result in a fast forward +update. + -A lonely <src> parameter (without a colon and a destination) pushes -the <src> to the same name in the destination repository. +`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. + Pushing an empty <src> allows you to delete the <dst> ref from the remote repository. -- 1.6.0.2.514.g23abd3 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH 1/3] Documentation: simplify refspec format description 2009-01-25 23:45 ` [PATCH 1/3] Documentation: simplify refspec format description Anders Melchiorsen 2009-01-25 23:45 ` [PATCH 2/3] Documentation: more git push examples Anders Melchiorsen @ 2009-01-26 6:24 ` Junio C Hamano 1 sibling, 0 replies; 5+ messages in thread From: Junio C Hamano @ 2009-01-26 6:24 UTC (permalink / raw) To: Anders Melchiorsen; +Cc: git Anders Melchiorsen <mail@cup.kalibalik.dk> writes: > diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt > index ebdd948..820c140 100644 > --- a/Documentation/pull-fetch-param.txt > +++ b/Documentation/pull-fetch-param.txt > @@ -5,10 +5,10 @@ > of a remote (see the section <<REMOTES,REMOTES>> below). > > <refspec>:: > - The canonical format of a <refspec> parameter is > - `+?<src>:<dst>`; that is, an optional plus `{plus}`, followed > - by the source ref, followed by a colon `:`, followed by > - the destination ref. > + The format of a <refspec> parameter is an optional plus > + `{plus}`, followed by the source ref <src>, followed > + by a colon `:`, followed by the destination ref <dst>. > + Find various forms of refspecs in examples section. > + > The remote ref that matches <src> > is fetched, and if <dst> is not empty string, the local I think this is *much* nicer, but I do not think git-fetch.txt has examples to fall back on. The patch to git-push.txt would not have this issue; the exmaple is there in the page itself. But I think it might be even better to briefly describe what it means, like this patch on top of yours does to git-push.txt. The fetch/pull side already has the corresponding description immediately after that, so I'd suggest just removing the reference to non-existing examples section. I found your 2/3 and 3/3 good improvements. Documentation/git-push.txt | 3 ++- Documentation/pull-fetch-param.txt | 3 +-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git i/Documentation/git-push.txt w/Documentation/git-push.txt index 3fd4bbb..ea45935 100644 --- i/Documentation/git-push.txt +++ w/Documentation/git-push.txt @@ -36,7 +36,8 @@ OPTIONS The format of a <refspec> parameter is an optional plus `{plus}`, followed by the source ref <src>, followed by a colon `:`, followed by the destination ref <dst>. - Find various forms of refspecs in examples section. + It is used to specify with what <src> object the <dst> ref + in the remote repository is to be updated. + The <src> side represents the source branch (or arbitrary "SHA1 expression", such as `master~4` (four parents before the diff --git i/Documentation/pull-fetch-param.txt w/Documentation/pull-fetch-param.txt index 820c140..f9811f2 100644 --- i/Documentation/pull-fetch-param.txt +++ w/Documentation/pull-fetch-param.txt @@ -8,12 +8,11 @@ The format of a <refspec> parameter is an optional plus `{plus}`, followed by the source ref <src>, followed by a colon `:`, followed by the destination ref <dst>. - Find various forms of refspecs in examples section. + The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast forwarded using <src>. -Again, if the optional plus `+` is used, the local ref +If the optional plus `+` is used, the local ref is updated even if it does not result in a fast forward update. + ^ permalink raw reply related [flat|nested] 5+ messages in thread
end of thread, other threads:[~2009-01-26 6:25 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2009-01-25 23:45 [PATCH 0/3] Documentation: refine refspec description Anders Melchiorsen 2009-01-25 23:45 ` [PATCH 1/3] Documentation: simplify refspec format description Anders Melchiorsen 2009-01-25 23:45 ` [PATCH 2/3] Documentation: more git push examples Anders Melchiorsen 2009-01-25 23:45 ` [PATCH 3/3] Documentation: rework src/dst description in git push Anders Melchiorsen 2009-01-26 6:24 ` [PATCH 1/3] Documentation: simplify refspec format description Junio C Hamano
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).