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 current directory is used.

-br [DIR [...]]

Remove bookmark from specified directories. If none is specified, 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:

-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 previously saved directory tree information and start scanning from scratch. By default, the smart scan mode is used whenever possible 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 cannot 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 displayed.

-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.

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

/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 directory (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 immediately.

ALTERNATE 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

COMMAND SUMMARY

SkipDir (allowed value = directory /r"directory", optional GlobDot and GlobPath override allowed)

This tell kcd to skip scanning for directories inside the specified 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 directory. 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 directories 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 properly 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 version >= 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. SortTree 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/Yellow/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

<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 displayed 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

\ ' " ` ~

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

*

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 wildcards.

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

SAMPLE CONFIGURATION FILE

# 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

[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 profiles can be introduced using in similar manner. There is no limit on the number of profiles. The only restriction is the name of the profile. The profile name must be a valid C or C++ identifier, i.e., contains 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 specified. 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 configuration of `*'. Afterward, any changes to `*' does not affect the previously 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.

Shell message reporting that it cannot find a particular file or directory (the actual message depends on the shell used).

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:

`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.