Re: [PATCH 1/7] Documentation: do not use regexp in refspec descriptions

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 31, 2008, 05:35 UTC
Message-ID: <7v7i7pba2x.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1225311945-17100-2-git-send-email-mail@cup.kalibalik.dk>

Anders Melchiorsen <mail@cup.kalibalik.dk> writes:

Show 5 quoted lines

> The refspec format description was a mix of regexp and BNF, making it
> very difficult to read.
>
> The syntax is now easier to read, though wrong: all parts of the
> refspec are actually optional.

It probably is easier to read, but strictly speaking it is not wrong. The two parts, <src> and <dst>, _always_ exist, even though either or both of them can be an empty string.

Show 12 quoted lines

> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index 6150b1b..df99c0b 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -32,7 +32,7 @@ OPTIONS
>  
>  <refspec>...::
>  	The canonical format of a <refspec> parameter is
> -	`+?<src>:<dst>`; that is, an optional plus `{plus}`, followed
> +	`[+]<src>:<dst>`; that is, an optional plus `{plus}`, followed
>  	by the source ref, followed by a colon `:`, followed by
>  	the destination ref.

I am wondering if it would be clearer and easier to understand if we just said:

  	The canonical format of a <refspec> 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.