vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

remote.txt (13527B)


      1 *remote.txt*	For Vim version 9.2.  Last change: 2026 Jun 05
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 Vim client-server communication				*client-server*
      8 
      9 1. Common functionality		|clientserver|
     10 2. X11 specific items		|x11-clientserver|
     11 3. MS-Windows specific items	|w32-clientserver|
     12 4. Socket server specific items	|socketserver-clientserver|
     13 
     14 ==============================================================================
     15 1. Common functionality					*clientserver*
     16 
     17 When compiled with the |+clientserver| option, Vim can act as a command
     18 server.  It accepts messages from a client and executes them.  At the same
     19 time, Vim can function as a client and send commands to a Vim server.
     20 
     21 The following command line arguments are available:
     22 
     23     argument			meaning	~
     24 
     25    --remote [+{cmd}] {file} ...					*--remote*
     26 				Open the file list in a remote Vim.  When
     27 				there is no Vim server, execute locally.
     28 				There is one optional init command: +{cmd}.
     29 				This must be an Ex command that can be
     30 				followed by "|".
     31 				The rest of the command line is taken as the
     32 				file list.  Thus any non-file arguments must
     33 				come before this.
     34 				You cannot edit stdin this way |--|.
     35 				The remote Vim is raised.  If you don't want
     36 				this use >
     37 				 vim --remote-send "<C-\><C-N>:n filename<CR>"
     38 <
     39    --remote-silent [+{cmd}] {file} ...			*--remote-silent*
     40 				As above, but don't complain if there is no
     41 				server and the file is edited locally.
     42    --remote-wait [+{cmd}] {file} ...				*--remote-wait*
     43 				As --remote, but wait for files to complete
     44 				(unload) in remote Vim.
     45    --remote-wait-silent [+{cmd}] {file} ...		*--remote-wait-silent*
     46 				As --remote-wait, but don't complain if there
     47 				is no server.
     48 							*--remote-tab*
     49    --remote-tab			Like --remote but open each file in a new
     50 				tabpage.
     51 							*--remote-tab-silent*
     52    --remote-tab-silent		Like --remote-silent but open each file in a
     53 				new tabpage.
     54 							*--remote-tab-wait*
     55    --remote-tab-wait		Like --remote-wait but open each file in a new
     56 				tabpage.
     57 
     58 						*--remote-tab-wait-silent*
     59    --remote-tab-wait-silent	Like --remote-wait-silent but open each file
     60 				in a new tabpage.
     61 								*--servername*
     62    --servername {name}		Become the server {name}.  When used together
     63 				with one of the --remote commands: connect to
     64 				server {name} instead of the default (see
     65 				below).  The name used will be uppercase.  If
     66 				using the socketserver, you can specify a
     67 				path, see |socketserver-name| for more
     68 				details.
     69 								*--remote-send*
     70    --remote-send {keys}		Send {keys} to server and exit.  The {keys}
     71 				are not mapped.  Special key names are
     72 				recognized, e.g., "<CR>" results in a CR
     73 				character.
     74 								*--remote-expr*
     75    --remote-expr {expr}		Evaluate {expr} in server and print the result
     76 				on stdout.
     77 								*--serverlist*
     78    --serverlist			Output a list of server names.
     79 								*--clientserver*
     80    --clientserver {method}	Use the specified method {method} as the
     81 				backend for clientserver functionality.  Can
     82 				either be "socket", "x11", or "mswin".
     83 							    *$VIM_CLIENTSERVER*
     84 				If the "$VIM_CLIENTSERVER" environment
     85 				variable is set, then Vim will interpret the
     86 				value just like the --clientserver argument.
     87 				If it is set and --clientserver is provided in
     88 				the command line, then --clientserver takes
     89 				priority.
     90 				{only available when compiled with both |+X11|
     91 				and |+socketserver| features, or
     92 				|+socketserver| on MS-Windows}
     93 
     94 Examples ~
     95 
     96 Edit "file.txt" in an already running GVIM server: >
     97     gvim --remote file.txt
     98 
     99 Edit "file.txt" in an already running server called FOOBAR: >
    100     gvim --servername FOOBAR --remote file.txt
    101 
    102 Edit "file.txt" in server "FILES" if it exists, become server "FILES"
    103 otherwise: >
    104     gvim --servername FILES --remote-silent file.txt
    105 
    106 This doesn't work, all arguments after --remote will be used as file names: >
    107     gvim --remote --servername FOOBAR file.txt
    108 
    109 Edit file "+foo" in a remote server (note the use of "./" to avoid the special
    110 meaning of the leading plus): >
    111     vim --remote ./+foo
    112 
    113 Tell the remote server "BLA" to write all files and exit: >
    114     vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>'
    115 
    116 
    117 SERVER NAME						*client-server-name*
    118 
    119 By default Vim will try to register the name under which it was invoked (gvim,
    120 egvim ...).  This can be overridden with the --servername argument.  If the
    121 specified name is not available, a postfix is applied until a free name is
    122 encountered, i.e. "gvim1" for the second invocation of gvim on a particular
    123 X-server.  The resulting name is available in the servername builtin variable
    124 |v:servername|.  The case of the server name is ignored, thus "gvim" and
    125 "GVIM" are considered equal.  Note if a socket server is being used, there are
    126 some differences, see |socketserver-differences|.
    127 
    128 When Vim is invoked with --remote, --remote-wait or --remote-send it will try
    129 to locate the server name determined by the invocation name and --servername
    130 argument as described above.  If an exact match is not available, the first
    131 server with the number postfix will be used.  If a name with the number
    132 postfix is specified with the --servername argument, it must match exactly.
    133 
    134 If no server can be located and --remote or --remote-wait was used, Vim will
    135 start up according to the rest of the command line and do the editing by
    136 itself.  This way it is not necessary to know whether gvim is already started
    137 when sending command to it.
    138 
    139 The --serverlist argument will cause Vim to print a list of registered command
    140 servers on the standard output (stdout) and exit.  If a socket server is being
    141 used, there are caveats, see |socketserver-differences|.
    142 							*{server}*
    143 The {server} argument is used by several functions.  When this is an empty
    144 string then on Unix the default server name is used, which is "GVIM".  On
    145 MS-Windows an empty string does not work.
    146 
    147 Win32 Note: Making the Vim server go to the foreground doesn't always work,
    148 because MS-Windows doesn't allow it.  The client will move the server to the
    149 foreground when using the --remote or --remote-wait argument and the server
    150 name starts with "g".
    151 
    152 
    153 REMOTE EDITING
    154 
    155 The --remote argument will cause a |:drop| command to be constructed from the
    156 rest of the command line and sent as described above.
    157 The --remote-wait argument does the same thing and additionally sets up to
    158 wait for each of the files to have been edited.  This uses the BufUnload
    159 event, thus as soon as a file has been unloaded, Vim assumes you are done
    160 editing it.
    161 Note that the --remote and --remote-wait arguments will consume the rest of
    162 the command line.  I.e. all remaining arguments will be regarded as filenames.
    163 You can not put options there!
    164 
    165 
    166 FUNCTIONS
    167 								*E240* *E573*
    168 There are a number of Vim functions for scripting the command server.  See
    169 the description in |builtin.txt| or use CTRL-] on the function name to jump to
    170 the full explanation.
    171 
    172     synopsis				     explanation ~
    173     remote_startserver( name)		     run a server
    174     remote_expr( server, string, idvar)      send expression
    175     remote_send( server, string, idvar)      send key sequence
    176     serverlist()			     get a list of available servers
    177     remote_peek( serverid, retvar)	     check for reply string
    178     remote_read( serverid)		     read reply string
    179     server2client( serverid, string)	     send reply string
    180     remote_foreground( server)		     bring server to the front
    181 
    182 See also the explanation of |CTRL-\_CTRL-N|.  Very useful as a leading key
    183 sequence.
    184 The {serverid} for server2client() can be obtained with expand("<client>")
    185 
    186 ==============================================================================
    187 2. X11 specific items					*x11-clientserver*
    188 				    *E247* *E248* *E251* *E258* *E277*
    189 
    190 The communication between client and server goes through the X server.  The
    191 display of the Vim server must be specified.  The usual protection of the X
    192 server is used, you must be able to open a window on the X server for the
    193 communication to work.  It is possible to communicate between different
    194 systems.
    195 
    196 By default, a GUI Vim will register a name on the X-server by which it can be
    197 addressed for subsequent execution of injected strings.  Vim can also act as
    198 a client and send strings to other instances of Vim on the same X11 display.
    199 
    200 When an X11 GUI Vim (gvim) is started, it will try to register a send-server
    201 name on the 'VimRegistry' property on the root window.
    202 
    203 A non GUI Vim with access to the X11 display (|xterm-clipboard| enabled), can
    204 also act as a command server if a server name is explicitly given with the
    205 --servername argument, or when Vim was built with the |+autoservername|
    206 feature.
    207 
    208 An empty --servername argument will cause the command server to be disabled.
    209 
    210 To send commands to a Vim server from another application, read the source
    211 file src/if_xcmdsrv.c, it contains some hints about the protocol used.
    212 
    213 ==============================================================================
    214 3. Win32 specific items					*w32-clientserver*
    215 
    216 Every Win32 Vim can work as a server, also in the console.  You do not need a
    217 version compiled with OLE.  Windows messages are used, this works on any
    218 version of MS-Windows.  But only communication within one system is possible.
    219 
    220 Since MS-Windows messages are used, any other application should be able to
    221 communicate with a Vim server.  An alternative is using the OLE functionality
    222 |ole-interface|.
    223 
    224 When using gvim, the --remote-wait only works properly this way: >
    225 
    226 	start /w gvim --remote-wait file.txt
    227 <
    228 ==============================================================================
    229 4. Socket server specific items			    *socketserver-clientserver*
    230 						    *E1564* *E1565* *E1566*
    231 
    232 NOTE: Vim version before patch 9.2.511 use a different socketserver backend
    233 which is incompatible with the new one, which is based on channels and JSON.
    234 
    235 The communication between client and server is done using channels internally.
    236 When using the traditional/generic clientserver naming (only available on
    237 Unix), sockets are placed in these directories in the following order of
    238 availability:
    239     1. "$XDG_RUNTIME_DIR/vim" if $XDG_RUNTIME_DIR is set in the environment.
    240     2. "$TMPDIR/vim-[uid]", where "[uid]" is the uid of the user.  This
    241        directory will have the access permissions set to 700 so only the user
    242        can read or write from/to it.  If $TMPDIR is not set, "/tmp" is used.
    243 
    244 						    *socketserver-name*
    245 When specifying the server id/name, it can be taken as a generic name or an
    246 absolute or relative path.  If the server id starts with either a "/"
    247 (absolute) or "./" | "../" (relative), then it is taken as path to the socket.
    248 Otherwise the server id will be the filename of the socket which will be
    249 placed in the above common directories.  Note that a server id/name can only
    250 contain slashes "/" if it is taken as a path, so names such as "abc/dir" will
    251 be invalid.  This feature is only available on Unix.
    252 
    253 						    *socketserver-address*
    254 In addition, the socketserver can also be created as a |channel-address|. To
    255 do this, prefix the address with "channel:" (which will be ignored).  This is
    256 available on both Unix and MS-Windows, and is the only available naming for the
    257 socketserver backend on Windows.  However, note that |ch_listen()|
    258 restrictions apply, meaning only port numbers can be used for TCP sockets.
    259 
    260 If the name is prefixed with "name:", then the legacy servername behaviour is
    261 used, so "name:VIM" is the same as "VIM".
    262 
    263 Unless Vim is compiled with |+autoservername| feature, the socket server will
    264 have to started explicitly, similar to X11. This is unless a X11 GUI Vim is
    265 being used.
    266 
    267 If Vim crashes or does not exit cleanly, the socket server will not remove the
    268 socket file and it will be left around.  This is generally not a problem,
    269 because if a socket name is taken, Vim checks if the socket in its place is
    270 dead (not attached to any process), and can replace it instead of finding a
    271 new name.  This is only relevant for Unix.
    272 
    273 						    *socketserver-differences*
    274 Most of the functionality is the same as the other clientserver backends.
    275 
    276 However, the server id or client id will not be a number like X11 or
    277 MS-Windows (shown in hex representation), instead it is the absolute path to
    278 the socket.  This can be seen via the |v:servername| variable.  If the name is
    279 a channel address, then it will be the address with the "a/" prefix as well.
    280 
    281 Note when using |--remote-wait|, the client id will look like "t/<some
    282 number>". This naming is specifically for this command, and attempting to use
    283 it as an address will fail.
    284 
    285 If on Unix, the |--serverlist| argument will act just like X11, however it
    286 only checks the given common directories above.  If a custom path is used for
    287 a socket, it will not be detected, such as a path either not in
    288 $XDG_RUNTIME_DIR or <$TMPDIR or /tmp>/vim of the |--serverlist| Vim process.
    289 If on MS-Windows, then the |--serverlist| argument will output nothing.
    290 
    291 The |+socketserver| feature is automatically enabled when on Unix or
    292 MS-Windows, and the |+channel| feature is enabled
    293 
    294 						    *socketserver-x11*
    295 If Vim is compiled with |+socketserver| and another clientserver backend, then
    296 deciding which backend to use is done at startup time, via the
    297 |--clientserver| argument.  By default if it is not specified, then the native
    298 backend (X11 or MS-Window messages) will be used, if available.  A Vim
    299 instance using a socket server cannot communicate with one using another
    300 clientserver backend.
    301 
    302  vim:tw=78:sw=4:ts=8:noet:ft=help:norl: