Infrastructure and commands to manage the environment for processes started

within tmux.

There is a global environment, copied from the external environment when the
server is started and each sesssion has an (initially empty) session
environment which overrides it.

New commands set-environment and show-environment manipulate or display the
environments.

A new session option, update-environment, is a space-separated list of
variables which are updated from the external environment into the session
environment every time a new session is created - the default is DISPLAY.

1 files changed, 66 insertions, 0 deletions

diff --git a/tmux.1 b/tmux.1
index 58609e12..1aebdbaf 100644
--- a/tmux.1
+++ b/tmux.1
@@ -1321,6 +1321,18 @@ entry for terminals which support 88 or 256 colours:
 .Bd -literal -offset indent
 "*88col*:colors=88,*256col*:colors=256"
 .Ed
+.It Ic update-environment Ar variables
+Set a space-separated string containing a list of environment variables to be
+copied into the session environment when a new session is created or an
+existing session is attached.
+Any variables that do not exist in the source environment are set to be
+removed from the session environment (as if
+.Fl r
+was given to the
+.Ic set-environment
+command).
+The default is
+.Ev DISPLAY .
 .It Xo Ic visual-activity
 .Op Ic on | off
 .Xc
@@ -1525,6 +1537,60 @@ or the global window options if
 .Fl g
 is used.
 .El
+.Sh ENVIRONMENT
+When the server is started,
+.Nm
+copies the environment into the
+.Em global environment ;
+in addition, each session has a
+.Em session environment .
+When a window is created, the session and global environments are merged with
+the session environment overriding any variable present in both.
+This is the initial environment passed to the new process.
+.Pp
+The
+.Ic update-environment
+session option may be used to update the session environment from the client
+when a new session is created or an old reattached.
+.Nm
+also initialises the
+.Ev TMUX
+variable with some internal information to allow commands to be executed
+from inside, and the
+.Ev TERM
+variable with the correct terminal setting of
+.Ql screen .
+.Pp
+Commands to alter and view the environment are:
+.Bl -tag -width Ds
+.It Xo Ic set-environment
+.Op Fl gru
+.Op Fl t Ar target-session
+.Ar name Op Ar value
+.Xc
+Set or unset an environment variable.
+If
+.Fl g
+is used, the change is made in the global environment; otherwise, it is applied
+to the session environment for
+.Ar target-session .
+The
+.Fl u
+flag unsets a variable.
+.Fl r
+indicates the variable is to be removed from the environment before starting a
+new process.
+.It Xo Ic show-environment
+.Op Fl g
+.Op Fl t Ar target-session
+.Xc
+Display the environment for
+.Ar target-session
+or the global environment with
+.Fl g .
+Variables removed from the environment are prefixed with
+.Ql - .
+.El
 .Sh STATUS LINE
 .Nm
 includes an optional status line which is displayed in the bottom line of each