threads / patch / 17362

patch, 3 partsDocumentation: more git push examples

Subject: [PATCH 2/3] Documentation: more git push examples

## tl;dr

5 messages between Jan 25, 2009 and Jan 26, 2009. Diffs are folded; open one to read it.

replies: 4people: 2as markdown or json

Anders Melchiorsen· Jan 25, 2009, 23:45 UTC · lore

[PATCH 0/3] Documentation: refine refspec description

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.

Anders Melchiorsen· Jan 25, 2009, 23:45 UTC · re: Anders Melchiorsen · lore

[PATCH 1/3] Documentation: simplify refspec format description

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(-)

Show changes to 2 files +8 −8

Documentation/git-push.txt, Documentation/pull-fetch-param.txt

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

Anders Melchiorsen· Jan 25, 2009, 23:45 UTC · re: Anders Melchiorsen · lore

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(-)

Show changes to Documentation/git-push.txt +13 −3

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

Anders Melchiorsen· Jan 25, 2009, 23:45 UTC · re: Anders Melchiorsen · lore

[PATCH 3/3] Documentation: rework src/dst description in git push

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(-)

Show changes to Documentation/git-push.txt +12 −11

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

Junio C Hamano· Jan 26, 2009, 06:24 UTC · re: Anders Melchiorsen · lore

Re: [PATCH 1/3] Documentation: simplify refspec format description

Anders Melchiorsen <mail@cup.kalibalik.dk> writes:

Show 19 quoted lines

> 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(-)

Show changes to diff +3 −3

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.
 +