MIGRATION

Migration Guide

v2.4.x to v2.5.0: CLI Consistency Changes

v2.5.0 standardizes the CLI interface for swap and sops commands. Both now use consistent scope behavior:

• No args = vault level (default)
• With files = file level
• --global = all vaults

Breaking Changes

Old Command	New Command
rsenv swap vault-out	rsenv swap out
rsenv swap all-out	rsenv swap out --global
rsenv swap all-status	rsenv swap status --global
rsenv swap all-out -C /path	rsenv swap out --global --vault-base /path
rsenv swap all-status -C /path	rsenv swap status --global --vault-base /path

Default Behavior Change

swap out without arguments now defaults to vault level (like sops encrypt):

Old	New
swap out → error	swap out → vault level
swap out --vault → vault level	swap out → vault level

gitignore Scope Change

The gitignore commands now operate on a single scope by default:

Old Behavior	New Behavior
gitignore-sync (no flag) synced both vault and global	gitignore-sync syncs vault only
gitignore-sync --global synced global only	gitignore-sync --global syncs global only

To sync both scopes, run the command twice:

rsenv sops gitignore-sync           # vault
rsenv sops gitignore-sync --global  # global

New Features

• File-level sops operations: rsenv sops encrypt <file> and rsenv sops decrypt <file>
• Consistent scope behavior: No args = vault, with args = file, --global = all vaults

Quick Migration

# Update aliases/scripts
sed -i 's/swap vault-out/swap out/g' ~/.bashrc
sed -i 's/swap out --vault/swap out/g' ~/.bashrc
sed -i 's/swap all-out/swap out --global/g' ~/.bashrc
sed -i 's/swap all-status/swap status --global/g' ~/.bashrc

---

Migration Guide: rs-env (v1) to rsenv (v2)

Migrating from rs-env v1 to rsenv v2 takes about 5 minutes. Your environment files work unchanged.

Quick Migration

# 1. Install v2
cargo install rsenv

# 2. Uninstall v1 (optional)
cargo uninstall rs-env

# 3. Update shell aliases (see below)

# 4. Verify
rsenv --version

Command Mapping

All v1 commands moved under the env subcommand:

v1 (rs-env)	v2 (rsenv)
rsenv build <file>	rsenv env build <file>
rsenv envrc <file>	rsenv env envrc <file>
rsenv select-leaf <file>	rsenv env envrc <file>
rsenv files <file>	rsenv env files <file>
rsenv select [dir]	rsenv env select [dir]
rsenv tree [dir]	rsenv env tree [dir]
rsenv branches [dir]	rsenv env branches [dir]
rsenv edit [dir]	rsenv env edit [dir]
rsenv edit-leaf <file>	rsenv env edit-leaf <file>
rsenv tree-edit [dir]	rsenv env tree-edit [dir]
rsenv leaves [dir]	rsenv env leaves [dir]
rsenv link <files>	rsenv env link <files>
rsenv unlink <file>	rsenv env unlink <file>

Shell Alias Updates

If you have aliases, update them:

# Before (v1)
alias envbuild='rsenv build'
alias envselect='rsenv select'
alias envtree='rsenv tree'

# After (v2)
alias envbuild='rsenv env build'
alias envselect='rsenv env select'
alias envtree='rsenv env tree'

File Format: No Changes

The # rsenv: directive is fully backward compatible:

# rsenv: parent.env
export MY_VAR=value

Your existing .env files work without modification.

What's New in v2

v2 adds three major capabilities beyond environment management:

Vault System

Unified secure storage outside your project:

rsenv init vault        # Create vault for project
rsenv info              # Show vault status

File Guarding

Move sensitive files to vault, leave symlinks:

rsenv guard add secrets.yaml
rsenv guard list
rsenv guard restore secrets.yaml

File Swapping

Temporary development overrides:

rsenv swap init config.yml    # Move to vault
rsenv swap in config.yml      # Use vault version
rsenv swap out config.yml     # Restore original
rsenv swap status

SOPS Encryption

Encrypt vault contents:

rsenv sops encrypt
rsenv sops decrypt
rsenv sops status

Configuration

Unified config at ~/.config/rsenv/rsenv.toml:

rsenv config init --global
rsenv config show
rsenv config path

Environment Variables

New variables in v2:

Variable	Purpose
RSENV_VAULT	Path to current project's vault
RSENV_SWAPPED	Set to 1 when files are swapped in
RSENV_VAULT_BASE_DIR	Override vault base directory

Gradual Adoption

You can adopt v2 features incrementally:

1. Day 1: Use rsenv env commands (drop-in replacement)
2. Later: Initialize vault with rsenv init vault
3. As needed: Guard sensitive files, set up swapping

The vault features are optional. You can use rsenv purely for environment hierarchy management, just like v1.

Troubleshooting

"command not found: rsenv"

# Check installation
which rsenv
cargo install rsenv

Old aliases still use v1 syntax

# Find aliases
grep -r "rsenv build\|rsenv select\|rsenv tree" ~/.bashrc ~/.zshrc ~/.config/fish

# Update to v2 syntax

v1 and v2 both installed

# Remove v1
cargo uninstall rs-env

# Verify only v2
rsenv --version

See Also

• Quick Start - Get started with v2
• Core Concepts - Understand the vault philosophy
• Command Reference - Complete command documentation