https://github.com/sherpalabsio/local_sherpa
Define folder specific aliases, functions and variables in your shell.
https://github.com/sherpalabsio/local_sherpa
aliases bash direnv environment shell-extension terminal zsh
Last synced: about 1 month ago
JSON representation
Define folder specific aliases, functions and variables in your shell.
- Host: GitHub
- URL: https://github.com/sherpalabsio/local_sherpa
- Owner: sherpalabsio
- License: other
- Created: 2024-06-20T11:15:09.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-10T18:13:57.000Z (8 months ago)
- Last Synced: 2025-02-14T07:24:45.580Z (8 months ago)
- Topics: aliases, bash, direnv, environment, shell-extension, terminal, zsh
- Language: Shell
- Homepage:
- Size: 370 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
----------
[](https://github.com/sherpalabsio/local_sherpa/actions/workflows/ci.yml)
[](#supported-shells)
## Define folder specific aliases, functions and variables in your shell
Sherpa is a shell extension that allows you to define new or override existing aliases, functions or variables on a per-folder basis, with support for nesting.
It's similar to [Direnv](https://github.com/direnv/direnv), but with fewer features and added support for aliases and functions.
## ASCII Demo
```sh
$ cd ~/projects
$ c # short for console
# IRB (Interactive Ruby Shell) starts
# ctrl + d to exit
$ cd ~/projects/project_elixir
$ c
# IEx (Interactive Elixir) starts
# ctrl + c to exit
$ cd ~/projects/project_postgres
$ c
# Docker container with Postgres starts
# PSQL (PostgreSQL interactive terminal) in the container starts
```
The above is accomplished with the help of Sherpa and the files below.
```sh
# ~/.zshrc or ~/.bashrc
alias c='irb'
# ~/projects/project_elixir/.envrc
alias c='iex'
# ~/projects/project_postgres/.envrc
c() {
# Start the Postgres container if it's not running
[ -z "$(docker compose ps -q)" ] && docker compose up -d
docker compose exec db psql -U postgres
}
```
## Basic usage
1. $ cd ~/projects/project_awesome
2. $ sherpa edit
1. Sherpa opens the env file in your editor
2. You update, save then close it
3. Sherpa unloads the previous version, trusts and loads the current one automatically
3. You can nest envs by repeating this in subdirectories
4. [Disco](https://www.youtube.com/watch?v=UkSPUDpe0U8)
For more details see the [Features](#features) section.
## Supported shells
- Zsh (5.3.1 or higher)
- Bash (4.3 or higher)
## Tested on
- macOS 13 - Ventura
- macOS 14 - Sonoma
- macOS 15 - Sequoia
- Ubuntu 22.04
- Ubuntu 24.04
## Installation
### Homebrew
```sh
brew install sherpalabsio/sherpalabsio/local_sherpa
```
### Automated
```sh
curl -s https://raw.githubusercontent.com/sherpalabsio/local_sherpa/main/scripts/install.sh | bash
```
This script will automatically:
- Install the latest version to `~/.local/lib`
- Symlink the `init` file to `~/.local/bin/local_sherpa_init`
- Add `~/.local/bin` to your `PATH` (if not already present)
- Configure your shell profile (`~/.zshrc` or `~/.bashrc`) to initialize Sherpa
### Manual
- Download a release (local_sherpa_X.X.X.tar.gz) from the [releases page](https://github.com/sherpalabsio/local_sherpa/releases)
- Symlink the `init` file as `local_sherpa_init` somewhere in your `PATH`
- Add `eval "$(local_sherpa_init)"` to your shell profile (e.g. `~/.zshrc`, `~/.bashrc`)
### Git configuration
Exclude the env files (.envrc) globally so you won't commit them by mistake.
```sh
echo ".envrc" >> $(git config --global core.excludesfile)
```
## Upgrading to the latest version
`$ sherpa update`
## Features
See the full list of commands by running `$ sherpa` in your shell.
### Security
Sherpa won't load any env file unless you trust it first (`$ sherpa trust`).\
This is to prevent running unknown code when you `cd` into a directory.
When an env file changes you have to trust it again unless you edited it
with `$ sherpa edit` which trusts and reloads the env file after you close it
in your editor.
You can untrust an env file with `sherpa untrust`.
### Command palette with fuzzy finder for the local env (experimental)
`$ sherpa palette`
It requires [fzf](https://github.com/junegunn/fzf?tab=readme-ov-file#installation).
Offers a list of available commands and variables in the current env.\
Select a command hit enter then hit enter again to run it.
The list can be less accurate if the dynamic env file parsing is not enabled.
Enable it by setting the `SHERPA_ENABLE_DYNAMIC_ENV_FILE_PARSING` environment variable to `true`.
#### Bind it to Shift + Command + P:
Make sure your terminal sends `^[[80;9u` or a similar escape sequence when
you press Shift + Command + P.
```sh
# Zsh (~/.zshrc)
__sherpa_palette() {
sherpa palette
}
zle -N __sherpa_palette
bindkey "^[[80;9u" __sherpa_palette
# For tmux: bindkey "^[P" __sherpa_palette
# Bash (~/.bashrc)
__sherpa_palette() {
sherpa palette
}
bind -x '"\e[80;9u":__sherpa_palette'
```
### Env loading and unloading
- Sherpa loads the env from a `.envrc` file when you `cd` into a directory
- It sources the env file meaning its whole content is executed in the current shell
- It overrides the existing aliases, functions and variables
- Sherpa unloads the env when you leave a directory
- It removes the newly added aliases, functions and variables
- It restores the overridden items to their previous state
- Going into a subdirectory does not unload the env of the parent directory
- Sherpa partially supports nested envs
- Loading parent envs is not supported you have to `cd` into the parent directory first
### Dynamic env loading and unloading (experimental)
Non exported variables and dynamically created entities are unloaded only if the
`SHERPA_ENABLE_DYNAMIC_ENV_FILE_PARSING` environment variable is set to `true`.
This can slow down `cd` because Sherpa executes the env file in a subshell
three times when you `cd` into a directory.
### Aliases and functions in the env file taking precedence
Declaring a function in the env file with the same name as an existing alias
will override the alias automatically. No need to call `unalias`.\
The same applies to declaring aliases in the env
file with the same name as existing functions.
### Command inheritance (experimental)
This is an unreleased feature available only in the `main` branch.
By calling `super` in a function, you can invoke the overridden function or alias.
#### Example:
```sh
# ~/.zshrc or ~/.bashrc
function_name() {
local param1="$1"
echo "Original function with param: $param1"
}
# ~/projects/project_elixir/.envrc
function_name() {
super "$@"
echo "Overridden function"
}
cd ~
function_name 1
# Prints:
# Original function with param: 1
cd ~/projects/project_elixir
function_name 1
# Prints:
# Original function with param: 1
# Overridden function
```
### Loading envs from parent directories automatically
This is not supported currently. Feel free to open a feature request.
### Running a script when leaving a directory
This is not supported currently. Feel free to open a feature request.\
Alternatively, you can use: https://github.com/hyperupcall/autoenv
## Configuration
Set these environment variables to configure Sherpa's behavior:
```sh
export SHERPA_ENV_FILENAME='.env' # Default: .envrc
# To support unloading non-exported variables and dynamically created shell entities
export SHERPA_ENABLE_DYNAMIC_ENV_FILE_PARSING=true
# To auto dump the env into a .envrc.example file when running `sherpa edit`
export SHERPA_DUMP_ENV_ON_EDIT=true
```
## Settings
### Log level
It affects only the current and new terminal sessions.
```sh
$ sherpa talk more # - Decrease the log level | Alias: -
$ sherpa talk less # - Increase the log level | Alias: +
$ sherpa shh # - Silence
```
### Disable/enable Sherpa
It affects only the current and new terminal sessions.
```sh
$ sherpa off # aliases: sleep, disable
Sherpa: All envs are unloaded. Sherpa goes to sleep.
$ sherpa on # aliases: work, enable
Sherpa: Env is loaded. Sherpa is ready for action.
```
## Cookbook
Same shortcut different behavior based on the current directory.
### Start your dev environment
```sh
# ~/projects/rails_project_with_docker/.envrc
dev() {
docker_compose_up # Start the Docker daemon and the containers if needed
__run_bundle_install # Install Ruby dependencies if needed
__run_rails_db_migrate # Apply database schema changes if needed
__run_yarn_install # Install JavaScript dependencies if needed
__stop_stuck_rails_server # Stop any running Rails server if they didn't stop earlier
bin/rails s
}
# ~/projects/elixir_phoenix_project/.envrc
alias dev='mix phx.server'
```
### Run tests
```sh
# ~/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/.envrc
alias t='yarn test'
```
### Spin up a Rails console in production
```sh
# ~/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"'
```
## Troubleshooting
```sh
$ sherpa status
$ sherpa debug
$ sherpa diagnose
```
## Local development
Run `$ make` to see the available commands.\
There are a few docker containers to support the local development.
### Testing
All *_test.sh files are run recursively from the tests directory.
Replace `$ make test` with `$ make test_zsh` or `$ make test_bash` to run the tests for a specific shell.
```sh
# 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 from a folder for all the supported shells
$ make test tests/features
# Run all the tests for all the supported shells in Ubuntu
$ make test_all_in_ubuntu
# Run all the tests for all the supported shells in Ubuntu
$ make test_all_in_ubuntu
```
### Linting
```sh
$ make lint
```
## Credits
The core functionality (var, func and alias stashing) of this project was inspired by [Varstash](https://github.com/cxreg/smartcd?tab=readme-ov-file#varstash).
Special thanks to its author:
- Dave Olszewski