From 64329ed7606bd833ead054a9b54e5c408ad119a2 Mon Sep 17 00:00:00 2001 From: Peter Toth Date: Mon, 15 Jul 2024 20:08:00 +0400 Subject: [PATCH] Update the readme --- README.md | 102 ++++++++++++++++++++++--------------- vendor/smartcd/varstash.sh | 2 + 2 files changed, 63 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 03f060d..edd7209 100644 --- a/README.md +++ b/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 git@github.com: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 + +The varstash library is modified to fit the needs of this project. diff --git a/vendor/smartcd/varstash.sh b/vendor/smartcd/varstash.sh index 5267da2..dbc2dba 100644 --- a/vendor/smartcd/varstash.sh +++ b/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