NVIM(1)

💅 NVIM(1) — the manual page, but make it a group chat

okay bestie, you're looking at the General Commands Manual, section 1, and honestly? this one ate. it's nvim, and we're about to go through literally every single flag together. no skipping. grab a strawberry 🍓 and let's go.

---

✨ NAME ✨

nvim — edit text. that's it. that's the whole assignment. iconic behaviour, no notes. 💅

---

🌸 SYNOPSIS 🌸

here's how you summon her:

nvim [options] [file ...]
nvim [options] -
nvim [options] -t tag
nvim [options] -q [errorfile]

---

🦋 DESCRIPTION 🦋

so nvim is a text editor based on Vim. you start it up, you throw some options and/or files at it, and she just goes:

nvim [options] [file ...]

commands inside nvim start with a colon (:), like a little summoning circle. type :help subject and you get help on that specific subject. use <Tab> and CTRL-D to complete subjects (that's :help cmdline-completion if you wanna read up, iykyk).

the quickref help section is a condensed reference of editor features, and it's lowkey everything:

:help quickref

if you're new to Vim/Nvim, start with the 30-minute tutorial:

:Tutor

and after installing/updating Nvim, it's genuinely a good idea to run the self-check:

:checkhealth

now the positional stuff:

• file ... — file(s) to edit. opens one buffer per file. to switch between buffers, use the :next and :previous commands. it's giving tab management but make it vintage. 🌈
• - — reads text from standard input until EOF, then opens a buffer with that text. user input is read from standard error, which should be a terminal. so don't pipe your feelings in wrong, bestie. 🙈

---

💖 OPTIONS 💖

okay this is the part everyone skips and you will NOT skip it. 40-ish options, we're doing all of them. periodt. 👑

• -t tag — finds tag in the tags file, the associated file becomes the current file and the associated command is executed. cursor is positioned at the tag location in the file. :help tag-commands ✨
• -q [errorfile] — QuickFix mode. displays the first error in errorfile. if errorfile is omitted, the value of the 'errorfile' option is used (defaults to errors.err). further errors can be jumped to with the :cnext command. :help quickfix
• -- — end of options. remaining arguments are treated as literal file names, including filenames starting with hyphen (-). so your weird little -file.txt is safe now 🫶
• -e — Ex mode, reading stdin as Ex commands. :help Ex-mode
• -E — Ex mode, reading stdin as text. :help Ex-mode
• -es — Silent (non-interactive) Ex mode, reading stdin as Ex commands. useful for scripting because it does NOT start a UI, unlike -e. :help silent-mode
• -Es — Silent (non-interactive) Ex mode, reading stdin as text. useful for scripting because it does NOT start a UI, unlike -E. :help silent-mode
• -d — Diff mode. show the difference between two to eight files, similar to sdiff(1). :help diff
• -R — Read-only mode. sets the 'readonly' option. implies -n. buffers can still be edited, but cannot be written to disk if already associated with a file. to overwrite a file, add an exclamation mark to the relevant Ex command, such as :w!. :help 'readonly'
• -m — resets the 'write' option, to disable file modifications. writing to a file is disabled, but buffers can still be modified.
• -M — resets the 'write' and 'modifiable' options, to disable file and buffer modifications. full lockdown, she's not letting you touch anything 😭
• -b — Binary mode. :help edit-binary
• -A — Arabic mode. sets the 'arabic' option.
• -H — Hebrew mode. sets the 'hkmap' and 'rightleft' options.
• -V[N][file] — Verbose mode. prints debug messages. N is the 'verbose' level, defaults to 10. if file is specified, append messages to file instead of printing them. :help 'verbose'
• -D — Vimscript debug mode. started when executing the first command from a script. :help debug-mode
• -n — disable the use of swap files. sets the 'updatecount' option to 0. can be useful for editing files on a slow medium. 🐌
• -r [file] — Recovery mode. if file is omitted then list swap files with recovery information. otherwise the swap file file is used to recover a crashed session. the swap file has the same name as the file it's associated with, but with .swp appended. :help recovery
• -L [file] — alias for -r. twins fr fr.
• -u vimrc — use vimrc instead of the default ~/.config/nvim/init.vim. if vimrc is NORC, do not load any initialization files (except plugins). if vimrc is NONE, loading plugins is also skipped. :help initialization
• -i shada — use shada instead of the default ~/.local/state/nvim/shada/main.shada. if shada is NONE, do not read or write a ShaDa file. :help shada
• --noplugin — skip loading plugins (by setting the 'noloadplugins' option). implied by -u NONE.
• --clean — start Nvim with "factory defaults" (only builtin plugins, no user config/plugins, no shada). :help --clean — this is the "fresh out the box, no baggage" vibe check 🧚
• -o[N] — open N windows stacked horizontally. if N is omitted, open one window for each file. if N is less than the number of file arguments, allocate windows for the first N files and hide the rest.
• -O[N] — like -o, but tile windows vertically. ⬆️⬇️
• -p[N] — like -o, but for tab pages.
• +[linenum] — for the first file, position the cursor on line linenum. if linenum is omitted, position the cursor on the last line of the file. +5 and -c 5 on the command-line are equivalent to :5 inside nvim.
• +/[pattern] — for the first file, position the cursor on the first occurrence of pattern. if pattern is omitted, the most recent search pattern is used (if any). +/foo and -c /foo on the command-line are equivalent to /foo and :/foo inside nvim. :help search-pattern
• +command, -c command — execute command after reading the first file. up to 10 instances allowed. "+foo" and -c "foo" are equivalent.
• --cmd command — like -c, but execute command before processing any vimrc. up to 10 instances of these can be used independently from instances of -c.
• -l script [args] — execute Lua script with optional [args] after processing any preceding Nvim startup arguments. all [args] are treated as script arguments and are passed literally to Lua, that is, -l stops processing of Nvim arguments. :help -l
• -S [session] — execute session after the first file argument has been read. if session filename ends with .lua it is executed as Lua instead of Vimscript. equivalent to -c "source session". session cannot start with a hyphen (-). if session is omitted then Session.vim is used, if found. :help session-file
• -s scriptin — read normal mode commands from scriptin. the same can be done with the command :source! scriptin. if the end of the file is reached before nvim exits, further characters are read from the keyboard.
• -w scriptout — append all typed characters to scriptout. can be used for creating a script to be used with -s or :source!.
• -W scriptout — like -w, but truncate scriptout. she's ruthless, she clears the whole thing 💀
• --startuptime file — during startup, append timing messages to file. can be used to diagnose slow startup times. (hi, that's you, with 400 plugins, we see you 👀)
• --api-info — dump API metadata serialized to msgpack and exit.
• --embed — use standard input and standard output as a msgpack-rpc channel. :help --embed
• --headless — do not start a UI. when supplied with --embed this implies that the embedding application does not intend to (immediately) start a UI. also useful for "scraping" messages in a pipe. :help --headless
• --listen address — start RPC server on this pipe or TCP socket.
• -h, --help — print usage information and exit.
• -v, --version — print version information and exit.

---

🌈 ENVIRONMENT 🌈

the vibes your environment is setting. all of them matter:

• NVIM_APPNAME — the name of sub-directories used within each XDG user directory. defaults to nvim. :help $NVIM_APPNAME
• NVIM_LOG_FILE — low-level log file, usually found at ~/.local/state/nvim/nvim.log. :help $NVIM_LOG_FILE
• VIM — used to locate user files, such as init.vim. system-dependent. :help $VIM
• VIMRUNTIME — used to locate runtime files (documentation, syntax highlighting, etc.).
• XDG_CONFIG_HOME — path to the user-local configuration directory, see "FILES". defaults to ~/.config. :help xdg
• XDG_STATE_HOME — like XDG_CONFIG_HOME, but used to store data not generally edited by the user, namely swap, backup, and ShaDa files. defaults to ~/.local/state. :help xdg
• XDG_DATA_HOME — like XDG_CONFIG_HOME, but used to store data not generally edited by the user, things like runtime files. defaults to ~/.local/share. :help xdg
• VIMINIT — Ex commands to be executed at startup. :help VIMINIT
• SHELL — used to initialize the 'shell' option, which decides the default shell used by features like :terminal, :!, and system().

---

🎀 FILES 🎀

where she keeps her stuff:

• ~/.config/nvim/init.lua — user-local nvim Lua configuration file.
• ~/.config/nvim — user-local nvim configuration directory. see also XDG_CONFIG_HOME.
• $VIM/sysinit.vim — system-global nvim configuration file.
• $VIM — system-global nvim runtime directory.

---

👑 AUTHORS 👑

giving credit where credit is due, always:

Nvim was started by Thiago de Arruda. most of Vim was written by Bram Moolenaar. Vim is based on Stevie, worked on by Tim Thompson, Tony Andrews, and G.R. (Fred) Walter. :help credits 🫶

---

and that's the whole page, bestie. this edition shipped on the Debian manual set, dated December 17, 2017. go edit some text, you absolute icon 💖✨🦋