Nvmm / Documentation

• Choosing a Neovim
• Appearance
• Tabs vs Buffers
• Command-line helper
• Environment
• Drag and Drop
• IMEs and Dead Keys
• Hidden Settings

• Choosing a Neovim

  Nvmm is bundled with its own copy of Neovim and uses it by default. Like MacVim, it just works “out of the box”. There is no need to download a separate copy of Neovim to use Nvmm.

  You do, however, have the option to use a different version of Neovim if you wish. To do so, open the Settings panel and choose Other… from the Neovim popup menu. Use the file browser that appears to select an nvim executable of your choice. It must be Neovim 0.12 or newer. Symlinks are kept as chosen, so a package manager’s bin/nvim keeps working after you upgrade.

  This setting applies to new windows, including those opened by the command-line helper. Windows that are already open keep the Neovim they started with. If the chosen Neovim fails to start, Nvmm tells you and opens Settings so you can fix it.

  Help menu topics always come from the bundled Neovim’s help files. If your own Neovim lacks a topic, it will report the error itself.

  ↑ Back to top

• Appearance

  You have some options for how to set Light or Dark mode with Nvmm as well as ways to respond to changes in appearance.

  Setting Appearance

  Nvmm’s Settings panel has options for following the System Appearance, always using Light or Dark mode, or following Neovim’s 'background' option. This affects the title bar, scrollbar, and other Mac parts of the window. Your colorscheme is still in charge of the text area.

  Responding to Appearance Changes

  Nvmm exposes the editor view’s effective appearance as g:nvmm_os_appearance with the following values:

  • 0 → light
  • 1 → dark
  • 2 → high-contrast light
  • 3 → high-contrast dark

  When Nvmm changes this variable, it triggers the User NvmmOSAppearanceChanged autocmd.

  For example, with Appearance set to System in the Settings panel, add this to your init.lua to switch between a light and a dark colorscheme when the system appearance changes:

  local function update_colorscheme()
    local appearance = vim.g.nvmm_os_appearance
    if not appearance then return end
    local light = appearance == 0 or appearance == 2
    vim.cmd.colorscheme(light and "my_light_colorscheme" or "my_dark_colorscheme")
  end
  
  local group = vim.api.nvim_create_augroup(
    "NvmmAppearance",
    { clear = true }
  )
  
  vim.api.nvim_create_autocmd("User", {
    group = group,
    pattern = "NvmmOSAppearanceChanged",
    callback = update_colorscheme,
  })
  
  -- Apply the appearance now if Nvmm has already set it.
  update_colorscheme()
  

  ↑ Back to top

• Tabs vs Buffers

  Most users know that Neovim’s tabs (technically tabpages) don’t work quite the same way tabs work in most other Mac apps. Nevertheless, most Vim and Neovim GUI clients treat tabpages as if they were regular tabs by default.

  In order to be consistent with most people’s expectations, Nvmm does this too, but it also lets you choose if you’d prefer to use buffers instead.

  By default, opening a file makes a new tabpage. If the file is already showing in a tab, Nvmm jumps to it instead of opening it again.

  Turn on Open files in buffers instead of tabs in Settings and files open as buffers in the current window instead.

  This setting applies to:

  • File → New, which makes an empty tabpage or buffer
  • File → Open…
  • Files opened from the Finder, Open Recent, or open -a Nvmm
  • Files dropped on a window while holding ⌥
  • Files opened by the command-line helper

  By pairing this option with a plugin like vim-buftabline, you get the best of both worlds: buffers that look and act like conventional tabs.

  Note: With this option turned on, File → New will only make a new empty buffer if the current one is not empty. With this option turned off, you will always get a new tabpage.

  File → New Window (⌥⌘N) always opens a new Mac window with its own Neovim.

  To learn more about Neovim buffers and tabpages, see :help windows.txt and :help tabpage.txt.

  ↑ Back to top

• Command-line helper

  Nvmm bundles nvim and nvmm, a command-line helper that opens files in a running Nvmm or launches it if needed.

  To use both nvmm and nvim easily, put their folder in your PATH. For example, assuming Nvmm is in your /Applications folder and you are using zsh, put this in your ~/.zprofile:

  export PATH="/Applications/Nvmm.app/Contents/bin:$PATH"
  

  Alternatively, you can symlink one or both:

  ln -s /Applications/Nvmm.app/Contents/bin/nvmm ~/.local/bin/nvmm
  ln -s /Applications/Nvmm.app/Contents/bin/nvim ~/.local/bin/nvim
  

  Example nvmm usage

  nvmm                 # open a new window in the current directory
  nvmm a.txt           # open file
  nvmm --reuse a.txt   # open file in the best existing window
  nvmm -p a.txt b.txt  # one tab per file
  nvmm +42 a.txt       # put cursor at line 42
  nvmm --wait a.txt    # open file and wait until its window is closed
  nvmm --help          # show all supported options
  

  Each nvmm invocation opens a new window with Neovim running in the current directory, using the same environment as your shell. --reuse instead opens files in the best existing window, or activates an existing window when no files are given. If no window exists, it opens one. --reuse cannot be combined with --wait or Neovim options.

  Options

  +                 Start at end of file
  +<lnum>           Start at line <lnum>
  +/<pattern>       Start at the first line containing <pattern>
  +<cmd>, -c <cmd>  Execute <cmd> after loading the first file
  -d                Diff mode
  -f, --wait        Foreground mode - wait until the window is closed
  -h, --help        Print this help message
  -o                Open one horizontal window per file
  -O                Open one vertical window per file
  -p                Open one tabpage per file
  -R                Read-only mode
  --clean           Factory defaults - no user config or plugins
  --reuse           Reuse the best existing Nvmm window
  

  When you open several files without -d, -o, -O, or -p, they follow the Tabs vs Buffers setting.

  --clean starts Neovim without your config or plugins, which is useful when you’re tracking down a problem. It doesn’t reset Nvmm’s own settings.

  nvmm exits with 0 when Nvmm accepts the request (or, with --wait, when the window closes), 1 if something goes wrong, and 2 if the command line is wrong.

  Using Nvmm with Git

  --wait keeps nvmm running until the window closes, which is what Git and other tools expect from an editor:

  git config --global core.editor "nvmm --wait"
  

  Note that --wait waits for the whole window to close, not just the file. Quit with :wq or close the window when you’re done.

  ↑ Back to top

• Environment

  Mac apps opened from the Finder or the Dock don’t get the environment variables your shell sets up, like PATH. That can cause trouble for plugins that run tools such as language servers, formatters, or git. Nvmm handles this in two ways, depending on how a window was opened.

  Windows opened by the nvmm helper get the exact environment of the shell where you ran it. If you’re in a project directory with a special PATH or an activated virtualenv, Neovim sees the same thing. A window reused with --reuse keeps the environment it already had.

  All other windows, such as those opened from the Dock, File → New Window, or the Finder, start Neovim through your login shell. The shell reads your login profile first, so Neovim gets the PATH and variables you set there.

  For zsh, the login profile is ~/.zprofile (and ~/.zshenv, which zsh always reads). Note that ~/.zshrc is not read, since it is only for interactive shells. If a tool works in Terminal but not in an Nvmm window, move the export lines it depends on from ~/.zshrc into ~/.zprofile.

  A window’s Neovim also starts in a sensible directory: the current directory for the nvmm helper, the folder of the first file when the Finder opens files in a new window, and your home folder otherwise.

  ↑ Back to top

• Drag and Drop

  You can drop files from the Finder onto an Nvmm window.

  Dropping without ⌥ inserts the files’ paths as text, like most Mac apps do:

  • In Normal, Insert, or Visual mode, the paths are put after the cursor, one per line, and left selected.
  • On the command line or in a terminal buffer, they are pasted on one line, separated by spaces. Paths aren’t quoted, so be careful with names that contain spaces.

  Holding ⌥ while dropping opens the files instead, as tabpages or buffers depending on the Tabs vs Buffers setting.

  A drop is ignored while Neovim is waiting for you to answer a prompt.

  ↑ Back to top

• IMEs and Dead Keys

  Nvmm uses the Mac’s own text input system, so dead keys, ⌥ characters, input methods (IMEs) for languages like Chinese, Japanese, and Korean, and the emoji & symbols viewer (⌃⌘Space) all work the way they do in other Mac apps.

  While you are composing text with an IME or a dead key, the unfinished text is called the pre-edit (Apple calls it marked text). Nvmm draws the pre-edit right at the cursor, and the IME’s candidate window appears next to it. In Insert mode, the pre-edit pushes the text after the cursor to the right, like in other Mac apps, staying inside the current Neovim window. In other modes, it’s drawn over the text instead.

  The pre-edit is only a preview. Nothing goes into your buffer until you commit it, so choosing a different candidate or cancelling leaves no trace in Neovim, including its undo history. If you press a key the input method doesn’t use, such as an arrow key, Nvmm commits the pre-edit first and then sends the key to Neovim.

  Pre-edit text is laid out on a single line. If it’s too long to fit, Nvmm keeps the part you’re editing in view.

  ↑ Back to top

• Hidden Settings

  A few settings don’t have a spot in the Settings panel. They are all on by default. You can turn them off in Terminal, then restart Nvmm:

  defaults write com.mowglii.Nvmm NVEnableProgressBar -bool false
  defaults write com.mowglii.Nvmm NVEnableContextSensitiveMouseCursor -bool false
  defaults write com.mowglii.Nvmm NVEnableNativePowerlineSymbols -bool false
  

  • NVEnableProgressBar shows a thin progress bar across the top of the window when Neovim reports progress for a running task.
  • NVEnableContextSensitiveMouseCursor changes the mouse pointer depending on what it is over, such as an I-beam over text or a resize arrow over a window separator.
  • NVEnableNativePowerlineSymbols draws Powerline separators (the arrow and slant shapes used by many status lines) so they line up exactly with the text cells, instead of using the font’s version.

  To turn one back on, delete it:

  defaults delete com.mowglii.Nvmm NVEnableProgressBar
  

  ↑ Back to top