Linux Dev Environment with Vim

My personal development environment for WSL/Linux. Covers Vim and Bash configuration, language-specific tooling, and a debugging setup powered by Vimspector.

Repository Structure

File	Description
vimrc	Vim config
bashrc	Bash config
shortcuts.txt	Quick reference for all shortcuts and commands
envsetup	Setup script for new machines

---

Index

Section	Description
First-Time Setup	Everything needed to get the environment running on a new machine
Language Setup	Per-language install steps, tooling, and shortcuts
Debugging	How the Vimspector debugger works and how to use it
Daily Reference	Shortcuts, aliases, and UI reference for everyday use
Maintenance	How to push and pull config changes across machines

---

First-Time Setup

The steps below are the full manual reference. If you prefer an automated setup, see envsetup which handles all of this interactively.

Important: This repo must be cloned to ~/vimfiles. If you cloned it elsewhere, create a symlink so scripts and config paths resolve correctly:

ln -sf /path/to/your/vimfiles ~/vimfiles

Required

1 — Clone the repo

git clone https://github.com/vit-ui/vimfiles.git ~/vimfiles

2 — Upgrade Vim and install Node.js

This setup requires a recent Vim build. If your system ships an older version, upgrade it:

sudo add-apt-repository ppa:jonathonf/vim && sudo apt update && sudo apt install vim

Install Node.js via nvm (Node Version Manager — installs Node without sudo and works on all platforms):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.nvm/nvm.sh
nvm install --lts
nvm alias default lts/*

3 — Link configuration files

Vim and Bash look for .vimrc and .bashrc in your home directory. Link them from this repo so your config stays version-controlled:

ln -sf ~/vimfiles/vimrc ~/.vimrc
ln -sf ~/vimfiles/bashrc ~/.bashrc
source ~/.bashrc

These are symbolic links — the actual files stay in this repo. Any edit to ~/.vimrc is really an edit to ~/vimfiles/vimrc, which you can then commit and push. Run source ~/.bashrc after linking to apply bash changes to the current terminal session without restarting it.

4 — Install vim-plug and plugins

vim-plug is the plugin manager. Install it:

curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
  https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

Then open Vim and run:

:PlugInstall

On the first open, Vim automatically creates and configures ~/.gitignore_global to ignore tags files and .vimspector.json (the per-project debugger config file).

5 — Install system tools

Universal Ctags — generates tag files for code symbol navigation, required by the Gutentags plugin:

sudo apt install universal-ctags

shellcheck — static analysis tool for shell scripts, used by coc-sh for diagnostics in .sh and .bashrc files:

sudo apt install shellcheck

glow — terminal Markdown renderer, used by :Preview, \mp, and the setupdocs alias:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install glow

6 — Add envsetup to PATH

If you ran envsetup init, this is done automatically. If you are doing the setup manually:

chmod +x ~/vimfiles/envsetup
sudo ln -sf ~/vimfiles/envsetup /usr/local/bin/envsetup

---

Optional

ripgrep

A fast file content search tool that replaces grep for code search. Used with rg in the terminal:

sudo apt install ripgrep

GitHub CLI (gh)

Command-line interface for GitHub operations (creating pull requests, cloning repos, etc.). Not required for the environment to work.

Via webi (gets latest version):

curl -sS https://webi.sh/gh | sh

Via apt (auto-updates with apt upgrade):

sudo apt install gh

Authenticate after installing:

gh auth login

---

envsetup Script

envsetup is a setup script that automates the First-Time Setup steps above. It is interactive, idempotent (safe to re-run), and works on apt, dnf, pacman, and brew systems.

Usage

envsetup init              # First-time setup — interactive
envsetup lang go           # Set up Go (also: python, markdown)
envsetup info              # Open this README with glow
envsetup help              # Show usage

What it does

envsetup init walks you through the same steps as First-Time Setup above, asking which languages and optional tools to install. Each step checks if it is already done and skips it if so.

envsetup lang <n> sets up a single language at any time after init — useful when you want to add a language later without re-running the full setup.

After init completes, envsetup is available from anywhere on the system.

What it does NOT do

• Per-project debugger setup — run :InstallDebugger <adapter> in Vim from your project root when needed. See Debugging.

---

Language Setup

All languages format automatically on save via CoC. No manual step is needed when adding a new language — install its CoC extension and formatter and formatting will work on save automatically.

Go

Requirements

• Go binary
• Delve (the Go debugger binary — must be installed manually, see step 3)

1 — Install Go

The script below fetches the latest stable release from Go's API, detects your CPU architecture, and installs to /usr/local/go:

GO_VER=$(curl -s "https://go.dev/dl/?mode=json" \
    | grep -o '"version":"go[^"]*"' | head -1 | cut -d'"' -f4)
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -Lo "/tmp/${GO_VER}.linux-${ARCH}.tar.gz" \
    "https://go.dev/dl/${GO_VER}.linux-${ARCH}.tar.gz"
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf "/tmp/${GO_VER}.linux-${ARCH}.tar.gz"
rm "/tmp/${GO_VER}.linux-${ARCH}.tar.gz"

Alternatively, download the .tar.gz manually from go.dev/dl and run:

sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go_XX.X.tar.gz

Verify:

go version

The Go binary directories are already in PATH via .bashrc.

2 — Install Go tooling

Inside Vim:

:GoUpdateBinaries

This installs gopls (the Go language server) and other vim-go tooling using go install internally.

3 — Install Delve

Delve is the Go debugger binary. Vimspector's delve adapter is a config layer that tells Vimspector how to talk to Delve via DAP (Debug Adapter Protocol — a standard interface between editors and debuggers) — it does not download the binary itself. Install it manually:

go install github.com/go-delve/delve/cmd/dlv@latest

4 — Set up the debugger

Navigate to your project root and open Vim:

cd ~/my-project
vim .

Then run:

:InstallDebugger delve

When launching a debug session with \gc, Vimspector prompts for ${program}. Enter the path to your entry point, e.g. . or ./cmd/myapp.

See Debugging for how this works.

Shortcuts

Command/Shortcut	Description
\r	Run current file
\t	Run tests
:GoAddTags	Add JSON tags to struct fields

---

Python

Requirements

• Python 3 and pip
• pipx (tool manager for Python CLI programs)
• black (formatter)
• debugpy (downloaded automatically by :InstallDebugger debugpy, see step 3)

1 — Install Python 3 and pip

They may already be present. Check:

python3 --version
pip --version

If missing:

sudo apt install python3 python3-pip

2 — Install pipx and black

pipx installs Python CLI tools each in their own isolated environment, while still exposing the binary globally on your PATH. This avoids polluting the system Python without needing flags like --break-system-packages:

sudo apt install pipx
pipx ensurepath

Install black (the formatter called on save for Python files):

pipx install black

Verify:

black --version

3 — Set up the debugger

Navigate to your project root and open Vim:

cd ~/my-project
vim .

Then run:

:InstallDebugger debugpy

When launching a debug session with \gc, Vimspector prompts for ${program}. Enter the path to your entry point, e.g. main.py or ./src/main.py.

Unlike Delve for Go, debugpy is a pure Python package — Vimspector downloads it directly from GitHub into its gadgets directory. No separate binary install is needed.

See Debugging for how this works.

Shortcuts

Command/Shortcut	Description
\r	Run current file with Python 3

---

Markdown

Requirements

• glow (terminal Markdown renderer — installed in First-Time Setup step 5)

Three CoC extensions handle Markdown automatically after :PlugInstall: coc-markdownlint (lints style violations as you type and on save), coc-prettier (formats prose on save), and coc-marksman (a Markdown language server that enables \d and \fr on internal document links between .md files).

Shortcuts

Command/Shortcut	Description
\mp	Open rendered preview in a terminal split
:Preview	Same as \mp

---

Debugging (Vimspector + DAP)

How it works

Debugging is powered by Vimspector using DAP (Debug Adapter Protocol — a standard interface between editors and language-specific debuggers). Vimspector acts as the DAP client: it sends commands (set breakpoint, step over, etc.) and the language-specific debugger executes them.

There are two separate components per language:

1. The debugger — the actual program doing the debugging. Whether Vimspector downloads this or you install it manually depends on what the debugger is. See each language block above for details.
2. The Vimspector gadget — a config layer that tells Vimspector how to launch and communicate with that debugger. This is what :InstallDebugger installs.

The InstallDebugger command

:InstallDebugger is a custom command defined in .vimrc. It does two things:

• Runs :VimspectorInstall <adapter>, which downloads the gadget into ~/.vim/plugged/vimspector/gadgets/
• Creates (or merges into) a .vimspector.json in the current directory with a launch configuration for that adapter

It does not install the debugger binary itself in all cases — see each language block for what is and isn't handled automatically.

Must be run from the project root. Navigate there first and open Vim with vim ., then run :InstallDebugger <adapter>.

Using Go as the reference example, the generated .vimspector.json looks like:

{
  "configurations": {
    "delve": {
      "adapter": "delve",
      "filetypes": ["go"],
      "configuration": {
        "request": "launch",
        "program": "${program}",
        "args": [],
        "cwd": "${workspaceRoot}",
        "env": {},
        "mode": "debug"
      }
    }
  }
}

Run :Format on .vimspector.json to pretty-print it after generation.

Debug flow

When you launch a debug session with \gc, Vimspector prompts for ${program}. The entry point to enter depends on the language — see the relevant language block in Language Setup.

Shortcut	Action
\gb	Toggle breakpoint
\gc	Launch / Continue
\gn	Step Over
\gi	Step Into
\go	Step Out
\gs	Stop session
\gr	Restart
\gq	Hard reset Vimspector

Default leader is \

---

Daily Reference

Vim

The full shortcut reference is in shortcuts.txt. Access it with:

:Shortcuts

or from the terminal:

shortcuts

A few non-obvious ones worth knowing up front:

Shortcut	What it does
dd	Remapped — clears line contents but leaves the empty line
dl	Deletes the line entirely (default dd behavior)
qq	Exits insert mode (same as <Esc>)
\d / \b	Jump into definition / jump back
\cp / \cn	Jump to previous / next diagnostic (error or warning)

Bash

The terminal aliases and Git shortcuts are in shortcuts.txt. The custom functions worth knowing by name:

• mkcd <dir> — creates a directory and immediately enters it
• up [n] — go up N directories (e.g., up 3 = cd ../../..)
• git() — wraps git to print git status after every successful command except status, help, and pull. Bypass with command git <args>.
• vim() — no arguments opens the current directory in netrw. Multiple arguments open in vertical splits.

Quick Config Access

Command	Description
cdv	Jump to ~/vimfiles
evim	Open vimrc, bashrc, and shortcuts.txt in splits
shortcuts	Open shortcuts.txt in less for reading
setupdocs	Open this README with glow
gcp	git commit && git push in one step

UI Reference

Status line fields:

Field	Meaning
Filename	Current file path
[+]	Unsaved changes
[RO]	Read-only file
%	File progress
L:C	Line and column

Cursor shape (works in WSL and common Linux terminals):

• Block — Normal mode
• Beam — Insert mode
• Underline — Replace mode

Window navigation — use \h \j \k \l to move between splits. Works inside Vimspector panels and :terminal buffers as well.

---

Maintenance

Push local changes

Use when you edit your config locally and want to save it to the repo:

cd ~/vimfiles
git add .
git commit -m "update config"
git push

Pull remote changes

Use when syncing your environment from the repo (e.g., on a new machine after initial setup):

cd ~/vimfiles
git pull
source ~/.bashrc

source ~/.bashrc applies any bash changes to the current terminal session without restarting it.