srcenv.1

.\" Automatically generated by Pandoc 3.6
.\"
.TH "SRCENV" "1" "December 2024" "srcenv 1.6.0" "General Commands Manual"
.SH NAME
\f[B]srcenv\f[R] \[em] cross\-shell tool for sourcing POSIX compliant
\&.env scripts
.SH SYNOPSIS
.PP
\f[B]srcenv\f[R] <\f[I]shell\f[R]> [\f[I]options\f[R]] [\f[I]files\f[R]]
.PD 0
.P
.PD
\f[B]srcenv\f[R] init|rc <\f[I]shell\f[R]> [\-\-cmd \f[I]name\f[R]]
[\-\-sh \f[I]sh\f[R]] [\-\- \f[I]options\f[R]]
.PD 0
.P
.PD
\f[B]srcenv\f[R]
[\f[B]\-h\f[R]|\f[B]\-\-help\f[R]|\f[B]\-\-version\f[R]]
.SH 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.
.PP
srcenv depends on jq(1) ≥ 1.5 being available; see \c
.UR https://jqlang.github.io/jq
.UE \c
\ for installation options.
.SH EXIT STATUS
srcenv exits 0 on success, 1 on error, 2 on invalid option, 5 on JSON
parsing error and 127 on command not found.
.SH COMMANDS
.TP
init
Generate the integration script to be sourced with command name
\f[CR]\[ga]\f[R]src\f[CR]\[ga]\f[R] \f[I](change with \-\-cmd)\f[R] and
POSIX shell \f[CR]\[ga]\f[R]sh\f[CR]\[ga]\f[R] \f[I](change with
\-\-sh)\f[R].
For details, see SHELL INTEGRATION section below.
.TP
rc
Generate the command to add to your shell\[cq]s configuration file to
source the integration script.
For details, see SHELL INTEGRATION section below.
.SH SHELLS
.TP
ash, dash
Format the output as an Ash/Dash script.
.TP
bash
Format the output as a Bash script.
.TP
clink
Format the output as a Clink/Windows Command shell script.
.TP
cmd, command
Format the output as a Windows Command shell script.
.TP
csh, tcsh
Format the output as a Csh/Tcsh script.
.TP
elvish
Format the output as an Elvish script.
.TP
env
Format the output as a .env file.
.TP
fish
Format the output as a Fish script.
.TP
ion
Format the output as an ion script.
.TP
json
Format the output as JSON.
.TP
ksh, pdksh, mksh
Format the output as a Ksh script.
.TP
murex
Format the output as a Murex script.
.TP
launchd
Format the output as a launchd environment script.
.TP
nu, nushell
Format the output as a Nushell script.
.TP
posix, sh
Format the output as a POSIX shell script.
.TP
pwsh, powershell
Format the output as a PowerShell script.
.TP
xonsh
Format the output as a Xonsh script.
.TP
zsh
Format the output as a Zsh script.
.SH OPTIONS
.TP
\-\-color WHEN, \-\-color=WHEN
Specify when to use colored output: *auto*, never or always.
\f[CR]\[ga]\f[R]auto\f[CR]\[ga]\f[R] disables colors if the output goes
to a pipe.
.TP
\-\-export\-colors
Cache terminal capabilities to SRCENV_RESTORE to improve performance.
For details, see ENVIRONMENT section below.
.TP
\-\-clear\-colors
Clear cached terminal capabilities from SRCENV_RESTORE.
.TP
\-x VAR, \-\-exclude VAR, \-x=VAR, \-\-exclude=VAR
Exclude VAR from exported variables (can be used multiple times).
.TP
\-f FORMAT, \-f=FORMAT, \-\-format FORMAT, \-\-format=FORMAT
Format the output as anything (shell or jq interpolated string).
For details, see FORMAT section below.
.TP
\-i INPUT, \-i=INPUT, \-\-input INPUT, \-\-input=INPUT
Source from string value of INPUT.
.TP
\-
Source from STDIN.
.TP
\-b, \-\-backup
Backup changes to SRCENV_RESTORE for restore.
.TP
\-r, \-\-restore
Restore backed up changes from SRCENV_RESTORE.
.TP
\-c, \-\-clear
Clear backed up changes from SRCENV_RESTORE.
.TP
\-n
Do not backup changes and do not restore backed up changes.
.TP
\-\-no\-backup
Do not backup changes to SRCENV_RESTORE for restore.
.TP
\-\-no\-restore
Do not restore backed up changes from SRCENV_RESTORE.
.TP
\-m, \-\-modify
Allow modifying existing environment variables (Default).
.TP
\-w, \-\-write\-protect
Do not allow modifying existing environment variables.
.TP
\-j, \-\-json
Treat input as JSON.
.TP
\-p, \-\-posix
Treat input as POSIX (Default).
.TP
\-e, \-\-export
Export all variables (Default for .env files).
.TP
\-l, \-\-local
Do not export all variables.
.TP
\-s, \-\-sort
Sort the environment variables alphabetically (Default).
.TP
\-u, \-\-unsorted
Keep the environment variables unsorted.
.TP
\-q, \-\-quiet
Do not display changed environment variables.
.TP
\-v, \-\-verbose
Display changed environment variables.
.TP
\-h, \-\-help
Display help and exit.
.TP
\-\-version
Display the version number and exit.
.TP
\-\-debug
Display jq filter without sourcing and exit.
.SH SHELL INTEGRATION
srcenv can integrate with your shell and add the following command to
source \f[CR].env\f[R] scripts:
.SS Usage
.IP
.EX
src [options] [files]
    [\-h\f[B]|\f[R]\-\-help\f[B]|\f[R]\-\-version]
.EE
.SS Example
.IP
.EX
❯ src project.env     \f[I]# Sources \[ga]project.env\[ga]\f[R]
srcenv: +COMPILER_OPTIONS +PROJECT_PATH

❯ src project2.env    \f[I]# Reverts \[ga]project.env\[ga] and sources \[ga]project2.env\[ga]\f[R]
srcenv: \[ti]COMPILER_OPTIONS \-PROJECT_PATH +PROJECT2_PATH

❯ src \-\-restore       \f[I]# Reverts \[ga]project2.env\[ga] (same as src \-r)\f[R]
srcenv: \-COMPILER_OPTIONS \-PROJECT2_PATH

❯ src \-\-version       \f[I]# Shows the version of srcenv\f[R]
srcenv x.y.z

❯ _
.EE
.SS Integration
To add the \f[CR]\[ga]\f[R]src\f[CR]\[ga]\f[R] command, add the
following to your shell\[cq]s configuration file:
.TP
POSIX:
\f[CR]source <(srcenv init sh)\f[R]
.TP
Csh/Tcsh:
\f[CR]srcenv init csh | source /dev/stdin\f[R]
.TP
Elvish:
\f[CR]var src\[ti] = { }; eval &on\-end={|ns| set src\[ti] = $ns[src] } (srcenv init elvish)\f[R]
.TP
Murex:
\f[CR]srcenv init murex \-> source\f[R]
.TP
Nushell \f[I](env.nu)\f[R]:
\f[CR]srcenv init nu | save \-f srcenv.init.nu\f[R]
.TP
Nushell \f[I](config.nu)\f[R]:
\f[CR]source srcenv.init.nu\f[R]
.TP
Fish:
\f[CR]srcenv init fish | source\f[R]
.TP
ion:
\f[CR]eval \[dq]$(srcenv init ion)\[dq]\f[R]
.IP
.EX
NOTE: Usage is different; see ION SHELL section below.
.EE
.TP
PowerShell:
\f[CR]Invoke\-Expression (sh \[dq]/path/to/srcenv\[dq] init pwsh)\f[R]
.TP
Xonsh:
\f[CR]execx($(srcenv init xonsh))\f[R]
.TP
Windows Command shell \f[I](HKCU\[rs]SOFTWARE\[rs]Microsoft\[rs]Command Processor\[rs]AutoRun)\f[R]:
\f[CR]\[at]echo off & sh \[dq]/path/to/srcenv\[dq] init cmd > %TEMP%\[rs]srcenv.init.cmd && call %TEMP%\[rs]srcenv.init.cmd & del %TEMP%\[rs]srcenv.init.cmd & echo on\f[R]
.TP
Windows Command shell (Clink) \f[I](%LOCALAPPDATA%\[rs]clink\[rs]srcenv.lua)\f[R]:
\f[CR]os.execute(io.popen(\[aq]sh /path/to/srcenv init clink\[aq]):read(\[aq]*a\[aq]))\f[R]
.SS Tips
.TP
To use a different command name (e.g.\ \f[CR]\[ga]\f[R]magicenv\f[CR]\[ga]\f[R]), add \f[CR]\[ga]\f[R]\-\-cmd magicenv\f[CR]\[ga]\f[R]. You can also pass different arguments to srcenv with \f[CR]\[ga]\f[R]\-\-\f[CR]\[ga]\f[R] at the end. Without \f[CR]\[ga]\f[R]\-\-\f[CR]\[ga]\f[R], the default options are \f[CR]\[ga]\f[R]\-\-backup \-\-restore \-\-verbose\f[CR]\[ga]\f[R].
e.g.\ \f[CR]\[ga]\f[R]source <(srcenv init bash \-\-cmd srcundo \-\-
\-\-restore)\f[CR]\[ga]\f[R] creates a command named
\f[CR]\[ga]\f[R]srcundo\f[CR]\[ga]\f[R] that restores the last backed up
changes.
.PP
To improve performance or compatibility, you can specify different POSIX
shell with \f[CR]\[ga]\f[R]\-\-sh\f[CR]\[ga]\f[R].
If available, dash or ksh usually outperform bash and zsh.
.PP
To further improve performance when using colored output, use
\f[CR]\[ga]\f[R]src \-\-export\-colors\f[CR]\[ga]\f[R] \f[B]once\f[R] to
cache terminal capabilities in the
\f[CR]\[ga]\f[R]SRCENV_COLORS\f[CR]\[ga]\f[R] environment variable.
.PP
For non\-standard integration, use \f[CR]\[ga]\f[R]srcenv rc <shell>
[\-\-cmd name] [\-\-sh sh] [\-\- options]\f[CR]\[ga]\f[R] to output what
needs to be added to your shell\[cq]s configuration file.
.SH ION SHELL
ion shell implements variadic functions using the array syntax
\f[CR]\[ga]\f[R][\&...]\f[CR]\[ga]\f[R].
.TP
\f[CR]\[ga]\f[R]src\f[CR]\[ga]\f[R] arguments must be provided inside brackets.
e.g.\ \f[CR]\[ga]\f[R]src [ project.env ]\f[CR]\[ga]\f[R] or
\f[CR]\[ga]\f[R]src [ \-\-help ]\f[CR]\[ga]\f[R]
.PP
WARNING: ion shell has no way to unset environment variables; they are
instead set to an empty string.
.SH EXAMPLES
The following examples show how to source \f[CR].env\f[R] in different
shells:
.TP
POSIX:
\f[CR]source <(srcenv sh .env)\f[R]
.TP
Csh/Tcsh:
\f[CR]srcenv csh .env | source /dev/stdin\f[R]
.TP
Elvish:
\f[CR]eval (srcenv elvish .env | slurp)\f[R]
.TP
Murex:
\f[CR]srcenv murex .env \-> source\f[R]
.TP
Nushell:
\f[CR]srcenv json .env | from json | load\-env\f[R]
.TP
Fish:
\f[CR]srcenv fish .env | source\f[R]
.TP
ion:
\f[CR]eval \[dq]$(srcenv ion .env)\[dq]\f[R]
.TP
PowerShell:
\f[CR]Invoke\-Expression (sh \[dq]/path/to/srcenv\[dq] pwsh .env)\f[R]
.TP
Xonsh:
\f[CR]execx($(srcenv xonsh .env))\f[R]
.TP
Windows Command shell:
\f[CR]\[at]echo off & sh \[dq]/path/to/srcenv\[dq] cmd .env > %TEMP%\[rs]srcenv.temp.cmd && call %TEMP%\[rs]srcenv.temp.cmd & del %TEMP%\[rs]srcenv.temp.cmd & echo on\f[R]
.SH FORMAT
The format is either a shell
(e.g.\ \f[CR]\[ga]\f[R]json\f[CR]\[ga]\f[R]) or a jq(1) interpolated
string \f[CR]\[ga]\f[R]\[rs](\&...)\f[CR]\[ga]\f[R] where the key is
\f[CR]\[ga]\f[R]$k\f[CR]\[ga]\f[R], and the value
\f[CR]\[ga]\f[R].[$k]\f[CR]\[ga]\f[R].
A second interpolated string can be appended with the
\f[CR]\[ga]\f[R]??\f[CR]\[ga]\f[R] delimiter to format null values
\f[I](unset environment variables)\f[R].
Additionally, a prefix can be added to the output by adding
\f[CR]\[ga]\f[R]prefix{{\f[CR]\[ga]\f[R] at the start of the format, and
a suffix by adding \f[CR]\[ga]\f[R]}}suffix\f[CR]\[ga]\f[R] at the end
of the format
(e.g.\ \f[CR]\[ga]\f[R]prefix{{\[rs]($k)=\[rs].[$k]}}suffix\f[CR]\[ga]\f[R]).
.TP
Key:
\f[CR]\[rs]($k)\f[R]
.TP
Value:
\f[CR]\[rs](.[$k])\f[R]
.TP
Single quoted value:
\f[CR](.[$k]|\[at]sh)\f[R]
.TP
Double quoted value:
\f[CR](.[$k]|\[at]json)\f[R]
.TP
POSIX format:
\f[CR]export \[rs]($k)=\[rs](.[$k]|\[at]sh)??unset \[rs]($k)\f[R]
.SH ENVIRONMENT
.TP
SRCENV_JQ
If this environment variable is defined, srcenv will use it as the
location for jq(1).
.TP
SRCENV_JQ_BINARY
If this environment variable is defined, srcenv will pass the \-\-binary
option to jq(1).
.TP
SRCENV_COLOR
If this environment variable is defined, it will be the default value
for the \-\-color option.
.TP
SRCENV_COLORS
If this environment variable is defined, terminal capabilities will be
read from it as a list of ANSI sequences separated by
\f[CR]\[ga]\f[R]\[rs]032\f[CR]\[ga]\f[R].
It can also be used to theme srcenv.
.IP
.EX
\f[I]# Default theme\f[R]
SRCENV_COLORS=$(printf \[dq]$(tput sgr0)\[rs]032$(tput bold)\[rs]032$(tput dim)\[rs]032$(tput sitm)\[rs]032$(tput smul)\[rs]032$(tput setaf 0)\[rs]032$(tput setaf 1)\[rs]032$(tput setaf 2)\[rs]032$(tput setaf 3)\[rs]032$(tput setaf 4)\[rs]032$(tput setaf 5)\[rs]032$(tput setaf 6)\[rs]032$(tput setaf 7)\[dq])
.EE
.TP
COMSPEC, MUREX_PID, BASH_VERSION, KSH_VERSION, ZSH_VERSION
These environment variables are checked to detect Windows, Murex, Bash,
Ksh and Zsh respectively.
.SH SEE ALSO
Repository: https://github.com/ins0mniaque/srcenv
.PP
\f[B]sh(1)\f[R], \f[B]jq(1)\f[R]
.SH AUTHOR
Jean\-Philippe Leconte \c
.MT ins0mniaque@gmail.com
.ME \c
.SH BUGS
See GitHub Issues: https://github.com/ins0mniaque/srcenv/issues