Initial version complete

I dusted this off after years and had Claude finish
it for me.

caveat emptor: this is largely (though not entirely)
LLM generated as of this commit

1 files changed, 223 insertions, 0 deletions

diff --git a/man/ves.1 b/man/ves.1
new file mode 100644
index 0000000..79f27ce
--- /dev/null
+++ b/man/ves.1
@@ -0,0 +1,223 @@
+.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.