commit 96a0e5f265d11e7913ce71a3a1981b267bda79e5
parent c8c78b531bdbc1a6d555d33b74889ba8f3420fbf
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sat, 7 Jun 2025 07:49:04 -0700
docs: lua, UI events #34261
Diffstat:
7 files changed, 31 insertions(+), 17 deletions(-)
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
@@ -666,6 +666,7 @@ External UIs are expected to implement these common features:
the user).
- Support the text decorations/attributes given by |ui-event-hl_attr_define|.
The "url" attr should be presented as a clickable hyperlink.
+- Handle the "restart" UI event so that |:restart| works.
vim:tw=78:ts=8:sw=4:et:ft=help:norl:
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
@@ -64,18 +64,24 @@ Stop or detach the current UI
the channel to be closed, it may be (incorrectly) reported as
an error.
- Note: Not supported on Windows, currently.
+ Note: Not supported on Windows yet.
------------------------------------------------------------------------------
-Restart the embedded Nvim server
+Restart Nvim
*:restart*
:restart
- Detaches the embedded server from the UI and then restarts
- it. This fails when changes have been made
- and Vim refuses to |abandon| the current buffer.
+ Restarts the Nvim server with the same startup arguments
+ |v:argv| and reattaches the current UI to the new server.
+ All other UIs will detach.
+
+ This fails when changes have been made and Vim refuses to
+ |abandon| the current buffer.
+
+ Note: This only works if the UI and server are on the same
+ system.
+ Note: Not supported on Windows yet.
- Note: This only works if the UI started the server initially.
:restart!
Force restarts the embedded server irrespective of unsaved
buffers.
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -1814,9 +1814,11 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()*
• cmd (string[]) Command name and args
• pid (integer) Process ID
• wait (fun(timeout: integer|nil): SystemCompleted) Wait for the
- process to complete. Upon timeout the process is sent the KILL
- signal (9) and the exit code is set to 124. Cannot be called in
- |api-fast|.
+ process to complete, including any open handles for background
+ processes (e.g., `bash -c 'sleep 10 &'`). To avoid waiting for
+ handles, set stdout=false and stderr=false. Upon timeout the process
+ is sent the KILL signal (9) and the exit code is set to 124. Cannot
+ be called in |api-fast|.
• SystemCompleted is an object with the fields:
• code: (integer)
• signal: (integer)
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
@@ -222,6 +222,7 @@ TUI
UI
+• |:restart| restarts Nvim and reattaches the current UI.
• |:checkhealth| shows a summary in the header for every healthcheck.
• |ui-multigrid| provides composition information and absolute coordinates.
• `vim._extui` provides an experimental commandline and message UI intended to
@@ -229,7 +230,6 @@ UI
• Error messages are more concise:
• "Error detected while processing:" changed to "Error in:".
• "Error executing Lua:" changed to "Lua:".
-• |:restart| detaches the embedded server from the UI and then restarts it.
VIMSCRIPT
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
@@ -226,8 +226,7 @@ the editor.
sent from Nvim, like for |ui-cmdline|.
["chdir", path] ~
- The |current-directory| of the embedded Nvim process changed to
- `path`.
+ The |current-directory| changed to `path`.
["mode_change", mode, mode_idx] ~
Editor mode changed. The `mode` parameter is a string representing
@@ -249,6 +248,11 @@ the editor.
Indicates to the UI that it must stop rendering the cursor. This event
is misnamed and does not actually have anything to do with busyness.
+["restart"] ~
+ |:restart| command was used. The UI should stop-and-restart the Nvim
+ server using the same startup arguments |v:argv|, and reattach to the
+ new server.
+
["suspend"] ~
|:suspend| command or |CTRL-Z| mapping is used. A terminal client (or
another client where it makes sense) could suspend itself. Other
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
@@ -130,9 +130,10 @@ local utfs = {
--- @return vim.SystemObj Object with the fields:
--- - cmd (string[]) Command name and args
--- - pid (integer) Process ID
---- - wait (fun(timeout: integer|nil): SystemCompleted) Wait for the process to complete. Upon
---- timeout the process is sent the KILL signal (9) and the exit code is set to 124. Cannot
---- be called in |api-fast|.
+--- - wait (fun(timeout: integer|nil): SystemCompleted) Wait for the process to complete,
+--- including any open handles for background processes (e.g., `bash -c 'sleep 10 &'`).
+--- To avoid waiting for handles, set stdout=false and stderr=false. Upon timeout the process is
+--- sent the KILL signal (9) and the exit code is set to 124. Cannot be called in |api-fast|.
--- - SystemCompleted is an object with the fields:
--- - code: (integer)
--- - signal: (integer)
diff --git a/src/nvim/api/ui_events.in.h b/src/nvim/api/ui_events.in.h
@@ -29,6 +29,8 @@ void visual_bell(void)
FUNC_API_SINCE(3);
void flush(void)
FUNC_API_SINCE(3) FUNC_API_REMOTE_IMPL;
+void restart(void)
+ FUNC_API_SINCE(14) FUNC_API_REMOTE_ONLY FUNC_API_CLIENT_IMPL;
void suspend(void)
FUNC_API_SINCE(3);
void set_title(String title)
@@ -177,5 +179,3 @@ void msg_history_clear(void)
void error_exit(Integer status)
FUNC_API_SINCE(12);
-void restart(void)
- FUNC_API_SINCE(14) FUNC_API_REMOTE_ONLY FUNC_API_CLIENT_IMPL;
