Subject: Re: [FAQ?] Rationale for git's way to manage the index

From: Jakub Narebski <[email-masked]>
Date: Sat, 12 May 2007 11:35:12 +0200

Junio C Hamano wrote:
> Jakub Narebski <[email-masked]> writes:
> 
> > -'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...
> > +'git-add' [-n] [-v] [-f] (-u [[--] <file>...] | [--] <file>...)
> 
> I do not think this is correct; does -u take optionally path and
> when path is ambiguous you can add -- to disambiguate?
> 
> Honestly, I would rather not sprinkle synopsis with too many
> nested parentheses and brackets, which only makes it harder to
> see without giving a clear "this combines with that but is not
> compatible with the other" information.  Adding comment to the
> section that begins with "-u::" that says "... commit -a; this
> option does not take any paths parameters." would be cleaner,
> and easier to understand.
> 
> Of course, I would prefer a patch to allow use of paths with -u
> even more, but that is what I already said ;-).

This synopisis is for _after_ patch mentioned above. If you don't
like too complicated (too deeply nested) expression in synopsis, it
could always be written as:

-'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>...
+'git-add' [-n] [-v] [-f] [--] <file>...
+'git-add' [-n] [-v] [-f] -u [[--] <file>...]

or something like that
-- 
Jakub Narebski
Poland