dirvana

README

Dirvana - Reach directory nirvana

[!WARNING] Beta Status - We Need Your Feedback!

Dirvana is currently in beta. Found a bug? Have a feature request? Please open an issue!

Automatically load shell aliases, functions, and environment variables per directory.

Dirvana is a lightweight CLI tool that manages project-specific shell environments.

When you enter a directory, Dirvana automatically loads the configuration defined in .dirvana.yml, giving you instant access to project-specific commands and settings.

When you leave, everything is automatically unloaded.

The Problem

$ cd ~/projects/terraform
$ export TF_LOG=debug
$ alias tf="task terraform --"
$ alias plan="task terraform -- plan"
# ... and don't forget to unset everything when leaving!

The Solution

# .dirvana.yml
aliases:
  tf:
    command: task terraform --
    completion: terraform  # Auto-completion works!
  plan: task terraform -- plan

env:
  TF_LOG: debug

$ cd ~/projects/terraform
# Everything loads automatically!
$ tf <TAB>          # Auto-completion works!
  apply  console  destroy  init  plan  validate ...

$ cd ..
# Everything unloads automatically!

---

Features

• Fast: <10ms overhead with intelligent caching
• Secure: Authorization system prevents untrusted configs
• Hierarchical: Merge configurations from parent directories
• Simple: YAML configuration with JSON Schema validation
• Compatible: Works with Bash, Zsh, and Fish
• Auto-completion: Inherits completion from aliased commands
• Conditional Aliases: Execute commands based on runtime conditions
• Template Variables: Go templates with Sprig functions

---

Quick Start

1. Install

# Using go install
go install github.com/NikitaCOEUR/dirvana/cmd/dirvana@latest

# Or download binary
curl -L https://github.com/NikitaCOEUR/dirvana/releases/latest/download/dirvana-linux-amd64 -o /usr/local/bin/dirvana
chmod +x /usr/local/bin/dirvana

2. Setup Shell Hook

dirvana setup
source ~/.bashrc  # or ~/.zshrc, or ~/.config/fish/config.fish

3. Create Configuration

cd your-project
dirvana init
dirvana allow

That's it! Your environment is now automatically managed.

---

Configuration Example

# Simple aliases
aliases:
  # With auto-completion
  tf:
    command: task terraform -- # Execute a wrapper command that use specific variables
    completion: terraform      # But keep terraform completion

  # Conditional execution
  k:
    when:
      file: "$KUBECONFIG"      # Check if KUBECONFIG file exists
    command: kubecolor         # If exists, use command kubecolor based on $KUBECONFIG
    else: task kubecolor --    # else execute a task which generate your kubeconfig file and call kubecolor afterwards
    completion: kubectl        # Inherit kubectl completion

# Functions
functions:
  mkcd: |
    mkdir -p "$1" && cd "$1"

# Environment variables
env:
  KUBECONFIG: "/tmp/kubeconfig-{{.USER_WORKING_DIR | sha256sum | trunc 8}}"

---

Documentation

Full documentation is available at https://nikitacoeur.github.io/dirvana/

• Installation Guide - Detailed installation instructions
• Quick Start - Get up and running in 5 minutes
• Configuration Reference - Complete configuration guide
• Conditional Aliases - Runtime condition checks
• Template Variables - Go templates with Sprig functions
• Development Guide - Contributing and development

---

Contributing

Contributions are welcome! Please ensure:

• All commits follow Conventional Commits
• All tests pass: task test
• Code is formatted: task fmt
• Linter passes: task lint

---

Changelog

Release notes are generated from conventional commits and published on the GitHub Releases page.

License

MIT License - See LICENSE file for details

Author

Nikita C