kcd(1)kcd(1)NAMEkcd - Directory Change Utility
SYNOPSISkcd [-B] [DIR_SHORTCUT] [MATCH_NUMBER]
kcd [-b DIR_SHORTCUT] [-ba [DIR [...]]] [-br [DIR [...]]] [--config]
[--configattr] [--features] [-h] [--help] [-M] [-p PROFILE] [-r] [-rf]
[-rp DIR] [-rq] [-rQ] [-t [DIR]] [-tr [DIR]] [-T] [-v] [--version]
eval `kcdmain [-ia] [-ic] [-if] [-ias KCD_DIR] [-ics KCD_DIR] [-ifs
KCD_DIR] `
DESCRIPTIONkcd is a set of programs that help you navigate through directories
easily. kcd works by consulting the directory tree file for the list
of directories available. By default the file is named
~/.kcd.save.kcd.gz but may change according to the kcd configuration
file. This file is automatically created when kcd is run for the first
time.
When you type the command without any parameter, it will display the
saved entire directory tree and place the highlight bar on the current
directory. You can use arrow keys, Page Up, Page Down, Home and End
keys to move the highlight bar to the desired directory. Pressing
Enter will exit kcd and jump the the selected directory. If you choose
to remain in the current directory, just press F10.
Besides using arrow keys, etc. to move the highlight bar, you may type
the some text string to limit the highlight bar to move between items
containing the string. The text string is shown at the bottom of the
screen inside [...]. To restore highlight bar behavior, press Tab
key.
If you know the name of directory you want to change to, you can type
only a part of directory name as DIR_SHORTCUT parameter. If kcd found
from that there are more than 4 directories contain the text, it will
list all matched directories. You can again use arrow keys, Page Up,
Page Down, etc. to move the highlight bar and press Enter. If there
are less than or equal 4 matched directory, kcd will pick a directory
and jump. Repeat the same kcd command will go to the next matched one,
and so on. You may change the number of matched directory threshold to
any value other than 4 by modifying configuration file. See the CON‐
FIGURATION FILE section below. Optionally, you may specify MATCH_NUM‐
BER so that the directory corresponding to the number in the matched
list is used and kcd jump to that directory immediately.
The DIR_SHORTCUT may contain special symbols / and // to force the
matching of parent directories as well. For example
kcd usr/bin
matches /usr/bin and /usr/sbin but not /usr/local/bin since the direc‐
tory containing usr and bin must appeared right next to each other. On
the other hand
kcd usr//bin
allows any number of directories between the usr and bin and also
matches /usr/local/bin and /usr/local/lib/mozilla/bin.
OPTIONS
-b [DIR_SHORTCUT]
Display bookmarks matching DIR_SHORTCUT, or all bookmark if
DIR_SHORTCUT is not supplied.
-ba [DIR [...]]
Bookmark specified directories. If none is specified, the cur‐
rent directory is used.
-br [DIR [...]]
Remove bookmark from specified directories. If none is speci‐
fied, the current directory is used.
-B Search all directories, not just bookmarked ones.
--config
Display current configuration (excluding screen attributes)
obtained from SYSCONFDIR/kcd.conf and ~/.kcd.conf. SYSCONFDIR
is the directory given to --sysconfdir option during configure,
which usually is /etc, /usr/etc or /usr/local/etc.
--configattr
Display current screen attribute configuration.
--features
Display availability of all features:
xterm/rxvt resize
Yes if kcd can redraw itself if the size of xterm/rxvt
terminal changes.
mouse support
Yes if kcd can response to mouse click.
default scroll bar
Yes if scroll bar will be used. It can be overridden by
ScrollBar command in configuration file.
-h, --help
Display help message.
--helpinst
Display help for shell alias/function installation.
-M Don't scan directories given by MountDir.
-p PROFILE
Use the specified configuration profile. This must be the first
option present in the command line.
--profiles
Display the list of configuration profiles available.
-r Rescan directory tree using the default mode as specified in
configuration file.
-rf Rescan directory using full scan mode. kcd will ignore all pre‐
viously saved directory tree information and start scanning from
scratch. By default, the smart scan mode is used whenever pos‐
sible to reduce time needed for directory scanning.
The full scan mode is provided in case you change configuration
files - some command may not affect directory tree until you
rescan in full mode.
Another possible problem is that some old file system may not
have the change time (which is updated when directory permission
is changed) so that kcd cannot correctly update the directory
tree. (msdos file system is an example, but fortunately we can‐
not change their directory permission anyway.)
-rp DIR
Rescan part of directory tree beginning at DIR.
-rq Rescan directory tree using the quiet mode, overriding default
mode. No current progress is displayed.
-rQ Rescan directory tree using the verbose mode (opposite of -rq ),
overriding default mode. Current checked directory is dis‐
played.
-t [DIR]
Display partial directory tree beginning with DIR. If DIR is
not specified, the current directory is used.
-tr [DIR]
Like -t but rescan directory tree before display.
-T Display full directory tree.
-v, --version
Display version number.
Rescan options can be combined, i.e., `kcd -rf -rq' is the same as `kcd
-rfq'.
Following parameters are useful when you type `kcd' and get a command
not found error. `kcd' is actually a shell function or shell alias so
it must be setup before you can type any kcd command. You will have to
use `kcdmain' as the command name (since kcd command is not available
yet).
-ia Install shell alias when kcd is installed in /usr/bin.
-ic Install shell alias for csh or tcsh when kcd is installed in
/usr/bin.
-if Install shell function when kcd is installed in /usr/bin.
-ias KCD_DIR
Install shell alias when kcd is installed in the specified
directory KCD_DIR.
-ics KCD_DIR
Install shell alias for csh or tcsh when kcd is installed in the
specified directory KCD_DIR.
-ifs KCD_DIR
Install shell function when kcd is installed in the specified
directory KCD_DIR.
DIRECTORY TREE WINDOW
The directory tree window appears when you type kcd without any other
parameter. Initially kcd is in the navigation mode. You can use
arrow keys to move the highlight bar to any directory you want. There
is another mode called find mode which can be distinguish from naviga‐
tion mode by the string ` Find: ' displayed at the bottom of the
screen. Pressing arrow keys will move the highlight bar to the nearest
directory containing the search string inside the brackets ([...]).
Displayed at the last row on screen is the full path name of high‐
lighted directory.
KEYS IN NAVIGATION MODE
Arrow keys, Page up, Page down, Home and End
Move the highlight bar.
Space bar or Enter
Change to the highlighted directory and exit.
F10 or ^C (Ctrl-C)
Exit without changing directory.
F8 Repaint screen.
F9 Switch between status display: Destination directory <--> Key
help.
Center key on numeric keypad
Center highlight bar on the middle of the screen.
Characters from `a' to `z', from `A' to `Z' and from `0' to `9'
Switch to find mode.
`,' and `.'
Panning screen left/right. This works when the directory tree
is too wide to fit the screen.
KEYS IN FIND MODE
Any characters, Ins, Del, Backspace, left arrow, right arrow
Edit search string
Up arrow or Page up, down arrow or Page down
Go to the previous or next directory that match the search
string
Backspace or Del when the search string is empty or Tab
Return to navigation mode
Space bar or Enter
Change to the highlighted directory and exit.
F10 or ^C (Ctrl-C)
Exit without changing directory.
F8 Repaint screen.
For terminals without function keys, you can press ^F+num where num is
from 0 to 9 to get the same result. ^F+1 (Press and hold `Ctrl' key,
press and release `F', release `Ctrl', then press `1') is the same as
F1. Similarly ^F+2 to ^F+9 correspond to F2 to F9 respectively. To
emulate F10, use ^F+0.
DIRECTORY LEGENDS
All accessible directories (except links) are shown as green (color
console) or underlined (B&W console) and can be selected.
/dev and /proc plus other directories specified in SkipDir setting are
shown with [skipped]. Subdirectories inside skipped directories are
not displayed but you may able to access them using shell's cd command.
Directories with [*] means that it is not present in the saved file.
They are added automatically to the screen when current directory is
not in the file. The changes are not written to the file. So you have
to rescan directory if you do not intend to skip them.
Directories without execute permission are shown with [unreadable].
You cannot change to this directory.
Directories without read permission but with execute permission are
also shown with [unreadable] you cannot read the content of the direc‐
tory (using the ls command).
Symbolic links are shown with -> and the destination directory.
Selecting a symbolic link will jump to its destination directory while
still staying in kcd. You can navigate further or just press Enter to
jump there. Some symbolic links may point to a directory outside the
saved directory tree given in the StartDir configuration command.
These are displayed with [outside tree] Enter will jump there immedi‐
ately.
ALTERNATE KEY BINDING
You may change the keys used in kcd via KeyBinding configuration com‐
mands. Besides the default or kcd mode, Vi and Emacs modes are avail‐
able. The following is the summary of keys available in these two
modes. All arrow key, PageUp, PageDown, function keys retains the same
meaning as the default key binding.
Vi Mode
0, ^ First directory of line
$ Last directory of line
h, b, B
Previous directory
l, w, W
Next directory
k, - Up
j, +, _
Down
^B Previous page
^F Next page
^U, ^Y Scroll up
^D, ^E Scroll down
gg First page
G Last page
/ Search forward
? Search backward
^L Refresh screen
q, ZQ, ^C
Quit
For most commands, a number prefix to indicate the repeat count, such
as 5^B representing previous 5 pages, is supported.
Emacs mode
C-a First directory of line
C-e Last directory of line
C-b, M-b
Previous directory
C-f, M-f
Next directory
C-p Up
C-n Down
M-v Previous page
C-v Next page
C-s Search forward
C-r Search backward
C-c Quit
CONFIGURATION FILEkcd consults settings in /etc/kcd.conf, /usr/etc/kcd.conf,
/usr/local/etc/kcd.conf and ~/.kcd.conf, (in that order), each time the
program executes if available. Commands in the latter configuration
file will usually override the former one. However, you have to use
the ClearStartDir and ClearSkipDir commands in ~/.kcd.conf, for exam‐
ple, if you want to undo StartDir and SkipDir commands in
/etc/kcd.conf.
The syntax of each command is
command_name = value
All command names are case-insensitive. Values, however, depends on
whether the command requests a double quoted value or not. Only values
NOT in double quotes are treated as case-insensitive.
There are 2 possible ways to specify value for double quoted string:
glob, and regular expression.
Glob uses characters like `?' and `*' as wildcards. It is placed
within a pair of double quotes like "/usr/lib/lib*".
Regular expression uses extended regular expression format and is
placed within double quotes prefixed by either `R' or `r' such as
r"/usr/lib/lib[a-z]-.*". kcd automatically adds a `^' and `$' at the
beginning and the end of string, respectively.
The symbol `#' serves as comment and all characters starting from `#'
till end of line are ignored. The `#' inside double quotes, however,
will be treated as part of value passed to the command.
COMMAND SUMMARY
SkipDir (allowed value = directory /r"directory", optional GlobDot
and GlobPath override allowed)
This tell kcd to skip scanning for directories inside the speci‐
fied directory name. Multiple SkipDir commands are allowed.
/dev and /proc are automatically excluded from the list of
directories to be scanned. Directory name must be inside a pair
of double quote ("...").
You may override the current GlobDot and GlobPath settings for
this SkipDir command. Just specify each setting separated by
comma after the directory name.
Example: SkipDir = "/cdrom"
SkipDir = "~/*rc", GlobDot=yes
StartDir (allowed value = directory )
This tell kcd to start scanning from the specified directories.
Multiple StartDir commands are allowed. In that case, kcd will
generate output containing multiple directory trees. Directory
name must be inside a pair of double quote ("..."). If no
StartDir is specified, kcd starts scanning from the root direc‐
tory. Wild cards are not supported by StartDir.
Example: StartDir = "~"
MountDir (allowed value = directory , with optional actions
All/Tree/Skip)
This tell kcd to handle the specified directory according to the
action given:
All Always scan regardless if search string is provided in the
command line.
Tree Scan only when search string is not supplied.
Skip Always skip scanning.
If the action is not provided, the default Skip action is used.
Multiple actions, separated by commas can be specified. However
this is intended for features to be introduced later.
Wild cards are not supported by MountDir.
Example: MountDir = "/mnt/floppy", Skip
MountDir = "/mnt/usb", All
Note: Directories given by MountDir should not overlap. The
following does not work
MountDir = "/mnt/mount_c", All
MountDir = "/mnt/mount_c/temp", Skip
Use the following instead
MountDir = "/mnt/mount_c", All
SkipDir = "/mnt/mount_c/temp"
QuietFullScan (allowed value = yes/no, default value = no)
This command toggle progress report when kcd scan for directo‐
ries using full scan mode. Only the last QuietFullScan command
are effective. This option can be overridden by -rq or -rQ.
Example: QuietFullScan = yes
QuietSmartScan (allowed value = yes/no, default value = no)
This command is similar to QuietFullScan but is intended for
smart scan mode. This option can be overridden by `-rq' or
`-rQ'.
QuietPartialScan (allowed value = yes/no, default value = no)
This command is similar to QuietFullScan but is intended for
`-rp' option. This option can be overridden by `-rq' or `-rQ'.
SortTree (allowed value = yes/no, default value = yes)
This command cause kcd to sort the directory tree. If you
change the SortTree value from yes to no, directory tree must
be rescanned using full scan mode to make this command to prop‐
erly restore the original order.
GraphicChar (allowed value = yes/no, default value = yes)
Choose whether special line graphic and arrow characters are
used. If `no' is given, simple characters such as `+', `|',
`>', etc. is used instead.
ScrollBar (allowed value = yes/no, default value = yes for ncurses ver‐
sion >= 4.2)
Choose whether scroll bars will be displayed.
MouseScrollRate (allowed value: any number >= 0, default value = 2)
Select scrolling rate when mouse button is held down. Unit is
in 0.1 sec. Set to 0 disable this feature.
CaseSensitiveSort (allowed value = yes/no, default value = no)
Choose between case-sensitive or case-insensitive sort. Sort‐
Tree must be set to yes in order for this to be effective.
ClearSkipDir (allowed value = all/"directory"/r"directory")
Do not skip the specified directory previously set as SkipDir.
If `all' is used, ClearSkipDir discards all directory. /dev and
/proc are not affected by this command.
Example: ClearSkipDir = all
ClearSkipDir = "/dosc"
ClearStartDir (allowed value = all/"directory"/r"directory")
Do not use the specified directory previously set as StartDir.
If `all' is used, ClearStartDir discards all StartDir directory.
ClearMountDir (allowed value = all/"directory"/r"directory")
Do not use the specified directory previously set as MountDir.
If `all' is used, ClearMountDir discards all MountDir directory.
SpaceSelect (allowed value = yes/no, default value = yes)
Setting this to no, when in find mode, pressing spacebar will
not select the highlighted directory but proceed looking for the
directory containing the space.
ShowListThreshold (allowed value: any numbers >= 0, default value =
4)
If the number of matched directories given in the command line
is less than or equal this number, kcd will jump immediately.
Otherwise, the list of all matches are shown.
ShowNewDir (allowed value = yes/no/multi, default value = multi
Choose whether the new directory will be displayed when kcd
decides to jump without showing list of matches. `Multi' means
display only when there are multiple matches.
FuzzySize (allowed value: any numbers >= 0, default value = 10)
If there is no matched directories given in the command line,
kcd will search for directories that provide the closest match.
The number of matches is given by this configuration.
GlobDot (allowed value = yes/no, default value = no)
Select whether wildcard can match the leading `.' in the path
name. It effects only commands following it.
GlobPath (allowed value = yes/no, default value = no)
Select whether wildcard can match the `/' in the path name. It
effects only commands following it.
DefaultBackground (allowed value = Black/Red/Green/Yel‐
low/Blue/Magenta/Cyan/White, default value = Black)
Select background color for the directory tree window.
DefaultTree (allowed value = quoted string)
This specifies the default subtree displayed in directory tree
mode. It can be overriden by `-t' or `-T' options.
KeyBinding (allowed value = default/kcd/vi/emacs, default value =
default)
Select a particular key binding.
SCREEN ATTRIBUTE COMMAND SUMMARY
Screen attribute command for color display has the following syntax:
<ITEM>ColorAttr = [normal | <ATTR> ...] <FG_COLOR> on <BG_COLOR>
while for black and white display is:
<ITEM>BWAttr = [normal | <ATTR>]
Available values for <ITEM>:
Normal Majority of main window area, including line drawing characters,
inaccessible directories, [*], [skipped] and [unreadable].
Dir Directory names.
HighlightDir
Highlighted directory names.
SymLink
Symbolic links.
HighlightSymLink
Highlighted symbolic links.
Title Program name, text entered in find mode.
Status Status bar.
More Small area on rightmost column of display area that `+' is dis‐
played when window content is too wide to fit on the screen.
ScrollArrow
Arrows on the scroll bars.
ScrollBlock
The moving block on the scroll bars.
ScrollBar
Background of the scroll bars.
Available values for <ATTR>:
Standout Underline Reverse Blink Dim Bold
Available values for <FG_COLOR> and <BG_COLOR>:
Black Red Green Yellow
Blue Magenta Cyan White
<BG_COLOR> can also be Default which means that the background color of
the directory tree window is used here.
Example: # Change both foreground and background
NormalColorAttr = cyan on black
DirColorAttr = bold red on blue
SymLinkColorAttr = blue on white
# Change only foreground
NormalColorAttr = cyan on default
# For black and white display
NormalBWAttr = normal
DirBWAttr = underline
TitleBWAttr = bold reverse
Note: Whether a particular combination of attributes and/or colors
works is terminal dependent.
QUOTING RULES
The following symbols have special meanings inside double quotes values
(such as in SkipDir command):
\ ' " ` ~
and
* ? [ ]
for glob, or
^ . [ ] $ ( ) | * + ? { }
for regular expression. Currently the commands SkipDir, ClearSkipDir,
ClearStartDir, ClearMountDir can accept glob or regular expression.
`~' and `~username', where username is an account name, are properly
expanded to home directory when it appears at the beginning of the
string. The special symbols ``' and `'' are reserved for future use.
Control characters can be entered using \xHH quoting where HH is the
hexadecimal value of the character.
GLOB SPECIAL CHARACTERS
Shell wildcards normally does not match `/' and the leading `.' but the
behavior can be overridden using GlobPath and GlobDot commands respec‐
tively. Here is the list of wildcard pattern that kcd recognizes:
* Match any characters
? Match single character
[set] Match single character in the set Example: "lib[cm]" matches
libc and libm.
[!set] Match single character not in the set Example: "lib[!m]" matches
libc but not libm.
[^set] Same as [!set] but only available if in some cases. If glibc is
your C library (true on Linux), it works when the environment
variable POSIXLY_CORRECT is not set.
[from-to]
Match single character within the range Example: "x[a-m]m"
matches xbm but not xpm.
[:class:]
Match single character in the class where class can be one of
alpha upper lower digit alnum
xdigit space print punct graph cntrl blank
Example:
SkipDir = "~/.*"
SkipDir = "~/*/CVS"
Note that the matching rules depends on the C library in your system.
The above rules apply when you have POSIX.2 conforming library. System
with older libraries may not accept some of the rules.
If you want these symbols inside double quotes to actually refer to the
characters. You have to add an extra `\' in front of them. Note that
here, `*'band `?' refer to characters inside directory name, not wild‐
cards.
For example:
SkipDir = "~/\`Cool\?\'"
is used to skip the directory named
`Cool?'
(the enclosing quotes and the question mark are parts of the directory
name) inside your home directory. (You may not know that can created
this kind of weird directory name!)
REGULAR EXPRESSION SPECIAL CHARACTERS
For information check Section 7 of `regex' man pages, i.e., type `man 7
regex' in command line.
SAMPLE CONFIGURATION FILE
Following is for directory tree starting from root directory:
# Sample configuration file for kcd
SkipDir = "/cdrom" # Ignore cdrom mounting point
SkipDir = "/dosc" # MSDOS C: partition
Following is for directory tree starting from home directory:
# Another sample configuration file for kcd
StartDir = "~" # Start from home directory
SkipDir = "~/.terminfo" # No scan inside .terminfo
QuietFullScan = yes
QuietSmartScan = yes
PROFILES
This feature allows kcd to behave differently depending on the invoked
profile name. The following is an example of configuration file con‐
taining multiple profiles.
[kcd]
StartDir = "/"
[hcd]
StartDir = "~"
With the example above, two shell functions/aliases are introduced,
`kcd' and `hcd'. If you type `kcd' in the command line, the entire
system is searched and displayed. But if you want to restrict to only
inside home directory, you can use `hcd' command instead. More pro‐
files can be introduced using in similar manner. There is no limit on
the number of profiles. The only restriction is the name of the pro‐
file. The profile name must be a valid C or C++ identifier, i.e., con‐
tains only alphanumeric characters or underscore and must not begin
with a number.
There are two special profiles, `*' and `kcd'. The `*' profile is the
default profile and is used for commands when no profile name is speci‐
fied. The `kcd' profile is always created regardless if it actually
appears in the configuration file. An ordinary profile (including
`kcd'), when declared, will be initialized from the current configura‐
tion of `*'. Afterward, any changes to `*' does not affect the previ‐
ously initialized one. Here is an example.
ShowListThreshold = 3 # No profile specified yet,
# store in [*]
[kcd] # Copy configuration from [*]
# So the ShowListThreshold
# command also applies to [kcd]
StartDir = "/"
[*]
SkipDir = "~/.*" # Add SkipDir command to [*]
# Does not affect [kcd]
[hcd] # Inherit ShowListThreshold
# and SkipDir from [*]
StartDir = "~"
[ucd] # Inherit ShowListThreshold
# and SkipDir from [*]
StartDir = "/home"
Note: Profile may not work on some shells such as ash. bash and tcsh
work fine.
COMMON ERROR MESSAGES
Shell message reporting that it cannot find a particular file or directory
(the actual message depends on the shell used).
For example, bash displays `bash: dirname: No such file or directory'
Cause: kcd attempts to change to a directory that no longer exists.
Solution:
Rescan directory.
`kcd: cannot find a link containing the string ...'
Cause: kcd cannot find any directory matching specified string given in
the command line. This may due to:
1. There may be some typos in directory name given.
Solution: Retype the correct name.
2. The desired directory is created after the last directory
scan.
Solution: Rescan directory.
3. kcd has been configured to skip it.
Solution: Change directory manually by the `cd' command or mod‐
ify the configuration file (See the previous section).
`kcd: your ncurses library is bad. Refer to kcd README file for solution'
Cause:
1. ncurses library (libncurses.a or libncurses.so.X.X.X) in /usr/lib)
and header file (/usr/include/curses.h) do not match.
2. The library is built based using a different configuration, compiler
or library that is incompatible with the current installed ones.
3. The library is built not to support C++ applications.
Solution:
Recompile kcd.
AUTHORkcd is copyrighted (c) 1996,1997-9,2000-4,2005 by Kriang Lerdsuwanakij
<lerdsuwa@users.sourceforge.net>. For bug report, visit the program
home page is at
http://kcd.sourceforge.net
Version 7.15.0kcd Reference Manual kcd(1)
