Intro

“A writer is someone for whom writing is more difficult than it is for other people.” — Thomas Mann


 I’ve spent a lot of time building a consistent, unified environment across my machines and VMs. It’s great having the same powerful tools available almost everywhere, but keeping that setup portable between macOS, Windows, and Linux—while juggling different versions of Vim and gVim—takes some planning.

In this post, I’ll share my personal .vimrc along with a few tips, tricks, and lessons learned from years of periodically refining it.

🌐 Why Portability Matters

When your configuration works the same way on every system, you stop wasting time re-learning shortcuts, hunting for missing plugins, or adjusting to quirks between machines. A portable setup means you can drop into a fresh VM, a coworker’s laptop, or a remote server and feel instantly at home—your muscle memory works, your tools are there, and you can focus on the task instead of fighting the environment. For me, it also removes the mental friction of context-switching between macOS, Linux, and Windows, which makes me faster and keeps my workflow consistent.

Highlights of this .vimrc (Why it feels better than stock)

vimrc screenshot

One .vimrc to Rule Them All
Works across macOS, Linux, and Windows terminals with minimal assumptions and no odd dependencies. Drop it on a fresh box, run :PlugInstall, and you’re ready to work.

Readable, Low-Friction UI

  • Lightline statusline: fast, informative, and clean.
  • Line numbers with quick relative toggle: ,n.
  • Cursorline, wildmenu, ruler, and title for better orientation.
  • Dark-friendly colors: set background=dark + stock desert theme.

Better Search and Navigation

  • Smart search (ignorecase + smartcase, incsearch, hlsearch).
  • Split navigation on homerow: Ctrl-h/j/k/l.
  • Indent-based folding (all folds open by default).

Editing Defaults That Don’t Fight You

  • Spaces with 4-wide indent (expandtab, shiftwidth=4, softtabstop=4).
  • Filetype-aware tweaks for Python and shell built in.

Built-in Git and File Tools

  • FZF for instant file jumps: ,f (files), ,g (git files).
  • Fugitive: ,gs (status), ,gd (diff), ,gc (commit), ,gb (blame).
  • Undotree: ,u for undo history.
  • NERDTree available via :NERDTreeToggle.

My .vimrc

" ===============================
" Kevin's Portable .vimrc
" Clean, fast, readable.
" ===============================

let mapleader = ","           " Press Esc, comma then shortcut

" === General Behavior ===
set nocompatible              " Don't use old vi compatibility
set backspace=indent,eol,start " Backspace works over everything
set history=1000              " Command and search history
set hidden                    " Allow switching buffers without saving
set mouse=a                   " Enable mouse support in all modes

" === UI Enhancements ===
set number                    " Show absolute line numbers
set nowrap                    " Don't wrap long lines
set linebreak                 " Break lines at word boundaries
set showcmd                   " Show incomplete command in lower right
set cursorline                " Highlight current line
set ruler                     " Show cursor position in the status line
set wildmenu                  " Tab completion menu for commands
set title                     " Show file title in terminal title bar
set laststatus=2              " always show status line

" === Search Behavior ===
set hlsearch                  " Highlight search results
set incsearch                 " Show match while typing
set ignorecase                " Ignore case in searches...
set smartcase                 " ...unless capital letters used

" === Indentation ===
set expandtab                 " Use spaces instead of tabs
set shiftwidth=4              " Indent by 4 spaces
set tabstop=4                 " A tab character looks like 4 spaces
set softtabstop=4             " Insert 4 spaces when pressing Tab
set autoindent                " Copy indent from current line
set smartindent               " Do smart C-style indenting

" === Filetype-Specific Tweaks ===
filetype plugin indent on     " Enable filetype-specific plugins and indenting
autocmd FileType python setlocal expandtab shiftwidth=4 softtabstop=4
autocmd FileType sh     setlocal expandtab shiftwidth=4 softtabstop=4

" === Folding ===
set foldmethod=indent         " Fold based on indent levels
set foldlevel=99              " Open all folds by default

" === Performance Tweaks ===
set lazyredraw                " Don’t redraw while executing macros
set ttyfast                   " Assume a fast terminal connection
set noswapfile                " Don't use swapfiles
set nobackup                  " Don't keep backup files
set nowritebackup             " Don't backup before overwriting

" === Colors and Syntax ===
syntax on
set background=dark           " Tell colorschemes to use dark background
colorscheme desert            " Pick your favorite — 'desert' is safe and readable

" === Clipboard (if supported) ===
set clipboard=unnamedplus     " Use system clipboard (requires +clipboard)

" === Keybindings and Leader ===
" i am leaving this here as a warning to future generations to never do this
" let mapleader = " "           " Use SPACE as the <leader> key


" --- Smart Save ---
nnoremap <C-s> :w<CR>         " Ctrl+S to save

" --- Command Prompt Shortcut ---
" Use SPACE for command mode — normal mode only
nnoremap <silent> <SPACE> :


" --- Toggle hlsearch ---
nnoremap <leader>h :set hlsearch!<CR>    " Toggle search highlight on/off
nnoremap <leader><CR> :nohlsearch<CR>   " Clear highlight quickly

" --- Toggle relative numbers ---
nnoremap <leader>n :set relativenumber!<CR>

" --- Yank to system clipboard ---
vnoremap <C-c> "+y            " Ctrl+C in visual mode yanks to system clipboard

" --- Better window movement ---
nnoremap <C-h> <C-w>h
nnoremap <C-j> <C-w>j
nnoremap <C-k> <C-w>k
nnoremap <C-l> <C-w>l

" === my shortcuts ===
nnoremap <leader>f :Files<CR>           " FZF file search
nnoremap <leader>g :GFiles<CR>          " FZF Git files
nnoremap <leader>s :w<CR>               " Save file
nnoremap <leader>q :q<CR>               " Quit
" --- Git Integration ---
nnoremap <leader>gs :G<CR>               " ,gs → git status (fugitive)
nnoremap <leader>gc :G commit<CR>        " ,gc → git commit
nnoremap <leader>gd :G diff<CR>          " ,gd → git diff
nnoremap <leader>gb :G blame<CR>         " ,gb → git blame

" --- Undo and Session Tools ---
nnoremap <leader>u :UndotreeToggle<CR>   " ,u → toggle undo tree

" --- Editing Shortcuts ---
nnoremap <leader>w :w<CR>                " ,w → write file
nnoremap <leader>q :q<CR>                " ,q → quit
nnoremap <leader>x :x<CR>                " ,x → save and quit


" === Optional Fun Aliases ===
command WQ wq
command W w
command Q q
command E e

" === vim-plug plugin manager ===
call plug#begin('~/.vim/plugged')
Plug 'tpope/vim-fugitive'
Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
Plug 'junegunn/fzf.vim'
Plug 'preservim/nerdtree'
Plug 'itchyny/lightline.vim'
call plug#end()

I live a little dangerously (swap and backup disabled, etc.). If you want safer options, add this to the top of the .vimrc

" --- Safe persistence (portable)
set undofile
set undodir^=~/.vim/undo

set backup
set writebackup
set backupdir^=~/.vim/backup
set directory^=~/.vim/swap

" Create dirs if missing (once per boot)
if !isdirectory(expand('~/.vim/undo')) | call mkdir(expand('~/.vim/undo'), 'p') | endif
if !isdirectory(expand('~/.vim/backup')) | call mkdir(expand('~/.vim/backup'), 'p') | endif
if !isdirectory(expand('~/.vim/swap')) | call mkdir(expand('~/.vim/swap'), 'p') | endif

Usage notes

On new machines, I can do the following to have an identical setup:

Setting up this.vimrc on a New Machine

## Setting Up My `.vimrc` on a New Machine

# 1. Install Vim and helpers
# Ubuntu/Debian
sudo apt install vim git fzf ripgrep

# macOS (Homebrew)
brew install vim fzf ripgrep

# 2. Install vim-plug (plugin manager)
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
  https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

# 3. Link your vimrc from your dotfiles repo
ln -s ~/codelab/dotfiles/vimrc ~/.vimrc
# Adjust the path above if your dotfiles are elsewhere

# 4. Install plugins from within Vim
# (You can also do this from the shell)
vim +PlugInstall +qall

# 5. Optional: Enable Ctrl-S in terminal
echo 'stty -ixon' >> ~/.bashrc
# Prevents terminal freeze when pressing Ctrl-S in Vim

How to use these settings

Basics

  • Leader key: , — press this, then the shortcut.
  • Save: Ctrl-S or ,w
  • Quit: ,q
  • Save & Quit: ,x
  • Command-line mode: <Space> in normal mode starts :commands.
  • Line numbers: absolute by default; toggle relative → ,n
  • Move between splits: Ctrl-h, Ctrl-j, Ctrl-k, Ctrl-l
  • Folds: indent-based, all open by default (zc close, zo open)
  • Smart search: case-insensitive unless you type a capital.
  • Incremental search: matches appear as you type.
  • Toggle highlight: ,h
  • Clear highlight: ,<CR>

Clipboard

  • Yank to system clipboard: in visual mode, Ctrl-C

File & Project Tools

  • FZF file search: ,f
  • FZF git files: ,g
  • NERDTree: :NERDTreeToggle
  • Buffers: :ls to list, :b# to switch

Git Integration (vim-fugitive)

  • ,gs → git status
  • ,gd → git diff
  • ,gc → git commit
  • ,gb → git blame

Undo Tree

  • ,u → toggle undo history

Tips

  • Save as sudo:
    :w !sudo tee % > /dev/null
  • Search/replace in file:
    :%s/old/new/gc
  • Delete all lines not matching:
    :v/pattern/d

Macros

  • Record: qa → do stuff → q
  • Play: @a
  • Repeat last: @@
  • Run N times: 15@a

A few power moves

  • Save without sudo?
    :w !sudo tee % >/dev/null

  • Insert command output
    :r !date

  • Search & replace across project
    :args **/*.py:argdo %s/old/new/ge | update

  • Filter selection through shell
    :'<,'>!sort -u

  • Visual block insert
    Ctrl-v → Itext → Esc

  • Jump to mark
    mA to set, 'A to go

  • Ripgrep + quickfix
    :grep -R "needle" .:copen

  • Diff two files
    :w | vnew other.txt | diffthis | wincmd p | diffthis

  • Git in-place
    ,gs status · ,gd diff · ,gc commit

  • Undo history tree
    ,u


Combine with my article, Espanso and Friends for real life Street Fighter combos.


Feedback

Got a vim tip or trick? Email me: feedback@adminjitsu.com