From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 31 Oct 2008 05:35:50 GMT
Subject: Re: [PATCH 1/7] Documentation: do not use regexp in refspec descriptions
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:

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

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