Permalink
Browse files

use and document _Z_NO_RESOLVE_SYMLINKS variable

  • Loading branch information...
1 parent 55e1226 commit 30cbc62c10a2c8c044abe5576b42af074b3ee996 @rupa committed Jun 25, 2012
Showing with 70 additions and 46 deletions.
  1. +54 −43 README
  2. +13 −2 z.1
  3. +3 −1 z.sh
View
97 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)
View
15 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.
View
4 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() {

0 comments on commit 30cbc62

Please sign in to comment.