threads / patch / 14743

patchMake it clear that push can take multiple refspecs

Subject: [PATCH] Make it clear that push can take multiple refspecs

## tl;dr

8 messages between Jul 29, 2008 and Jul 30, 2008. Diffs are folded; open one to read it.

replies: 7people: 2as markdown or json

Abhijit Menon-Sen· Jul 29, 2008, 20:09 UTC · lore

Signed-off-by: Abhijit Menon-Sen <ams@toroid.org>
---
 Documentation/git-push.txt |   10 ++++++++--
 1 files changed, 8 insertions(+), 2 deletions(-)

Show changes to Documentation/git-push.txt +8 −2

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 94d07ab..b8c55dd 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -10,7 +10,8 @@ SYNOPSIS
 --------
 [verse]
 'git push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
-           [--repo=all] [-f | --force] [-v | --verbose] [<repository> <refspec>...]
+           [--repo=all] [-f | --force] [-v | --verbose]
+           [<repository> <refspec>...]
 
 DESCRIPTION
 -----------
@@ -33,7 +34,8 @@ OPTIONS
 	The canonical format of a <refspec> parameter is
 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
 	by the source ref, followed by a colon `:`, followed by
-	the destination ref.
+	the destination ref. Any number of <refspec> parameters
+	may be specified.
 +
 The <src> side represents the source branch (or arbitrary
 "SHA1 expression", such as `master~4` (four parents before the
@@ -180,6 +182,10 @@ 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 master master:other::
+	Find a ref that matches `master` in the source repository and in
+	the `origin` repository update refs `master` and `other` to it.
+
 git push origin master:satellite/master::
 	Find a ref that matches `master` in the source repository
 	(most likely, it would find `refs/heads/master`), and update

-- 
1.6.0.rc0.43.g2aa74

Junio C Hamano· Jul 29, 2008, 20:54 UTC · re: Abhijit Menon-Sen · lore

Re: [PATCH] Make it clear that push can take multiple refspecs

Abhijit Menon-Sen <ams@toroid.org> writes:

Show 14 quoted lines

> Signed-off-by: Abhijit Menon-Sen <ams@toroid.org>
> ---
>  Documentation/git-push.txt |   10 ++++++++--
>  1 files changed, 8 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index 94d07ab..b8c55dd 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -10,7 +10,8 @@ SYNOPSIS
>  --------
>  [verse]
>  'git push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
> -           [--repo=all] [-f | --force] [-v | --verbose] [<repository> <refspec>...]

Doesn't this already say you can have zero or more refspecs?

Abhijit Menon-Sen· Jul 29, 2008, 21:28 UTC · re: Junio C Hamano · lore

Re: [PATCH] Make it clear that push can take multiple refspecs

At 2008-07-29 13:54:35 -0700, gitster@pobox.com wrote:

>
> Doesn't this already say you can have zero or more refspecs?

It does, of course, but I've seen more than one question about how to do it now, even from people who looked at the manpage, and it seemed to me that adding an example wouldn't hurt.

-- ams

Junio C Hamano· Jul 29, 2008, 22:06 UTC · re: Abhijit Menon-Sen · lore

Re: [PATCH] Make it clear that push can take multiple refspecs

Abhijit Menon-Sen <ams@toroid.org> writes:

Show 7 quoted lines

> At 2008-07-29 13:54:35 -0700, gitster@pobox.com wrote:
>>
>> Doesn't this already say you can have zero or more refspecs?
>
> It does, of course, but I've seen more than one question about how to do
> it now, even from people who looked at the manpage, and it seemed to me
> that adding an example wouldn't hurt.

Adding an example would help to certain point, but beyond that certain point it becomes unnecessary noise that talks the obvious. If you saw the question asked many times in the real world, that would be a good indication that this patch falls into the "helpful" category, not "noise". Will queue.

I wonder if there are other manual pages with <thing>... notation that benefits from similar changes, though.

Thanks.

Abhijit Menon-Sen· Jul 29, 2008, 23:13 UTC · re: Junio C Hamano · lore

Re: [PATCH] Make it clear that push can take multiple refspecs

At 2008-07-29 15:06:57 -0700, gitster@pobox.com wrote:

>
> If you saw the question asked many times in the real world, that
> would be a good indication that this patch falls into the "helpful"
> category, not "noise". Will queue.

Thanks.

You may find the appended patch less noisy still. I certainly like being able to get rid of the "any number of..." sentence; and I also think the example is clearer, though I merged it into an existing one.

(I would also change the '+?<src>:<dst>' to '[+]<src>:<dst>'. It's a bit weird to use BOTH regex format and SYNOPSIS format in the same string.)

> I wonder if there are other manual pages with <thing>... notation that
> benefits from similar changes, though.

Yes, I see now that there are several that could use minor changes. Often nothing more than the following is needed:

-<committish>::
-       The object name of the committish.
+<committish>...::
+       A list of committish object names to describe.

(For git-describe, whose SYNOPSIS already mentions '<committish>...')

I'll submit another patch for those later.

-- ams

Show changes to Documentation/git-push.txt +9 −8

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 94d07ab..7f28ea6 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -10,7 +10,8 @@ SYNOPSIS
 --------
 [verse]
 'git push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
-           [--repo=all] [-f | --force] [-v | --verbose] [<repository> <refspec>...]
+           [--repo=all] [-f | --force] [-v | --verbose]
+           [<repository> <refspec>...]
 
 DESCRIPTION
 -----------
@@ -29,8 +30,8 @@ OPTIONS
 	The "remote" repository that is destination of a push
 	operation.  See the section <<URLS,GIT URLS>> below.
 
-<refspec>::
-	The canonical format of a <refspec> parameter is
+<refspec>...::
+	The canonical format of each <refspec> parameter is
 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
 	by the source ref, followed by a colon `:`, followed by
 	the destination ref.
@@ -180,11 +181,11 @@ 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 master:satellite/master::
-	Find a ref that matches `master` in the source repository
-	(most likely, it would find `refs/heads/master`), and update
-	the ref that matches `satellite/master` (most likely, it would
-	be `refs/remotes/satellite/master`) in `origin` repository with it.
+git push origin master:satellite/master dev:satellite/dev::
+	Use the source ref that matches `master` (e.g. `refs/heads/master`)
+	to update the ref that matches `satellite/master` (most probably
+	`refs/remotes/satellite/master`) in the `origin` repository, then
+	do the same for `dev` and `satellite/dev`.
 
 git push origin master:refs/heads/experimental::
 	Create the branch `experimental` in the `origin` repository

Junio C Hamano· Jul 29, 2008, 23:20 UTC · re: Abhijit Menon-Sen · lore

Re: [PATCH] Make it clear that push can take multiple refspecs

Abhijit Menon-Sen <ams@toroid.org> writes:

Show 17 quoted lines

> At 2008-07-29 15:06:57 -0700, gitster@pobox.com wrote:
>>
>> If you saw the question asked many times in the real world, that
>> would be a good indication that this patch falls into the "helpful"
>> category, not "noise". Will queue.
>
> Thanks.
>
> You may find the appended patch less noisy still. I certainly like being
> able to get rid of the "any number of..." sentence; and I also think the
> example is clearer, though I merged it into an existing one.
> ...
> -<refspec>::
> -	The canonical format of a <refspec> parameter is
> +<refspec>...::
> +	The canonical format of each <refspec> parameter is
>  	`+?<src>:<dst>`; that is, an optional plus `+`, followed

After re-reading this, prompted by your comment about "both synopsis syntax and regex in the same sentence, I actually do not see a problem with the original one. The synopsis talks about the ability for you to specify zero or more of whatever is called <refspec>, and here we define what _A_ refspec is.

Somehow I thought the issue was that we said "<refspec>...::" in the heading of the description without saying zero-or-more, but that is not the case here.

Abhijit Menon-Sen· Jul 30, 2008, 06:17 UTC · re: Junio C Hamano · lore

Re: [PATCH] Make it clear that push can take multiple refspecs

At 2008-07-29 16:20:00 -0700, gitster@pobox.com wrote:

>
> The synopsis talks about the ability for you to specify zero or more
> of whatever is called <refspec>, and here we define what _A_ refspec
> is.

Yes. The thing is, many places say "<refspec>..." both in the synopsis and in the description (e.g. add, am, apply, commit...), and doing it differently in some places seems more likely to be confusing than not.

I think it's nice if items in the description exactly match something in the synopsis. It gives me more confidence that someone didn't just forget to update one or the other.

(If you've queued the original git-push.txt patch, I'm happy to leave the others alone, or change them one way or another, as you wish.)

-- ams

Junio C Hamano· Jul 30, 2008, 06:24 UTC · re: Abhijit Menon-Sen · lore

Re: [PATCH] Make it clear that push can take multiple refspecs

Abhijit Menon-Sen <ams@toroid.org> writes:

> I think it's nice if items in the description exactly match something
> in the synopsis. It gives me more confidence that someone didn't just
> forget to update one or the other.

Yup; queued.  Thanks.