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

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

[Abhijit Menon-Sen]

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

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

[Junio C Hamano]

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

> 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?

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

[Abhijit Menon-Sen]

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

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

[Junio C Hamano]

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

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

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

[Abhijit Menon-Sen]

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

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

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

[Junio C Hamano]

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

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

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

[Abhijit Menon-Sen]

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

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

[Junio C Hamano]

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.