Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
A fork of `z' by rupa deadwyler with much improved zsh/bash completion and better results. The data file format and core algorithm are compatible with those of the original. http://blog.akinori.org/2013/03/06/kn…
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
Z(1) User Commands Manual Z(1) NAME z -- jump around SYNOPSIS z [-hclrtx] [string ...] 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' directory that matches all of the patterns given on the command line. Each pattern is a substring that the directory to look for must contain, not a regular expression like in the original version nor a glob pattern that you can use in shell completion described below. For convenience, a trailing slash in a pattern is treated specially so that the pattern also matches directories ending with the pattern string minus the trailing slash. That is, for instance, a pattern `log/' matches /var/log as well as /service/nginx/log/main, but not /home/user/logs. In addition to this, a double slash at the beginning or at the end of a pattern has special meanings. A double slash at the beginning denotes the root directory, and a double slash at the end denotes the end of a path. That is, a pattern `//var' matches /var/log but does not match /home/user/var/log, and a pattern `src//' matches /home/user/src/screen/src but does not match /home/user/src/screen. The $HOME part in a directory name is excluded before matching so that a word or substring that is in your account name does not hit every single directory under your home directory. OPTIONS -h Show a brief help message. -c Restrict matches to subdirectories of the current directory. -l List only. -r Sort by rank instead of `frecency'. -t Sort by recency instead of `frecency'. -x Remove the current directory from the datafile. Nonexistent directories are omitted from output and ignored in moving and completion but kept in database for future use. In listing, only top 20 directories are shown if stdout is a terminal. To show all, run z with a pipe, like `z | cat' or `z | less'. EXAMPLES z foo cd to most frecent directory matching foo z foo bar cd to most frecent directory matching foo and bar z -r foo cd to highest ranked directory matching foo z -t foo cd to most recently accessed directory matching foo z -l foo list all directories matching foo (by frecency) NOTES Installation: 1. Source z.sh from your $HOME/.bashrc or $HOME/.zshrc like this: . /path/to/z.sh Note that if you are using bash: - The line should go something like this: [[ -z $PS1 ]] || . /path/to/z.sh because bash(1) in some cases reads $HOME/.bashrc when the shell is not interactive and z.sh will emit an error message in that case. - The line should better be put after defining a completion method for cd if any, because z.sh tries to enhance an existing completion definition. 2. cd around for a while to build up the db. 3. PROFIT!! Optionally: Set _Z_CMD to change the command name (default `z'). Set _Z_DATA to change the data file name (default `$HOME/.z'). Set _Z_NO_COMPLETE_CD to disable advanced completion for cd. Set _Z_NO_RESOLVE_SYMLINKS to prevent symlink resolution. Set _Z_NO_PROMPT_COMMAND to handle PROMPT_COMMAND (bash) / precmd (zsh) yourself. Set _Z_EXCLUDE_DIRS to an array of directories to exclude. These settings should go in .bashrc / .zshrc before the line added above. Install the provided man page z.1 to somewhere in the man path 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 6000, all ranks are multiplied by 0.99. Entries with a rank lower than 1 are forgotten. Frecency: Frecency is a portmanteau of `recent' and `frequency'. It is a weighted rank that depends on how often and how recently something occurred. 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. Shell Completion: z supports interactive shell completion. After typing a string fragment, press TAB to complete on directories that matches the pattern. In addition to the double slash notation described above, and glob matching works here. z also enhances the completion for the cd command so you don't even need to learn about z at all. If you don't like this feature, it can be disabled. See the next section. ENVIRONMENT A function _z_cmd() is defined. The contents of the variable _Z_CMD is aliased to `_z_cmd'. If not set, _Z_CMD defaults to z. The environment variable _Z_DATA can be used to control the data file location. If it is not defined, the location defaults to `$HOME/.z'. The environment variable _Z_NO_RESOLVE_SYMLINKS can be set to prevent resolving of symlinks. If it is not set, symbolic links will be resolved when added to the data file. In bash, z prepends a command to the PROMPT_COMMAND environment variable to maintain its database. In zsh, z appends a function _z_precmd to the precmd_functions array. The environment variable _Z_NO_COMPLETE_CD can be set to disable advanced completion for cd. The environment variable _Z_NO_PROMPT_COMMAND can be set if you want to handle PROMPT_COMMAND or precmd yourself. The environment variable _Z_EXCLUDE_DIRS can be set to an array of directories to exclude from tracking. HOME is always excluded. Each element must be an absolute path, and if it ends with a slash, all its subdirectories are also excluded. FILES Data is stored in $HOME/.z. This can be overridden by setting the _Z_DATA environment variable. When initialized, z will raise an error if this path is a directory, and not function correctly. A man page (z.1) is provided. SEE ALSO autojump(1), bash(1), cdargs(1), j(1), zshall(1) AUTHORS rupa deadwyler <email@example.com> Akinori MUSHA <knu@iDaemons.org> HISTORY z was originally deveoloped by rupa deadwyler as a successor to j(1), a python free alternative to Joel Schaerer's autojump(1). The original version is maintained at <https://github.com/rupa/z>. This fork was started by Akinori MUSHA in early 2013 to improve zsh/bash completion usability and search results. The pattern matching conventions described above are exclusive features of this fork, while the data file format and the core algorithm are kept compatible with those of the original version. BUGS Please file bugs at <https://github.com/knu/z>. Unix June 24, 2013 Unix