Project Aliases (Zsh Plugin)

A lightweight Zsh plugin to manage per-project shell aliases.
Aliases are loaded automatically when you enter a project folder and removed automatically when you leave.

---

⚡ Quick Start

# Inside your project folder
echo "alias run='npm run dev'" > .proj_aliases
echo "alias test='npm test'" >> .proj_aliases

cd ~/my-project
# [project-aliases] Warning: Untrusted .proj_aliases found. Run 'palias allow' to trust and load it.

palias allow
# [project-aliases] Loaded and trusted aliases for project: /Users/username/my-project

run
# Executes: npm run dev

cd ..
# [project-aliases] Project aliases removed

---

✨ Features

• Define aliases per project in a .proj_aliases file.
• 🔒 Security-First: Requires explicit trust (palias allow) before loading a .proj_aliases file. If the file is modified externally, the trust is invalidated, preventing silent execution of untrusted code.
• Automatically load aliases when entering a trusted project folder.
• Automatically unload them when leaving.
• Keep a clean shell environment — no alias pollution between projects.
• Helper commands:
  • palias list → view currently active project aliases
  • palias edit → edit currently project aliases
  • palias reload → reload aliases for the current project without leaving the folder
  • palias allow → trust and load aliases for the current project
  • palias deny → untrust and unload aliases for the current project

---

📦 Installation

Oh My Zsh

1. Clone the plugin into your Oh My Zsh custom plugins folder:

   git clone https://github.com/dvigo/project-aliases.git ~/.oh-my-zsh/custom/plugins/project-aliases
   

2. Enable it in your ~/.zshrc:

   plugins=(... project-aliases)
   

3. Reload Zsh:

   source ~/.zshrc
   

---

🎥 Demo

TBD

---

⚙️ Configuration

No extra configuration is needed.
Simply create a .proj_aliases file in the root of any project you want to use aliases in.

Example .proj_aliases

alias run="npm run dev"
alias lint="eslint src/"
alias up="docker-compose up -d"
alias down="docker-compose down"

---

🖊️ Usage

Available commands:

palias list    # Shows active project aliases
palias edit    # Opens the current project's .proj_aliases in your editor
palias reload  # Reload aliases from the current project's .proj_aliases
palias allow   # Trust and load the current project's .proj_aliases
palias deny    # Untrust and unload the current project's .proj_aliases

Example session:

cd ~/dev/my-api
# [project-aliases] Warning: Untrusted .proj_aliases found. Run 'palias allow' to trust and load it.

palias allow
# [project-aliases] Loaded and trusted aliases for project: /Users/username/dev/my-api

up      # runs docker-compose up -d
down    # runs docker-compose down

# If you modify .proj_aliases, it becomes untrusted again. Re-run allow to load it:
palias allow

cd ..
# [project-aliases] Project aliases removed

---

🔧 Roadmap

• Add support for .proj_aliases.d/ folder with multiple alias files.
• Add an option to persist aliases across shells until manually cleared.
• Add support for project-specific environment variables.

---

📜 License

GNU General Public License v3.0 — See LICENSE for details.

---