I have often found the "Keyword Substitution" selection names in IDEA's CVS dialogs confusing and misleading. IMHO, the names used do not match the terms and names used in the most of the literature in the industry.
While I find a couple of IDEA's names confusion, I especially find the "no substitution" name very misleading. When I do a merge between two branches, I want to use a
-kk switch, as recommended in section
5.10 Merging and keywords
of the Cederqvist manual. This prevents "numerous conflicts during the merge, because
[without the -kk switch] the keywords are expanded differently in the revisions which you are merging."
Since I tend to think of
-kk as either "keywords-only" or "no values" – or possibly "no values substitution" – I often mistakenly select the "no substitution" option in IDEA, with is actually the
-kko switch. IMHO, "no substitution" makes no sense as a name for the -ko switch since it does substitute a value for the keyword; it substitutes the "old keyword string". Also, I do not logically associated "compression" with
-kk. I suppose one could argue that since it doesn't expand the keyword to the keyword and its value, it compresses it to just the keyword, but IMHO that is not an intuitive thought process.
Below is how the keyword modes are described in what I believe to be the most prevalent and reliable sources. All the sources typically have a common word or phrase in their definitions, which I have highlighted.
| IDEA current |
switch |
client help 1 |
CVS Pocket Ref 2 |
Cederqvist Manual 3 |
| expansion |
kkv |
(Default) Substitute keyword and value |
Keyword-Value mode |
Generate keyword strings using the default form |
| expansion locker |
kkvl |
Substitute keyword, value, and locker (if any) |
Keyword-Value-Locker mode |
Like `-kkv', except that a locker's name is always inserted if the given revision is currently locked. |
| compression |
kk |
Substitute keyword only |
Keyword-Only mode |
Generate only keyword names in keyword strings; omit their values |
| no substitution |
ko |
Preserve original string |
Old-Contents mode |
Generate the old keyword string, present in the working file just before it was checked in. |
| binary |
kb |
Mark file as binary |
Binary mode |
Like `-ko', but also inhibit conversion of line endings between the canonical form in which they are stored in the repository (linefeed only), and the form appropriate to the operating system in use on the client. |
| replacement |
kv |
Substitute value only |
Value-Only mode |
Generate only keyword values for keyword strings. |
In the very least, I believe the -kk "compression" and -ko "no substitution" names need to change. I also think the
-kv "replacement" name could be improved by changing it. I think the
-kkv "expansion" and
-kkvl "expansion locker" names work ok, but still would like to see them conform to the cvs client help information. At the very least, it might be nice to add "(CVS Default)" to the expansion name. Also as mention in JIRA IDEA-16043 that I opened, I think the names should show the actual swith to avoid all confusion. Here are my recommendations:
| switch |
current name |
recommended new name |
Severity |
| kkv |
expansion |
keyword & value (cvs default) -kkv |
low |
| kkvl |
expansion locker |
keyword & value with locker -kkvl |
low |
| kk |
compression |
keyword only -kk |
high |
| ko |
no substituion |
preserve old keyword & value -ko |
high |
| kb |
binary |
binary -kb |
na |
| kv |
replacement |
value only -kv |
medium |
I realize some of the recommended names are a bit long, but I beleive them to be the best choices for matching typical names.
References
1) cvs client ouput to command
cvs -H admin
2)
CVS Pocket Reference Guide, O'Reilly Publishing, ISBN 0-596-00003-0
3) Cederqvist Manual section
12.4 Substitution modes,
http://cvshome.org/cvs/manual/cvs-1.12.13/cvs_12.html#SEC103