Most of the variables reflect the situation on the local machine.
Often, they must use a different value when you operate in buffers with
a remote default directory. Think about the behavior when calling
shell — on your local machine, you might use /bin/bash
and rely on termcap, but on a remote machine, it may be /bin/ksh
and terminfo.
This can be accomplished with connection-local variables. Such
variables are declared depending on the value of
default-directory of the current buffer. When a buffer has a
remote default-directory, and there exist a connection-local
variable which matches default-directory, this alternative value
of the variable is used. Directory and file local variables override
connection-local variables. Unsafe connection-local variables are
handled in the same way as unsafe file-local variables (see Safety of File Variables).
Connection-local variables are declared as a group of variables/value
pairs in a profile, using the
connection-local-set-profile-variables function. The function
connection-local-set-profiles declares profiles for a given
criteria (the first argument), identifying a remote machine with respect
to default-directory of the current buffer:
(connection-local-set-profile-variables 'remote-terminfo
'((system-uses-terminfo . t)
(comint-terminfo-terminal . "dumb-emacs-ansi")))
(connection-local-set-profile-variables 'remote-ksh
'((shell-file-name . "/bin/ksh")
(shell-command-switch . "-c")))
(connection-local-set-profile-variables 'remote-bash
'((shell-file-name . "/bin/bash")
(shell-command-switch . "-c")))
(connection-local-set-profiles
'(:application tramp :machine "remotemachine")
'remote-terminfo 'remote-ksh)
This code declares three different profiles, remote-terminfo,
remote-ksh, and remote-bash. The profiles
remote-terminfo and remote-ksh are applied to all buffers
which have a remote default-directory matching the string
"remotemachine" as host name.
Criteria, the first argument of connection-local-set-profiles,
specifies, how the profiles match default-directory. It is a
plist identifying a connection and the application using this
connection. Property names might be :application,
:protocol, :user and :machine. The property value
of :application is a symbol, all other property values are
strings. In general the symbol tramp should be used as
:application value. Some packages use a different
:application (for example eshell or vc-git); they
say it in their documentation then. All properties are optional.
The other properties are used for checking default-directory.
The propertiy :protocol is used for the method a remote
default-directory uses, the property
:user is the remote user name, and the property :machine
is the remote host name. All checks are performed via
string-equal. The nil criteria matches all buffers
with a remote default directory.
Connection-local variables are not activated by default. A package
which uses connection-local variables must activate them for a given
buffer, specifying for which :application it uses them.
See Applying Connection Local Variables in The Emacs Lisp
Reference Manual, for details.
After the above definition of profiles and their activation, any connection made by Tramp to the ‘remotemachine’ system will use
t as the connection-specific value of system-uses-terminfo,
comint-terminfo-terminal,
shell-file-name,
shell-command-switch.
Be careful when declaring different profiles with the same variable, and setting these profiles to criteria which could match in parallel. It is unspecified which variable value is used then.
Be also careful when setting connection-local variables in a buffer,
which changes its major mode afterwards. Because all buffer-local
variables will be killed when changing the major mode, the
connection-local variable’s value would be lost. You can prevent this
by setting the respective variable’s permanent-local symbol
property to non-nil.