kcd - Kriang's Change Directory Version 7.14.0 (Dec 5, 2007) Copyright (c) 1996,1997-9,2000-4,2005 By Kriang Lerdsuwanakij email: lerdsuwa@users.sourceforge.net kcd home page: http://kcd.sourceforge.net Important Notice ================ This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. What Is kcd ? ============= kcd helps you navigate through directories easily in console or terminal command line. A shell alias or function is setup to provide the functionality. You can use it to jump to the desired directory through command line or full screen navigation. It works with shells bash, tcsh, pdksh, zsh, and ash. Although kcd is developed for Linux, it should also work with any UNIX operating system with the right libraries (libc, ncurses and zlib). To compile kcd yourself, you also need a decent C++ compiler. Minimum System Requirements =========================== - Linux or any UNIX-clone operating system. - gcc 3.0 and libstdc++ 3.0 (or newer). - ncurses 4.2 (or newer). - zlib 1.0.4 (or newer). Documentations in the Distribution ================================== README Program usage (This file) INSTALL Installation procedure COPYING GNU General Public License NEWS Summary of changes from previous versions FILELIST List of files and their functions BUGREPORT Instruction for obtaining stack backtrace if kcd dumps core RPM Instruction for generating kcd RPM packages UNICODE Instruction for building kcd with Unicode support TODO To do list for future versions kcd Basics ========== 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 kcd 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 or Ctrl-C. If you know the name of directory you want to change to, for example, `/usr/include', you can type kcd include To save some keystrokes, you can type only a part of `include' such as kcd incl If kcd found from that there are more than 4 directories contain the text `include' or `incl' (for the second example), it will list all matched directories. You can again use arrow keys, Page Up, Page Down, etc. to move the highlight bar to `/usr/include' and press Enter. Alternately, if you have to jump to, say, `/usr/include' that always appears as matched directory number 2 in the list. You can force kcd to jump to that directory immediately without showing a list by specifying this number in the command line as kcd incl 2 If there are less than or equal 4 matched directory, kcd will pick a directory and jump. Repeat the same kcd command, in this case `kcd include' or `kcd incl', will go to the next matched one, and so on. You can use shell's command history for this purpose. For example, in several shells, pressing Up arrow key and Enter will repeat the previous command. You may change the number of matched directory threshold to any value other than 4 by modifying kcd configuration file. See the `Configuration File' section below. On the other hand, if kcd cannot find the requested directory, fuzzy finding mode is used. In fuzzy mode, directories that approximately matches the given text is listed. By default, fuzzy mode will find 10 closest matches. This too can be changed by the configuration file. Special symbols `/' and `//' are available to fine tune directory matching. For example, the command line kcd usr/bin will find any directory containing `bin' such that its immediate parent directory contains `usr'. This matches `/usr/bin', and `/usr/sbin'. On the other hand, the command line kcd usr//bin this will find any directory containing `bin' such that any of its parent directories contain `usr'. This also matches `/usr/local/bin', and `/usr/local/lib/mozilla/bin' for example. Multiple such symbols may appear in the command line such as kcd usr//include//std You may create bookmarks via option `-ba' to help locate frequently accessed directories. When kcd searches for directories matching a given text and finds that at least one is bookmarked, then all non-bookmarked directories are ignored. So bookmarked directories are always chosen over non-bookmarked ones. You can override this behavior by supplying kcd with `-B' option before the text such as kcd -B incl You can also list all bookmarked directory using `-b' option. While in full screen mode, 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. The list of directories used in all operations above is taken from `~/.kcd.save.*.gz'. You may want to update it for added or removed directories. To update the file, type kcd -r This will still use some information from the old file, especially directory time stamp, to speedup directory scanning. If you found that simply using `kcd -r' is not accurate (see the "kcd Command Line Syntaxes" section for possible causes), use `kcd -rf' instead. Directory Tree Window ===================== The directory tree window appears when you type kcd without any other parameter. Following are the meaning of different colors and symbols used to display a directory in the tree. Green (color console) or underlined (B&W console) Accessible normal directories. You can move the highlight bar and press Enter to exit kcd and jump to this directory. Yellow (color console) or underlined bold (B&W console) Accessible symbolic link. If the link points inside the directory tree, selecting this directory will move to the linked directory while remaining in the directory tree window. On the other hand, if it points outside, selecting it will exit kcd and jump to the target directory. Gray (color console) or normal (B&W console) Inaccessible directory. You don't have permission to change into this directory. [skipped] Directory skipped from scanning so that its subdirectories are not displayed. /dev is always skipped since its content is really entry points for kernel drivers and this takes very long time to scan. /proc is also skipped due to continuously changing content. You can configure other directories to skip using `SkipDir' setting. See `Configuration File' section below for more information. [*] Directory is not currently present in the saved file. They are added automatically to the screen when current directory is not in the file. As of the current version of kcd, added directory are not written to file. To update your directory to disk, you have to rescan directory. [unreadable] You don't have either read permission to display the content or execute permission to change to this directory. [outside tree] This is a symbolic link that points outside saved directory tree. Key Binding =========== When kcd is first in full screen display, it stays in the `navigation' mode where you can use arrow keys to move the highlight bar around to any directory you want. There is another mode called `find' mode which highlight bar is restricted to directories that match the string appearing at the bottom of the screen. You can distinguish find mode by the string ` Find: ' displayed at the bottom of the screen. The matching search string is displayed inside the brackets ([...]). Note that strings both before and after `->' of the symbolic links are searched in find mode. Displayed at the last row on screen is the full path name of highlighted directory. Online help also utilizes this area. You can switch between different displays by repeatly pressing F9 key. By default, the key binding used is the one that has been used since kcd version 1.0. It is based on arrow keys, PageUp, PageDown, Home, End and function keys. This is also referred to as kcd mode. Beside this mode, Vi and Emacs key binding modes are provided. You may change the key binding via the KeyBinding configuration command. However, changing the action of individual keys is not available in the current version. kcd Key Binding =============== Note that in kcd key binding mode, you can press Ctrl-F follow by a number key fro 0 to 9 to get the same results as the function keys. This is handy for terminals without function key support. The number 1 to 9 correspond to F1 to F9 respectively. To emulate F10, use number 0. As an example, typing Ctrl-F+1 (Press and hold Ctrl key, press and release F, release Ctrl, then press and release 1) is the same as F1. Navigation Mode =============== Arrow keys, Page up, Page down, Home and End Move the highlight bar. Space bar or Enter If the highlighted directory is a normal directory: Change to that directory and exit. If the highlighted directory is a symbolic link: Move highlight bar to the linked directory. F10 or Ctrl-C Exit without changing directory. F8 Repaint screen. F9 or Ctrl-R 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. 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 If the highlighted directory is a normal directory: Change to that directory and exit. If the highlighted directory is a symbolic link: Move highlight bar to the linked directory. F10 or Ctrl-C Exit without changing directory. F8 or Ctrl-R Repaint screen. Vi Key Binding ============== In this configuration, key binding in navigation mode acts acts like cursor movement while find mode acts like text searching. All arrow keys, PageUp, PageDown, function keys, and Enter retains the same meaning as kcd key binding. Following is the list of keys available. 0, ^ First directory of line $ Last directory of line h, b, B Previous directory l, w, W Next directory k, - Up j, +, _ Down Ctrl-B Previous page Ctrl-F Next page Ctrl-U, Ctrl-Y Scroll up Ctrl-D, Ctrl-E Scroll down gg First page G Last page / Search forward ? Search backward Ctrl-L Refresh screen q, ZQ, Ctrl-C Quit For most commands, a number prefix to indicate the repeat count, such as 5 Ctrl-B representing previous 5 pages, is supported. Emacs Key Binding ================= In this configuration, key binding in navigation mode acts acts like cursor movement while find mode acts like text searching. All arrow keys, PageUp, PageDown, function keys, and Enter retains the same meaning as kcd key binding. Following is the list of keys available. The notation used below is the one used in Emacs. For example, C-b means Ctrl-B while M-b usually means Alt-B. 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 kcd Command Line Syntaxes ========================= kcd Display directory tree and allow you to choose the directory you would like to change to. kcd [-B] [] Search and change to the directory containing the TEXT string. Parent directories are excluded from string searching. For example, the command kcd lin will match /usr/src/linux-2.x.x, /usr/lib/gcc-lib/i486-linux, /usr/doc/SlingShot, etc. It does not match /usr/src/linux-2.x.x/fs because `lin' appear as the parent directory of `fs'. If you want to change to directory that contains some special symbols (for example, `&', `|', etc.), enclose the TEXT string with single quote '...'. For example, kcd 'b&w' Avoid using spaces (very common in VFAT file system) in the TEXT string. Some shell may not correctly parse the string, resulting an error message. NUMBER is the matched directory number used in case of multiple matches. If the option `-B' is specified, all directories are searched, not just the bookmarked ones. kcd -b [] Display bookmarks matching TEXT, or all bookmark if TEXT is not supplied. kcd -ba [ [...]] Bookmark specified directories. If none is specified, the current directory is used. kcd -br [ [...]] Remove bookmark from specified directories. If none is specified, the current directory is used. kcd -M Don't scan directories given by MountDir. kcd -t [] Display partial directory tree beginning with DIR. If DIR is not specified, the current directory is used. kcd -tr [] Like -t but rescan directory tree before display. kcd -T Display full directory tree. kcd --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. kcd --configattr Display current screen attribute configuration. kcd --profiles Display the list of configuration profiles available. kcd --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. UTF-8 support Yes if kcd is compiled with Unicode UTF-8 support. A Unicode enabled terminal is required for proper function. d_type speedup Yes if a faster way to obtain information whether a directory entry is a file or directory is available. kcd -h Display help message. or kcd --help kcd --helpinst Display help for shell alias/function installation. kcd -v Display version number. or kcd --version kcd -r Rescan directory tree using the default mode as specified in configuration file. kcd -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 change may not take effect 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.) kcd -rp Rescan part of directory tree beginning at DIR. kcd -rq Rescan directory tree using the quiet mode, overriding default mode. No current progress is displayed. kcd -rQ Rescan directory tree using the verbose mode (opposite of -rq), overriding default mode. Current checked directory is displayed. 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: -ia, -ic, -if, -ias, -ics, -ifs `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). The syntax for shell function/alias installation is eval `kcdmain