"nvim -es": disable shada #21723

Problem:
`nvim -es` (and `nvim -Es`) is the recommended way to non-interactively
run commands/vimscript. But it enables shada by default, which is
usually not wanted.

Solution:
- Disable shada by default for `nvim -es/-Es`. This can be overridden by
  `-i foo` if needed.
- Do NOT change the 'loadplugins' default.
  - User config + packages _should_ be enabled by default, for both `nvim
    -es` and `nvim -l`. Else any Lua packages you have can't be accessed
    without `-u path/to/config`, which is clumsy.
      - Use-cases:
        ```
        nvim --headless "+Lazy! sync" +qa
            would become: nvim -es "+Lazy! sync"
        nvim --headless +PlugInstall +qall
            would become: nvim -es +PlugInstall
        ```
  - Opt-out (`--clean` or `-u NONE`) is much easier than opt-in (`-u
    path/to/config`).
  -  User config/packages are analogous to pip packages, which are
     expected when doing `python -c ...`.

related: 7c94bcd2d77e2e54b8836ab8325460a367b79eae
related: ddd0eb6f5120a09b97867d2561ea61309038ccd2

4 files changed, 22 insertions, 14 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index b7c5a50443..6547a76f56 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -618,20 +618,20 @@ Example: TCP echo-server                                          *tcp-server*
 Multithreading                                            *lua-loop-threading*
 
 Plugins can perform work in separate (os-level) threads using the threading
-APIs in luv, for instance `vim.uv.new_thread`. Note that every thread
-gets its own separate Lua interpreter state, with no access to Lua globals
-in the main thread. Neither can the state of the editor (buffers, windows,
-etc) be directly accessed from threads.
+APIs in luv, for instance `vim.uv.new_thread`. Each thread has its own
+separate Lua interpreter state, with no access to Lua globals on the main
+thread. Neither can the editor state (buffers, windows, etc) be directly
+accessed from threads.
 
-A subset of the `vim.*` API is available in threads. This includes:
+A subset of the `vim.*` stdlib is available in threads, including:
 
 - `vim.uv` with a separate event loop per thread.
 - `vim.mpack` and `vim.json` (useful for serializing messages between threads)
 - `require` in threads can use Lua packages from the global |package.path|
 - `print()` and `vim.inspect`
 - `vim.diff`
-- most utility functions in `vim.*` for working with pure Lua values
-  like `vim.split`, `vim.tbl_*`, `vim.list_*`, and so on.
+- Most utility functions in `vim.*` that work with pure Lua values, like
+  `vim.split`, `vim.tbl_*`, `vim.list_*`, etc.
 - `vim.is_thread()` returns true from a non-main thread.
 
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index d573b01baa..b7606e65f5 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -295,6 +295,7 @@ PLUGINS
 
 STARTUP
 
+• |-es| ("script mode") disables shada by default.
 • Nvim will fail if the |--listen| or |$NVIM_LISTEN_ADDRESS| address is
   invalid, instead of silently skipping an invalid address.
 
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 3b0fa2b371..0bfbea75fb 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -207,12 +207,12 @@ argument.
 			:print
 			:set
 		With |:verbose| or 'verbose', other commands display on stderr: >
-			nvim -es +":verbose echo 'foo'"
-			nvim -V1 -es +foo
-
-<		User |config| is skipped unless |-u| was given.
-		Swap file is skipped (like |-n|).
-		User |shada| is loaded (unless "-i NONE" is given).
+			nvim -es +"verbose echo 'foo'"
+			nvim -V1 -es +"echo 'foo'"
+<
+		Skips user |config| unless |-u| was given.
+		Disables |shada| unless |-i| was given.
+		Disables swapfile (like |-n|).
 
 							*-l*
 -l {script} [args]
@@ -235,6 +235,11 @@ argument.
 			nvim +q -l foo.lua
 <		This loads Lua module "bar" before executing "foo.lua": >
 			nvim +"lua require('bar')" -l foo.lua
+<								    *lua-shebang*
+		You can set the "shebang" of the script so that Nvim executes
+		the script when called with "./" from a shell (remember to
+		"chmod u+x"): >
+			#!/usr/bin/env -S nvim -l
 <
 		Skips user |config| unless |-u| was given.
 		Disables plugins unless 'loadplugins' was set.
@@ -243,7 +248,7 @@ argument.
 
 							*-ll*
 -ll {script} [args]
-		Execute a Lua script, similarly to |-l|, but the editor is not
+		Executes a Lua script, similarly to |-l|, but the editor is not
 		initialized. This gives a Lua environment similar to a worker
 		thread. See |lua-loop-threading|.
 
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 9f28b373ee..a92ddf33e6 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -409,6 +409,8 @@ Startup:
 - |-es| and |-Es| have improved behavior:
     - Quits automatically, don't need "-c qa!".
     - Skips swap-file dialog.
+    - Optimized for non-interactive scripts: disables swapfile, shada.
+- |-l| Executes Lua scripts non-interactively.
 - |-s| reads Normal commands from stdin if the script name is "-".
 - Reading text (instead of commands) from stdin |--|:
     - works by default: "-" file is optional