Auto-loading project-specific `.aliases.sh` files in zsh with a unified `dev` command interface for starting/stopping development environments

.aliases.sh

# ~/workspace/your_project/.aliases.sh

# Your custom commands to make `dev start` and `dev stop` commands works
export DEV_START="bin/docker up && overmind start -f Procfile.dev"
export DEV_STOP="overmind quit && bin/docker down"

# any other project's specific commands or aliases
alias rgd="bin/rails docs_generate"

.zshrc

# ~/.zshrc

load_local_aliases() {
  local alias_files=()

        if [[ -f "$HOME/.aliases.sh" ]]; then
    alias_files+=("$HOME/.aliases.sh")
  fi

        local current_dir="$PWD"
        while [[ "$current_dir" != "/" ]]; do
                if [[ -f "$current_dir/.aliases.sh" ]]; then
                        alias_files=("$current_dir/.aliases.sh" "${alias_files[@]}")
                fi
                current_dir="$(dirname "$current_dir")"
        done

        for file in "${alias_files[@]}"; do
    source "$file"
  done
}

# auto load .aliases.sh file from current or parrent dirs
autoload -U add-zsh-hook
add-zsh-hook chpwd load_local_aliases
load_local_aliases

dev() {
  case "$1" in
    start)
                  if [[ -z "$DEV_START" ]]; then
                                echo "Error: ENV DEV_START is not defined"
                                return 1
      fi
      eval "$DEV_START"
      ;;
    stop)
                  if [[ -z "$DEV_STOP" ]]; then
                                echo "Error: ENV DEV_STOP is not defined"
                                return 1
      fi
      eval "$DEV_STOP"
      ;;
    *)
      echo "Usage: dev {start|stop}"
      return 1
      ;;
  esac
}

README.md

Project-Specific Aliases with Auto-Loading for Zsh

A zsh configuration that automatically loads project-specific aliases and provides a unified dev command interface for managing development environments.

Features

• Automatic alias loading: Automatically sources .aliases.sh files from your current directory and parent directories
• Project-specific commands: Define custom commands per project without polluting your global shell environment
• Unified dev interface: Simple dev start and dev stop commands that adapt to each project
• Hierarchical loading: Aliases are loaded from root to current directory, allowing inheritance and overrides

Installation

1. Add to your ~/.zshrc

Copy the code from this gist to your ~/.zshrc file.

2. Reload your shell

source ~/.zshrc

Usage

Create a project-specific aliases file

In your project directory, create a .aliases.sh file:

# ~/workspace/your_project/.aliases.sh

# Define dev start/stop commands
export DEV_START="bin/docker up && overmind start -f Procfile.dev"
export DEV_STOP="overmind quit && bin/docker down"

# Add project-specific aliases
alias rgd="bin/rails docs_generate"
alias test="bundle exec rspec"

Use the dev commands

cd ~/workspace/your_project

# Start your development environment
dev start

# Stop your development environment
dev stop

How It Works

The load_local_aliases() function:

1. Checks for ~/.aliases.sh (global aliases)
2. Traverses from the current directory up to the root
3. Collects all .aliases.sh files found
4. Sources them in order from root to current directory

This happens automatically when you start a shell or change directories (via the chpwd hook).

The dev command executes commands defined in $DEV_START and $DEV_STOP environment variables.

Tips

• Create ~/.aliases.sh for global aliases available everywhere
• Be cautious about sourcing .aliases.sh files from untrusted directories