Re: [PATCH RFC 1/3] add: add new --exclude option to git add

[Junio C Hamano <gitster@pobox.com>]

"Philip Oakley" <philipoakley@iee.org> writes:

> Maybe He/We would be better off adjusting the documentation such that
> these 'magic' capabilities are brought out of their hiding places into
> regular view - e.g. a paragraph within the 'git add' documentation
> (and/or other commands) showing how such excludes are easily done with
> a few simple keystrokes....

I agree documenting is good, but I do not think it belongs to "git
add".  For example, shouldn't "git log -- \*.c ':!secret.c'" work
the same way?

> 'git help revisions' doesn't appear to cover it.

Of course not, because "revisions" would cover revisions, and
pathspecs are different animals ;-) Again, I agree there should be a
section somewhere close to the central place that talks about
pathspecs in general and then talk about pathspec magic there.

There are some references in git(1) but they talk about ways to
implicitly enable the magic to _all_ pathspecs, before introducing
the readers to what the magics are and how they can use them.

Perhaps in git(1), before we introduce "GIT COMMANDS", we may want
to have a new section that talks about the general structure of the
Git command line, laying out the general rules such as

 * dashed options come first
 * revisions and ranges come second
 * pathspecs come last

The first one is described in detail in gitcli(7) and how revisions
are spelled is given in gitrevisions(7).  How pathspecs are spelled
and used may want to be its own gitpathspecs(7), or if there are not
too many rules, can be spelled out there inline.  Either way, we
would want a brief section in git(1) to serve as a jumping board for
the former two, at least. Also descriptions for --literal-pathspecs
and friends would want to refer to either the section or have a
direct reference to gitpathspecs(7) if we are going to write it a
new file.