ze.sh

ze.sh is a frecency-based directory jumper for bash, zsh, ksh93, and mksh (e.g. Termux/Android), forked from z.sh, with exponential moving sum (EMS) scoring model as well as several behavioral fixes and adjustments, see list of changes.

Installation

Source from your shell rc file:

Important: Unlike z.sh, ze.sh does not track ordinary cd commands. It only tracks navigation performed through the ze command itself. However, since ze accepts explicit pathnames just as cd does, it covers ordinary pathname-based cd usage as a subset. If you want to also track ordinary cd commands, add

to your shell rc file. If you do not install this alias, directories reached via ordinary cd commands are not recorded in the database.

Design

ze.sh departs from z.sh in three fundamental ways:

Event clock: z.sh couples score decay to wall-clock time. This causes a well-known failure mode: after any extended period of inactivity, all scores decay toward zero, and the first directories visited on return immediately dominate the ranking regardless of prior history. The underlying issue is that elapsed wall-clock time during shell inactivity carries no information about directory relevance. ze.sh replaces wall-clock time with an event clock: each cd action advances the clock by one tick. The clock stands still during inactive periods and no score decay occurs during such periods.

Scoring: z.sh's scoring heuristic multiplies a cumulative visit count by a recency factor derived from the most recent visit timestamp. This can produce undesirable ranking — a long-unvisited directory with a large historical visit count can jump near or to the top on first revisit. ze.sh replaces this with a monoexponential decay kernel: the score is the sum of individual, exponentially decayed unit impulses at each visit time, representing an exponential moving sum (mathematically equivalent to the Unix load-average computation, but applied to a binary directory-visit event stream). The decay rate is controlled by _ZE_LAMBDA (default 8e-3/cd action, half-life ln(2)/lambda ≈ 87 cd actions (about 2 days at 40 cd/day)).

Tracking: z.sh requires shell precommand hooks (PROMPT_COMMAND in bash, precmd in zsh) that fire on every command, updating the score of whichever directory the shell is currently in. This means any command executed in directory A increases that directory's score. For a directory jumper, using command activity within a directory as a measure of how often a user might want to reach that directory (so that it should be scored highly) seems inferior to monitoring only cd activity. Therefore, ze.sh removes the hooks entirely. Only explicit ze-based directory changes (or bare cd if aliased to _ze_cd) trigger database updates.

For broader shell compatibility, ze.sh furthermore uses typeset instead of local and [[/(()) instead of [/test throughout. The latter is not a compatibility requirement — all target shells support [ — but [[ is a shell keyword with cleaner semantics: no word splitting on unquoted variables, unambiguous &&/|| operators, and pattern matching support. In ze.sh, the function f { ... } definition style is used throughout instead of POSIX-style f() { ... } — in ksh93 and mksh, typeset variables are only locally scoped inside functions defined with the function keyword, whereas POSIX style functions do not provide local scoping in these shells. For historical POSIX sh compatibility, z.sh used [ and f() { } but was never actually POSIX-compatible due to its use of arrays, process substitution, and shell-specific completion builtins — ze.sh drops the pretense and uses the cleaner syntax consistently.

Database format

The database at ~/.ze/ze.db is a plain text file with one entry per line:

(1): ze.sh retains entries for directories that no longer exist (e.g. unmounted filesystems) and filters them at match time rather than pruning them on update.

Usage

ze [options] [pattern|path|-]
ze [-cefhlrt] [args]

Changes from z.sh

(1): The common-prefix heuristic of z.sh overrides the highest-scoring match in favor of a shorter path when all matches share a common prefix. With a well-calibrated scoring model this is counterproductive — the highest-scoring match is the statistically most likely intended destination. For cases where manual selection is still needed, ze -f provides an interactive fallback.

(2): Absolute pathnames are recognized by z.sh only if given as the last argument - a side effect of tab completion handling. Argument order matters: z foo /path cds directly while z /path foo pattern-matches. Relative pathnames are never recognized and always treated as pattern.

(3): ze.sh retains database entries for directories on transiently unavailable filesystems (USB drives, NFS mounts). They are ignored during matching but reactivate when the filesystem is remounted. z.sh prunes such entries immediately on the next cd action. In ze.sh, score-based pruning takes place when the db exceeds a configurable size limit (default: 512 entries), which eventually removes lowest scoring entries including never-again-used stale entries.

(4): The legacy behaviour to resolve all symlinks to physical paths for storage in the db seems not optimal for a directory navigation tool where logical paths are usually the expected paradigm. Consequently, ze.sh honours the logical paths by default. To revert to legacy behaviour, set _ZE_RESOLVE_SYMLINKS to any non-empty value.

Configuration

fzf integration

If fzf is installed, ze -f [pattern] opens an interactive selector showing all matching directories ranked by frecency score, best match at top. Select by pathname pattern or by entry number.

ze -f        # interactive selection from all tracked directories
ze -f foo    # interactive selection from directories matching foo

Migrating from z.sh

If you have an existing ~/.z database, you can convert it for use with ze.sh by issuing:

mkdir -p ~/.ze
# Only run the following if ~/.ze/ze.db does not already exist:
now=$(awk -F'|' '{ now += $2 } END { print now }' ~/.z)
sort -t'|' -k3,3n ~/.z | awk -F'|' -v now="$now" '
    BEGIN { OFS="|"; lambda=8e-3 }
    {   ticks += $2
        r = exp(-lambda)
        score = $2 == 1 ? 1 : (1 - r^$2) / (1 - r)
        score *= exp(-lambda * (now - ticks))
        print $1, $2, ticks, score
    }' > ~/.ze/ze.db

This maps z.sh's three-column format to ze.sh's four-column format. Entries are sorted by their original timestamp and assigned global cumulative visit counts as tick values accordingly. The score approximation assumes all visits were evenly distributed over time. Directories not visited recently will start with correspondingly lower initial scores. In subsequent use, the scores will adjust and develop according to ze's algorithm.

Related tools

SD — ksh93/bash/zsh, shell-native, single-file, explicit event log with configurable kernel scoring (default: exponential), cycling through matches. More fully featured than ze.sh in several respects. SD stores the full visit history as an event log. Scores can therefore be recomputed from scratch if the decay parameter or scoring model is changed.

zoxide — compiled Rust binary inspired by z.sh, wider shell support including fish and nushell, widely adopted. Like z.sh, frecency scoring multiplies cumulative visit count by a recency factor based on the most recent visit which can produce undesirable ranking — a long-unvisited directory with a large historical visit count can acquire a disproportionately high rank on first revisit if its historical visit count is large.

ze.sh occupies a specific niche: minimal, shell-native, single-file, ksh93- and mksh-compatible, tracking only intentional navigation rather than all shell activity. The exponential moving sum scoring on an event clock is comparable to SD's approach for a fixed decay parameter. However, only SD provides the ability to modify the decay parameter at any time and to fully reconstruct the corresponding scores from scratch.

License

MIT — see LICENSE.