vimfiles

Windows Vim 8 configuration files based on the recommendations of Ruslan Osipov, Keep Your vimrc file clean and The musings of bluz71.

:help vimrc recommends moving vimrc and gvimrc to vimfiles to make the setup more portable.

Installation

Several applications are assumed to be in the PATH, install git-scm and select User Git and optional Unix tools from the Windows Command Prompt. See steps to add a local bin directory for the other applications referenced in the vim configuration files.

$Software = @(
  'Git.Git',
  'vim.vim',
  'Anaconda.Miniconda3',
  # KeeAgent is not available.
  'DominikReichl.KeePass',
  'Microsoft.PowerToys',
  'Microsoft.WindowsTerminal'
  # Universal ctags is not available.
)
$Software |  ForEach-Object -Process {
  winget install $_
}

Install Vim on Windows Subsystem for Linux

On Debian derivatives, like Ubuntu, the dotfiles repository provides an installation script for a compatible version of Vim with GTK3. It also links ~/.vim/ to Windows $USERPROFILE/vimfiles/ to share configuration across environments.

Install Vim on Windows

Vim-win32-installer includes python3/dyn currently linked to Python 3.10. Download and install or use chocolatey: choco install vim.

vimfiles installation

If you are not using WSL, to install in Unix based systems:

# Clone will fail if .local/ does not exist.
git clone https://github.com/jfishe/vimfiles.git $HOME/.local/vimfiles
ln -s $HOME/.local/vimfiles/vimfiles $HOME/.vim
cd $HOME/.local/vimfiles
git submodule update --init --recursive

To install in Windows under $env:LOCALAPPDATA\vimfiles and symbolic link to $HOME.

cd $env:TMP
curl  --output Install-Vimfiles.ps1 `
  https://raw.githubusercontent.com/jfishe/vimfiles/master/Install-Vimfiles.ps1

# To change defaults:
Get-Help .\Install-Vimfiles.ps1 -Full

# Clone and install submodules.
.\Install-Vimfiles.ps1 -Clone

# Symlink vimfiles and dotfiles to $HOME.
.\Install-Vimfiles.ps1 -Link

# Create Start-Menu shortcuts.
.\Install-Vimfiles.ps1 -Shortcut

# Copy wsl -d Ubuntu /usr/share/dict/words to vimfiles/dictionary/words.
# Install dictionary if needed.
.\Install-Vimfiles.ps1 -Dictionary

# Download Moby Thesaurus from
# https://raw.githubusercontent.com/zeke/moby/master/words.txt
.\Install-Vimfiles.ps1 -Thesaurus

# Create/update conda environment compatible with `python3/dyn`.
# Create/update Vim batch files to activate vim_python prior to starting Vim.
.\Install-Vimfiles.ps1 -Conda

If you plan to share vimfiles with Windows Subsystem for Linux (WSL), ensure git uses line feed for EOL. Install-Vimfiles.ps1 automates this by setting the global .gitconfig to override the system defaults.

Windows Environment

On Windows systems %HOMEDRIVE%%HOMEPATH%, e.g., U:\. may point to a different path than %USERPROFILE%—i.e., C:\Users\<user name>. git-scm defaults to %HOMEDRIVE%%HOMEPATH%. Defining %HOME%, overrides this behavior.

1. Open Control Panel.
2. Search for environment.
3. Select Edit environment variables for your account
4. Select New.
5. Variable name: HOME
6. Variable value: %USERPROFILE%
7. Select OK.
8. Select Path and Edit.
9. Select New and enter %USERPROFILE%\bin.
10. Select OK, twice.
11. Open git-bash or git-cmd and confirm directory is C:\Users\<user name>.

Windows Python Version

On Windows python3/dyn may point to a later version of python than conda supports in the base environment. Copy or update gvim.bat. The usual locations are:

• %LOCALAPPDATA%\Microsoft\WindowsApps\gvim.bat
• %WINDIR%\gvim.bat

Adding a call to conda and creating a Start-Menu shortcut can resolve the issue, e.g:

Installing with chocolatey will clobber the Vim batch files because it replaces any it finds in $env:WINDIR and $env:LOCALAPPDATA\Microsoft\WindowsApps. The following snippet ensures the batch files are in $env:LOCALAPPDATA\Microsoft\WindowsApps and calls a Vim function to activate a compatible conda envirionment. See Anaconda and Miniconda for installation instructions.

Rebuild the vim_python whenever the python minor version changes, e.g. from Python 3.9 to 3.10. Edit environment.yml to update the python version and move other packages to the - pip: group as needed. Conda packages typically lag python versions; the pip versions tend to update first.

# Determine python3/dyn library linked to Vim, e.g., python310.dll.
$VimVersion = vim --version |
  Select-String -Pattern '-DDYNAMIC_PYTHON3_DLL=\\"(python\d{0,3}).dll\\"'
# python[version='>=3.10'] matches python310.
Write-Output $VimVersion.Matches.Groups[1].Value

Anaconda and Miniconda

Install Miniconda or Anaconda per the directions in the Anaconda Documentation.

Windows 10 includes a python executable in $env:LOCALAPPDATA/Microsoft/WindowsApps/, which interferes with [Conquer of Completion (CoC)]. Remove python.exe and python3.exe or run one of them to install Python 3 from the Microsoft Store.

environment.yml lists the conda and pip packages needed for the Vim configuration.

To add packages to the conda environment for use by Vim:

# Update conda. The installer is typically out of date.
conda update -n base -c defaults conda

# Initialize conda for the various shells on the computer
conda init

# Create a vim_python environment compatible with the installed version of Vim.
$File = $env:LOCALAPPDATA\vimfiles\environment.yml
conda env create --file $File

# Periodically update the base and vim_python environments.
conda update -n base -c defaults conda
conda update -n vim_python --all

Windows Registry

Vim's install.exe tries to add right-click menus to explorer, but usually fails, even when installing with administrator rights. ~\vim\vim82\GvimExt64\GvimExt.reg provides an example but assumes the dll and executable are in the PATH. GvimExt.reg provides a working version, assuming vim is installed in %USERPROFILE%.

The following will request administrator permission and add the contents of GvimExt.reg to the Window Registry. Validate the file against the version included with Vim.

regedit /S GvimExt.reg

Thesaurus

Setup instructions are included in vimrc to install the Moby Thesaurus List by Grady Ward from Project Gutenberg. Use a browser; the site blocks scripted download.

Moby-thesaurus.org/ maintains words.txt.

Dictionary

Refer to :help dictionary and download or symlink dictionary/words. See below for symlink instrucitons.

On Windows 10, you can symlink to a dictionary in a WSL 1 Distro. It may work with WSL 2.

1. If needed, use the default WSL to install the dictionary. It should symlink to /usr/share/dict/words, which vimfiles/vimrc assumes for non-Windows platforms.
2. Adjust the path below, as needed. Windows does resolve nested symlinks, so use the resolved path to the dictionary.
3. Replace <distro_name> with the default WSL distro, e.g., WLinux, Ubuntu, etc.

Install-Vimfiles.ps1 -Dictionary assumes Ubuntu is the default and copies the dictionary since symlinks into WSL fail when the distro isn't started.

grepprg and grepformat

ripgrep should be installed with chocolatey or conda.

Gutentags & Universal ctags

• Gutentags
• universal-ctags provides direction for obtaining pre-built ctags binary without needing source-forge.

Conquer of Completion (CoC)

Conquer of Completion does not depend on the python compiled with Vim. It supports Node.js modules that perform the linting functions of ALE.

The script after/plugin/coc.vim installs extensions using g:coc_global_extensions. Install CoC under opt instead of start to allow disabling when node.js is unavailable.

Asynchronous Lint Engine (ALE)

The Asynchronous Lint Engine supports various linting (ALELint) and formatting (ALEFix) tools. Many of these are Node.js packages. See jfishe/ALE_Nodejs for a list and installation instructions. Others, such as black can be installed by conda or pip. See environment.yml for a list.

Jupyter Notebook

git configuration

nbdime is configured by:

pip install nbdime
nbdime config-git --enable --global

Default Browser

The default browser on Windows 7 and 10 needs to remain IE/Edge to avoid conflicts with various applications. ~/.jupyter/jupyter_notebook_config.py is modified to specify Chrome as the notebook and lab browser since IE is not compatible with notebook v. 5.

Windows Setup

Console

Download the latest release of ColorTool and extract into the PATH, e.g., ~/bin. Include the schemes directory and add any additional schemes, as desired. Create a hard-link mklink /h from ~/bin/schemes to each of the .itermcolors files in $env:PROFILE directory.

New schemes may be tested and exported to iTerm2 format with terminal.sexy.

• Introducing the Windows Console Colortool
• ColorTool.

Setup Python Project

cookiecutter cookiecutter-pypackage

Change to the pypackage directory you created and make initial commit to source control.

git init
git add .
git commit -m "Initial project scaffold"
git status

virtualenv env
# Use env/bin/activate on Linux
env\Scripts\activate
pip install -e .

Git

ElateralLtd git commit template provides a template and installation script for standard git commit messages.

The Vim that ships with Git-bash can use the same profile as Gvim. Using WSL bash is the easiest method to create soft-links. Git-bash won't and recommends using mklink, but mklink usually has complex ACL issues, especially in a corporate environment. PowerShell and CMD do not recognize soft-linked directories so use mklink /J LINK TARGET.

The following assumes that git-bash has been configured to use %USERPROFILE% as home, which may be different than the default %HOMEDRIVE%%HOMEPATH%. Also, Documents could be My Documents. Adjust the path for actual location of vimfiles and vimwiki. The vim startup script assumes that for anything, except Windows cmd.exe, that these files are located in $HOME. Soft-links allow pointing to the actual location.

Git Hooks

Tim Pope's Effortless Ctags with Git shows how to rebuild Ctags with git hooks. Note they do not work under PowerShell or CMD but do not seem to cause problems either. To work under WSL:

ln -s /mnt/c/Users/fishe/AppData/Local/vimfiles/.git_template ~/.git_template

To make hooks available from Windows, if you have any .bat or .ps1 hooks:

.\Install-Vimfiles.ps1 -Link

The Case for Pull Rebase

The Case for Pull Rebase recommends avoiding merge commits, except when they're useful, such as for Pull Request merges.

git pull --rebase|-r # Normal to avoid merge commits.
git pull --rebase=preserve # When local merge commit preserved, like Pull Request.
git config --global pull.rebase preserve

# if you're on Git 2.18 or later
git pull --rebase=merges
git config --global pull.rebase merges

Git diff for Excel Files

Xltrail suggested 3 steps to make Spreadsheet Compare work with git diff. The proposed DOS batch script does not work with Microsoft Office 2016 because spreadsheetcompare is not an installed application. Install a modified version, which uses AppVLP.exe, as follows:

cmd /c "mklink $env:USERPROFILE\bin\xldiff.bat $env:LOCALAPPDATA\vimfiles\xldiff.bat"

.gitconfig defines [diff "excel"] and .gitattributes_global sets diff=excel for all Excel file extensions. The batch script pauses git so that it does not delete any temporary files it creates. Press <Enter> in the shell after exiting spreadsheetcompare.

KeePass2, KeeAgent and SSH

KeeAgent (for KeePass) on Bash on Windows / WSL provides a howto. Git-bash only requires export SSH_AUTH_SOCK=~/keeagent_msys.socket in .bash_profile, depending on the KeeAgent settings in KeePass2.

Map Caps Lock to Escape, or any key to any key

On Windows install PowerToys or Uncap.

Install PowerToys

• choco install powertoys
• Open PowerToys Settings application.
• In Keyboard Manager, map Caps Lock to Esc.

vimfiles Update

Install the plugins in the Git repository.

git pull
git submodule update --init --recursive
vim -c 'packloadall | helptags ALL | qa'

Update to the latest versions and commit the changes, if any.

git submodule update --init --recursive --remote
vim -c 'packloadall | helptags ALL | qa'
git commit -am "chore: update submodules"
git push