diff --git a/README.md b/README.md index 567277f..36aced5 100644 --- a/README.md +++ b/README.md @@ -2,253 +2,141 @@ **Hierarchical environment variable management for modern development workflows** -> [Documentation](https://sysid.github.io/hierarchical-environment-variable-management/) +> [Documentation](https://sysid.github.io/hierarchical-environment-variable-management/) | [Wiki](https://github.com/sysid/rs-env/wiki) -## Overview +[![Crates.io](https://img.shields.io/crates/v/rs-env.svg)](https://crates.io/crates/rs-env) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -Managing environment variables across different environments (development, staging, production) and configurations (regions, features, services) is a common challenge in cloud-native projects. `rsenv` solves this by implementing hierarchical inheritance where child configurations automatically inherit and can override parent values. +## Why rs-env? -**Key Benefits:** -- **Zero Duplication**: Share common variables across environments while customizing specific values -- **Clear Provenance**: Easily trace where each variable value originates in the hierarchy -- **Type Safety**: Built-in validation and structured configuration management -- **Developer Experience**: Interactive selection, editing, and integration with popular tools - -## Features - -### Core Functionality -- **Hierarchical Inheritance**: Build environment trees from `.env` files with parent-child relationships -- **Smart Override Logic**: Child variables automatically override parent values with clear precedence rules -- **Standalone File Support**: Automatically detect and include independent `.env` files as single-node trees -- **Environment Expansion**: Full support for `$VAR` and `${VAR}` syntax in paths and comments -- **Flexible Linking**: Link files with comments supporting variable spacing: `# rsenv: parent.env` - -### Interactive Tools -- **Fuzzy Selection**: Built-in fuzzy finder (skim) for rapid environment discovery and selection -- **Smart Editing**: Edit entire hierarchies side-by-side or individual files with full context -- **Tree Visualization**: Display hierarchical relationships and identify leaf nodes -- **Branch Analysis**: Linear representation of all environment chains +Managing environment variables across different environments (development, staging, production) and configurations (regions, features, services) creates massive duplication in traditional `.env` files. **rs-env solves this** by implementing hierarchical inheritance where child configurations automatically inherit and override parent values. -### Integrations -- **[direnv](https://direnv.net/)**: Automatic environment activation when entering directories -- **[JetBrains IDEs](https://plugins.jetbrains.com/plugin/7861-envfile)**: Native IDE integration via EnvFile plugin -- **Shell Integration**: Generate completion scripts for bash, zsh, fish, and powershell +**Key Benefits:** +- **Zero Duplication** - Share common variables across environments while customizing specific values +- **Clear Provenance** - Easily trace where each variable value originates in the hierarchy +- **Interactive Tools** - Fuzzy selection, side-by-side editing, and tree visualization +- **Modern Integrations** - Works with direnv, JetBrains IDEs, and popular shells -### Concept -![concept](doc/concept.png) +## Quick Demo + ## Installation -### From crates.io ```bash +# From crates.io cargo install rs-env -``` -### From source -```bash +# From source git clone https://github.com/sysid/rs-env cd rs-env/rsenv cargo install --path . ``` -## Quick Start +**Requirements**: Rust 1.70+ ([Install Rust](https://rustup.rs/)) -### 1. File Structure -Create linked environment files using `# rsenv:` comments: +## 30-Second Example + +Create a hierarchy where child environments inherit from parents: ```bash -# base.env +# base.env - Shared configuration export DATABASE_HOST=localhost export LOG_LEVEL=info -# production.env +# production.env - Inherits from base, overrides specific values # rsenv: base.env -export DATABASE_HOST=prod.example.com -export LOG_LEVEL=warn +export DATABASE_HOST=prod-db.example.com +export LOG_LEVEL=error export ENVIRONMENT=production ``` -### 2. Basic Usage +Build the complete environment: + ```bash -# Build complete environment from hierarchy +# Build production environment rsenv build production.env -# Load into current shell +# Load into your shell source <(rsenv build production.env) -# Interactive selection with fuzzy finder -rsenv select environments/ - -# View tree structure -rsenv tree environments/ - -# Find all leaf environments -rsenv leaves environments/ -``` - -### 3. Advanced Features -```bash -# Edit entire hierarchy side-by-side -rsenv tree-edit environments/ - -# Update direnv integration -rsenv envrc production.env - -# Link files programmatically -rsenv link base.env staging.env production.env +# Verify +echo $DATABASE_HOST # prod-db.example.com (from production.env) +echo $LOG_LEVEL # error (from production.env) ``` -## File Format +**Result**: `production.env` inherits `base.env` variables and overrides what changes. The `# rsenv: base.env` comment creates the parent-child link. -### Environment Files -- Use `export VAR=value` syntax (shell-compatible) -- Support single and double quotes -- Include `# rsenv: parent.env` comments for hierarchy +## Core Features -### Linking Syntax -```bash -# Basic parent reference -# rsenv: parent.env +### Hierarchical Inheritance +- Build environment trees from `.env` files with parent-child relationships +- Smart override logic: child variables automatically override parent values +- Standalone file support: independent `.env` files work as single-node trees -# Multiple parents (creates DAG structure) -# rsenv: base.env shared.env - -# Environment variable expansion -# rsenv: $HOME/config/base.env - -# Flexible spacing (all valid) -# rsenv:parent.env -# rsenv: parent.env -# rsenv: parent.env -``` - -## Command Reference - -### Core Commands -| Command | Description | Example | -|---------|-------------|---------| -| `build` | Build complete environment from hierarchy | `rsenv build prod.env` | -| `leaves` | List all leaf environment files | `rsenv leaves environments/` | -| `tree` | Display hierarchical structure | `rsenv tree environments/` | -| `branches` | Show linear representation of all chains | `rsenv branches environments/` | - -### Interactive Commands -| Command | Description | Example | -|---------|-------------|---------| -| `select` | Interactive environment selection + direnv update | `rsenv select environments/` | -| `edit` | Interactive selection and editing | `rsenv edit environments/` | -| `tree-edit` | Side-by-side editing of hierarchies | `rsenv tree-edit environments/` | - -### Management Commands -| Command | Description | Example | -|---------|-------------|---------| -| `envrc` | Update .envrc file for direnv | `rsenv envrc prod.env .envrc` | -| `files` | List all files in hierarchy | `rsenv files prod.env` | -| `link` | Create parent-child relationships | `rsenv link base.env prod.env` | - -### Global Options -- `-d, --debug`: Enable debug logging (use multiple times for increased verbosity) -- `--generate`: Generate shell completion scripts (bash, zsh, fish, powershell) -- `--info`: Display version and configuration information - -## Examples - -### Basic Workflow - - -### Interactive Selection - - -### Tree Editing - - -## Integrations - -### direnv Integration -[direnv](https://direnv.net/) provides automatic environment activation: +### Interactive Tools +- **Fuzzy Selection** - Built-in fuzzy finder for rapid environment discovery +- **Smart Editing** - Edit entire hierarchies side-by-side or individual files +- **Tree Visualization** - Display relationships and identify leaf nodes -```bash -# Generate .envrc for automatic loading -rsenv envrc production.env .envrc +### Integrations +- **[direnv](https://direnv.net/)** - Automatic environment activation when entering directories +- **[JetBrains IDEs](https://plugins.jetbrains.com/plugin/7861-envfile)** - Native IDE integration via EnvFile plugin +- **Shell Completion** - bash, zsh, fish, and powershell support -# Interactive selection with direnv update -rsenv select environments/ +## How It Works -# Manual direnv commands -direnv allow # Enable .envrc -direnv reload # Refresh environment -``` +![Concept](doc/concept.png) -### JetBrains IDEs -Integration via [EnvFile plugin](https://plugins.jetbrains.com/plugin/7861-envfile): +Environment files form **directed acyclic graphs (DAGs)** where: +1. Child files link to parents via `# rsenv: parent.env` comments +2. Variables are inherited and merged from parent to child +3. Child values override parent values (last defined wins) +4. The `build` command compiles the complete environment -1. Install the EnvFile plugin -2. Create a run configuration script: - ```bash - #!/bin/bash - # runenv.sh - rsenv build "${RUN_ENV}.env" - ``` -3. Configure the plugin to use `runenv.sh` -4. Set `RUN_ENV` environment variable in your run configuration +## Essential Commands -[![jetbrain](doc/jetbrain.png)](doc/jetbrain.png) +| Command | Purpose | +|---------|---------| +| `rsenv build ` | Build complete environment from hierarchy | +| `rsenv select ` | Interactive selection + direnv update | +| `rsenv tree ` | Display hierarchical structure | +| `rsenv edit ` | Interactive selection and editing | -### Shell Integration -Generate completion scripts for your shell: +**[Full Command Reference](https://github.com/sysid/rs-env/wiki/Command-Reference)** -```bash -# Bash -rsenv --generate bash > ~/.bash_completion.d/rsenv +## Documentation -# Zsh -rsenv --generate zsh > ~/.zsh/completions/_rsenv +**New to rs-env?** Start with the [Quick Start Guide](https://github.com/sysid/rs-env/wiki/Quick-Start) -# Fish -rsenv --generate fish > ~/.config/fish/completions/rsenv.fish -``` +**Comprehensive documentation** is available in the [rs-env Wiki](https://github.com/sysid/rs-env/wiki): +- **Getting Started**: [Quick Start](https://github.com/sysid/rs-env/wiki/Quick-Start), [Installation](https://github.com/sysid/rs-env/wiki/Installation), [Core Concepts](https://github.com/sysid/rs-env/wiki/Core-Concepts) +- **Core Features**: [Building Environments](https://github.com/sysid/rs-env/wiki/Building-Environments), [Viewing Hierarchies](https://github.com/sysid/rs-env/wiki/Viewing-Hierarchies), [File Format](https://github.com/sysid/rs-env/wiki/File-Format) +- **Interactive Tools**: [Interactive Selection](https://github.com/sysid/rs-env/wiki/Interactive-Selection), [Tree Editing](https://github.com/sysid/rs-env/wiki/Tree-Editing) +- **Integrations**: [direnv](https://github.com/sysid/rs-env/wiki/direnv-Integration), [JetBrains IDEs](https://github.com/sysid/rs-env/wiki/JetBrains-IDEs), [Shell Completion](https://github.com/sysid/rs-env/wiki/Shell-Completion) +- **Advanced**: [Managing Links](https://github.com/sysid/rs-env/wiki/Managing-Links), [Complex Hierarchies](https://github.com/sysid/rs-env/wiki/Complex-Hierarchies) +- **Reference**: [Command Reference](https://github.com/sysid/rs-env/wiki/Command-Reference), [Troubleshooting](https://github.com/sysid/rs-env/wiki/Troubleshooting) +## Contributing -## Development +Contributions are welcome! See the [Development Guide](https://github.com/sysid/rs-env/wiki/Development) for details on building, testing, and contributing. -### Building from Source ```bash +# Quick start for contributors git clone https://github.com/sysid/rs-env cd rs-env/rsenv +cargo test -- --test-threads=1 cargo build --release ``` -### Running Tests -```bash -# Run all tests (single-threaded to prevent conflicts) -cargo test -- --test-threads=1 +## License -# Run with debug output -RUST_LOG=debug cargo test -- --test-threads=1 +MIT License - see [LICENSE](LICENSE) for details. -# Test via Makefile (includes interactive tests) -make test -``` +## Links -### Project Structure -- **`src/lib.rs`**: Core environment expansion and tree building logic -- **`src/builder.rs`**: TreeBuilder for constructing hierarchical structures -- **`src/arena.rs`**: Arena-based tree data structures -- **`src/cli/`**: Command-line interface and command implementations -- **`tests/`**: Comprehensive test suite with example environments - -### Testing Notes -- Interactive tests using skim require a valid terminal and are run via Makefile -- Tests run single-threaded to prevent file system conflicts -- Test resources in `tests/resources/environments/` demonstrate complex hierarchies - -### Contributing -1. Fork the repository -2. Create a feature branch -3. Add tests for new functionality -4. Ensure all tests pass: `cargo test -- --test-threads=1` -5. Run formatting: `cargo fmt` -6. Run linting: `cargo clippy` -7. Submit a pull request +- 📦 [crates.io Package](https://crates.io/crates/rs-env) +- 📖 [Wiki Documentation](https://github.com/sysid/rs-env/wiki) +- 🐛 [Issue Tracker](https://github.com/sysid/rs-env/issues) +- 💬 [Discussions](https://github.com/sysid/rs-env/discussions) diff --git a/doc/example-walkthrough/README.md b/doc/example-walkthrough/README.md new file mode 100644 index 0000000..8f4bf22 --- /dev/null +++ b/doc/example-walkthrough/README.md @@ -0,0 +1,44 @@ +# Example Walkthrough + +This directory contains a realistic example of hierarchical environment configuration used throughout the rs-env documentation. + +## Structure + +``` +base.env # Shared base configuration + └─ cloud.env # Cloud-specific overrides + └─ production.env # Production-specific overrides +dev.env # Standalone development environment +``` + +## Files + +- **base.env**: Base configuration shared across all environments + - DATABASE_HOST, DATABASE_PORT, LOG_LEVEL, APP_NAME + +- **cloud.env**: Inherits from base.env, overrides for cloud deployments + - Overrides: DATABASE_HOST, LOG_LEVEL + - Adds: CLOUD_PROVIDER, REGION + +- **production.env**: Inherits from cloud.env, production-specific settings + - Overrides: DATABASE_HOST, LOG_LEVEL, REGION + - Adds: ENVIRONMENT, API_KEY, ENABLE_MONITORING + +- **dev.env**: Standalone file for local development (no parent) + - Independent configuration for development workflow + +## Usage + +```bash +# Build production environment (inherits base → cloud → production) +rsenv build production.env + +# Build development environment (standalone) +rsenv build dev.env + +# View the hierarchy +rsenv tree . + +# List all leaf environments +rsenv leaves . +``` diff --git a/doc/example-walkthrough/base.env b/doc/example-walkthrough/base.env new file mode 100644 index 0000000..8557e66 --- /dev/null +++ b/doc/example-walkthrough/base.env @@ -0,0 +1,5 @@ +# Base configuration - shared across all environments +export DATABASE_HOST=localhost +export DATABASE_PORT=5432 +export LOG_LEVEL=info +export APP_NAME=my-cloud-app diff --git a/doc/example-walkthrough/cloud.env b/doc/example-walkthrough/cloud.env new file mode 100644 index 0000000..e706527 --- /dev/null +++ b/doc/example-walkthrough/cloud.env @@ -0,0 +1,7 @@ +# rsenv: base.env + +# Cloud-specific configuration +export DATABASE_HOST=db.cloud.internal +export LOG_LEVEL=warn +export CLOUD_PROVIDER=aws +export REGION=us-east-1 diff --git a/doc/example-walkthrough/dev.env b/doc/example-walkthrough/dev.env new file mode 100644 index 0000000..2b3ebe0 --- /dev/null +++ b/doc/example-walkthrough/dev.env @@ -0,0 +1,7 @@ +# Standalone development environment (no parent) +export DATABASE_HOST=localhost +export DATABASE_PORT=5432 +export LOG_LEVEL=debug +export APP_NAME=my-cloud-app +export ENVIRONMENT=development +export DEBUG=true diff --git a/doc/example-walkthrough/production.env b/doc/example-walkthrough/production.env new file mode 100644 index 0000000..85ad6ac --- /dev/null +++ b/doc/example-walkthrough/production.env @@ -0,0 +1,9 @@ +# rsenv: cloud.env + +# Production-specific configuration +export DATABASE_HOST=prod-db.cloud.internal +export LOG_LEVEL=error +export ENVIRONMENT=production +export API_KEY=prod-secret-key-12345 +export REGION=us-east-1 +export ENABLE_MONITORING=true diff --git a/doc/example/prod.env b/doc/example/prod.env index d087e46..0003925 100644 --- a/doc/example/prod.env +++ b/doc/example/prod.env @@ -1,4 +1,4 @@ -# rsenv shared/level3.env +# rsenv: shared/level3.env other stuff # comments