z - Jump Around: Deployment & Usage Guide

A shell script for navigating your filesystem using "frecency" (frequency + recency) tracking.

1. Prerequisites

Shell: POSIX-compatible shell (bash, zsh, dash, ksh, or fish*)
Tools: curl or wget (for downloading), git (optional)
Permissions: Write access to $HOME (for data file)

*Note: For fish shell, use the z-fish port instead.

2. Installation

Method A: Direct Download (Recommended)

# Download to local bin
mkdir -p ~/bin
curl -o ~/bin/z.sh https://raw.githubusercontent.com/rupa/z/master/z.sh

# Make executable
chmod +x ~/bin/z.sh

Method B: Git Clone

# Clone repository
git clone https://github.com/rupa/z.git ~/opt/z

# Create symlink in local bin
mkdir -p ~/bin
ln -s ~/opt/z/z.sh ~/bin/z.sh

Method C: Package Manager

# macOS (Homebrew)
brew install z

# Debian/Ubuntu
sudo apt-get install z

# Arch Linux
sudo pacman -S z

3. Configuration

Add to your shell configuration file:

Bash (~/.bashrc):

# Source z
. ~/bin/z.sh

Zsh (~/.zshrc):

# Source z
. ~/bin/z.sh

System-wide (optional):

# Copy to system profile
sudo cp ~/bin/z.sh /etc/profile.d/z.sh

Environment Variables

Add these before sourcing z.sh to customize behavior:

# Change command name (default: z)
_Z_CMD=j

# Change data file location (default: ~/.z)
_Z_DATA=~/.z-data

# Don't resolve symlinks (treat symlink and target as separate)
_Z_NO_RESOLVE_SYMLINKS=1

# Exclude directories (colon-separated)
_Z_EXCLUDE_DIRS="/tmp:/var/tmp:$HOME/private"

# Only allow owner to access data file (security)
_Z_OWNER=$USER

Reload shell configuration:

source ~/.bashrc  # or ~/.zshrc

4. Build & Run

No build step required. z is a pure shell script.

Usage

# Jump to directory containing 'foo'
z foo

# Jump to directory matching multiple patterns
z foo bar

# List ranking (frecency scores)
z -l

# List with scores
z -l foo

# Restrict to current directory's subdirectories
z -c foo

# Go to most recent match (not highest frecency)
z -r foo

# Interactive selection (if multiple matches)
z -i foo

How It Works

Tracking: Every time you cd, z logs the directory to $_Z_DATA
Ranking: Directories gain points based on frequency and recency
Matching: z finds the highest-ranked directory matching your pattern

5. Deployment

Personal Machine (Standard)

Follow Installation and Configuration sections above.

Shared Server (Multi-user)

# Install to shared location
sudo mkdir -p /usr/local/libexec
sudo curl -o /usr/local/libexec/z.sh https://raw.githubusercontent.com/rupa/z/master/z.sh

# Add to system-wide profile
echo '. /usr/local/libexec/z.sh' | sudo tee /etc/profile.d/z.sh

Container/Docker

# Add to Dockerfile
RUN curl -o /usr/local/bin/z.sh https://raw.githubusercontent.com/rupa/z/master/z.sh && \
    echo '. /usr/local/bin/z.sh' >> /etc/bash.bashrc

CI/CD Integration

For build scripts that need directory navigation:

# .github/workflows/example.yml
steps:
  - name: Install z
    run: |
      curl -o z.sh https://raw.githubusercontent.com/rupa/z/master/z.sh
      echo "source $PWD/z.sh" >> $HOME/.bashrc
      
  - name: Use z in scripts
    run: |
      bash -c 'source z.sh && z my-project && make build'

6. Troubleshooting

"z: command not found"

Cause: Shell not sourced or wrong file location
Fix:

# Verify file exists
ls -la ~/bin/z.sh

# Source manually to test
. ~/bin/z.sh

# Check shell config reload
source ~/.bashrc  # or ~/.zshrc

"No matches found" or no jump history

Cause: Database empty or not tracking
Fix:

# Check if data file exists and has content
cat ~/.z

# Navigate around to populate database
cd /var
cd /usr/local
cd ~

# Verify tracking is working
z -l

Permission denied on data file

Cause: File created with wrong permissions or shared system
Fix:

# Fix ownership
sudo chown $USER:$USER ~/.z

# Set secure permissions
chmod 600 ~/.z

# Or change data file location
export _Z_DATA=~/.config/z-data

Not tracking certain directories

Cause: Exclusion list or symlink resolution
Fix:

# Check exclusion environment variable
echo $_Z_EXCLUDE_DIRS

# Disable symlink resolution if needed
export _Z_NO_RESOLVE_SYMLINKS=1

Slow performance on large databases

Cause: Database grown too large
Fix:

# Clean up non-existent directories
z -c  # This triggers cleanup of deleted directories

# Or manually edit data file
vim ~/.z  # Remove old entries

Conflicts with other tools (e.g., fasd, autojump)

Cause: Multiple tools using same command alias
Fix:

# Change z command name
export _Z_CMD=jump

# Or uninstall conflicting tool
sudo apt-get remove autojump

How to Deploy & Use rupa/z