NAME¶
xd - eXtra fast Directory changer
SYNOPSIS¶
xd [OPTIONS]
arguments
DESCRIPTION¶
The program
xd is used to perform e
Xtra 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
- --history [filename]
A history of previously made choices is kept in the file filename. If
--history is specified, but the filename is left empty the history
file $HOME/.xd.his is used. This file should only be modified by
xd itself. If you can’t resist editing it then use the
following example showing the format of the lines in the history file.
1292596154 1 /home/frank/svn/xd/
The first field is the time (in seconds since the epoch) the entry was
written, the second field is the number of times the entry has been
selected and the third field is the associated path.
- o
- --history-lifetime spec
The lifetime of the entries in the history file. The specification consists
of a number followed by D, W, M or Y, representing, resp.
days, weeks, months, or years. A month is considered a period of 30 days,
a year a period of 365 days. If the specification is omitted a lifetime of
1M (one month) is used. Entries older than history-lifetime
are disregarded as history-items and are removed from the history
file.
- o
- --history-maxsize nr
The maximum number of entries the history file may contain. By default there
is no limit. When history-maxsize is specified and more than the
maximum number of history items are found in the history file then the
nr most popular choices are kept. Usually the cut-off point will be
somewhere within a popularity category. In that case the most recently
selected alternatives within that category are kept.
- o
- --history-position [top|bottom]
When specified alternatives found in the history will be displayed either at
the top of the list or at the bottom of the list. If this option is
omitted then the elements in the history will be intermixed with new
alternatives. The next option history-separate is only used when
this option is also specified. By merely specifying
history-position the history items are shown at the top of the
list.
- o
- --history-separate
When specified, a blank line is written between the items in the history and
new alternatives (not previously selected). This option is only
interpreted when the previous option is also specified.
- 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
but for some directives
value is optional.
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 configuration 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
- history [filename]
A history of previously made choices is kept in the file filename. If
history is specified, but the filename is left empty the history
file $HOME/.xd.his is used. This file should only be modified by
xd itself. If you can’t resist editing it then use the
following example showing the format of the lines in the history file.
1292596154 1 /home/frank/svn/xd/
The first field is the time (in seconds since the epoch) the entry was
written, the second field is the number of times the entry has been
selected and the third field is the associated path.
- o
- history-lifetime spec
The lifetime of the entries in the history file. The specification consists
of a number followed by D, W, M or Y, representing, resp.
days, weeks, months, or years. A month is considered a period of 30 days,
a year a period of 365 days. If the specification is omitted a lifetime of
1M (one month) is used. Entries older than history-lifetime
are disregarded as history-items and are removed from the history
file.
- o
- history-maxsize nr
The maximum number of entries the history file may contain. By default there
is no limit. When history-maxsize is specified and more than the
maximum number of history items are found in the history file then the
nr latest choices are kept. Each previously made selection counts
as one. If a new alternative is selected it always becomes an element in
the history list.
- o
- history-position [top|bottom]
When specified alternatives found in the history will be displayed either at
the top of the list or at the bottom of the list. If this option is
omitted then the elements in the history will be intermixed with new
alternatives. The next directive history-separate is only used when
this directive is also specified. By merely specifying
history-position the history items are shown at the top of the
list.
- o
- history-separate
When specified, a blank line is written between the items in the history and
new alternatives (not previously selected). This directive is only
interpreted when the previous directive is also specified.
- 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).