.TH VES 1 "June 2026" "sh-ves" "User Commands"
.SH NAME
ves \- Bourne shell virtual environment system
.SH SYNOPSIS
.B ves
.I command
.RI [ arguments ]
.SH DESCRIPTION
.B sh-ves
manages named collections of environment variables, called
.IR environments ,
and swaps between them within a shell session. Activating an environment
applies its stored variables over the current shell; deactivating it
restores every variable to its prior state exactly, including variables
that did not previously exist.
.PP
.B sh-ves
is not a package manager and does not install software. It only manages
environment variables, so installing the different versions of compilers
or libraries that an environment points at is up to the user.
.PP
The
.B ves
command is a shell function, not a binary; it must be loaded by sourcing
.I ves-init.sh
in the shell's rc or profile file (see
.BR FILES ).
Environments do not compose: only one environment may be active at a
time, and activating a second one is refused (but see
.BR switch ).
.SH COMMANDS
.TP
.BI "create " [\-\-override] " " name
Create a new environment. By default the new environment overrides
nothing. With
.BR \-\-override ,
the variables listed in
.B SHVES_OVERRIDE_VARS
(by default: PATH, LDPATH, LD_LIBRARY_PATH, and CPATH) are stored as
empty strings, so activating the environment truncates them.
.TP
.BI "delete " name
Delete an environment. The active environment cannot be deleted.
.TP
.BI "copy " "src dst"
Copy an environment to a new name.
.TP
.BI "rename " "old new"
Rename an environment. The active environment cannot be renamed.
.TP
.BI "activate " name
Activate an environment, exporting all of its stored variables. The
prior value of each variable is saved for restoration. Fails if another
environment is already active.
.TP
.B deactivate
Deactivate the active environment, restoring all overridden variables
to their pre-activation values.
.TP
.BI "switch " name
Deactivate the current environment (if any), then activate
.IR name .
.TP
.BI "run " "name command ..."
Run a single command inside an environment without activating it in the
current shell. The environment is applied in a subshell, so no
deactivation is necessary. The exit status is that of the command.
.TP
.BI "export " [\-\-env=name] " " "variable value"
Set a variable within an environment. With no
.B \-\-env
option, the active environment is targeted. If the target environment is
active, the variable is also exported into the live shell.
.TP
.BI "unset " [\-\-env=name] " " variable
Remove a variable from an environment entirely. If the target
environment is active, the live variable is restored to its
pre-activation value.
.TP
.BI "show " [name]
Print the variables stored in an environment, one
.I VAR=value
per line. Defaults to the active environment.
.TP
.BI "var-add " [\-\-env=name] " " [\-\-append] " " "variable value"
Prepend
.I value
to a path-like (colon-delimited) variable, or append it with
.BR \-\-append .
If the variable is not yet stored in the environment, it is seeded from
the live shell value first, so prepending to PATH never truncates it.
Values are expanded according to the rules in
.B PATH EXPANSION
below.
.TP
.BI "var-rm " [\-\-env=name] " " "variable value"
Remove an entry from a path-like variable. The value is expanded with
the same rules as
.BR var-add ,
so entries can be removed using the same form they were added with.
.TP
.BI "list " [\-\-index] " " variable
List the entries of a path-like variable from the live shell, one per
line, in order of precedence. With
.BR \-\-index ,
each entry is prefixed with its numeric (0-based) index.
.TP
.B envs
List all created environments.
.TP
.BI "prompt " [symbol]
Print a prompt fragment of the form
.BI ( "symbol name" )
when an environment is active, and nothing otherwise.
.I symbol
defaults to
.BR VENV .
Intended for inclusion in PS1; it performs no color manipulation, so
color codes may be added around it.
.TP
.B help
Print a usage summary.
.SH PATH EXPANSION
For
.B var-add
and
.BR var-rm ,
values that do not begin with
.B /
or
.B ./
are expanded for convenience: values added to PATH are prefixed with
.IR $XDG_DATA_HOME /ves/bin/,
and values added to LDPATH or LD_LIBRARY_PATH are prefixed with
.IR $XDG_DATA_HOME /ves/lib/.
It is advisable to install binaries and libraries that participate in
ves environments into independent directories within these two
locations, e.g.
.IR ~/.local/share/ves/bin/gcc-4/ .
Other variables are never expanded.
.SH ENVIRONMENT
.TP
.B XDG_DATA_HOME
Base directory for sh-ves data. Defaults to
.IR ~/.local/share .
.TP
.B SHVES_SCRIPTS_DIR
Location of the sh-ves scripts. Defaults to
.IR ~/.local/bin/ves_scripts .
.TP
.B SHVES_OVERRIDE_VARS
Space-separated list of variables truncated by
.BR "create \-\-override" .
Defaults to
.BR "PATH LDPATH LD_LIBRARY_PATH CPATH" .
.TP
.B SHVES_ENV_NM
Name of the currently active environment. Exported while an environment
is active; read by
.BR "ves prompt" .
Do not set manually.
.SH FILES
.TP
.I ~/.local/bin/ves_scripts/ves-init.sh
Initialization file. Source this from your shell's rc or profile file:
.IP
.EX
\&. ~/.local/bin/ves_scripts/ves-init.sh
.EE
.TP
.I $XDG_DATA_HOME/ves/envs/
One file per environment, holding its name header and stored variables.
.TP
.I $XDG_DATA_HOME/ves/bin/, $XDG_DATA_HOME/ves/lib/
Suggested locations for binaries and libraries used by ves environments
(see
.BR "PATH EXPANSION" ).
.SH FISH
In
.BR fish (1),
.B ves
is provided by a shim function installed to
.IR ~/.config/fish/functions/ves.fish ,
with tab completions in
.IR ~/.config/fish/completions/ .
The shim runs each command through the POSIX implementation in an
.BR sh (1)
subshell and replays the resulting environment changes into the fish
session, so all commands behave identically. For prompt integration, use
the quoted command substitution form so that empty output does not
swallow adjacent arguments:
.IP
.EX
function fish_prompt
    echo -n "$(ves prompt) "(prompt_pwd)' $ '
end
.EE
.SH EXAMPLES
Set up an environment for a project needing GCC 4 and libexample 6.12,
previously installed under the sh-ves data directories:
.IP
.EX
$ ves create example_project
$ ves activate example_project
$ ves var-add PATH gcc-4
$ ves var-add LDPATH libexample-6.12
.EE
.PP
Run a single build inside that environment without activating it:
.IP
.EX
$ ves run example_project make
.EE
.SH EXIT STATUS
0 on success, 1 on operational errors (missing environment, activation
conflicts, and similar), 2 on usage errors.
.SH SEE ALSO
.BR sh (1),
.BR env (1),
.BR fish (1)
.SH LICENSE
sh-ves is licensed under the GNU Affero General Public License,
version 3.