Sherpa - Project based development environment

Sherpa carries your local environment settings for you as you cd through projects, space and time.

Status

🚧 Unstable, under active development.

Demo - Core functionality

$ cd ~/projects

$ echo "$VAR_1"
GLOBAL VAR
$ alias_1
GLOBAL ALIAS
$ function_1
GLOBAL FUNCTION

$ cd project_awesome

$ echo "$VAR_1"
LOCAL VAR PROJECT AWESOME
$ alias_1
LOCAL ALIAS PROJECT AWESOME
$ function_1
LOCAL FUNCTION PROJECT AWESOME

$ cd ..

$ echo "$VAR_1"
GLOBAL VAR
$ alias_1
GLOBAL ALIAS
$ function_1
GLOBAL FUNCTION

The above is accomplished with the help of Sherpa and the files below.

# ~/.bashrc or ~/.zshrc etc...
export VAR_1="GLOBAL VAR"

alias alias_1='echo "GLOBAL ALIAS"'

function_1() {
  echo "GLOBAL FUNCTION"
}

# ~/projects/project_awesome/.envrc
export VAR_1="LOCAL VAR PROJECT AWESOME"

alias alias_1='echo "LOCAL ALIAS PROJECT AWESOME"'

function_1() {
  echo "LOCAL FUNCTION PROJECT AWESOME"
}

Basic usage

1. $ cd ~/projects/project_awesome
2. $ sherpa edit
   1. It opens the local env file in your editor
   2. It trusts and loads it automatically when you close it
3. You can nest envs by repeating this in subdirectories
4. Disco

For more details see the Features section.

Supported shells

• Zsh
• Bash

Tested on

• macOS 12 - Monterey
• macOS 13 - Ventura
• macOS 14 - Sonoma
• Ubuntu 20.04
• Ubuntu 22.04

Supported data structures and things

• Exported variables
• Aliases
• Functions

Unexported variables and other data types are not supported yet.

Side effect

When sherpa loads the local env, it sources the local env file meaning its whole content is executed in the current shell.

Installation

# Clone the repo
$ git clone [email protected]:tothpeter/local_sherpa.git ~/.dotfiles/lib/local_sherpa

# Hook it into your shell
## Zsh
$ echo "source ~/.dotfiles/lib/local_sherpa/init.sh" >> ~/.zshrc
## Bash
$ echo "source ~/.dotfiles/lib/local_sherpa/init.sh" >> ~/.bashrc

# Exclude the local env files (.envrc) globally in Git
$ echo ".envrc" >> $(git config --global core.excludesfile)

# Optional but recommended
alias se='sherpa edit'
alias st='sherpa trust'
alias upgrade_sherpa='git -C ~/.dotfiles/lib/local_sherpa pull'

Features

See the full list of commands by running $ sherpa in your shell.

Security

Sherpa won't load any local env file unless you trust the directory first. This is to prevent running malicious code when you cd into a directory.

$ echo "alias rs=rspec" > ~/projects/project_awesome/.envrc
$ cd ~/projects/project_awesome
Sherpa: The local env file is not trusted. Run `sherpa trust` to mark it as trusted.
$ rs
command not found: rs
$ sherpa trust
Sherpa: Trusted!
$ rs
# rspec starts

When a local env file changes you have to trust the directory again.

Use sherpa edit. It opens the local env file in your editor then trusts it automatically when you close the file.

You can untrust a directory with sherpa untrust.

Loading envs from parent directories automatically

It is not supported currently. Feel free to open a feature request.

Env loading and unloading

• Sherpa supports nested envs
  • It unload the envs in the correct order to restore the overridden items.
• Sherpa does not unload the loaded envs when you cd into a subdirectory.

Demo

# Given the following directory structure with the corresponding local env files
# ~/projects/.envrc
# ~/projects/project_awesome/.envrc
# ~/projects/project_awesome/subdir

$ cd ~/projects/
# Sherpa loads the local env for projects
# Items defined in this folder override the items defined in the global env
$ cd project_awesome
# Sherpa does not unload the previous local env
# Sherpa loads the local env for project_awesome
# Items defined in this folder override the items defined in previous envs
$ cd subdir
# Sherpa does not unload the previous local envs
$ cd ..
# Sherpa does not reload the local env for project_awesome
$ cd ..
# Sherpa unloads the local env for project_awesome and restores the local env for projects
# This rolls back the overrides made by the local env for project_awesome
$ cd ..
# Sherpa unloads the local env for projects and restores the global env
# This rolls back the overrides made by the local env for projects

Running a script when leaving a directory

It is not supported currently. Feel free to open a feature request.
Alternatively, you can use: https://github.com/hyperupcall/autoenv

Configuration

Set the following environment variable anywhere to instruct Sherpa on how to operate.

export SHERPA_ENV_FILENAME='.env' # Default: .envrc

Settings

Log level

It affects only the current and new terminal sessions.

sherpa talk more   - Decrease the log level
sherpa talk less   - Increase the log level
sherpa talk        - Debug level | Aliases: debug
sherpa shh         - Silence
sherpa log [LEVEL] - Set a specific log level | Levels: debug, info, warn, error, silent | Aliases: talk

Disable/enable Sherpa

It affects only the current and new terminal sessions.

$ sherpa off # aliases: sleep, disable
Sherpa: All envs are unloaded. Sherpa goes to sleep.
$ sherpa on # aliases: work, enable
Sherpa: Local env is loaded. Sherpa is ready for action.

Cookbook

Run RSpec in a container or else

# Run RSpec in the `project-awesome-api` Docker container

# ~/projects/project_awesome_api/.envrc
alias de='docker exec -it project-awesome-api'
alias rs='de rspec'

# Run RSpec on the host machine

# ~/projects/project_for_mortals/.envrc
alias rs='bin/rspec'

With this config RSpec will run depending on in which directory you cd into.

Run the tests the same way in different projects

# ~/projects/project_ruby_with_docker/.envrc
alias t='docker exec -it project-awesome-api rspec'

# ~/projects/project_elixir/.envrc
alias t='mix test'

# ~/projects/project_js_with_jest/.envrc
alias t='yarn test'

Rails console in production 🤫

# ~/projects/project_with_heroku/.envrc
alias rc_prod='heroku run rails c -a APP_NAME'

# ~/projects/project_with_aws/.envrc
alias rc_prod='ssh -i /path/key-pair-name.pem user@hostname "/var/app/current/bin/rails console"'

Start your dev environment

# ~/projects/project_with_docker/.envrc
alias up='docker-compose up -d'
alias upb='docker-compose up --build -d'
alias down='docker-compose down'

# ~/projects/project_basic/.envrc
alias up='bin/rails s'

Troubleshooting

$ sherpa diagnose

Local development

Testing

All *_test.sh files are run recursively from the tests directory.

# Run all the tests for all the supported shells
$ make test

# Run a single test for all the supported shells
$ make test tests/features/edit_test.sh

# Run all the tests for Zsh
$ make test_zs

# Run a single test for Zsh
$ make test_zs tests/features/edit_test.sh

# Run all the tests for Bash
$ make test_bash

# Run a single test for Bash
$ make test_bash tests/features/edit_test.sh

# Run all the tests for all the supported shells in Ubuntu
$ make test_all_in_ubuntu

# Run a single test for all the supported shells in Ubuntu
$ make test_all_in_ubuntu tests/features/edit_test.sh

# Test the performance for all the supported shells
# It is not a real test, it is more like a benchmark
$ make test_performance

Linting

$ make lint

Credits

This project uses the varstash library from smartcd, which is licensed under the Artistic License.

Special thanks to the original author:

• Dave Olszewski [email protected]

The varstash library is modified to fit the needs of this project.