stow/oh-my-zsh/.oh-my-zsh/plugins/scd/README.md

   1 # scd - smart change of directory
   2
   3 Define `scd` shell function for changing to any directory with
   4 a few keystrokes.
   5
   6 `scd` keeps history of the visited directories, which serves as an index of
   7 the known paths.  The directory index is updated after every `cd` command in
   8 the shell and can be also filled manually by running `scd -a`.  To switch to
   9 some directory, `scd` needs few fragments of the desired path to match with
  10 the index.  A selection menu is displayed in case of several matches, with a
  11 preference given to recently visited paths.  `scd` can create permanent
  12 directory aliases, which appear as named directories in zsh session.
  13
  14 ## INSTALLATION NOTES
  15
  16 Besides oh-my-zsh, `scd` can be used with *bash*, *dash* or *tcsh*
  17 shells and is also available as Vim plugin
  18 [scd.vim](https://github.com/pavoljuhas/scd.vim) and
  19 [IPython](https://ipython.org) extension.  For installation details, see
  20 https://github.com/pavoljuhas/smart-change-directory.
  21
  22 ## SYNOPSIS
  23
  24 ```sh
  25 scd [options] [pattern1 pattern2 ...]
  26 ```
  27
  28 ## PATTERNS
  29
  30 Patterns may use all zsh [glob operators](
  31 http://zsh.sourceforge.net/Doc/Release/Expansion.html#Glob-Operators)
  32 available with *extendedglob* option.  Specified patterns must match
  33 the absolute path and at least one of them must match in the tail.
  34 Several special patterns are also recognized as follows:
  35
  36 <dl><dt>
  37 ^PAT</dt><dd>
  38   PAT must match at the beginning of the path, for example, "^/home"</dd><dt>
  39 PAT$</dt><dd>
  40   require PAT to match the end of the path, "man$"</dd><dt>
  41 ./</dt><dd>
  42   match only subdirectories of the current directory</dd><dt>
  43 :PAT</dt><dd>
  44   require PAT to match over the tail component, ":doc", ":re/doc"</dd>
  45 </dl>
  46
  47
  48 ## OPTIONS
  49
  50 <dl><dt>
  51 -a, --add</dt><dd>
  52   add current or specified directories to the directory index.</dd><dt>
  53
  54 --unindex</dt><dd>
  55   remove current or specified directories from the index.</dd><dt>
  56
  57 -r, --recursive</dt><dd>
  58   apply options <em>--add</em> or <em>--unindex</em> recursively.</dd><dt>
  59
  60 --alias=ALIAS</dt><dd>
  61   create alias for the current or specified directory and save it to
  62   <em>~/.scdalias.zsh</em>.</dd><dt>
  63
  64 --unalias</dt><dd>
  65   remove ALIAS definition for the current or specified directory from
  66   <em>~/.scdalias.zsh</em>.  Use "OLD" to purge aliases to non-existent
  67   directories.</dd><dt>
  68
  69 -A, --all</dt><dd>
  70   display all directories even those excluded by patterns in
  71   <em>~/.scdignore</em>.  Disregard the unique matching for a
  72   directory alias and filtering of less likely paths.</dd><dt>
  73
  74 -p, --push</dt><dd>
  75   use "pushd" to change to the target directory.</dd><dt>
  76
  77 --list</dt><dd>
  78   show matching directories and exit.</dd><dt>
  79
  80 -v, --verbose</dt><dd>
  81   display directory rank in the selection menu.</dd><dt>
  82
  83 -h, --help</dt><dd>
  84   display this options summary and exit.</dd>
  85 </dl>
  86
  87
  88 ## Examples
  89
  90 ```sh
  91 # Index recursively some paths for the very first run
  92 scd -ar ~/Documents/
  93
  94 # Change to a directory path matching "doc"
  95 scd doc
  96
  97 # Change to a path matching all of "a", "b" and "c"
  98 scd a b c
  99
 100 # Change to a directory path that ends with "ts"
 101 scd "ts$"
 102
 103 # Show selection menu and ranking of 20 most likely directories
 104 scd -v
 105
 106 # Alias current directory as "xray"
 107 scd --alias=xray
 108
 109 # Jump to a previously defined aliased directory
 110 scd xray
 111 ```
 112
 113 ## FILES
 114
 115 <dl><dt>
 116 ~/.scdhistory</dt><dd>
 117     time-stamped index of visited directories.</dd><dt>
 118
 119 ~/.scdalias.zsh</dt><dd>
 120     scd-generated definitions of directory aliases.</dd><dt>
 121
 122 ~/.scdignore</dt><dd>
 123     <a href="http://zsh.sourceforge.net/Doc/Release/Expansion.html#Glob-Operators">
 124     glob patterns</a> for paths to be ignored in the scd search, for example,
 125     <code>/mnt/backup/*</code>.  The patterns are specified one per line
 126     and are matched assuming the <em>extendedglob</em> zsh option.  Lines
 127     starting with "#" are skipped as comments.  The .scdignore patterns
 128     are not applied in the <em>--all</em> mode.</dd>
 129 </dl>
 130
 131
 132 ## ENVIRONMENT
 133
 134 <dl><dt>
 135 SCD_HISTFILE</dt><dd>
 136     path to the scd index file (by default ~/.scdhistory).</dd><dt>
 137
 138 SCD_HISTSIZE</dt><dd>
 139     maximum number of entries in the index (5000).  Index is trimmed when it
 140     exceeds <em>SCD_HISTSIZE</em> by more than 20%.</dd><dt>
 141
 142 SCD_MENUSIZE</dt><dd>
 143     maximum number of items for directory selection menu (20).</dd><dt>
 144
 145 SCD_MEANLIFE</dt><dd>
 146     mean lifetime in seconds for exponential decay of directory
 147     likelihood (86400).</dd><dt>
 148
 149 SCD_THRESHOLD</dt><dd>
 150     threshold for cumulative directory likelihood.  Directories with
 151     a lower likelihood compared to the best match are excluded (0.005).
 152     </dd><dt>
 153
 154 SCD_SCRIPT</dt><dd>
 155     command script file where scd writes the final <code>cd</code>
 156     command.  This variable must be defined when scd runs in its own
 157     process rather than as a shell function.  It is up to the
 158     scd caller to use the output in <em>SCD_SCRIPT</em>.</dd>
 159 </dl>