.TH "xd" "1" "1994\-2013" "xd\&.3\&.22\&.09\&.tar\&.gz" "xd \- fast directory changes" .PP .SH "NAME" xd \- eXtra fast Directory changer .PP .SH "SYNOPSIS" \fBxd\fP [OPTIONS] \fIarguments\fP .PP .SH "DESCRIPTION" .PP The program \fBxd\fP is used to perform e\fBX\fPtra fast \fBD\fPirectory changes\&. Usually to change a directory the user is required to enter a command like, e\&.g\&., \fIcd /usr/local/bin\fP, possibly with the aid of shell completion\&. In many cases this is a tedious task: shell completion shows all entries, including files, when we\(cq\&re only interested in directories and the full specification of our intented directory may eventually require many keyboard actions\&. .PP \fBXd\fP was designed a long time ago (in the early 90s) to reduce the effort of changing a directory\&. Often we\(cq\&re well aware to which directory we want to change, and it\(cq\&s easy to produce the initial directory characters of that directory\&. E\&.g\&., if the intent is to \fIcd\fP to \fI/usr/local/bin\fP, it\(cq\&s rather easy to produce the letters \fIulb\fP\&. .PP \fBXd\fP capitalizes on this capability\&. By providing the initial directory characters of directories \fBxd\fP will determine the proper expansion allowing you to change directories fast\&. So, entering the command \fIxd ulb\fP will result in the expansion \fI/usr/local/bin\fP\&. .PP Often life is not that easy\&. Often there are multiple expansions from a given set of initial characters\&. E\&.g\&., when entering \fIxd ulb\fP \fBxd\fP may find several alternatives\&. E\&.g\&., .nf 1: /usr/lib/base\-config 2: /usr/lib/bonobo 3: /usr/lib/bonobo\-activation 4: /usr/local/bin .fi If these are the alternatives, this is exactly what \fBxd\fP will show you\&. Then, by simply pressing the \fI3\fP key (\fIno\fP \fIEnter\fP key required) \fBxd\fP will produce the required \fI/usr/local/bin\fP\&. .PP Commands to \fBxd\fP can be specified so as to fine\-tune \fBxd\fP\(cq\&s behavior: .IP o By default (as specified by the configuration file, see below) expansions may start at the user\(cq\&s home directory or at the system\(cq\&s root directory\&. .IP o Initial character \fB/\fP: If the first character of the command is \fI/\fP all expansions will be performed from the system\(cq\&s root directory\&. E\&.g\&., \fIxd /t\fP will result in \fI/tmp\fP but not in \fI/home/user/tmp\fP\&. .IP o Initial character \fB\&.\fP: If the first character of the command is \fI\&.\fP all expansions will be performed from the user\(cq\&s home directory\&. E\&.g\&., \fIxd \&.t\fP will result in \fI/home/user/tmp\fP but not in \fI/tmp\fP .IP o Initial character \fB0\fP: If the first character of the command is \fI0\fP, all expansions will start at the current working directory\&. In fact, this is a specialization of the following, more general form: .IP o Initial character \fB1\&.\&.9\fP: If the first character of the command is a digit between \fI1\fP and \fI9\fP all expansions will start at that parent directory level of the current working directory (up to the system\(cq\&s root directory)\&. E\&.g\&., if the current working directory is \fI/usr/share/doc\fP then \fIxd 2lb\fP will offer the alterative \fI/usr/local/bin\fP: two steps up, then look for directories starting with \fIl\fP and therein directories starting with \fIb\fP\&. .IP o Separators (space, forward slash and underscore (\fI \fP, / 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\&., \fIxd u l bi\fP will not produce the alternative \fI/usr/lib/base\-config\fP anymore, since \fIbase\-config\fP does not start with \fIbi\fP\&. In this case only \fI/usr/local/bin\fP is produced\&. Separators may be mixed (\fIxd u/l bi\fP is identical to \fIxd u l bi\fP)\&. Since the \fI/\fP can also be used as a root\-directory specification, a conflict is implied by a command like \fIxd /u l bi\fP\&. 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)\&. .PP If there\(cq\&s only one solution, \fBXd\fP 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 \fIEnter\fP key)\&. If there is no solutioon \fBxd\fP will write the text \fINo Solutions\fP to the standard error stream\&. .PP When \fIxd\fP 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 \fIxd\fP will be called by a shell alias, providing the \fIcd\fP command with \fBxd\fP\(cq\&s output (see below at the \fBSHELL SCRIPTS\fP section) executing \fIcd `xd $*`\fP\&. The default dot produced by \fBxd\fP will then prevent a unintended change of directory\&. .PP If \fBxd\fP is called without arguments then \fIusage\fP information is written to the standard error stream\&. .PP \fBXd\fP may be further configured using options and a configuration file, discussed in the \fBOPTIONS\fP and \fBCONFIGURATION FILE\fP sections below\&. .PP .SH "GENERALIZED DIRECTORY SEARCH" .PP Starting with version 3\&.10\&.0 \fBxd\fP also supports generalized directory search command processing (GDS)\&. When GDS is requested separators are no longer required, and \fBxd\fP will find all posible alternatives resulting from all possible sequential combinations of the initial search command\&. GDS is activated either by specifying the \fI\-g\fP command line flag or by entering \fIgeneralized\-search\fP in \fBxd\fP\(cq\&s configuration file\&. Alternatively, when the latter is specified then the \fI\-\-traditional\fP command line option will suppress GDS\&. .PP Under GDS each initial substring of the command to \fBxd\fP will be considered as the initial characters of a directory\&. E\&.g\&., if the command \fIxd tmps\fP is entered using GDS then directories matching the following search patterns will be found; .IP o \fI/t*/m*/p*/s*/\fP .IP o \fI/t*/m*/ps*/\fP .IP o \fI/t*/mp*/s*/\fP .IP o \fI/t*/mps*/\fP .IP o \fI/tm*/p*/s*/\fP .IP o \fI/tm*/ps*/\fP .IP o \fI/tmp*/s*/\fP .IP o \fI/tmps*/\fP Only the first of these will be considered under the traditional processing mode\&. .PP 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 \fIxd tm/ps\fP the following patterns will be considered: .IP o \fI/t*/m*/p*/s*/\fP .IP o \fI/t*/m*/ps*/\fP .IP o \fI/tm*/p*/s*/\fP .IP o \fI/tm*/ps*/\fP In this set all of the previous patterns showing the \fI\&.\&.\&.mp\&.\&.\&.\fP combination were dropped, as a directory change is forced between the \fIm\fP and \fIp\fP characters\&. .PP .SH "RETURN VALUE" .PP \fBXd\fP returns 0 to the operating system unless an error occurs (e\&.g\&., when a non\-existing configuration file is specified), or \fBxd\fP\(cq\&s version or usage info is shown or requested\&. .PP .SH "OPTIONS" .PP 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\&. .IP o \fB\-\-add\-root\fP \fIcondition\fP .br If the search starts at the user\(cq\&s home directory an additional search starting at the system\(cq\&s root directory may be performed as well, depending on the value specified for the \fIadd\-root\fP option\&. Alternatives are \fInever\fP (no additional search is performed); \fIif\-empty\fP (an additional search is performed if the initial search did not yield any directory); or \fIalways\fP (an additional search is always performed)\&. There is also a configuration file directive \fIadd\-root\fP (see below)\&. .IP .IP o \fB\-\-all\fP \fB\-a\fP .br If the configuration file (see below) contains \fIignore\fP directives then these directives are ignored when computing the alternatives from which the user may select a directory to change to\&. .IP .IP o \fB\-\-config\-file\fP=\fIfilename\fP (\fB\-c\fP) .br The name of an \fBxd\fP configuration file\&. By default \fBxd\fP will look for the file \fI\&.xdrc\fP in the user\(cq\&s home directory\&. The existence of the default file is optional\&. .IP .IP o \fB\-\-directories\fP \fIinclusion\fP .br Directories may be also be reached via symbolic links\&. The inclusion type \fIall\fP will add these symbolic links to the list of alternatives\&. The inclusion type \fIunique\fP will prevent the symbolic links from being added to the list of alternatives\&. There is also a configuration file directive \fIdirectives\fP (see below)\&. .IP .IP o \fB\-\-generalized\-search\fP \fB\-g\fP .br When this option is specified \fBxd\fP will use GDS unless the directive \fItraditional\fP is specified in the configuration file\&. .IP .IP o \fB\-\-help\fP (\fB\-h\fP) .br Basic usage information is written to the standard error stream\&. .IP .IP o \fB\-\-history\fP \fI[filename]\fP .br A history of previously made choices is kept in the file \fIfilename\fP\&. If \fI\-\-history\fP is specified, but the filename is left empty the history file \fI$HOME/\&.xd\&.his\fP is used\&. This file should only be modified by \fIxd\fP itself\&. If you can\(cq\&t resist editing it then use the following example showing the format of the lines in the history file\&. .nf 1292596154 1 /home/frank/svn/xd/ .fi 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\&. .IP .IP o \fB\-\-history\-lifetime\fP \fIspec\fP .br The lifetime of the entries in the history file\&. The specification consists of a number followed by \fID, W, M\fP or \fIY\fP, 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 \fI1M\fP (one month) is used\&. Entries older than \fIhistory\-lifetime\fP are disregarded as history\-items and are removed from the history file\&. .IP .IP o \fB\-\-history\-maxsize\fP \fInr\fP .br The maximum number of entries the history file may contain\&. By default there is no limit\&. When \fIhistory\-maxsize\fP is specified and more than the maximum number of history items are found in the history file then the \fInr\fP 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\&. .IP .IP o \fB\-\-history\-position\fP \fI[top|bottom]\fP .br 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 \fIhistory\-separate\fP is only used when this option is also specified\&. By merely specifying \fIhistory\-position\fP the history items are shown at the top of the list\&. .IP .IP o \fB\-\-history\-separate\fP .br 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\&. .IP .IP o \fB\-\-start\-at\fP \fIorigin\fP .br Defines the default start location of directory searches\&. Origin \fIhome\fP results in all default searches to start at the user\(cq\&s home directory\&. Origin \fIroot\fP results in searches to begin at the disk\(cq\&s root (\fI/\fP) directory\&. There is also a configuration file directive \fIstart\-at\fP (see below)\&. .IP .IP o \fB\-\-traditional\fP .br When this option is specified \fBxd\fP will not use GDS but will use its traditional mode\&. It overrules a \fIgeneralized\-search\fP directive specified in the configuration file as well as the \fI\-g\fP option\&. .IP .IP o \fB\-\-verbose\fP (\fB\-V\fP) .br More extensive information about the actions taken by the \fBxd\fP program is written to the standard error stream\&. .IP .IP o \fB\-\-version\fP (\fB\-v\fP) .br \fBXd\fP\(cq\&s version number is written to the standard error stream\&. .PP .SH "CONFGURATION FILE" .PP The default configuration file is \fI\&.xdrc\fP in the user\(cq\&s home directory\&. It may be overruled by the program\(cq\&s \fI\-\-debug\fP flag\&. .PP Empty lines are ignored\&. Information at and beyond \fI#\fP\-characters is interpreted as comment and is ignored as well\&. .PP All directives in \fBxd\fP configuration files follow the pattern .nf directive value .fi but for some directives \fIvalue\fP is optional\&. .PP 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 \fIlast\fP directive will be used (with the exception of the \fIignore\fP directive, see below)\&. All directives are interpreted \fIcase sensitively\fP\&. Non\-empty lines not beginning with a recognized directive are silently ignored\&. .PP The following directives can be used in the configuration file\&. Default values are shown between parentheses\&. .IP o \fBadd\-root\fP \fIwhen\fP (if\-empty) .br If the search starts at the user\(cq\&s home directory an additional search starting at the system\(cq\&s root directory may be performed as well, depending on the value specified for the \fIadd\-root\fP directive\&. .br If \fIwhen\fP is specified as \fIalways\fP then an additional search is always performed\&. .br If it is specified as \fIif\-empty\fP then an additional search is performed if the initial search (starting at the user\(cq\&s home directory) did not yield any directory\&. .br If it is specified as \fInever\fP no additional search is performed\&. .br This directive is overruled by the \fI\-\-\-add\-root\fP command line option\&. .IP .IP o \fBdirectories\fP \fIwhich\fP (all) .br Directories may be also be reached via symbolic links\&. The specification \fIall\fP will add these symbolic links to the list of alternatives\&. The specification \fIunique\fP will prevent the symbolic links from being added to the list of alternatives\&. .br This directive is overruled by the \fI\-\-\-directories\fP command line option\&. .IP .IP o \fBgeneralized\-search\fP .br When this directive is specified \fBxd\fP will use GDS by default\&. .IP .IP o \fBhistory\fP \fI[filename]\fP .br A history of previously made choices is kept in the file \fIfilename\fP\&. If \fIhistory\fP is specified, but the filename is left empty the history file \fI$HOME/\&.xd\&.his\fP is used\&. This file should only be modified by \fIxd\fP itself\&. If you can\(cq\&t resist editing it then use the following example showing the format of the lines in the history file\&. .nf 1292596154 1 /home/frank/svn/xd/ .fi 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\&. .IP .IP o \fBhistory\-lifetime\fP \fIspec\fP .br The lifetime of the entries in the history file\&. The specification consists of a number followed by \fID, W, M\fP or \fIY\fP, 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 \fI1M\fP (one month) is used\&. Entries older than \fIhistory\-lifetime\fP are disregarded as history\-items and are removed from the history file\&. .IP .IP o \fBhistory\-maxsize\fP \fInr\fP .br The maximum number of entries the history file may contain\&. By default there is no limit\&. When \fIhistory\-maxsize\fP is specified and more than the maximum number of history items are found in the history file then the \fInr\fP 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\&. .IP .IP o \fBhistory\-position\fP \fI[top|bottom]\fP .br 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 \fIhistory\-separate\fP is only used when this directive is also specified\&. By merely specifying \fIhistory\-position\fP the history items are shown at the top of the list\&. .IP .IP o \fBhistory\-separate\fP .br 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\&. .IP .IP o \fBignore\fP \fIpath\fP .br The configuration file may contain multiple \fIignore\fP directives which are \-\-different from the way other directives are handled\-\- all interpreted\&. Each \fIignore\fP directive is followed by a path specification as shown in a list of alternatives produced by \fBxd\fP or an initial substring of such a path terminating in a \fI*\fP character\&. When \fBxd\fP encounters a path matching any of the \fIignore\fP directives (with the \fI*\fP interpreted as `any further directory name\(cq\& specification) it will not display that path in its list of alternatives\&. This directive is overruled by the \fI\-\-\-all\fP command line option\&. .IP .IP o \fBstart\-at\fP \fIvalue\fP (home) .br Defines the default start location of directory searches\&. Values are \fIhome\fP and \fIroot\fP\&. When \fIhome\fP is specified all searches start at the user\(cq\&s home directory\&. When \fIroot\fP is specified searches start at the disk\(cq\&s root (\fI/\fP) directory\&. If the directory is omitted or if another value is specified then the default is used, which is \fIhome\fP\&. This directive is overruled by the \fI\-\-\-start\-at\fP command line option\&. .IP .IP o \fBtraditional\fP .br This directive may be used to request the use of \fBxd\fP\(cq\&s traditional mode\&. It overrules the \fI\-g\fP command line option and the \fIgeneralized\-search\fP directive\&. ) .PP .SH "SHELL SCRIPTS" .PP Assuming \fBxd\fP is installed in \fI/usr/bin\fP scripts can be defined around \fBxd\fP for various shell programs\&. This allows the shell to change directories under control of \fBxd\fP\&. .PP To use \fBxd\fP with the \fBbash\fP(1)\-shell, the following script can be used (to be added to, e\&.g\&., \fI\&.profile\fP): .nf xd() # function to do `cd` using `xd` { cd `/usr/bin/xd $*` } .fi .PP To use \fBxd\fP with the \fBtcsh\fP(1)\-shell, the following alias can be added to, e\&.g\&., the \fI~/\&.alias\fP file: .nf alias xd \(cq\&cd `\exd \e!*`\(cq\& .fi Having defined the \fIxd\fP alias or script \fIxd \&.\&.\&.\fP commands will result in the automatic or selected change of the current working directory .PP .SH "EXAMPLES" .PP .nf 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\(cq\& (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 .fi Assuming the following directories exist: .nf /usr/lib/bonobo /usr/lib/bonobo\-activation /usr/local/bin .fi then the following two \fIignore\fP specifications in \fBxd\fP\(cq\&s configuration file will result in ignoring the \fIbonobo\fP directory alternatives: .PP First specification: .nf ignore /usr/lib/bonobo ignore /usr/lib/bonobo\-activation .fi Second specification: .nf ignore /usr/lib/bonobo* .fi .PP .SH "FILES" .IP o \fB$HOME/\&.xdrc\fP: Default location of the configuration file .IP o \fIhttp://xd\-home\&.sourceforge\&.net/\fP: Home directory .PP .SH "BUGS" .PP None reported .PP .SH "ABOUT xd" .PP The program \fBxd\fP 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 \fBC++\fP\&. The original \fBC++\fP code is still available (\fIhttps://oosix\&.icce\&.rug\&.nl/svnroot/xd/tags/start/xd/\fP) and is funny to look at as it is a remarkable illustration of \fBC++\fP code written by \fBC\fP programmers who had just learned about \fBC++\fP\&. Versions \fI2\&.x\fP have been used until 2008, and in late August 2008 I rewrote \fBxd\fP completely, reflecting my current views about \fBC++\fP, resulting in versions \fI3\&.x\&.y\fP and beyond\&. The \fI3\&.x\&.y\fP and later versions extensively use the facilities offered by the \fBbobcat\fP(7) library\&. .PP .SH "ACKNOWLEDGEMENTS" .PP GDS was added to \fBxd\fP following a suggestion by Bram Neijt (bram at neijt dot nl)\&. .PP .SH "AUTHOR" .PP Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl)\&.