kcd(1)

NAME
kcd - Directory Change Utility

SYNOPSIS
kcd [DIR_SHORTCUT]
kcd [--config] [--configattr] [--features] [-h] [--help] [-r] [-rf] [-rp DIR] [-rq] [-rQ] [-v] [--version] eval `kcdmain [-ia] [-ic] [-if] [-ias KCD_DIR] [-ics KCD_DIR] [-ifs KCD_DIR] `

DESCRIPTION
kcd is a set of programs that help you navigate through directories easily. kcd works by consulting the directory tree file ~/.kcd.save.gz for the list of directories available. 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.

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 CONFIGURATION FILE section below.

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.

  OPTIONS

--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 overrided by ScrollBar command in configuration file.

-h, --help
    Display help message.

--helpinst
    Display help for shell alias/function installation.

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

-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 navigation 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 highlighted 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 directory (using the ls command).

Symbolic links are shown with -> and the destination directory. If the destination directory cannot be found (such as skipped or dangling link), it is marked with [not found]. Note that in find mode, only strings before `->' are searched.

CONFIGURATION FILE
kcd 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 example, 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. All value NOT in double quotes are also case-insensitive. `~' and `~username', where username is an account name, are properly expanded to home directory. Wildcards `*', `?' and regular expressions are not supported.

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
    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 quot ("...").
    Example:    SkipDir = "/cdrom"

StartDir
    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 quot ("..."). If no StartDir is specified, kcd starts scanning from the root directory.
    Example:    StartDir = "~"

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

CaseSensitiveSort (allowed value = yes/no, default value = no)
    Choose between case-sensitive or case-insensive sort. SortTree must not be set to no in order for this to be effective.

ClearSkipDir (allowed value = all/"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")
    Do not use the specified directory previously set as StartDir. If `all' is used, ClearStartDir discards all StartDir 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.

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.

  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 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
The following symbols have special meanings inside double quotes values (such as in SkipDir command):

        \ ' " ` * ? < >

Currently the commands SkipDir, ClearSkipDir, ClearStartDir can accept `*', `?', `[' and `]' and interpret them as shell wildcard pattern. Those wildcards normally does not match `/' and leading `.' but the behavior can be overrided using GlobPath and GlobDot commands respectively. 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 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!)

``' and `'' are not part of wildcards and are reserved for future use.

  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

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

AUTHOR
kcd is copyrighted (c) 1996,1997-9,2000 by Kriang Lerdsuwanakij <lerdsuwa@users.sourceforge.net>. For bug report, visit the program home page is at
http://kcd.sourceforge.net