Update the readme

README.md

@@ -1,14 +1,14 @@
-# Local Sherpa to the Rescue
+# Sherpa - project based development environment
 
-Sherpa carries your local environment settings for you as you `cd` around your projects.
+Sherpa carries your local environment settings for you as you `cd` through projects, space and time.
 
 ## Status
 
-Unstable, under heavy development.
+🚧 Unstable, under active development.
 
 [![example workflow](https://github.com/tothpeter/local_sherpa/actions/workflows/ci.yml/badge.svg)](https://github.com/tothpeter/local_sherpa/actions/workflows/ci.yml)
 
-## Demo
+## Demo - Core functionality
 
 ```shell
 $ cd ~/projects
@@ -39,7 +39,7 @@ $ function_1
 GLOBAL FUNCTION
 ```
 
-The above is accomplished with the help of Local Sherpa and the files below.
+The above is accomplished with the help of Sherpa and the files below.
 
 ```shell
 # ~/.bashrc or ~/.zshrc etc...
@@ -64,37 +64,13 @@ function_1() {
 ```
 
 ## Usage
-### Setup / config local env
+### Config local env
 1. $ cd ~/projects/project_awesome
 2. $ sherpa edit
 3. [Disco](https://www.youtube.com/watch?v=UkSPUDpe0U8)
 
 For more details see the [Features](#features) section.
 
-### 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.
-
-``` bash
-$ echo "alias rs=rspec" > ~/projects/project_awesome/.sherparc
-$ 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`.
-
 ## Supported shells
 
 - Zsh
@@ -118,9 +94,8 @@ Unexported variables and other data types are not supported yet.
 
 ## Side effect
 
-When sherpa loads the local env, it loads not only variables, aliases, and functions
-but it sources the local env file. This means that the whole content
-of the local env file is executed in the current shell.
+When sherpa loads the local env, it sources the local env file meaning its
+whole content is executed in the current shell.
 
 ## Installation
 
@@ -129,7 +104,7 @@ of the local env file is executed in the current shell.
 $ git clone [email protected]:tothpeter/local_sherpa.git ~/.dotfiles/lib/local_sherpa
 # Hook it into your shell
 $ echo "source ~/.dotfiles/lib/local_sherpa/local_sherpa.sh" >> ~/.zshrc
-# Exclude the local env Sherpa files (.sherparc) globally in Git
+# Exclude the local env files (.sherparc) globally in Git
 $ echo ".sherparc" >> $(git config --global core.excludesfile)
 
 # Optional but recommended
@@ -142,12 +117,40 @@ alias upgrade_sherpa='git -C ~/.dotfiles/lib/local_sherpa pull'
 
 See the full list of commands by running `$ sherpa` in your shell.
 
-### Loading local env from parent directories automatically
+### 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.
+
+``` bash
+$ echo "alias rs=rspec" > ~/projects/project_awesome/.sherparc
+$ 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.
 
-It is not supported currently. Feel free to open a feature request issue
-if you find it useful.
+### Env loading and unloading
 
-### Flexible nested local env loading and unloading
+- Sherpa does not unload the loaded envs when you `cd` into a subdirectory.
+- Sherpa can load nested envs and unload them in the correct order so your previously loaded envs are restored even if the nested envs override them.
+
+#### Demo
 
 ```shell
 # Given the following directory structure with the corresponding local env files
@@ -176,7 +179,7 @@ $ cd ..
 
 ### Disable/enable Sherpa
 
-It effects only the current and new sessions.
+It affects only the current and new terminal sessions.
 
 ```shell
 $ sherpa sleep # aliases: off, disable
@@ -185,13 +188,19 @@ $ sherpa work # aliases: on, enable
 Sherpa: Local is env loaded. Sherpa is ready for action.
 ```
 
+### 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 variables anywhere to instruct Sherpa how operate.
+Set the following environment variables anywhere to instruct Sherpa on how
+to operate.
 
 ```shell
 export SHERPA_ENABLED=false # Default: true
-export SHERPA_ENV_FILENAME='.env' # Default: .sherparc
+export SHERPA_ENV_FILENAME='.envrc' # Default: .sherparc
 # Control how much Sherpa talks
 export SHERPA_LOG_LEVEL='no talking' # Default: info | Values: debug, info, no talking
 ```
@@ -278,3 +287,14 @@ $ make test_all_in_ubuntu
 ```shell
 $ make lint
 ```
+
+## Credits
+
+This project uses the [varstash](https://github.com/cxreg/smartcd?tab=readme-ov-file#varstash)
+library from [smartcd](https://github.com/cxreg/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.

vendor/smartcd/varstash.sh

@@ -1,4 +1,6 @@
 ################################################################################
+# This library is modified to fit the needs of the Local Sherpa project.
+
 # Stash/unstash support for per-directory variables
 #
 #   Copyright (c) 2009,2012 Dave Olszewski <[email protected]>