From: Junio C Hamano Date: Mon, 26 Jan 2009 06:24:06 GMT Subject: Re: [PATCH 1/3] Documentation: simplify refspec format description Message-ID: <7viqo2a8l5.fsf@gitster.siamese.dyndns.org> In-Reply-To: <1232927133-30377-2-git-send-email-mail@cup.kalibalik.dk> Anders Melchiorsen 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 <> below). > > :: > - The canonical format of a parameter is > - `+?:`; that is, an optional plus `{plus}`, followed > - by the source ref, followed by a colon `:`, followed by > - the destination ref. > + The format of a parameter is an optional plus > + `{plus}`, followed by the source ref , followed > + by a colon `:`, followed by the destination ref . > + Find various forms of refspecs in examples section. > + > The remote ref that matches > is fetched, and if 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 parameter is an optional plus `{plus}`, followed by the source ref , followed by a colon `:`, followed by the destination ref . - Find various forms of refspecs in examples section. + It is used to specify with what object the ref + in the remote repository is to be updated. + The 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 parameter is an optional plus `{plus}`, followed by the source ref , followed by a colon `:`, followed by the destination ref . - Find various forms of refspecs in examples section. + The remote ref that matches is fetched, and if is not empty string, the local ref that matches it is fast forwarded using . -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. +