[PATCH] keyword: improve help for kwfiles

[Christian Ebert]

* timeless on Sunday, June 28, 2009 at 13:53:35 +0300
> On Sun, Jun 28, 2009 at 1:42 PM, Christian Ebert<blacktrash at gmx.net> wrote:
>> hm, one configures the filenames, not the files themselves I thought ...
> 
> oh gah. fail. i think you want file paths, perhaps. can you provide a
> more detailed explanation?

Yes, the docs for the extension (full to the brim of more pidgin
English), available canonically via

$ hg help keyword
keyword extension - expand keywords in tracked files

This extension expands RCS/CVS-like or self-customized $Keywords$ in
tracked text files selected by your configuration.

Keywords are only expanded in local repositories and not stored in the
change history. The mechanism can be regarded as a convenience for the
current user or for archive distribution.

Configuration is done in the [keyword] and [keywordmaps] sections of
hgrc files.

Example:

    [keyword]
    # expand keywords in every python file except those matching "x*"
    **.py =
    x*    = ignore

Note: the more specific you are in your filename patterns
      the less you lose speed in huge repositories.

For [keywordmaps] template mapping and expansion demonstration and
control run "hg kwdemo".

An additional date template filter {date|utcdate} is provided.

The default template mappings (view with "hg kwdemo -d") can be
replaced with customized keywords and templates. Again, run "hg
kwdemo" to control the results of your config changes.

Before changing/disabling active keywords, run "hg kwshrink" to avoid
the risk of inadvertently storing expanded keywords in the change
history.

To force expansion after enabling it, or a configuration change, run
"hg kwexpand".

Also, when committing with the record extension or using mq's qrecord,
be aware that keywords cannot be updated. Again, run "hg kwexpand" on
the files in question to update keyword expansions after all changes
have been checked in.

Expansions spanning more than one line and incremental expansions,
like CVS' $Log$, are not supported. A keyword template map
"Log = {desc}" expands to the first line of the changeset description.

list of commands:

 kwdemo     print [keywordmaps] configuration and an expansion example
 kwexpand   expand keywords in the working directory
 kwfiles    print filenames configured for keyword expansion
 kwshrink   revert expanded keywords in the working directory

enabled extensions:

 keyword     expand keywords in tracked files

use "hg -v help keyword" to show aliases and global options

> is it possible to match this/file and not that/file ?

Yes.
 
>> I wanted to emphasize the fact that this command is (just) a
>> configuration check.
> 
> i'd still prefer list or something...

Sure.

>> $ echo 'c = ignore' >> .hg/hgrc
>> $ hg kwfiles -a -u
>> K a
>> K b
>> I c
> 
> How did anyone know that K/? meant?

*K*eyword expansion candidate?

(not *K*ellogg's *K*orn Flakes ;-) )

To someone already familiar with the flags of "hg status" not
that difficult a guess, I thought. But something analogous to the
status help would be:

    With -a/--all and -v/--verbose the codes used to show the status
    of files are:
    K = keyword expansion candidate
    I = ignored

c
-- 
_B A U S T E L L E N_ lesen! --->> <http://www.blacktrash.org/baustellen/>