Abhijit Menon-Sen [off-list ref] writes:
At 2008-07-29 13:54:35 -0700, gitster@pobox.com wrote:
quoted
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.
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