The working environment (wenv) project offloads the tedious work required to provide clean, project-specific environments that allow users to easily leverage the power of their shell. It acts as an extremely lightweight layer that connects tmux, Zsh, and your other favorite shell tools.

For a more thorough introduction, see https://grish.dev/blog/wenv.

• Zsh
• tmux

For now, the installation is manual -- fortunately, it's also relatively painless. The following steps (or variations on them) should get the job done (note that you may want to store this repo somewhere permanent and symlink to its contents instead of copying to make updates easier):

1. Clone this repository.

2. Create the directory $XDG_CONFIG_HOME/wenv (or $HOME/.config/wenv) and put both the template file and extensions directory there. Also, create a directory inside of that wenv directory called wenvs, which will store the wenv files for all of your projects. If you're in this repository, you can run the following lines to complete this step:

   export wenv_cfg="${XDG_CONFIG_HOME:-$HOME/.config}/wenv"
   mkdir -p "$wenv_cfg/wenvs"
   ln -s <path-to-this-repo>/{template,extensions} "$wenv_cfg"

3. Put the wenv and _wenv files wherever you like, and add the following lines to your zshrc:

   # source wenv file
   source <path-to-wenv-file>

4. To load the completions, you can move or symlink the _wenv file to a directory in your fpath. For example, if the completion file is at ~/src/wenv/_wenv and you store completions in $XDG_DATA_HOME/zsh/completions/, you would run:

   ln -s `~/src/wenv/_wenv` `$XDG_DATA_HOME/zsh/completions/`

   Then ensure the path is in your fpath by adding this to your zshrc:

   fpath=($XDG_DATA_HOME/zsh/completions $fpath)

5. In order for wenvs to work with tmux, the following line should be added to your zshrc:

   [[ -n "$WENV" ]] && wenv_source -c "$WENV"

   This makes it so that the wenv associated with a given tmux session can be loaded whenever a new pane or window is opened within that session.

Wenv name in prompt

It's useful to have the name of the wenv in your prompt, as both an easy reference for which wenv you're in and sometimes as a debugging tool to verify whether a wenv properly loaded. This used to be the default, but for better flexibility it's now up to the user to configure this.

A simple way to do this would be to add the following lines to your zshrc:

wenv_prompt() {
    [[ -n "$WENV" ]] && echo "($WENV) "
}

setopt prompt_subst
PS1="\$(wenv_prompt)$PS1"

This prepends the name of the active wenv in parentheses, followed by a space, before your prompt. This may be added before or after the code added in step 4. For more information on the prompt_subst option in Zsh, see https://zsh.sourceforge.io/Doc/Release/Prompt-Expansion.html.

Clean wenv startup history

When you run the wenv start command, you'll get the following command in your shell's history:

source $tmp_start_file && rm -f $tmp_start_file

This command is prefixed with space -- this means that if you have the HIST_IGNORE_SPACE Zsh option set, that command won't be saved in your shell history. To set this option, add the following to your zshrc:

setopt HIST_IGNORE_SPACE

USAGE
  wenv [-h] <cmd>

OPTIONS
  -h                    Display this help message.

SUBCOMMANDS
  start <wenv>          Start the working environment <wenv>.
  stop                  Stop the current working environment.
  new                   Create a new working environment.
  list                  List all wenvs
  edit <wenv>           Edit the wenv file for <wenv>.
  rename <old> <new>    Rename wenv <old> to <new>.
  remove <wenv>         Delete the wenv file for <wenv>.
  source <wenv>         Source the wenv file for <wenv>.
  cd <wenv>             Change to <wenv>'s base directory.
  extension <cmd>       Interact with wenv extensions.
  bootstrap <wenv>      Run <wenv>'s bootstrap function.

Run `wenv <cmd> -h` for more information on a given subcommand <cmd>.

See the Walkthrough for further elaboration and examples.

Variables

• wenv_dir: The path to the base directory of this project.
• wenv_deps: An array containing the names of the wenvs that this wenv is dependent on.
• wenv_extensions: An array containing the names of the extensions to load for the wenv.

Functions

• startup_wenv() is run whenever you start the wenv. This function is good for starting up any necessary daemons, setting up a tmux layout, opening programs (e.g. a text editor), etc. It will run inside "$wenv_dir".
• shutdown_wenv() is run when you stop the wenv. This can be used to stop daemons started by startup_wenv(), and do any other cleanup.
• bootstrap_wenv() sets up the environment that the wenv expects to exist. For example, this function might pull down a git repository for development or check to ensure that all packages required by this wenv are installed. You can run this function on a wenv <wenv> by running wenv bootstrap <wenv>.

The utility of wenvs takes a bit of time to explain. This walkthrough gives the basic configuration/commands for getting started while also explaining what I've found them to be useful for. If you're experienced with shell scripting, you'll see that much of the value of wenvs comes from allowing the user to leverage the tools provided by shells. This project is less focused on forcing a specific workflow for users and more focused on giving users a convenient environment in which to define their own workflow unrestricted by the limitations of a single terminal.

The example wenvs in the examples directory give concrete examples of wenv definitions for general projects. Each example includes a comprehensive description of the wenv's definition and features that are used to create a clean and useful environment. I recommend going through these examples, as they compliment this walkthrough.

Here's an example that creates a wenv for a project called 'hello-world':

$ mkdir hello-world
$ cd hello-world
$ wenv new hello-world

The wenv new command will copy the wenv template file into a new wenv file called hello-world. The template file provides a base structure for a new wenv. On my machine, the above wenv command creates a new wenv file that starts with the following lines:

wenv_dir=""
wenv_deps=()
wenv_extensions=('wd')

startup_wenv() {}
shutdown_wenv() {}
bootstrap_wenv() {}

((only_load_wenv_vars == 1)) && return 0

# define all desired aliases/functions/etc. here

Each project's wenv start with a set of variables and functions that make it a wenv, which are all of the variables and functions defined above. Below the above block is where any shell aliases/functions/etc. for the project should be defined.

A shell running a wenv will have environment variables exported that correspond to the variables defined in the wenv file:

• WENV_DIR will contain the value of wenv_dir.
• WENV_DEPS will contain the value of wenv_deps.
• WENV_EXTENSIONS will contain the value of wenv_extensions.

The most important of these is wenv_dir, which we'll focus on first.

The wenv_dir value represents the base directory of the project. When we start a wenv with e.g. wenv start hello-world, we'll automatically cd into the project's wenv_dir. Further, whenever a wenv is active, we can run wenv cd (without an argument) to cd into its base directory from anywhere. If we want to cd into an inactive wenv's wenv_dir, we can do so by passing the wenv name as an argument -- e.g. wenv cd hello-world.

In the example in the previous section, wenv_dir's value was automatically populated with our current working directory (this may be overidden with the -d flag).

Now let's talk about what you can do when starting a wenv. The startup_wenv() function is run whenever you activate a wenv with wenv start <wenv>. This can be useful for running startup commands, e.g.

startup_wenv() {
    sudo systemctl start docker
}

Or opening programs like text editors:

startup_wenv() {
    $EDITOR main.cpp
}

Additionally the startup_wenv() function can be used to automatically create Tmux layouts for the project.

So, we can start our wenv with a horizontal split with the startup function:

startup_wenv() {
    tmux split -h
}

We can also open a file in our text editor in the new pane:

startup_wenv() {
    tmux split -h "$EDITOR main.cpp"
}

Other tmux commands can be useful in specifying a layout as well. For example, if we wanted to create a small vertical pane under the initial pane then refocus on the larger pane:

startup_wenv() {
    tmux split
    tmux resize-pane -y 7
    tmux select-pane -U
}

Note that wenv start will cd into "$wenv_dir" before startup_wenv() is run, so you can assume you'll be in the wenv's base directory when writing your startup_wenv() functions. Additionally, your wenv aliases will be sourced once startup_wenv() is called, so can take advantage of any environment variables/functions defined outside of wenv_def().

This is essentially the opposite of startup_wenv() -- it runs whenver you deactivate the current wenv with wenv stop. So, if we have a wenv whose startup_wenv() function runs sudo systemctl start docker, our shutdown_wenv() might be:

shutdown_wenv() {
    sudo systemctl stop docker
}

Note, however, that the wenv stop command doesn't deactivate the wenv if shutdown_wenv() returns a non-zero exit code. You can always pass the -f flag to wenv stop to close the wenv even if shutdown_wenv() fails.

wenv_deps is an array of wenvs that this wenv is dependent on. Essentially, every wenv in wenv_deps is sourced when starting the wenv. Let's take the example of a wenv for IPTB (which we'll call iptb):

# ...

export IPTB_ROOT="$HOME/.iptb"

Let's say we wanted to create another wenv that also used IPTB, and therefore also needs to set the IPTB_ROOT variable. We could initialize the new wenv with the iptb wenv as a base using wenv new -i iptb <new_wenv>, so our new wenv would have the same export command. However, this approach isn't particularly maintainable -- e.g. if the IPTB developers decide to rename the IPTB_ROOT variable, all wenvs that use IPTB would have to update that variable's value. Alternatively, we could just source the iptb wenv and get all of its environment variables every time we start any wenv that uses IPTB. To do this, we'd add iptb to our wenv_deps:

wenv_deps=('iptb')

Wenv extensions define shell code that may be reused across multiple wenvs. A wenv extension is nothing more than a shell file that you want to source in every shell of a wenv. Extensions are stored in "$WENV_CFG/extensions". To load an extension, add its name to the wenv_extensions array. For example, if we wanted to load the wd and edit extensions, we'd write:

wenv_extensions=('wd' 'edit')

Then the files "$WENV_CFG/extensions/wd" and "$WENV_CFG/extensions/edit" would be sourced in every shell of our wenv. See the wd and edit extension files for more information on their usage.