[PATCH] keyword: improve help for kwfiles

[Christian Ebert]

* timeless on Sunday, June 28, 2009 at 08:13:10 +0300
> On Fri, Jun 26, 2009 at 6:36 PM, Christian Ebert<blacktrash at gmx.net> wrote:
> 
>> -    '''print files currently configured for keyword expansion
> 
> i actually want to use "files",

hm, one configures the filenames, not the files themselves I thought ...

>> +    Check which filenames in the working directory are matched by the
>> +    [keyword] configuration patterns.
> 
> "check" is odd. do you mean "list", "show", or something else?

I wanted to emphasize the fact that this command is (just) a
configuration check.

>> +    Useful to prevent inadvertent keyword expansion and to exclude
>> +    binary files from being being processed by the extension
>> +    (speed up).
> 
>> +    Use "hg kwfiles -u" to display untracked filenames as well.
> 
> without a hint for recognizing which is which, this is really odd :)

Well, the complete help output in crew is:

hg kwfiles [OPTION]... [FILE]...

print filenames configured for keyword expansion

    Check which filenames in the working directory are matched by the
    [keyword] configuration patterns.

    Useful to prevent inadvertent keyword expansion and to speed up
    execution by including only filenames that are actual candidates
    for expansion.

    Use -u/--untracked to display untracked filenames as well.

options:

 -a --all        show keyword status flags of all files
 -i --ignore     show files excluded from expansion
 -u --untracked  additionally show untracked files
 -I --include    include names matching the given patterns
 -X --exclude    exclude names matching the given patterns

use "hg -v help kwfiles" to show global options

So, -a/-all shows, errmh, all files with a corresponding flag.

Perhaps an example makes this clearer:

$ cat .hg/hgrc
[keyword]
** =
$ hg kwfiles
a
b
$ hg kwfiles -a
K a
K b
$ hg kwfiles -u
a
b
c
$ hg kwfiles -a -u
K a
K b
K c

So, file c is untracked, but a potential candidate for expansion.
Suppose a want to hg add it and do not want keywords expanded in
it, I can now exclude it:

$ echo 'c = ignore' >> .hg/hgrc
$ hg kwfiles -a -u
K a
K b
I c
$ hg kwfiles -a
K a
K b
$ hg kwfiles
a
b
$ hg kwfiles -u
a
b

So, -u/--untracked means that untracked files are included in the
check, test, probing, or whatever you call it.

c
-- 
\black\trash movie    _C O W B O Y_  _C A N O E_  _C O M A_
Ein deutscher Western/A German Western
-->> http://www.blacktrash.org/underdogma/ccc.html
-->> http://www.blacktrash.org/underdogma/ccc-en.html