z/README

Z(1)				  User Commands				     Z(1)



NAME
       z - jump around


SYNOPSIS
       z [-h] [-l] [-r] [-t] [regex1 regex2 ... regexn]


AVAILABILITY
       bash, zsh


DESCRIPTION
       Tracks your most used directories, based on 'frecency'.

       After a short learning phase, z will take you to the most 'frecent' direc‐
       tory that matches ALL of the regexes given on the command line.


OPTIONS
       -h show a brief help message
       -l list only
       -r match by rank only
       -t match by recent access only


EXAMPLES
       z foo	 cd to most frecent dir matching foo
       z foo bar cd to most frecent dir matching foo and bar
       z -r foo	 cd to highest ranked dir matching foo
       z -t foo	 cd to most recently accessed dir matching foo
       z -l foo	 list all dirs matching foo (by frecency)


NOTES
       Installation:

       Optionally:
	Set $_Z_CMD in .bashrc/.zshrc to change the command (default z).
	Set $_Z_DATA to change the datafile (default $HOME/.z).

       Put something like this in your $HOME/.bashrc:

	. /path/to/z.sh

       Put something like this in your $HOME/.zshrc:

	. /path/to/z.sh
	function precmd () {
	  _z --add "$(pwd -P)"
	}

       cd around for a while to build up the db.

       PROFIT!!

       Optionally:
	Install the provided man page z.1 somewhere like /usr/local/man/man1.

       Aging:

       The rank of directories maintained by z undergoes aging based on a  simple
       formula.	 The rank of each entry is incremented every time it is accessed.
       When the sum of ranks is greater than 1000, all ranks  are  multiplied  by
       0.9. Entries with a rank lower than 1 are forgotten.

       Frecency:

       Frecency	 is  a	portmantaeu of 'recent' and 'frequency'. It is a weighted
       rank that depends on how often and how recently something occured. As  far
       as I know, Mozilla came up with the term.

       To z, a directory that has low ranking but has been accessed recently will
       quickly have higher rank than a directory accessed frequently a long  time
       ago.

       Frecency is determined at runtime.

       Common:

       When  multiple  directories  match all queries, and they all have a common
       prefix, z will cd to the shortest matching directory,  without  regard  to
       priority.   This has been in effect, if undocumented, for quite some time,
       but should probably be configurable or reconsidered.

       Tab Completion

       z supports tab completion. After any number of  arguments,  press  TAB  to
       complete	 on  directories  that match each argument. Due to limitations of
       the completion implementations, only the last argument will  be	completed
       in the shell.

       Internally,  z  decides you've requested a completion if the last argument
       passed is an absolute path to an existing directory. This may cause  unex‐
       pected behavior if the last argument to z begins with /.


ENVIRONMENT
       A function _z() is defined.

       An alias $_Z_CMD='_z 2>&1' is defined. If not set, $_Z_CMD defaults to z.

       In  bash,  z  uses the PROMPT_COMMAND environment variable to maintain its
       database. Specifically it prepends:

	_z --add "$(pwd -P 2>/dev/null)" 2>/dev/null;

       to any existing PROMPT_COMMAND. zsh users need to manually set precmd() as
       described in the installation instructions.


FILES
       Data is stored in $_Z_DATA. If not set, $_Z_DATA defaults to $HOME/.z

       A man page (z.1) is provided.


SEE ALSO
       regex(7), cdargs, pushd, popd, autojump, cdargs

       Please file bugs at https://github.com/rupa/z/



z				  February 2011				     Z(1)