From 30cbc62c10a2c8c044abe5576b42af074b3ee996 Mon Sep 17 00:00:00 2001 From: rupa Date: Mon, 25 Jun 2012 11:47:46 -0400 Subject: [PATCH] use and document _Z_NO_RESOLVE_SYMLINKS variable --- README | 97 ++++++++++++++++++++++++++++++++-------------------------- z.1 | 15 +++++++-- z.sh | 4 ++- 3 files changed, 70 insertions(+), 46 deletions(-) diff --git a/README b/README index 6c6989e..e7309fa 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -Z(1) User Commands Z(1) +Z(1) User Commands Z(1) @@ -17,8 +17,8 @@ AVAILABILITY 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. + After a short learning phase, z will take you to the most 'frecent' + directory that matches ALL of the regexes given on the command line. OPTIONS @@ -29,92 +29,103 @@ OPTIONS EXAMPLES - z foo cd to most frecent dir matching foo + 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) + 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). + Set $_Z_CMD in .bashrc/.zshrc to change the command (default z). + Set $_Z_DATA to change the datafile (default $HOME/.z). + Set $_Z_NO_RESOLVE_SYMLINKS to prevent symlink resolution. + (These settings should go before the lines below.) Put something like this in your $HOME/.bashrc: - . /path/to/z.sh + . /path/to/z.sh Put something like this in your $HOME/.zshrc: - . /path/to/z.sh - function precmd () { - _z --add "$(pwd -P)" - } + . /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. + 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. + The rank of directories maintained by z undergoes aging based on a sim‐ + ple 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. + 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. + 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. + 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. + 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 com‐ + pleted 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 /. + Internally, z decides you've requested a completion if the last argu‐ + ment passed is an absolute path to an existing directory. This may + cause unexpected 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. + 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 + The environment variable $_Z_DATA can be used to control the datafile + 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 datafile. + + 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; + _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. + 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 + Data is stored in $HOME/.z. This can be overridden by setting the + $_Z_DATA environment variable. A man page (z.1) is provided. @@ -126,4 +137,4 @@ SEE ALSO -z February 2011 Z(1) +z February 2011 Z(1) diff --git a/z.1 b/z.1 index 5742379..651d511 100644 --- a/z.1 +++ b/z.1 @@ -43,6 +43,10 @@ Optionally: Set \fB$_Z_CMD\fR in .bashrc/.zshrc to change the command (default \fBz\fR). .br Set \fB$_Z_DATA\fR to change the datafile (default \fB$HOME/.z\fR). +.br + Set \fB$_Z_NO_RESOLVE_SYMLINKS\fR to prevent symlink resolution. +.br + (These settings should go before the lines below.) .P Put something like this in your \fB$HOME/.bashrc\fR: .P @@ -110,6 +114,13 @@ A function \fB_z()\fR is defined. An alias \fB$_Z_CMD\fR='_z 2>&1' is defined. If not set, \fB$_Z_CMD\fR defaults to \fBz\fR. .P +The environment variable \fB$_Z_DATA\fR can be used to control the datafile +location. If it is not defined, the location defaults to \fB$HOME/.z\fR. +.P +The environment variable \fB$_Z_NO_RESOLVE_SYMLINKS\fR can be set to prevent +resolving of symlinks. If it is not set, symbolic links will be resolved when +added to the datafile. +.P In bash, \fBz\fR uses the \fBPROMPT_COMMAND\fR environment variable to maintain its database. Specifically it prepends: .P @@ -119,8 +130,8 @@ to any existing \fbPROMPT_COMMAND\fR. zsh users need to manually set \fBprecmd()\fR as described in the installation instructions. .SH FILES -Data is stored in \fB$_Z_DATA\fR. If not set, \fB$_Z_DATA\fR defaults to -\fB$HOME/.z\fR +Data is stored in \fB$HOME/.z\fR. This can be overridden by setting the +\fB$_Z_DATA\fR environment variable. .P A man page (\fBz.1\fR) is provided. diff --git a/z.sh b/z.sh index eb293d3..92af9bf 100755 --- a/z.sh +++ b/z.sh @@ -179,12 +179,14 @@ _z() { alias ${_Z_CMD:-z}='_z 2>&1' +[ "$_Z_NO_RESOLVE_SYMLINKS" ] || _Z_RESOLVE_SYMLINKS="-P" + if complete &> /dev/null; then # bash tab completion complete -C '_z --complete "$COMP_LINE"' ${_Z_CMD:-z} # populate directory list. avoid clobbering other PROMPT_COMMANDs. echo $PROMPT_COMMAND | grep -q "_z --add" - [ $? -gt 0 ] && PROMPT_COMMAND='_z --add "$(pwd -P 2>/dev/null)" 2>/dev/null;'"$PROMPT_COMMAND" + [ $? -gt 0 ] && PROMPT_COMMAND='_z --add "$(pwd '$_Z_RESOLVE_SYMLINKS' 2>/dev/null)" 2>/dev/null;'"$PROMPT_COMMAND" elif compctl &> /dev/null; then # zsh tab completion _z_zsh_tab_completion() {