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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 26, 2009, 06:24 UTC
Message-ID: <7viqo2a8l5.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1232927133-30377-2-git-send-email-mail@cup.kalibalik.dk>

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

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