Turv: A Simple and Secure Way to Manage Environment Variables per Directory 🛠️

Patrick P — Wed, 19 Feb 2025 11:43:38 +0000

Introduction

If you’ve ever switched between projects with different configurations, you’ve probably run into conflicts with environment variables. Maybe you’re using different Terraform versions, managing multiple Git credentials, or handling cloud provider configurations. Manually setting and unsetting environment variables can be a pain—this is where Turv comes in.

This constant reconfiguration creates friction and introduces the risk of using incorrect settings at crucial moments.

Turv automatically manages environment variables, aliases, and tool configurations based on your current directory, making project switching seamless. Unlike similar tools, Turv emphasizes security through an approval system that prevents unintended execution of environment files.

Turv is a directory-based environment loader that automatically sets environment variables when you enter a project directory and removes them when you leave. Inspired by tools like direnv, autoenv, and dirsh, Turv is built with security, simplicity, and flexibility in mind.

Key Features

✅ Comprehensive Environment Handling – Variables, aliases, and functions are loaded when entering a directory and unloaded when leaving.
🔗 Tool Compatibility – Works alongside zoxide, broot, Vault CLI, and 1Password CLI.
🔐 Security-First Design – Prompts for approval before sourcing new environment files.
🔄 Change Detection – Requires re-approval if environment files are modified.
⚙️ Minimal Dependencies – Works with standard utilities like jq or yq.
🖥️ Shell Compatibility – Supports both Bash and Zsh.

Practical Use Cases

Here's where Turv really shines:

⚡ Project-Specific Aliases – Load custom shortcuts and functions that make sense only within specific projects.
🔑 Authentication Context – Switch between different Vault or 1Password CLI profiles automatically.
🚀 Integration with Navigation Tools – Works perfectly alongside zoxide or broot for seamless directory changes.
🌳 Git Worktrees – Each worktree can have its own environment configuration.
📝 Custom Shell Functions – Define project-specific functions that only exist when needed.
🏗️ Version Management – Automatically switch between different versions of Node.js, Python, or other tools as you move between project directories.

Examples:

Some private pet project:

One of many different work projects

As you can see, at least the Gitlab token is clashing. By combining multiple tools, this is no longer a concern and by using Turv, all of this is loaded automatically.

How Turv Works

1️⃣ Enter a directory with an environment file (default: .envrc), and Turv prompts for approval before sourcing it.
2️⃣ If approved, Turv loads the environment variables, aliases, and functions automatically.
3️⃣ When leaving the directory, Turv unloads those configurations to prevent conflicts.
4️⃣ If the .envrc file changes, Turv detects modifications and asks for re-approval.

This approach combines convenience with security: you get automated configuration without risking unintended execution.

When you navigate to this directory, Turv will automatically load these aliases and exports, allowing you to use the correct tool versions without manual configuration.

The Security Advantage

Unlike some alternatives, Turv's built-in approval system protects you by:

1️⃣ Never executing environment files without explicit approval.
2️⃣ Storing approval status securely using JSON/YAML.
3️⃣ Detecting file changes to prevent unauthorized modifications.
4️⃣ Allowing you to inspect files before approval.

Getting More From Turv

Advanced users can extend Turv by implementing custom _load and _unload functions in their environment files, enabling project-specific setup and teardown operations that go beyond simple aliases and exports. 🎯

💡 Try it out today:
GitLab Repository
Github Mirror

Credits & Inspiration 🌍

Turv is inspired by the following projects:

🔗 direnv – A shell extension for managing project-based environments.
🔗 autoenv – A tool for per-directory shell environment settings.
🔗 dirsh – A concept for automatic directory-based environment loading.

DEV Community: Patrick P