No description
Find a file
Andy Li 5027cc403a pin neovim 0.11.7 and LSP server versions
- init.lua warns at startup when Neovim isn't the pinned 0.11.7
- mason ensure_installed pins each server version
- treesitter: don't auto-install latex (needs the tree-sitter CLI)
- README: install Neovim from the official release instead of brew/snap,
  Node >= 22.22.2 (Ubuntu: from nodejs.org), tmux 3.4-3.5a SIXEL note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 13:18:57 +11:00
config pin neovim 0.11.7 and LSP server versions 2026-10-27 13:18:57 +11:00
.gitignore add readme 2026-08-31 17:27:23 +10:00
.p10k.zsh add readme 2026-08-31 17:27:23 +10:00
.zshrc add readme 2026-08-31 17:27:23 +10:00
README.md pin neovim 0.11.7 and LSP server versions 2026-10-27 13:18:57 +11:00

dot_files

Personal dotfiles for zsh, Neovim, and tmux, used across macOS and Ubuntu servers. The repo exists to bring a fresh machine up to my usual setup quickly — clone it, then copy (or symlink) each piece into place.

Some settings are platform-specific (macOS vs Ubuntu); those guard themselves so the same files work on both.

Layout

.zshrc          # zsh + oh-my-zsh + powerlevel10k, aliases, auto-tmux   -> ~/.zshrc
.p10k.zsh       # the powerlevel10k prompt itself (segments, colors)     -> ~/.p10k.zsh
config/nvim/    # Neovim: packer, commit-pinned plugins, native LSP      -> ~/.config/nvim
config/tmux/    # tmux: tpm-managed plugins                              -> ~/.config/tmux

.zshenv is not in this repo — it holds machine-local secrets. See Secrets for what to recreate by hand.

Two deployment targets

This repo serves two kinds of machine. Follow one of the paths below.

Mac (local) Ubuntu (remote server)
Terminal runs here yes — Alacritty no, you SSH in
Nerd Font install required skip — the font is a local terminal thing
Neovim + LSP full full
tmux full full minus continuum
Session save/restore yes skip — servers stay up; nothing to restore
Clipboard pbcopy via tmux-yank OSC 52 → forwarded to your Mac terminal

Common to both:

git clone https://git.andyli.info/andyli/dot_file.git ~/dot_files && cd ~/dot_files

Path A — Mac (local machine)

A1. Prerequisites

brew install zsh git tmux ripgrep node

Install a Nerd Font and select it in Alacritty. Powerlevel10k's segments are glyphs; without it the prompt renders as boxes and question marks.

Neovim is pinned to 0.11.7 — install it from the official release as in Neovim (pinned), not brew install neovim (brew ships 0.12.x now). Node.js ≥ 22.22.2 and Python are needed for the LSP servers (ts_ls, eslint, pyright); brew's node is new enough, and mason installs the server binaries itself.

A2. oh-my-zsh, theme, plugin

chsh -s "$(which zsh)"
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

git clone https://github.com/zsh-users/zsh-autosuggestions \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions"
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k"

A3. zsh

cp .zshrc ~/
cp .p10k.zsh ~/          # BOTH files, or you get a stock prompt

A4. Secrets, then re-exec

Create ~/.zshenv — see Secrets below. Then:

exec zsh

Do not skip the re-exec. .zshrc exports XDG_CONFIG_HOME on line 1, and config/tmux/tmux.conf uses ${XDG_CONFIG_HOME} for its tpm path. Start tmux from a shell without that variable and the path expands to /tmux/plugins/tpm/tpm — tpm silently never loads and you get zero plugins.

A5. Neovim

A build toolchain is required — nvim-treesitter compiles each parser from C on install:

xcode-select --install          # macOS: provides cc, make, git

Install packer first. The config calls packadd('packer.nvim') on line 4 of lua/theprimeagen/packer.lua and has no self-bootstrap — if packer isn't already on disk, nvim throws on every launch. Clone it into Neovim's start pack directory so it loads automatically:

git clone --depth 1 https://github.com/wbthomason/packer.nvim \
  ~/.local/share/nvim/site/pack/packer/start/packer.nvim

That path is not arbitrary — ~/.local/share/nvim/site is Neovim's data dir (:echo stdpath('data')), and anything under pack/*/start/ is sourced at startup. Keep the clone on one line if you retype it; a stray trailing backslash creates a file literally named \.

Then drop the config in and sync:

mkdir -p ~/.config && cp -r ./config/nvim ~/.config
nvim

The first launch will print errors (module 'telescope' not found and similar) — that is expected, the plugins aren't fetched yet. Ignore them, run:

:PackerSync

Wait for it to finish, then restart nvim with no file and let mason and nvim-treesitter finish downloading (the [mason-lspconfig.nvim] / [nvim-treesitter] messages). If a Press ENTER prompt appears, press Enter — mason's installs are paused while it is on screen. Errors should be gone.

Every plugin is pinned to an exact commit in config/nvim/lua/theprimeagen/packer.lua, so :PackerSync reproduces identical versions on every machine rather than pulling latest. The LSP servers are pinned the same way in after/plugin/lsp.lua ("lua_ls@3.19.2", …), and Neovim itself in Neovim (pinned).

You do not install Lua. Neovim embeds LuaJIT, so .lua config files run out of the box — there is no apt install lua step. The only Lua-related piece is the language server (lua_ls), which mason installs for you on first launch; it is already listed in ensure_installed in after/plugin/lsp.lua.

Verify:

:checkhealth      " overall — look for treesitter and LSP sections
:Mason            " server install status: lua_ls, ts_ls, eslint, pyright
:PackerStatus     " which plugins are installed

A6. tmux (full, with continuum)

cp -r ./config/tmux ~/.config
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
tmux

Press prefix + I (capital i) to install plugins. Continuum then auto-saves every ~5 minutes to ~/.local/share/tmux/resurrect/ and auto-restores when the tmux server starts.


Path B — Ubuntu (remote server)

Same as Path A except: no font, no continuum.

B1. Prerequisites

sudo apt update && sudo apt install -y zsh git tmux ripgrep curl

Neovim and Node.js do not come from apt or snap: snap's nvim is 0.12.x, the neovim PPAs ship whatever is current, and Ubuntu 22.04's nodejs is v12 — too old for the LSP servers. Install both into ~/.local from the official releases (no sudo): Neovim (pinned) and Node.js on Ubuntu.

No Nerd Font here — glyphs are rendered by your Mac's terminal, not the server. Install the font locally (Path A) and the remote prompt renders fine.

B2. oh-my-zsh, theme, plugin

Identical to A2.

B3. zsh

cp .zshrc ~/
cp .p10k.zsh ~/

Then edit ~/.zshrc and drop the mac-only lines if they bother you — the clearDNS alias and the mapf-visualizer PATH are already guarded, so they are harmless no-ops on Linux.

⚠️ Nested tmux. .zshrc runs exec tmux when $TMUX is unset. TMUX is not forwarded over SSH, so connecting from inside a local tmux session starts a second tmux on the server. If that annoys you, guard the block with [ -z "$SSH_CONNECTION" ] or remove it on servers.

B4. Secrets

See Secrets below. Drop the cargo line if Rust isn't installed there, otherwise every shell errors on startup. Then exec zsh — the same XDG_CONFIG_HOME warning as A4 applies.

B5. Neovim

Identical to A5, except the compiler toolchain comes from apt instead of Xcode:

sudo apt install -y build-essential      # cc + make, needed to build treesitter parsers

Without it :PackerSync completes but every treesitter parser fails to build, and you get no syntax highlighting.

Optional — the word list. cmp-dictionary completes from a plain wordlist. macOS ships /usr/share/dict/words; Ubuntu does not. The config filters the path list to files that exist, so a server without one simply gets no dictionary completions — it will not error. If you do want them:

sudo apt install -y wamerican          # or wbritish

(If you ever see bad argument #1 to 'decode' (string expected, got nil) from cmp_dictionary/dict/trie.lua, it means a configured wordlist path was not readable — that guard in after/plugin/lsp.lua is what prevents it.)

B6. tmux — skip continuum

cp -r ./config/tmux ~/.config
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm

Then comment out these lines in ~/.config/tmux/tmux.conf before starting tmux:

# line 126
set -g @plugin 'tmux-plugins/tmux-continuum'
# lines 136-137
set -g @continuum-restore 'on'
set -g @continuum-save-interval '5'

Leave tmux-resurrect (line 125) in place — prefix + Ctrl-s / prefix + Ctrl-r still work for manual save/restore; you just lose the automatic timer. Servers stay up for weeks, so there is rarely anything to restore.

Start tmux and press prefix + I.

Why the config still matters on a server — even without continuum, this tmux.conf is far from stock:

  • escape-time 10 — the default 500ms makes Esc lag noticeably in nvim
  • default-terminal "xterm-256color" — without it tmux reports screen (8 colors) and zsh-autosuggestions' grey fg=8 degrades to plain white
  • splits inherit the current directory (-c "#{pane_current_path}")
  • C-h/j/k/l pane navigation that passes through to nvim
  • M-1..M-0 direct window switching, base-index 1, renumber-windows on

B7. Clipboard on a server

There is no pbcopy and no X display, so tmux-yank has nothing local to write to. set-clipboard on is already set, so tmux emits OSC 52 and your Mac's terminal picks the text up over the SSH connection. Do not install xclip/xsel on a headless box — tmux-yank prefers them over OSC 52 and copying will silently stop working.


Reference

Requirements

  • Neovim 0.11.7, exactly — see Neovim (pinned). The config uses the native vim.lsp API and pins aerial to its nvim-0.11 branch (aerial's master requires 0.12+).
  • zsh + oh-my-zsh, git, tmux, ripgrep. Avoid tmux 3.4–3.5a built with SIXEL support (Homebrew's is): it mistakes nvim's startup terminal queries for an image and flashes SIXEL IMAGE (1x1). Fixed in 3.6.
  • For LSP: Node.js ≥ 22.22.2 (ts_ls 6.0.2's minimum; eslint and pyright run on it too) and Python (pyright). mason installs the server binaries on first launch, at the versions pinned in after/plugin/lsp.lua.
  • Optional: fzf, neofetch, lolcat — guarded, skipped if absent.

Neovim (pinned)

Neovim is pinned to 0.11.7 the same way the plugins are pinned to commits: every plugin in packer.lua was tested against it. brew, snap and the PPAs all move to the latest release, so install the official build into ~/.local instead. .zshrc puts ~/.local/bin ahead of Homebrew and /usr/bin in $PATH, and init.lua warns at startup if any other version is running.

NVIM_VERSION=0.11.7
NVIM_BUILD=nvim-macos-arm64   # Intel Mac: nvim-macos-x86_64 · Ubuntu: nvim-linux-x86_64 (ARM: nvim-linux-arm64)

curl -fL -o /tmp/$NVIM_BUILD.tar.gz \
  https://github.com/neovim/neovim/releases/download/v$NVIM_VERSION/$NVIM_BUILD.tar.gz
xattr -c /tmp/$NVIM_BUILD.tar.gz 2>/dev/null   # macOS only: stops Gatekeeper blocking it
mkdir -p ~/.local/opt ~/.local/bin
tar xzf /tmp/$NVIM_BUILD.tar.gz -C ~/.local/opt
mv ~/.local/opt/$NVIM_BUILD ~/.local/opt/nvim-$NVIM_VERSION
ln -sfn ~/.local/opt/nvim-$NVIM_VERSION/bin/nvim ~/.local/bin/nvim

hash -r && nvim --version | head -1   # must print: NVIM v0.11.7

If nvim --version shows anything else, an older install is shadowing it — brew uninstall neovim, sudo snap remove nvim or sudo apt remove neovim.

To move to a new version: change NVIM_VERSION above and nvim_pin in config/nvim/lua/theprimeagen/init.lua, re-run the block, then :PackerSync.

Node.js on Ubuntu

Ubuntu's nodejs package is far too old for the LSP servers (22.04 ships v12; ts_ls and pyright exit on start with Client … quit with exit code 1). Install the current LTS from nodejs.org next to Neovim:

NODE_VERSION=24.22.1          # any LTS >= 22.22.2 works
NODE_BUILD=node-v$NODE_VERSION-linux-x64   # ARM: linux-arm64

curl -fL -o /tmp/$NODE_BUILD.tar.xz https://nodejs.org/dist/v$NODE_VERSION/$NODE_BUILD.tar.xz
mkdir -p ~/.local/opt ~/.local/bin
tar xJf /tmp/$NODE_BUILD.tar.xz -C ~/.local/opt
for b in node npm npx; do ln -sfn ~/.local/opt/$NODE_BUILD/bin/$b ~/.local/bin/$b; done

hash -r && node --version

If a server was installed while the old Node was active, reinstall it so mason rebuilds it with the new one: :MasonUninstall typescript-language-server pyright, then restart nvim.

Secrets

.zshenv is gitignored because it carries machine-local secrets. Recreate it by hand on every machine:

cat > ~/.zshenv <<'EOF'
. "$HOME/.cargo/env"

# Secrets live here (not .zshrc) so non-interactive shells — sweeps, cron — get
# them too. zsh sources .zshenv for every shell; .zshrc only for interactive.
export DISCORD_WEBHOOK="https://discord.com/api/webhooks/..."   # fill in
EOF

How the prompt is put together

.p10k.zsh is the prompt content (which segments, which colors); .zshrc only selects the powerlevel10k theme. Copy .zshrc alone and you get powerlevel10k's stock prompt, not this one.

ZSH_THEME must stay above source $ZSH/oh-my-zsh.sh — oh-my-zsh reads it only while loading, so setting it further down silently does nothing and you fall back to the default theme.

Auto-tmux

.zshrc auto-starts tmux on interactive login, guarded so it is skipped when tmux isn't installed or you are already inside a session. It uses exec tmux, so quitting tmux closes the terminal rather than dropping you to a bare shell. See B3 for the nested-tmux caveat over SSH.

Updating an existing machine

Plain cp only adds and overwrites — it never removes files you've since deleted from the repo, which leaves stale config behind (e.g. an old after/plugin/*.lua for a plugin you dropped). To keep a machine in sync, mirror with --delete or symlink instead of copying:

# mirror exactly — removes files that no longer exist in the repo
rsync -a --delete ./config/nvim/ ~/.config/nvim/
rsync -a --delete ./config/tmux/ ~/.config/tmux/

# or symlink, so the live config *is* the repo (deletions take effect immediately)
ln -s "$(pwd)/config/nvim" ~/.config/nvim
ln -s "$(pwd)/config/tmux" ~/.config/tmux

After syncing, bring the pinned versions in line:

  • Plugins — run :PackerSync; it checks out each plugin's pinned commit and removes plugins no longer in packer.lua.
  • LSP servers — mason applies a pin only when the server is missing. If a pin in after/plugin/lsp.lua changed, :MasonUninstall <package> and restart nvim to install the pinned version.
  • Neovim — if startup warns this config is pinned to …, install that version as in Neovim (pinned).