Local project aliases

I’m currently working on a project that uses both Python and React, and I often need to run long commands to start the backend or frontend, debug services, run tests, or set up the environment. Since uv doesn’t yet support task-runner functionality (there’s an open issue for it), and npm scripts only work inside the frontend directory,I needed a simpler, project-scoped solution that wouldn’t clutter version control with personal scripts.

To solve this, I added a small snippet to my Zsh configuration that automatically loads project-specific aliases from a .aliases file located anywhere in the project tree:

typeset -gA _TRUSTED_ALIAS_DIRS

while IFS= read -r line || [[ -n "$line" ]]; do
  _TRUSTED_ALIAS_DIRS["$line"]=1
done < /root/workspace/.aliases.trusted

typeset -g _LAST_PROJECT_DIR=""

_load_project_aliases() {
  local dir="$PWD"

  while [[ "$dir" != "/" ]]; do
    if [[ -f "$dir/.aliases" && -n "${_TRUSTED_ALIAS_DIRS['$dir']}" ]]; then
      if [[ "$_LAST_PROJECT_DIR" != "$dir" ]]; then
        source "$dir/.aliases"
        _LAST_PROJECT_DIR="$dir"
      fi
      return
    fi
    dir="${dir:h}"
  done

  _LAST_PROJECT_DIR=""
}

add-zsh-hook chpwd _load_project_aliases
_load_project_aliases

unset -f _load_project_aliases

This function walks up the current working directory, finds the nearest .aliases file, and loads it automatically whenever I navigate into the project.

Inside my .aliases file, I keep convenient shortcuts like:

alias run-backend=""
alias run-frontend=""
alias run-tests=""
alias run-functions=""

alias debug-backend=""
alias debug-functions=""

alias init-env=""

This approach keeps my workflow clean, private, and project-specific. It’s a practical way to use long or repetitive commands without cluttering my global shell configuration.