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 with the aid of shell completion. In
many cases 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 a directory. Often we’re well aware to which directory we
want to change, and it’s easy to produce the initial directory
characters of that directory. E.g., if the intent is to cd to
/usr/local/bin, it’s rather easy to produce the letters ulb.
Xd capitalizes on this capability. By providing the initial directory
characters of directories xd will determine the proper expansion
allowing you to change directories fast. So, entering the command xd
ulb will result in the expansion /usr/local/bin.
Often life is not that easy. Often there are multiple expansions from a
given set of initial characters. E.g., when entering xd ulb xd may find
several alternatives. E.g.,
1: /usr/lib/base-config
2: /usr/lib/bonobo
3: /usr/lib/bonobo-activation
4: /usr/local/bin
If these are the alternatives, this is exactly what xd will show you.
Then, by simply pressing the 3 key (no Enter key required) xd will
produce the required /usr/local/bin.
Commands to xd can be specified so as to fine-tune xd’s behavior:
o By default (as specified by the configuration file, see below)
expansions may start at the user’s home directory or at the
system’s root directory.
o Initial character /: If the first character of the command is /
all expansions will be performed from the system’s root
directory. E.g., xd /t will result in /tmp but not in
/home/user/tmp.
o Initial character .: If the first character of the command is .
all expansions will be performed from the user’s home directory.
E.g., xd .t will result in /home/user/tmp but not in /tmp
o Initial character 0: If the first character of the command is 0,
all expansions will start at the current working directory. In
fact, this is a specialization of the following, more general
form:
o Initial character 1..9: If the first character of the command is
a digit between 1 and 9 all expansions will 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 alterative
/usr/local/bin: two steps up, then look for directories starting
with l and therein directories starting with b.
o Separators (space, forward slash and underscore ( , / and _)):
sometimes it is clear that there are many alternatives and the
intention is to reduce that number. By using a separator
subsequently nested directories must start with the characters
between the separators. E.g., xd u l bi will not 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.
Separators may be mixed (xd u/l bi is identical to xd u l bi).
Since the / can also be used as a root-directory specification,
a conflict is implied by a command like xd /u l bi. This
conflict is solved by given the initial character a higher
precedence than the separator. Using the underscore (_)
separator in this case is another way to solve the conflict
(which in practice hardly ever occurs).
If there’s only one solution, Xd will write that directory to its
standard output stream. If there are multiple solutions, a list of at
most 62 alternatives (10 for the numbers 0..9, 26 for the letters a..z
and 26 for the letters A..Z) will be 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 will write 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, but for the selected directory name which is
written to the standard output stream. 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
will then prevent a unintended change of directory.
If xd is called without arguments then 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.
GENERALIZED DIRECTORY SEARCH
Starting with version 3.10.0 xd also supports generalized directory
search command processing (GDS). When GDS is requested separators are
no longer required, and xd will find all posible alternatives resulting
from all possible sequential combinations of the initial search
command. GDS is activated either by specifying the -g command line flag
or by entering generalized-search in xd’s configuration file.
Alternatively, when the latter is specified then the --traditional
command line option will suppress GDS.
Under GDS each initial substring of the command to xd will be
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*/ Only the first of these will be considered under the
traditional processing mode.
Multiple command line arguments, the slash and the underscore can still
be used with GDS in which case they force a directory change in 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 VALUE
Xd returns 0 to the operating system unless an error occurs (e.g., when
a non-existing configuration file is specified), or xd’s version or
usage info is shown or requested.
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.
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. Alternatives are never (no additional search is
performed); if-empty (an additional search is performed if the
initial search did not yield any directory); or always (an
additional search is always performed). There is also a
configuration file directive add-root (see below).
o --all -a
If the configuration file (see below) contains ignore directives
then these directives are ignored when computing the
alternatives from which the user may select a directory to
change to.
o --config-file=filename (-c)
The name of an xd configuration file. By default xd will look
for the file .xdrc in the user’s home directory. The existence
of the default file is optional.
o --directories inclusion
Directories may be also be reached via symbolic links. The
inclusion type all will add these symbolic links to the list of
alternatives. The inclusion type unique will prevent the
symbolic links from being added to the list of alternatives.
There is also a configuration file directive directives (see
below).
o --generalized-search -g
When this option is specified xd will use GDS unless the
directive traditional is specified in the configuration file.
o --help (-h)
Basic usage information is written to the standard error stream.
o --start-at origin
Defines the default start location of directory searches. Origin
home results in all default searches to start at the user’s home
directory. Origin root results in searches to begin at the
disk’s root (/) directory. There is also a configuration file
directive start-at (see below).
o --traditional
When this option is specified xd will not use GDS but will use
its traditional mode. It overrules a generalized-search
directive specified in the configuration file as well as the -g
option.
o --verbose (-V)
More extensive information about the actions taken by the xd
program is written to the standard error stream.
o --version (-v)
Xd’s version number is written to the standard error stream.
CONFGURATION FILE
The default configuration file is .xdrc in the user’s home directory.
It may be overruled by the program’s --debug flag.
Empty lines are ignored. Information at and beyond #-characters is
interpreted as comment and is ignored as well.
All directives in xd configuration files follow the pattern
directive value
A line may at most contain one directive, but white space (including
comment at the end of the line) is OK. The same directive may be
specified multiple times, in which case the last directive will be used
(with the exception of the ignore directive, see below). All directives
are interpreted case sensitively. Non-empty lines not beginning with a
recognized directive are silently ignored.
The following directives can be used in the initial section of the
grammar specification file. Default values are shown between
parentheses.
o add-root when (if-empty)
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
directive.
If when is specified as always then an additional search is
always performed.
If it is specified as if-empty then an additional search is
performed if the initial search (starting at the user’s home
directory) did not yield any directory.
If it is specified as never no additional search is performed.
This directive is overruled by the ---add-root command line
option.
o directories which (all)
Directories may be also be reached via symbolic links. The
specification all will add these symbolic links to the list of
alternatives. The specification unique will prevent the symbolic
links from being added to the list of alternatives.
This directive is overruled by the ---directories command line
option.
o generalized-search
When this directive is specified xd will use GDS by default.
o ignore path
The configuration file may contain multiple ignore directives
which are --different from the way other directives are
handled-- all interpreted. Each ignore directive is followed by
a path specification as shown in a list of alternatives produced
by xd or an initial substring of such a path terminating in a *
character. When xd encounters a path matching any of the ignore
directives (with the * interpreted as ‘any further directory
name’ specification) it will not display that path in its list
of alternatives. This directive is overruled by the ---all
command line option.
o start-at value (home)
Defines the default start location of directory searches. Values
are home and root. When home is specified all searches start at
the user’s home directory. When root is specified searches start
at the disk’s root (/) directory. If the directory is omitted or
if another value is specified then the default is used, which is
home. This directive is overruled by the ---start-at command
line option.
o traditional
This directive may be used to request the use of xd’s
traditional mode. It overrules the -g command line option and
the generalized-search directive. )
SHELL SCRIPTS
Assuming xd is installed in /usr/bin scripts can be defined around xd
for various shell programs. This allows the shell to change directories
under control of xd.
To use xd with the bash(1)-shell, the following script can be used (to
be added to, e.g., .profile):
xd() # function to do ‘cd‘ using ‘xd‘
{
cd ‘/usr/bin/xd $*‘
}
To use xd with the tcsh(1)-shell, the following alias can be added to,
e.g., the ~/.alias file:
alias xd ’cd ‘\xd \!*‘’
Having defined the xd alias or script xd ... commands will result in
the automatic or selected change of the current working directory
EXAMPLES
xd ulb - all directories starting subsequently,
with u, l and b origin is default, or
specified in .xdrc as home or root
xd 0t - all directories starting with t below the cwd
xd 2t - all directories starting at the ‘grandparent’
(2 steps up) of the cwd
xd --start-at root t
- all directories at the root starting with t
xd .. - all directories starting with a dot in the cwd
Assuming the following directories exist:
/usr/lib/bonobo
/usr/lib/bonobo-activation
/usr/local/bin
then the following two ignore specifications in xd’s configuration file
will result in ignoring the bonobo directory alternatives:
First specification:
ignore /usr/lib/bonobo
ignore /usr/lib/bonobo-activation
Second specification:
ignore /usr/lib/bonobo*
FILES
o $HOME/.xdrc: Default location of the configuration file
o http://xd-home.sourceforge.net/: Home directory
BUGS
None reported
ABOUT xd
The program xd was initially (before 1994) written for the MS-DOS
platform. In 1994 it was designed to work under Unix (Linux, AIX) and
it was converted to C++. The original C++ code is still available
(https://oosix.icce.rug.nl/svnroot/xd/tags/start/xd/) and is funny to
look at as it is a remarkable illustration of C++ code written by C
programmers who had just learned about C++. Versions 2.x have been used
until 2008, and in late August 2008 I rewrote xd completely, reflecting
my current views about C++, resulting in versions 3.x.y and beyond. The
3.x.y and later versions extensively use the facilities offered by the
bobcat(7) library.
ACKNOWLEDGEMENTS
GDS was added to xd following a suggestion by Bram Neijt (bram at neijt
dot nl).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).