From: René Scharfe <l.s.r@web.de>
Date: Sat, 31 Aug 2013 07:46:54 GMT
Subject: Re: Officially start moving to the term 'staging area'
Message-ID: <52219F6E.6090605@web.de>
In-Reply-To: <CAMP44s3m_7UffHfie8=_izPt5tCw+9SXPa4sqoHuphuVyTHqcw@mail.gmail.com>

Am 29.08.2013 22:36, schrieb Felipe Contreras:
> On Thu, Aug 29, 2013 at 3:03 PM, René Scharfe <l.s.r@web.de> wrote:
>> If you have a --work-tree option then parseopt accepts --work as well,
>> unless it's ambiguous, i.e. another option starts with --work, too.  So you
>> can have a descriptive, extra-long option and type just a few characters at
>> the same time.
>
> Right, but what do we use in the documentation? Writing --work-tree in
> the 'git reset' table for example would be rather ugly. I'm fine with
> --work-tree, but I think it would be weird to have short-hands in the
> documentation, although not entirely bad.

I don't see what's so ugly about it.

The git command itself has a --work-tree parameter for specifying the 
location of the checked-out files, however.  It could be confusing to 
have the same parameter do different things:

	$ git reset --work-tree=/some/where reset --work-tree

Perhaps a note in the documentation is enough to clear this up.


In general I think that the full long option should be mentioned in 
synopsis and description, while abbreviated parameters could be used in 
an example.  The ability to understand unambiguous shortened options is 
a general feature and doesn't have to be explained in the manpage for a 
specific command.

NB: It would be nice to have more commands use parseopt, for that 
feature alone.

René