Re: [PATCH RFC 1/3] add: add new --exclude option to git add
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 15, 2015, 21:50 UTC
- Message-ID
- <xmqq4mpmszf2.fsf@gitster.dls.corp.google.com>
- In-Reply-To
- <D9562ECC995343B3A51D449DC2B46CBC@PhilipOakley>
"Philip Oakley" <philipoakley@iee.org> writes:
Show 5 quoted lines
> 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.