srcenv

Installation / Usage / Roadmap / Contributing

A cross-shell tool for sourcing POSIX compliant .env scripts.

Description

srcenv takes a snapshot of the POSIX shell environment, sources the .env scripts and prints a shell specific script exporting the environment variables that have changed since the snapshot, with support for reverting those changes.

Installation

Important

sh (or any POSIX shell) is required to evaluate the .env scripts. On Windows, srcenv can use sh.exe installed by git.

jq (version ≥ 1.5) is required and needs to be in your PATH; see installation options.

Homebrew

brew install ins0mniaque/srcenv/srcenv

Arch / Debian / RPM packages

Download the latest packages from the GitHub release page.

Windows

PowerShell

Install for current user:

# Create installation directory
New-Item "$Env:LOCALAPPDATA\srcenv" -ItemType Directory

# Download srcenv to installation directory
Invoke-WebRequest https://raw.githubusercontent.com/ins0mniaque/srcenv/main/srcenv -OutFile "$Env:LOCALAPPDATA\srcenv\srcenv"

Add to $HOME\Documents\PowerShell\Profile.ps1:

# Add POSIX shell (sh) to PATH
$Env:PATH += ";$Env:ProgramFiles\Git\usr\bin\"

# Initialize srcenv
Invoke-Expression (sh "$Env:LOCALAPPDATA\srcenv\srcenv" init pwsh)

Windows Command shell (cmd)

Install for current user:

Download srcenv to %LOCALAPPDATA%\srcenv directory or use PowerShell script above to install srcenv.

Run or add to HKEY_CURRENT_USER\SOFTWARE\Microsoft\Command Processor\AutoRun registry key:

@echo off

rem Add POSIX shell (sh) to PATH
set PATH=%PATH%;%PROGRAMFILES%\Git\usr\bin\

rem Initialize srcenv
sh "%LOCALAPPDATA%\srcenv\srcenv" init cmd > %TEMP%\srcenv.init.cmd && call %TEMP%\srcenv.init.cmd & del %TEMP%\srcenv.init.cmd

echo on

Manual

Download the latest script and/or man page and make it executable:

curl -OL https://raw.githubusercontent.com/ins0mniaque/srcenv/main/srcenv
curl -OL https://raw.githubusercontent.com/ins0mniaque/srcenv/main/srcenv.1

chmod +x srcenv

or

Clone the repository:

git clone https://github.com/ins0mniaque/srcenv

Usage

srcenv can integrate with your shell and add the following command to source .env scripts:

src [options] [files]
    [-h|--help|--version]

❯ src project.env     # Sources `project.env`
srcenv: +COMPILER_OPTIONS +PROJECT_PATH

❯ src project2.env    # Reverts `project.env` and sources `project2.env`
srcenv: ~COMPILER_OPTIONS -PROJECT_PATH +PROJECT2_PATH

❯ src --restore       # Reverts `project2.env` (same as src -r)
srcenv: -COMPILER_OPTIONS -PROJECT2_PATH

❯ src --version       # Shows the version of srcenv
srcenv x.y.z

❯ _

Shell integration

To add the src command, add the following to your shell's configuration file:

Shell	Command
POSIX	source <(srcenv init bash)
	source <(srcenv init dash)
	source <(srcenv init ksh)
	source <(srcenv init zsh)
Csh/Tcsh	srcenv init csh | source /dev/stdin
	srcenv init tcsh | source /dev/stdin
Elvish	var src~ = { }; eval &on-end={|ns| set src~ = $ns[src] } (srcenv init elvish)
Murex	srcenv init murex -> source
Nushell	srcenv init nu | save -f srcenv.init.nu (env.nu)
	source srcenv.init.nu (config.nu)
Fish	srcenv init fish | source
ion	eval "$(srcenv init ion) (Usage is different; see ion shell)
PowerShell	Invoke-Expression (sh "/path/to/srcenv" init pwsh)
Xonsh	execx($(srcenv init xonsh))
Windows Command	@echo off & sh "/path/to/srcenv" init cmd > %TEMP%\srcenv.init.cmd && call %TEMP%\srcenv.init.cmd & del %TEMP%\srcenv.init.cmd & echo on (HKCU\SOFTWARE\Microsoft\Command Processor\AutoRun)
Windows Command (Clink)	os.execute(io.popen('sh /path/to/srcenv init clink'):read('*a')) (%LOCALAPPDATA%\clink\srcenv.lua)

Note

To use a different command name (e.g. magicenv), add --cmd magicenv. You can also pass different arguments to srcenv with -- at the end. Without --, the default options are --backup --restore --verbose.

e.g. source <(srcenv init bash --cmd srcundo -- --restore) creates a command named srcundo that restores the last backed up changes.

Tip

To improve performance or compatibility, you can specify different POSIX shell with --sh. If available, dash or ksh usually outperform bash and zsh.

To further improve performance when using colored output, use src --export-colors once to cache terminal capabilities in the SRCENV_COLORS environment variable.

For non-standard integration, use srcenv rc <shell> [--cmd name] [--sh sh] [-- options] to output what needs to be added to your shell's configuration file.

For a list of supported options, see src --help.

ion shell

ion shell implements variadic functions using the array syntax [...]. src arguments must be provided inside brackets.

e.g. src [ project.env ] or src [ --help ]

Warning

ion shell has no way to unset environment variables; they are instead set to an empty string.

Direct usage (without shell integration)

The following table shows how to source .env in different shells:

Shell	Command
POSIX	source <(srcenv sh .env)
Csh/Tcsh	srcenv csh .env | source /dev/stdin
Elvish	eval (srcenv elvish .env | slurp)
Murex	srcenv murex .env -> source
Nushell	srcenv json .env | from json | load-env
Fish	srcenv fish .env | source
ion	eval "$(srcenv ion .env)
PowerShell	Invoke-Expression (sh "/path/to/srcenv" pwsh .env)
Xonsh	execx($(srcenv xonsh .env))
Windows Command	@echo off & sh "/path/to/srcenv" cmd .env > %TEMP%\srcenv.temp.cmd && call %TEMP%\srcenv.temp.cmd & del %TEMP%\srcenv.temp.cmd & echo on

For a list of supported shells and options, see srcenv --help.

For more advanced usage see the srcenv(1) manpage (man ./srcenv.1).

Roadmap

• Add Clink support
• Add ion support
• Add Xonsh support
• Automatic mode (à la direnv)

Contributing

See CONTRIBUTING.md for more information on how to contribute.