{"id":25868283,"url":"https://github.com/sherpalabsio/local_sherpa","last_synced_at":"2026-04-28T21:34:17.460Z","repository":{"id":245311097,"uuid":"817751521","full_name":"sherpalabsio/local_sherpa","owner":"sherpalabsio","description":"Define folder specific aliases, functions and variables in your shell","archived":false,"fork":false,"pushed_at":"2026-03-01T17:52:33.000Z","size":425,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-01T19:46:28.699Z","etag":null,"topics":["aliases","bash","direnv","environment","shell-extension","terminal","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sherpalabsio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-06-20T11:15:09.000Z","updated_at":"2026-03-01T17:52:37.000Z","dependencies_parsed_at":"2024-06-26T20:29:49.065Z","dependency_job_id":"d3f91b33-20a9-4790-aee8-82337112b75c","html_url":"https://github.com/sherpalabsio/local_sherpa","commit_stats":null,"previous_names":["tothpeter/local_sherpa","nomadsherpa/local_sherpa","sherpalabsio/local_sherpa"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/sherpalabsio/local_sherpa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherpalabsio%2Flocal_sherpa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherpalabsio%2Flocal_sherpa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherpalabsio%2Flocal_sherpa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherpalabsio%2Flocal_sherpa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sherpalabsio","download_url":"https://codeload.github.com/sherpalabsio/local_sherpa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sherpalabsio%2Flocal_sherpa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32400866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aliases","bash","direnv","environment","shell-extension","terminal","zsh"],"created_at":"2025-03-02T04:37:06.502Z","updated_at":"2026-04-28T21:34:17.446Z","avatar_url":"https://github.com/sherpalabsio.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"media/logo_dark_mode.svg\"\u003e\n    \u003cimg alt=\"Logo\" src=\"media/logo_light_mode.svg\" width=\"355\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n----------\n\n[![CI](https://github.com/sherpalabsio/local_sherpa/actions/workflows/ci.yml/badge.svg)](https://github.com/sherpalabsio/local_sherpa/actions/workflows/ci.yml)\n[![Version](https://img.shields.io/badge/Version-0.2.2-2e3436.svg)](https://github.com/sherpalabsio/local_sherpa/releases)\n[![Supportedshells](https://img.shields.io/badge/Supported_shells-Zsh,_Bash-2e3436.svg)](#supported-shells)\n\n## Define folder specific aliases, functions and variables in your shell\n\nSherpa 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.\n\nIt's similar to [Direnv](https://github.com/direnv/direnv), but with fewer features and added support for aliases and functions.\n\n## Demo\n\n[![Watch the video](https://img.youtube.com/vi/GRfuaiR-nho/0.jpg)](https://www.youtube.com/watch?v=GRfuaiR-nho)\n\n## ASCII Demo\n\n```sh\n$ cd ~/projects\n\n$ c # short for console\n# IRB (Interactive Ruby Shell) starts\n# ctrl + d to exit\n\n$ cd ~/projects/project_elixir\n$ c\n# IEx (Interactive Elixir) starts\n# ctrl + c to exit\n\n$ cd ~/projects/project_postgres\n$ c\n# Docker container with Postgres starts\n# PSQL (PostgreSQL interactive terminal) in the container starts\n```\n\nThe above is accomplished with the help of Sherpa and the files below.\n\n```sh\n# ~/.zshrc or ~/.bashrc\nalias c='irb'\n\n# ~/projects/project_elixir/.envrc\nalias c='iex'\n\n# ~/projects/project_postgres/.envrc\nc() {\n  # Start the Postgres container if it's not running\n  [ -z \"$(docker compose ps -q)\" ] \u0026\u0026 docker compose up -d\n  docker compose exec db psql -U postgres\n}\n```\n\n## Basic usage\n\n1. $ cd ~/projects/project_awesome\n2. $ sherpa edit\n    1. Sherpa opens the env file in your editor\n    2. You update, save then close it\n    3. Sherpa unloads the previous version, trusts and loads the current one automatically\n3. You can nest envs by repeating this in subdirectories\n4. [Disco](https://www.youtube.com/watch?v=UkSPUDpe0U8)\n\nFor more details see the [Features](#features) section.\n\n## Supported shells\n\n- Zsh (5.3.1 or higher)\n- Bash (4.3 or higher)\n\n## Tested on\n\n- macOS 14 - Sonoma\n- macOS 15 - Sequoia\n- macOS 26 - Tahoe\n- Ubuntu 22.04\n- Ubuntu 24.04\n\n## Installation\n\n### Homebrew\n\n```sh\nbrew install sherpalabsio/sherpalabsio/local_sherpa\n```\n\n### Automated\n\n```sh\ncurl -s https://raw.githubusercontent.com/sherpalabsio/local_sherpa/main/scripts/install.sh | bash\n```\n\nThis script will automatically:\n- Install the latest version to `~/.local/lib`\n- Symlink the `init` file to `~/.local/bin/local_sherpa_init`\n- Add `~/.local/bin` to your `PATH` (if not already present)\n- Configure your shell profile (`~/.zshrc` or `~/.bashrc`) to initialize Sherpa\n\n### Manual\n\n- Download a release (local_sherpa_X.X.X.tar.gz) from the [releases page](https://github.com/sherpalabsio/local_sherpa/releases)\n- Symlink the `init` file as `local_sherpa_init` somewhere in your `PATH`\n- Add `eval \"$(local_sherpa_init)\"` to your shell profile (e.g. `~/.zshrc`, `~/.bashrc`)\n\n### Git configuration\n\nExclude the env files (.envrc) globally so you won't commit them by mistake.\n\n```sh\necho \".envrc\" \u003e\u003e $(git config --global core.excludesfile)\n```\n\n## Upgrading to the latest version\n\n`$ sherpa update`\n\n## Features\n\nSee the full list of commands by running `$ sherpa` in your shell.\n\n### Security\n\nSherpa won't load any env file unless you trust it first (`$ sherpa trust`).\\\nThis is to prevent running unknown code when you `cd` into a directory.\n\nWhen an env file changes you have to trust it again unless you edited it\nwith `$ sherpa edit` which trusts and reloads the env file after you close it\nin your editor.\n\nYou can untrust an env file with `sherpa untrust`.\n\n### Command palette with fuzzy finder for the local env (experimental)\n\n`$ sherpa palette`\n\n![demo](https://github.com/user-attachments/assets/3e398ec5-cf77-460e-83ee-3af5036f4c72)\n\nIt requires [fzf](https://github.com/junegunn/fzf?tab=readme-ov-file#installation).\n\nOffers a list of available commands and variables in the current env.\\\nSelect a command hit enter then hit enter again to run it.\n\nThe list can be less accurate if the dynamic env file parsing is not enabled.\nEnable it by setting the `SHERPA_ENABLE_DYNAMIC_ENV_FILE_PARSING` environment variable to `true`.\n\n#### Bind it to Shift + Command + P:\n\nMake sure your terminal sends `^[[80;9u` or a similar escape sequence when\nyou press Shift + Command + P.\n\n```sh\n# Zsh (~/.zshrc)\n__sherpa_palette() {\n  sherpa palette\n}\n\nzle -N __sherpa_palette\nbindkey \"^[[80;9u\" __sherpa_palette\n# For tmux: bindkey \"^[P\" __sherpa_palette\n\n# Bash (~/.bashrc)\n__sherpa_palette() {\n  sherpa palette\n}\n\nbind -x '\"\\e[80;9u\":__sherpa_palette'\n```\n\n### Env loading and unloading\n\n- Sherpa loads the env from a `.envrc` file when you `cd` into a directory\n  - It sources the env file meaning its whole content is executed in the current shell\n  - It overrides the existing aliases, functions and variables\n- Sherpa unloads the env when you leave a directory\n  - It removes the newly added aliases, functions and variables\n  - It restores the overridden items to their previous state\n  - Going into a subdirectory does not unload the env of the parent directory\n- Sherpa partially supports nested envs\n  - Loading parent envs is not supported you have to `cd` into the parent directory first\n\n### Dynamic env loading and unloading (experimental)\n\nNon exported variables and dynamically created entities are unloaded only if the\n`SHERPA_ENABLE_DYNAMIC_ENV_FILE_PARSING` environment variable is set to `true`.\n\nThis can slow down `cd` because Sherpa executes the env file in a subshell\nthree times when you `cd` into a directory.\n\n### Aliases and functions in the env file taking precedence\n\nDeclaring a function in the env file with the same name as an existing alias\nwill override the alias automatically. No need to call `unalias`.\\\nThe same applies to declaring aliases in the env\nfile with the same name as existing functions.\n\n### Command inheritance (experimental)\n\nBy calling `super \"$@\"` in a function, you can invoke the original function or alias that you are overriding.\n\n#### Example:\n\n```sh\n# ~/.zshrc or ~/.bashrc\nfunction_name() {\n  local param1=\"$1\"\n  echo \"Original function with param: $param1\"\n}\n\n# ~/projects/project_elixir/.envrc\nfunction_name() {\n  super \"$@\"\n  echo \"Overridden function\"\n}\n\ncd ~\nfunction_name 1\n# Prints:\n# Original function with param: 1\n\ncd ~/projects/project_elixir\nfunction_name 1\n# Prints:\n# Original function with param: 1\n# Overridden function\n```\n\n### Loading envs from parent directories automatically\n\nThis is not supported currently. Feel free to open a feature request.\n\n### Running a script when leaving a directory\n\nThis is not supported currently. Feel free to open a feature request.\\\nAlternatively, you can use: https://github.com/hyperupcall/autoenv\n\n## Configuration\n\nSet these environment variables to configure Sherpa's behavior:\n\n```sh\nexport SHERPA_ENV_FILENAME='.env' # Default: .envrc\n# To support unloading non-exported variables and dynamically created shell entities\nexport SHERPA_ENABLE_DYNAMIC_ENV_FILE_PARSING=true\n# To auto dump the env into a .envrc.example file when running `sherpa edit`\nexport SHERPA_DUMP_ENV_ON_EDIT=true\n```\n\n## Settings\n\n### Log level\n\nIt affects only the current and new terminal sessions.\n\n```sh\n$ sherpa talk more # - Decrease the log level | Alias: -\n$ sherpa talk less # - Increase the log level | Alias: +\n$ sherpa shh       # - Silence\n```\n\n### Disable/enable Sherpa\n\nIt affects only the current and new terminal sessions.\n\n```sh\n$ sherpa off # aliases: sleep, disable\nSherpa: All envs are unloaded. Sherpa goes to sleep.\n$ sherpa on # aliases: work, enable\nSherpa: Env is loaded. Sherpa is ready for action.\n```\n\n## Cookbook\n\nSame shortcut different behavior based on the current directory.\n\n### Start your dev environment\n\n```sh\n# ~/projects/rails_project_with_docker/.envrc\ndev() {\n  docker_compose_up # Start the Docker daemon and the containers if needed\n\n  __run_bundle_install # Install Ruby dependencies if needed\n  __run_rails_db_migrate # Apply database schema changes if needed\n  __run_yarn_install # Install JavaScript dependencies if needed\n\n  __stop_stuck_rails_server # Stop any running Rails server if they didn't stop earlier\n\n  bin/rails s\n}\n\n# ~/projects/elixir_phoenix_project/.envrc\nalias dev='mix phx.server'\n```\n\n### Run tests\n\n```sh\n# ~/projects/project_ruby_with_docker/.envrc\nalias t='docker exec -it project-awesome-api rspec'\n\n# ~/projects/project_elixir/.envrc\nalias t='mix test'\n\n# ~/projects/project_js/.envrc\nalias t='yarn test'\n```\n\n### Spin up a Rails console in production\n\n```sh\n# ~/projects/project_with_heroku/.envrc\nalias rc_prod='heroku run rails c -a APP_NAME'\n\n# ~/projects/project_with_aws/.envrc\nalias rc_prod='ssh -i /path/key-pair-name.pem user@hostname \"/var/app/current/bin/rails console\"'\n```\n\n## Troubleshooting\n\n```sh\n$ sherpa status\n$ sherpa debug\n$ sherpa diagnose\n```\n\n## Local development\n\nRun `$ make` to see the available commands.\\\nThere are a few docker containers to support the local development.\n\n### Testing\n\nAll *_test.sh files are run recursively from the tests directory.\n\nReplace `$ make test` with `$ make test_zsh` or `$ make test_bash` to run the tests for a specific shell.\n\n```sh\n# Run all the tests for all the supported shells\n$ make test\n\n# Run a single test for all the supported shells\n$ make test tests/features/edit_test.sh\n\n# Run all the tests from a folder for all the supported shells\n$ make test tests/features\n\n# Run all the tests for all the supported shells in Ubuntu\n$ make test_all_in_ubuntu\n\n# Run all the tests for all the supported shells in Ubuntu\n$ make test_all_in_ubuntu\n```\n\n### Linting\n\n```sh\n$ make lint\n```\n\n## Credits\n\nThe core functionality (var, func and alias stashing) of this project was inspired by [Varstash](https://github.com/cxreg/smartcd?tab=readme-ov-file#varstash).\n\nSpecial thanks to its author:\n- Dave Olszewski \u003ccxreg@pobox.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsherpalabsio%2Flocal_sherpa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsherpalabsio%2Flocal_sherpa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsherpalabsio%2Flocal_sherpa/lists"}