NAME

xd - eXtra fast Directory changer

SYNOPSIS

xd [OPTIONS] arguments

DESCRIPTION

The program xd is used to perform eXtra fast Directory changes. Usually to change a directory the user is required to enter a command like, e.g., cd /usr/local/bin, possibly using shell completion. Often this is a tedious task: shell completion shows all entries, including files, when we’re only interested in directories and the full specification of our intented directory may eventually require many keyboard actions.

Xd was designed a long time ago (in the early 90s) to reduce the effort of changing directories. Often we’re well aware to which directory we want to change, and it’s easy to provide the initial directory characters of that directory. E.g., if the intent is to cd to /usr/local/bin, it’s easy to specify the letters ulb.

Xd capitalizes on this capability. By providing the initial directory characters of directories xd determines the expansion(s) allowing you to do fast directory changes. So, after entering the command xd ulb xd may directly perform the change-directory to /usr/local/bin.

Often, however, multiple alternatives can match the specified series of characters. E.g., when entering xd ulb xd may find several alternatives, like

 1: /usr/lib/base-config
 2: /usr/lib/bonobo
 3: /usr/lib/bonobo-activation
 4: /usr/local/bin

If these are the alternatives, then this is exactly what xd shows you. Then, by simply pressing the 4 key (no Enter key required) xd performs the required /usr/local/bin (see also the section DIRECT KEY ENTRY).

Xd’s behavior can be fine-tuned in various ways:

o: by default (as specified by the configuration file, see below) xd looks for expansions starting at the user’s home directory or at the system’s root directory;
o: initial character /: if the first character of the command is / then all expansions are performed from the system’s root directory. E.g., xd /t produces /tmp but not /home/user/tmp;
o: initial character .: if the first character of the command is . then by default all expansions are performed from the user’s home directory. E.g., xd .t results in /home/user/tmp but not in /tmp. The home directory recognition character can be altered using the --homedir-char option, see below (section OPTIONS). When merely specifying xd . then xd changes the current directory to the user’s home directory.
o: initial character 0: If the first character of the command is 0, then all expansions start at the current working directory. When merely specifying xd 0 then xd returns leaving the current directory unchanged. When additional characters are appended to 0 then this command operates like the following, starting from the current working directory;
o: initial character 1..9: If the first character of the command is a digit between 1 and 9 then all expansions start at that parent directory level of the current working directory (up to the system’s root directory). E.g., if the current working directory is /usr/share/doc then xd 2lb will offer the alternative /usr/local/bin: two steps up, then look for directories starting with l and therein directories starting with b. When merely specifying one of these characters xd changes the current directory to the indicated parent, up to the root-directory (e.g., specifying xd 5 at /usr/bin changes the current directory to the root-directory)
o: separators (space, and the forward slash (`/’)): sometimes it is clear that there are many alternatives and the intention is to reduce that number. By using separators subsequently nested directories must start with the characters between the separators. E.g., xd u l bi doesn’t produce the alternative /usr/lib/base-config anymore, since base-config does not start with bi. In this case only /usr/local/bin is produced. When used as initial character in a pattern the forward slash always indicates the root-directory;
o: search patterns may contain dots (like .s). In such cases the dot represents hidden directories. However, xd usually also finds patterns containing /./, as the current directory matches the dot. Such patterns are considered spurious and are not reported.

If there’s only one solution, Xd prepares for a direct directory change to the solution’s directory.

If there are multiple solutions, then by default lists of at most 62 alternatives (10 for the numbers 0..9, 26 for the letters a..z and 26 for the letters A..Z) are written to the standard error stream from which the user may select an alternative by simply pressing the key associated with the selection of choice. If no selection is requested any other key may be pressed (e.g., the space bar or the Enter key). If there is no solutioon xd writes the text No Solutions to the standard error stream.

When xd is given at least one argument, all its output is sent to the standard error stream, except for the selected directory name which should become the next working directory.

Xd may insert the cd command directly into the command shell from where xd was called. See also section SHELL SCRIPTS). In this mode of operation xd returns a single dot if no selection is made, preventing an unintended change of directory.

If no selection is made or if the selection process is aborted a single dot is written to the standard output stream. Usually xd will be called by a shell alias, providing the cd command with xd’s output (see below at the SHELL SCRIPTS section) executing cd `xd $*`. The default dot produced by xd prevents an unintended change of directory.

When xd is merely given an initial directory specification, like a single dot (.) or digit (a digit in the set [0..9]) then xd returns the implied path. Specifying a parent before the root-directory (E.g., entering `xd 5’ when the current working directory is `/tmp’) results in writing the root directory (`/’) to the standard output stream.

If xd is called without arguments its usage information is written to the standard error stream.

Xd may be further configured using options and a configuration file, discussed in the OPTIONS and CONFIGURATION FILE sections below.

DIRECT KEY ENTRY

To pass the directory change command to the shell’s input buffer xd calls the function ioctl(2). That function is still available, although it’s also considered a somewhat deprecated function. But even though it’s available, by default it may not work. The program sysctl(8) shows the values of system variables, among which dev.tty.legacy_tiocsti:

    sysctl -a | grep tiocsti
    dev.tty.legacy_tiocsti = 0

If, at your computer, sysctl shows dev.tty.legacy_tiocsti = 0 then define a file /etc/sysctl.d/tiocsti.conf containing the line

    dev.tty.legacy_tiocsti=1

Then, after rebooting ioctl will work as described in its man-page.

Alternatively, a shell script or alias can be defined to pass the command to your shell. E.g., when using the tcsh shell program the following alias can be defined:

    alias xd ’cd `\xd --no-input \!*`’

Or, when using bash, define a function xd calling, e.g., /usr/bin/xd:

    xd()
    {
        cd `/usr/bin/xd --no-input "$*"`
    }

GENERALIZED DIRECTORY SEARCH

Xd also supports generalized directory search commands (GDS). When GDS is requested separators are no longer required, and xd finds all possible alternatives resulting from all possible sequential combinations of the initial search command. GDS is activated either by specifying the -g option or by entering generalized-search in xd’s configuration file. Alternatively, when the latter is specified then the --traditional command line option suppresses GDS.

When using GDS each initial substring of the command to xd is considered as the initial characters of a directory. E.g., if the command xd tmps is entered using GDS then directories matching the following search patterns will be found;

o: /t*/m*/p*/s*/
o: /t*/m*/ps*/
o: /t*/mp*/s*/
o: /t*/mps*/
o: /tm*/p*/s*/
o: /tm*/ps*/
o: /tmp*/s*/
o: /tmps*/ With the traditional processing mode only the first one of these alternative patterns is considered.

Multiple command line arguments, the slash, and the underscore can still be used with GDS. In this case they force a directory change using the considered patterns. E.g., with the command xd tm/ps the following patterns will be considered:

o: /t*/m*/p*/s*/
o: /t*/m*/ps*/
o: /tm*/p*/s*/
o: /tm*/ps*/ In this set all of the previous patterns showing the ...mp... combination were dropped, as a directory change is forced between the m and p characters.

RETURN VALUES

Xd may return the following values to its caller, allowing scripts calling xd to make decisions that depend on the actually performed action by xd:

o: 0 is returned if xd issued a cd command;
o: 1 is returned if xd received a non-space character, not selecting a directory to change to. When the input option has been specified this character is inserted into the command shell’s input buffer;
o: 2 is returned if xd received a space (or Enter) character, indicating that xd should perform no further action;
o: 3 is returned if no directory was found matching the argument passed to xd;
o: 4 is returned if the --help or --version option was specified (see their descriptions in the OPTIONS section);
o: 5 is returned if an error was encountered (e.g., when a non-existing configuration file is specified).

OPTIONS

If available, single letter options are listed between parentheses following their associated long-option variants. Single letter options require arguments if their associated long options require arguments as well.

Most options can also be specified in xd’s configuration file, in which case the long option variants must be used, omitting the initial two dashes (see the section CONFIGURATION FILE below for specific details about the configuration file.

By default the options can also be specified in the configuration file. If an option cannot be specifiied in the configuration file it is explicitly stated at its description.

Options that are specified as command-line options take priority over options specified in the configuration file.

o: --add-root condition
If the search starts at the user’s home directory an additional search starting at the system’s root directory may be performed as well, depending on the value specified for the add-root option. Conditions are

o: never (no additional search is performed),
o: if-empty (an additional search is performed if the initial search did not yield any directory),
o: always (an additional search is always performed);