summaryrefslogtreecommitdiff
path: root/plugins
diff options
context:
space:
mode:
Diffstat (limited to 'plugins')
-rw-r--r--plugins/scd/README.md123
-rwxr-xr-xplugins/scd/scd350
-rw-r--r--plugins/scd/scd.plugin.zsh19
3 files changed, 492 insertions, 0 deletions
diff --git a/plugins/scd/README.md b/plugins/scd/README.md
new file mode 100644
index 000000000..ea7c72464
--- /dev/null
+++ b/plugins/scd/README.md
@@ -0,0 +1,123 @@
+# scd - smart change of directory
+
+Define `scd` shell function for changing to any directory with
+a few keystrokes.
+
+`scd` keeps history of the visited directories, which serves as an index of
+the known paths. The directory index is updated after every `cd` command in
+the shell and can be also filled manually by running `scd -a`. To switch to
+some directory, `scd` needs few fragments of the desired path to match with
+the index. A selection menu is displayed in case of several matches, with a
+preference given to recently visited paths. `scd` can create permanent
+directory aliases, which appear as named directories in zsh session.
+
+## INSTALLATION
+
+For oh-my-zsh, add `scd` to the `plugins` array in the ~/.zshrc file as in the
+[template file](../../templates/zshrc.zsh-template#L45).
+
+Besides zsh, `scd` can be used with *bash*, *dash* or *tcsh*
+shells and is also available as [Vim](http://www.vim.org/) plugin and
+[IPython](http://ipython.org/) extension. For installation details, see
+https://github.com/pavoljuhas/smart-change-directory.
+
+## SYNOPSIS
+
+```sh
+scd [options] [pattern1 pattern2 ...]
+```
+
+## OPTIONS
+
+<dl><dt>
+-a, --add</dt><dd>
+ add specified directories to the directory index.</dd><dt>
+
+--unindex</dt><dd>
+ remove specified directories from the index.</dd><dt>
+
+-r, --recursive</dt><dd>
+ apply options <em>--add</em> or <em>--unindex</em> recursively.</dd><dt>
+
+--alias=ALIAS</dt><dd>
+ create alias for the current or specified directory and save it to
+ <em>~/.scdalias.zsh</em>.</dd><dt>
+
+--unalias</dt><dd>
+ remove ALIAS definition for the current or specified directory from
+ <em>~/.scdalias.zsh</em>.</dd><dt>
+
+--list</dt><dd>
+ show matching directories and exit.</dd><dt>
+
+-v, --verbose</dt><dd>
+ display directory rank in the selection menu.</dd><dt>
+
+-h, --help</dt><dd>
+ display this options summary and exit.</dd>
+</dl>
+
+## Examples
+
+```sh
+# Index recursively some paths for the very first run
+scd -ar ~/Documents/
+
+# Change to a directory path matching "doc"
+scd doc
+
+# Change to a path matching all of "a", "b" and "c"
+scd a b c
+
+# Change to a directory path that ends with "ts"
+scd "ts(#e)"
+
+# Show selection menu and ranking of 20 most likely directories
+scd -v
+
+# Alias current directory as "xray"
+scd --alias=xray
+
+# Jump to a previously defined aliased directory
+scd xray
+```
+
+# FILES
+
+<dl><dt>
+~/.scdhistory</dt><dd>
+ time-stamped index of visited directories.</dd><dt>
+
+~/.scdalias.zsh</dt><dd>
+ scd-generated definitions of directory aliases.</dd>
+</dl>
+
+# ENVIRONMENT
+
+<dl><dt>
+SCD_HISTFILE</dt><dd>
+ path to the scd index file (by default ~/.scdhistory).</dd><dt>
+
+SCD_HISTSIZE</dt><dd>
+ maximum number of entries in the index (5000). Index is trimmed when it
+ exceeds <em>SCD_HISTSIZE</em> by more than 20%.</dd><dt>
+
+SCD_MENUSIZE</dt><dd>
+ maximum number of items for directory selection menu (20).</dd><dt>
+
+SCD_MEANLIFE</dt><dd>
+ mean lifetime in seconds for exponential decay of directory
+ likelihood (86400).</dd><dt>
+
+SCD_THRESHOLD</dt><dd>
+ threshold for cumulative directory likelihood. Directories with
+ lower likelihood are excluded unless they are the only match to
+ scd patterns.
+ </dd><dt>
+
+SCD_SCRIPT</dt><dd>
+ command script file where scd writes the final <code>cd</code>
+ command. This variable must be defined when scd runs in its own
+ process rather than as a shell function. It is up to the
+ scd caller to use the output in <em>SCD_SCRIPT</em>.</dd>
+</dl>
diff --git a/plugins/scd/scd b/plugins/scd/scd
new file mode 100755
index 000000000..9e055eadd
--- /dev/null
+++ b/plugins/scd/scd
@@ -0,0 +1,350 @@
+#!/bin/zsh -f
+
+emulate -L zsh
+if [[ $(whence -w $0) == *:' 'command ]]; then
+ emulate -R zsh
+ alias return=exit
+ local RUNNING_AS_COMMAND=1
+fi
+
+local DOC='scd -- smart change to a recently used directory
+usage: scd [options] [pattern1 pattern2 ...]
+Go to a directory path that contains all fixed string patterns. Prefer
+recently visited directories and directories with patterns in their tail
+component. Display a selection menu in case of multiple matches.
+
+Options:
+ -a, --add add specified directories to the directory index
+ --unindex remove specified directories from the index
+ -r, --recursive apply options --add or --unindex recursively
+ --alias=ALIAS create alias for the current or specified directory and
+ store it in ~/.scdalias.zsh
+ --unalias remove ALIAS definition for the current or specified
+ directory from ~/.scdalias.zsh
+ --list show matching directories and exit
+ -v, --verbose display directory rank in the selection menu
+ -h, --help display this message and exit
+'
+
+local SCD_HISTFILE=${SCD_HISTFILE:-${HOME}/.scdhistory}
+local SCD_HISTSIZE=${SCD_HISTSIZE:-5000}
+local SCD_MENUSIZE=${SCD_MENUSIZE:-20}
+local SCD_MEANLIFE=${SCD_MEANLIFE:-86400}
+local SCD_THRESHOLD=${SCD_THRESHOLD:-0.005}
+local SCD_SCRIPT=${RUNNING_AS_COMMAND:+$SCD_SCRIPT}
+local SCD_ALIAS=~/.scdalias.zsh
+
+local ICASE a d m p i tdir maxrank threshold
+local opt_help opt_add opt_unindex opt_recursive opt_verbose
+local opt_alias opt_unalias opt_list
+local -A drank dalias dkey
+local dmatching
+
+setopt extendedhistory extendedglob noautonamedirs brace_ccl
+
+# If SCD_SCRIPT is defined make sure the file exists and is empty.
+# This removes any previous old commands.
+[[ -n "$SCD_SCRIPT" ]] && [[ -s $SCD_SCRIPT || ! -f $SCD_SCRIPT ]] && (
+ umask 077
+ : >| $SCD_SCRIPT
+)
+
+# process command line options
+zmodload -i zsh/zutil
+zmodload -i zsh/datetime
+zparseopts -D -- a=opt_add -add=opt_add -unindex=opt_unindex \
+ r=opt_recursive -recursive=opt_recursive \
+ -alias:=opt_alias -unalias=opt_unalias -list=opt_list \
+ v=opt_verbose -verbose=opt_verbose h=opt_help -help=opt_help \
+ || return $?
+
+if [[ -n $opt_help ]]; then
+ print $DOC
+ return
+fi
+
+# load directory aliases if they exist
+[[ -r $SCD_ALIAS ]] && source $SCD_ALIAS
+
+# works faster than the (:a) modifier and is compatible with zsh 4.2.6
+_scd_Y19oug_abspath() {
+ set -A $1 ${(ps:\0:)"$(
+ unfunction -m "*"; shift
+ for d; do
+ cd $d && print -Nr -- $PWD && cd $OLDPWD
+ done
+ )"}
+}
+
+# define directory alias
+if [[ -n $opt_alias ]]; then
+ if [[ -n $1 && ! -d $1 ]]; then
+ print -u2 "'$1' is not a directory"
+ return 1
+ fi
+ a=${opt_alias[-1]#=}
+ _scd_Y19oug_abspath d ${1:-$PWD}
+ # alias in the current shell, update alias file if successful
+ hash -d -- $a=$d &&
+ (
+ umask 077
+ hash -dr
+ [[ -r $SCD_ALIAS ]] && source $SCD_ALIAS
+ hash -d -- $a=$d
+ hash -dL >| $SCD_ALIAS
+ )
+ return $?
+fi
+
+# undefine directory alias
+if [[ -n $opt_unalias ]]; then
+ if [[ -n $1 && ! -d $1 ]]; then
+ print -u2 "'$1' is not a directory"
+ return 1
+ fi
+ _scd_Y19oug_abspath a ${1:-$PWD}
+ a=$(print -rD ${a})
+ if [[ $a != [~][^/]## ]]; then
+ return
+ fi
+ a=${a#[~]}
+ # unalias in the current shell, update alias file if successful
+ if unhash -d -- $a 2>/dev/null && [[ -r $SCD_ALIAS ]]; then
+ (
+ umask 077
+ hash -dr
+ source $SCD_ALIAS
+ unhash -d -- $a 2>/dev/null &&
+ hash -dL >| $SCD_ALIAS
+ )
+ fi
+ return $?
+fi
+
+# Rewrite the history file if it is at least 20% oversized
+if [[ -s $SCD_HISTFILE ]] && \
+(( $(wc -l <$SCD_HISTFILE) > 1.2 * $SCD_HISTSIZE )); then
+ m=( ${(f)"$(<$SCD_HISTFILE)"} )
+ print -lr -- ${m[-$SCD_HISTSIZE,-1]} >| ${SCD_HISTFILE}
+fi
+
+# Internal functions are prefixed with "_scd_Y19oug_".
+# The "record" function adds a non-repeating directory to the history
+# and turns on history writing.
+_scd_Y19oug_record() {
+ while [[ -n $1 && $1 == ${history[$HISTCMD]} ]]; do
+ shift
+ done
+ if [[ $# != 0 ]]; then
+ ( umask 077; : >>| $SCD_HISTFILE )
+ p=": ${EPOCHSECONDS}:0;"
+ print -lr -- ${p}${^*} >> $SCD_HISTFILE
+ fi
+}
+
+if [[ -n $opt_add ]]; then
+ for a; do
+ if [[ ! -d $a ]]; then
+ print -u 2 "Directory $a does not exist"
+ return 2
+ fi
+ done
+ _scd_Y19oug_abspath m ${*:-$PWD}
+ _scd_Y19oug_record $m
+ if [[ -n $opt_recursive ]]; then
+ for d in $m; do
+ print -n "scanning ${d} ... "
+ _scd_Y19oug_record ${d}/**/*(-/N)
+ print "[done]"
+ done
+ fi
+ return
+fi
+
+# take care of removing entries from the directory index
+if [[ -n $opt_unindex ]]; then
+ if [[ ! -s $SCD_HISTFILE ]]; then
+ return
+ fi
+ # expand existing directories in the argument list
+ for i in {1..$#}; do
+ if [[ -d ${argv[i]} ]]; then
+ _scd_Y19oug_abspath d ${argv[i]}
+ argv[i]=${d}
+ fi
+ done
+ m="$(awk -v recursive=${opt_recursive} '
+ BEGIN {
+ for (i = 2; i < ARGC; ++i) {
+ argset[ARGV[i]] = 1;
+ delete ARGV[i];
+ }
+ }
+ 1 {
+ d = $0; sub(/^[^;]*;/, "", d);
+ if (d in argset) next;
+ }
+ recursive {
+ for (a in argset) {
+ if (substr(d, 1, length(a) + 1) == a"/") next;
+ }
+ }
+ { print $0 }
+ ' $SCD_HISTFILE ${*:-$PWD} )" || return $?
+ : >| ${SCD_HISTFILE}
+ [[ ${#m} == 0 ]] || print -r -- $m >> ${SCD_HISTFILE}
+ return
+fi
+
+# The "action" function is called when there is just one target directory.
+_scd_Y19oug_action() {
+ if [[ -n $opt_list ]]; then
+ for d; do
+ a=${(k)dalias[(r)${d}]}
+ print -r -- "# $a"
+ print -r -- $d
+ done
+ elif [[ $# == 1 ]]; then
+ if [[ -z $SCD_SCRIPT && -n $RUNNING_AS_COMMAND ]]; then
+ print -u2 "Warning: running as command with SCD_SCRIPT undefined."
+ fi
+ [[ -n $SCD_SCRIPT ]] && (umask 077;
+ print -r "cd ${(q)1}" >| $SCD_SCRIPT)
+ [[ -N $SCD_HISTFILE ]] && touch -a $SCD_HISTFILE
+ cd $1
+ # record the new directory unless already done in some chpwd hook
+ [[ -N $SCD_HISTFILE ]] || _scd_Y19oug_record $PWD
+ fi
+}
+
+# handle different argument scenarios ----------------------------------------
+
+## single argument that is an existing directory
+if [[ $# == 1 && -d $1 && -x $1 ]]; then
+ _scd_Y19oug_action $1
+ return $?
+## single argument that is an alias
+elif [[ $# == 1 && -d ${d::=${nameddirs[$1]}} ]]; then
+ _scd_Y19oug_action $d
+ return $?
+fi
+
+# ignore case unless there is an argument with an uppercase letter
+[[ "$*" == *[[:upper:]]* ]] || ICASE='(#i)'
+
+# calculate rank of all directories in the SCD_HISTFILE and keep it as drank
+# include a dummy entry for splitting of an empty string is buggy
+[[ -s $SCD_HISTFILE ]] && drank=( ${(f)"$(
+ print -l /dev/null -10
+ <$SCD_HISTFILE \
+ awk -v epochseconds=$EPOCHSECONDS -v meanlife=$SCD_MEANLIFE '
+ BEGIN { FS = "[:;]"; }
+ length($0) < 4096 && $2 > 0 {
+ tau = 1.0 * ($2 - epochseconds) / meanlife;
+ if (tau < -4.61) tau = -4.61;
+ prec = exp(tau);
+ sub(/^[^;]*;/, "");
+ if (NF) ptot[$0] += prec;
+ }
+ END { for (di in ptot) { print di; print ptot[di]; } }'
+ )"}
+)
+unset "drank[/dev/null]"
+
+# filter drank to the entries that match all arguments
+for a; do
+ p=${ICASE}"*${a}*"
+ drank=( ${(kv)drank[(I)${~p}]} )
+done
+
+# build a list of matching directories reverse-sorted by their probabilities
+dmatching=( ${(f)"$(
+ for d p in ${(kv)drank}; do
+ print -r -- "$p $d";
+ done | sort -grk1 | cut -d ' ' -f 2-
+ )"}
+)
+
+# if some directory paths match all patterns in order, discard all others
+p=${ICASE}"*${(j:*:)argv}*"
+m=( ${(M)dmatching:#${~p}} )
+[[ -d ${m[1]} ]] && dmatching=( $m )
+# if some directory names match last pattern, discard all others
+p=${ICASE}"*${(j:*:)argv}[^/]#"
+m=( ${(M)dmatching:#${~p}} )
+[[ -d ${m[1]} ]] && dmatching=( $m )
+# if some directory names match all patterns, discard all others
+m=( $dmatching )
+for a; do
+ p=${ICASE}"*/[^/]#${a}[^/]#"
+ m=( ${(M)m:#${~p}} )
+done
+[[ -d ${m[1]} ]] && dmatching=( $m )
+# if some directory names match all patterns in order, discard all others
+p=${ICASE}"/*${(j:[^/]#:)argv}[^/]#"
+m=( ${(M)dmatching:#${~p}} )
+[[ -d ${m[1]} ]] && dmatching=( $m )
+
+# do not match $HOME or $PWD when run without arguments
+if [[ $# == 0 ]]; then
+ dmatching=( ${dmatching:#(${HOME}|${PWD})} )
+fi
+
+# keep at most SCD_MENUSIZE of matching and valid directories
+m=( )
+for d in $dmatching; do
+ [[ ${#m} == $SCD_MENUSIZE ]] && break
+ [[ -d $d && -x $d ]] && m+=$d
+done
+dmatching=( $m )
+
+# find the maximum rank
+maxrank=0.0
+for d in $dmatching; do
+ [[ ${drank[$d]} -lt maxrank ]] || maxrank=${drank[$d]}
+done
+
+# discard all directories below the rank threshold
+threshold=$(( maxrank * SCD_THRESHOLD ))
+dmatching=( ${^dmatching}(Ne:'(( ${drank[$REPLY]} >= threshold ))':) )
+
+## process whatever directories that remained
+case ${#dmatching} in
+(0)
+ print -u2 "no matching directory"
+ return 1
+ ;;
+(1)
+ _scd_Y19oug_action $dmatching
+ return $?
+ ;;
+(*)
+ # build a list of strings to be displayed in the selection menu
+ m=( ${(f)"$(print -lD ${dmatching})"} )
+ if [[ -n $opt_verbose ]]; then
+ for i in {1..${#dmatching}}; do
+ d=${dmatching[i]}
+ m[i]=$(printf "%.3g %s" ${drank[$d]} $d)
+ done
+ fi
+ # build a map of string names to actual directory paths
+ for i in {1..${#m}}; dalias[${m[i]}]=${dmatching[i]}
+ # opt_list - output matching directories and exit
+ if [[ -n $opt_list ]]; then
+ _scd_Y19oug_action ${dmatching}
+ return
+ fi
+ # finally use the selection menu to get the answer
+ a=( {a-z} {A-Z} )
+ p=( )
+ for i in {1..${#m}}; do
+ [[ -n ${a[i]} ]] || break
+ dkey[${a[i]}]=${dalias[$m[i]]}
+ p+="${a[i]}) ${m[i]}"
+ done
+ print -c -r -- $p
+ if read -s -k 1 d && [[ -n ${dkey[$d]} ]]; then
+ _scd_Y19oug_action ${dkey[$d]}
+ fi
+ return $?
+esac
diff --git a/plugins/scd/scd.plugin.zsh b/plugins/scd/scd.plugin.zsh
new file mode 100644
index 000000000..0197c53a1
--- /dev/null
+++ b/plugins/scd/scd.plugin.zsh
@@ -0,0 +1,19 @@
+## The scd script should autoload as a shell function.
+autoload scd
+
+
+## If the scd function exists, define a change-directory-hook function
+## to record visited directories in the scd index.
+if [[ ${+functions[scd]} == 1 ]]; then
+ scd_chpwd_hook() { scd --add $PWD }
+ autoload add-zsh-hook
+ add-zsh-hook chpwd scd_chpwd_hook
+fi
+
+
+## Allow scd usage with unquoted wildcard characters such as "*" or "?".
+alias scd='noglob scd'
+
+
+## Load the directory aliases created by scd if any.
+if [[ -s ~/.scdalias.zsh ]]; then source ~/.scdalias.zsh; fi
generated by cgit v1.2.3-70-g09d2 (git 2.48.1) at 2025-11-04 14:07:00 +0000