Lazyman Notes

Lazyman Neovim Configuration Manager Notes

Lazy

The Lazyman Neovim configuration uses the Lazy plugin manager. The Lazyman Wiki includes a list of the Lazy loaded plugins in the Lazyman Neovim configuration sorted by load order and load time.

Mason

The Lazyman Neovim configuration uses the Mason portable package manager to easily install and manage LSP servers, DAP servers, linters, and formatters.

The first time nvim is executed Mason will install several packages required by the new Neovim configuration. Please be patient. If you exit Neovim prior to completion of the Mason installs, it will resume the next session.

The Lazyman Wiki includes a list of the Mason installed packages in the Lazyman Neovim configuration.

Packer

The lazyman command can be used to install and initialize Neovim configurations using the Packer plugin manager. To install and initialize a Packer managed Neovim configuration, specify the -P flag on the lazyman command line.

For example, to install and initialize the Abstract Neovim configuration at https://github.com/Abstract-IDE/Abstract invoke lazyman as follows:

lazyman -C https://github.com/Abstract-IDE/Abstract -N nvim-Abstract -P

This will clone the indicated repository into $HOME/.config/nvim-Abstract and initialize it using Packer with:

nvim --headless -c 'autocmd User PackerComplete quitall' -c 'PackerSync'

After export NVIM_APPNAME="nvim-Abstract", invoking nvim will bring up the Abstract Neovim configuration. Note, Abstract is now a supported Lazyman Neovim configuration and can be installed with lazyman -g.

Another Packer based Neovim configuration, this one using Fennel, is included as a Lazyman supported “Personal” config:

lazyman -w Fennel

To begin exploring this Neovim configuration:

NVIM_APPNAME="nvim-Fennel" nvim ~/.config/nvim-Fennel/fnl/conf/init.fnl

Another example of a Packer based Neovim configuration is the excellent MagicVim config, a fully supported Lazyman Neovim config. To install and initialize MagicVim:

lazyman -m

To begin exploring the MagicVim configuration:

NVIM_APPNAME="nvim-MagicVim" nvim

Plug

The lazyman command can be used to install and initialize Neovim configurations using the Plug plugin manager. To install and initialize a Plug managed Neovim configuration, specify the -p flag on the lazyman command line.

For example, to install and initialize the Optixal Neovim configuration at https://github.com/Optixal/neovim-init.vim invoke lazyman as follows:

lazyman -C https://github.com/Optixal/neovim-init.vim -N Optixal -p

After export NVIM_APPNAME="nvim-Optixal", invoking nvim will bring up the Optixal Neovim configuration. Note, the Optixal configuration is one of the supported Lazyman configs and can be installed with lazyman -w Optixal.

Another Plug based Neovim configuration serves as a second example:

lazyman -C https://github.com/offa/nvim-config -N Offa -p

To begin exploring this Neovim configuration:

NVIM_APPNAME="nvim-Offa" nvim ~/.config/nvim-Offa/init.lua

Also included as a supported Lazyman config is the previous Neovim configuration of the author which uses vim-plug and a vimscript initialization file. Install the Lazyman Plug config with the command lazyman -w Plug and start exploring with:

NVIM_APPNAME="nvim-Plug" nvim ~/.config/nvim-Plug/init.vim

Plug with Vim runtimepath manager

Finally, consider this Neovim configuration written in vimscript, stored in a subdirectory of a non-default git branch, using the vim-plug plugin manager, and relying on pathogen.vim to manage the runtimepath. Installing this Neovim configuration with lazyman requires several command line options:

lazyman -b vps -C https://github.com/xero/dotfiles \
        -D vim/.config/nvim -N Xero -p

This installs and initializes the configuration in ~/.config/nvim-Xero/ but fails to install pathogen. The pathogen.vim runtimepath manager can be installed with:

cfgdir="${HOME}/.config/nvim-Xero"
mkdir -p ${cfgdir}/autoload ${cfgdir}/bundle
curl -LSso ${cfgdir}/autoload/pathogen.vim https://tpo.pe/pathogen.vim

Open the configuration with NVIM_APPNAME="nvim-Xero" nvim and issue the command :PlugInstall. Now the configuration is properly initialized.

Health check

After installing and initializing the Neovim configuration, perform a health check while in Neovim with :checkhealth. Examine any warnings or errors and perform any necessary remedial actions such as installing missing packages or resolving keymap conflicts.

Profiling and benchmarking

A Makefile for profiling and benchmarking Neovim configurations is included in the Lazyman Neovim configuration at ~/.config/nvim-Lazyman/Makefile.

To create startup and loading profiles for a Neovim configuration:

cd ~/.config/nvim-<Name> # e.g. 'cd ~/.config/nvim-AstroNvim'
export NVIM_APPNAME="nvim-<Name>" # e.g. 'export NVIM_APPNAME="nvim-AstroNvim"
make -f ~/.config/nvim-Lazyman/Makefile profile

The files profile-startup.log and profile-viml.log will be generated.

Benchmarking a Neovim configuration startup requires hyperfine. If not present, install hyperfine with cargo:

cargo install --locked hyperfine

To benchmark a Neovim configuration:

cd ~/.config/nvim-<Name> # e.g. 'cd ~/.config/nvim-LazyVim'
export NVIM_APPNAME="nvim-<Name>" # e.g. 'export NVIM_APPNAME="nvim-LazyVim"
make -f ~/.config/nvim-Lazyman/Makefile benchmark

The files profile-bench-baseline.md, profile-bench-startup.md, profile-bench-baseline.log and profile-bench-startup.log will be generated.

Symbolic links

The NVIM_APPNAME procedure described above allows you to keep any existing ~/.config/nvim and install multiple Neovim configurations, each in its own separate ~/.config/$NVIM_APPNAME folder. Note, however, that if you create a symbolic link from ~/.config/$NVIM_APPNAME to ~/.config/nvim with the intention of using the Lazyman configuration without need of NVIM_APPNAME then you will also need to symlink ~/.local/share/$NVIM_APPNAME and ~/.local/state/$NVIM_APPNAME.

Shell initialization setup

If Lazyman is installed and initialized using the NVIM_APPNAME environment variable as described above then NVIM_APPNAME needs to be set when a lazyman initialized configuration is used. This can be done by setting and exporting this variable in your shell’s initialization file (e.g. .bashrc for Bash users, .zshrc for Zsh users). Add the line export NVIM_APPNAME="nvim-Lazyman" to your shell initialization and re-login or source the initialization file to use the Lazyman configuration.

However, setting NVIM_APPNAME in the shell initialization file fixes that environment variable to a single Neovim configuration and must be reset to use another configuration. A more flexible approach is to use shell aliases as described in the next section. Both approaches can be used, an export in the shell initialization file for the most frequently used Neovim configuration and aliases to override that for other configurations.

Github API rate limiting

If you are in a corporate network or large shared network you may encounter rate limiting issues when attempting to access the Github API. To increase your rate limit, create and export a Github personal access token:

export GITHUB_TOKEN=<your-github-token>

The nvims fuzzy selector

The lazyman installation and configuration automatically configures convenience aliases and shell functions for Lazyman installed Neovim configurations. One of these is the nvims shell function which dynamically creates a fuzzy searchable menu of installed Neovim configurations and launches Neovim with the selected Lazyman Neovim configuration.

See ~/.config/nvim-Lazyman/.lazymanrc.

Similarly, a neovides shell function can be used to select a Neovim configuration for use with the Neovim GUI neovide.

Both the nvims shell function and neovides shell function accept a -R flag which indicates removal of the selected Neovim configuration. Also supported is the -C filter option to nvims and neovides which specifies a filter string to match when generating the list of Neovim configurations to search and select.

The fuzzy searchable/selectable menu of Neovim configurations can also be shown with the command lazyman -S. Note also that both the nvims shell function and the lazyman -S command can accept additional filename arguments which are then passed to Neovim. For example, to edit /tmp/foo.lua with a Neovim configuration selected from the nvims menu:

nvims /tmp/foo.lua

Execute nvims directly at the shell prompt or by using the convenience key binding ctrl-n.

Similarly, if neovide is found in the execution PATH then a fuzzy selectable menu is provided with the neovides shell function and convenience key binding of ctrl-N to bring up that menu.

The following command line options are available with nvims and neovides:

-c command : specifies an Ex command to be executed after the first file has been read

-C filter : specifies a filter to use when generating the list of configurations to select from

-I : indicates display of the selected Neovim configuration information document

-R : indicates removal of the selected Neovim configurations

-S file : Executes Vimscript or Lua in file after the first file has been read. If no -S argument is provided then ~/.config/nvim-Lazyman/overrides.lua is used if not empty.

-U : displays a usage message and exits

Without arguments nvims and neovides generate a fuzzy search and selectable menu of all Lazyman installed Neovim configurations. Neovim or neovide will be opened using the selected configuration.

Example nvims and neovides usage

nvims : presents a fuzzy searchable and selectable menu of Neovim configurations and opens Neovim using the selected configuration

neovides : presents a fuzzy searchable and selectable menu of Neovim configurations and opens Neovide using the selected configuration

nvims -R : presents a fuzzy searchable and selectable menu of Neovim configurations and removes the selected Neovim configuration

nvims -C astro foo.lua : presents a fuzzy searchable and selectable menu of Neovim configurations with names containing the case insensitive string ‘astro’ and opens the file foo.lua with Neovim using the selected configuration

Lazyman .lazymanrc shell aliases and functions

The nvims shell function, when executed, presents a fuzzy searchable menu of the lazyman installed Neovim configurations. The lazyman installed Neovim configurations are maintained in the file ~/.config/nvim-Lazyman/.nvimdirs. Entries in this file are what nvims uses for its fuzzy selection menu. When Neovim configurations are installed or removed with lazyman this file is updated accordingly.

Note also that a convenience key binding has been created to launch nvims with ctrl-n.

Similarly, if neovide is found in the execution PATH then a fuzzy selectable menu is provided with the neovides shell function and convenience key binding of ctrl-N to bring up that menu.

Lazyman .nvimsbind shell key binding file

# $HOME/.config/nvim-Lazyman/.nvimsbind
# This file should be sourced from the shell initialization file
# after first sourcing ~/.config/nvim-Lazyman/.lazymanrc
command -v nvims > /dev/null && {
  if [ -n "$($SHELL -c 'echo $ZSH_VERSION')" ]; then
   bindkey -s ^n "nvims\n"
  elif [ -n "$($SHELL -c 'echo $BASH_VERSION')" ]; then
   bind -x '"\C-n": nvims'
  else
   bindkey -s ^n "nvims\n"
  fi
}
command -v neovide > /dev/null && {
  if [ -n "$($SHELL -c 'echo $ZSH_VERSION')" ]; then
   bindkey -s ^N "neovides\n"
  elif [ -n "$($SHELL -c 'echo $BASH_VERSION')" ]; then
   bind -x '"\C-N": neovides'
  else
   bindkey -s ^N "neovides\n"
  fi
}

The nvims Neovim configuration switching shell function was created by Elijah Manor. He created an excellent Neovim Config Switcher video in which he provides details on use and customization of the nvims shell function.

Lazyman has incorporated and adapted the nvims shell function for use with the Lazyman installed Neovim configurations. The nvims shell function is automatically configured during lazyman installation.

The .lazymanrc file also creates aliases for ls, less, and others including a tldrf alias that allows fuzzy searching and selecting from the list of cheatsheets supported by tldr. Try out the tldrf command to quickly and easily display documentation for thousands of commands. The idea for the tldrf alias came from another video by Elijah Manor.

Using aliases

In addition to exporting NVIM_APPNAME in your shell initialization file, you may wish to create aliases to execute with the various Neovim configurations you have installed. For example, aliases could be created to use Neovim configurations installed in ~/.config/nvim-LazyVim and ~/.config/nvim-LunarVim as follows:

alias nvim-lazy="NVIM_APPNAME=nvim-LazyVim nvim"
alias nvim-lunar="NVIM_APPNAME=nvim-LunarVim nvim"

After sourcing these aliases in your shell, to invoke Neovim with the LazyVim configuration run nvim-lazy filename.py and to invoke Neovim with the LunarVim config run nvim-lunar proposal.md.

Open URL command

The lazyman command includes support for opening Neovim configuration info documents in a browser. The command used to open a file URL varies from system to system and can be problematic. On macOS the open command is used and works fairly flawlessly. However, on Linux there are a variety of ways, none of which work well on all platforms. The lazyman command does its best to figure out what command to use to open a file URL but this may not always result in success. If opening a configuration information document fails, the open URL command can be overriden in ~/.config/nvim-Lazyman/.lazymanrc. To override the open URL command and/or set the BROWSER environment variable, uncomment and edit the following section of code there:

# Command to open a URL
# Set this to override the defaults:
#   On macOS the default is the 'open' command
#   Linux default is 'python3 -m webbrowser' then 'xdg-open' then 'gio open'
# export URL_OPEN_COMMAND="your custom command"
# For example, to use 'gio' rather than Python's webbrowser module on Linux:
# export URL_OPEN_COMMAND="gio open"
#
# To specify the browser, set the BROWSER environment variable. For example:
# export BROWSER="w3m"

Using lazyman to explore configurations

Another alternative to setting NVIM_APPNAME in the environment or with an alias is to use the lazyman command to specify which Neovim configuration to use with this invocation. This is done using the -E config option to lazyman. When invoking lazyman with the -E config argument, the Neovim configuration can be specified by setting config to one of astronvim, ecovim, kickstart, lazyman, lazyvim, lunarvim, nvchad, or any Neovim configuration directory in ~/.config. For example, to edit the file foo.lua using the LazyVim Neovim configuration:

lazyman -E lazyvim foo.lua

Now you’re using the LazyVim Neovim configuration to edit foo.lua, all of the LazyVim key bindings, plugins, options, and configuration will be used.

To instead use the LunarVim Neovim configuration to edit foo.lua:

lazyman -E lunarvim foo.lua

Before using lazyman -E <config> … to explore a Neovim configuration, first install and initialize the <config> configuration with lazyman.

When invoked with the -E config option, lazyman sets the NVIM_APPNAME environment variable to the specified config and executes nvim with all following arguments. This is a pretty easy way to explore all the lazyman installed and initialized Neovim configurations.