jk's blog

Wireguard Pt. 2: Hub and Spoke with iptables

Mon, 11 May 2026 00:00:00 +0000

In my last post I demonstrated how to set up a simple 1:1 Wireguard VPN. In my homelab I have expanded that architecture. I have a Kubernetes cluster with three nodes, and I wanted to be able to ssh into the nodes outside my home network, so I set up a Wireguard interface on each node. I then port forwarded a router port for each node so I could access each node individually. The architecture looked like this:

---
title: Partial mesh
---
flowchart LR
    ED@{shape: tag-rect, label: "External Host"}
    ED --> Gateway
    Gateway -->|Port forward| n1@{ shape: tag-rect, label: "LAN Host 1"}
    Gateway -->|Port forward| n2@{ shape: tag-rect, label: "LAN Host 2"}
    Gateway -->|Port forward| n3@{ shape: tag-rect, label: "LAN Host 3"}
    subgraph LAN
        Gateway
        n1
        n2
        n3
    end

NOTE: For all diagrams in this post, a rectangle with a diagonal notch represents a device with a Wireguard interface.

I have four Wireguard interfaces I’m maintaining in this design – one for each device. Sometime after I set up the network I inherited a new laptop. To add the new laptop to my existing VPN I needed to update a total of four Wireguard config files, which was mildly annoying. When I later went to add an old Raspberry Pi as a fourth node to my cluster, I decided the architecture wasn’t scalable and started looking for a new design for my network.

Hub and spoke networking

Enter hub-and-spoke networking. In this architecture all traffic flows through a central host where access controls, routing rules, etc. can be configured. The previous design didn’t follow the client-server pattern as every LAN host was also part of the VPN, each with its own Wireguard interface. With the new architecture, ingress traffic from a new source can be permitted for the entire LAN by updating a single interface. Here’s how the network looks after the redesign:

---
title: Hub-and-spoke
---
flowchart LR
    ED@{ shape: tag-rect, label: "External
    Host 1"} --> Gateway
    ED2@{ shape: tag-rect, label: "External
    Host 2"} --> Gateway
    Gateway -->|Port forward| n1@{ shape: tag-rect, label: "LAN Host 1
    (Wireguard Server)"}
    n1 -. Forward .-> n2[LAN Host 2]
    n1 -. Forward .-> n3[LAN Host 3]
    subgraph LAN
        Gateway
        n1
        n2
        n3
    end

In this new architecture, Host 1 acts as our server which terminates all our Wireguard traffic and forwards it within the LAN. We can talk to hosts on the LAN that aren’t connected to the VPN. This means extra hosts added to the LAN can be routable without additional configuration. Not only is it easier to make LAN hosts reachable from the VPN this way; it’s also more secure as VPN traffic flowing through a single point is easier to administer.

What makes this possible is the AllowedIPs attribute in the Wireguard config. I mentioned in my last post that for egress traffic, the AllowedIPs indicates the CIDR ranges that get routed to the peer from the enclosing block. The important part is that CIDR range does not have to be part of the VPN’s subnet range. So we can set the AllowedIP range to be the LAN’s range, and when the packet arrives at the Wireguard server it will forward that packet through its LAN interface. We only need to allow forwarding packets on the Wireguard server.

Kernel forwarding

To start forwarding packets between interfaces, the kernel needs to be told to allow it. By default, most systems disable this to prevent inadvertently acting as a router. To enable it persistently, add the following line to /etc/sysctl.conf:

net.ipv4.ip_forward = 1

Without this setting, the kernel will drop any packet destined for a different interface. /etc/sysctl.conf is the configuration file for the sysctl program, which reads and writes kernel parameters at runtime. The config files can also exist in the /etc/sysctl.d/ directory. Run sudo sysctl --system to reload your configuration without having to reboot.

iptables

Now we need to enable packet forwarding in the operating system’s iptables. I won’t go into great depth on iptables as I am no expert on them, but the general iptable hierarchy looks like this:

Tables
Chains
Rules

…where Tables are made up of Chains, and Chains are made up of Rules. The list of available Tables and Chains are preset by the system. Tables are separated by area of concern and support different types of Rules. The available tables are:

filter (default): Table used for filtering packets
nat: Set network address translation rules on packets
mangle: Modify packet headers
raw: Specialized alteration of packets
security: Access control rules on SELinux only

Chains are just the step in the traffic flow that some rule is applied to. Here’s a description of the available Chains and what Tables they can be applied to:

Chain	Step	Relevant iptables
`INPUT`	Just before the packet is given to the local process	`filter` `mangle` `raw`
`OUTPUT`	Just after being produced by the local process	`filter` `mangle` `nat` `raw`
`FORWARD`	Any packets being routed through the host, just after prerouting	`filter` `mangle`
`PREROUTING`	Just as packets arrive on the network interface	`nat` `mangle` `raw`
`POSTROUTING`	Just before packets leave through the network interface	`nat` `mangle`

See this article for a great in-depth explanation of iptables.

Applying iptables rules to our Wireguard server

It’s good to understand iptables broadly, but this is probably too much information. We only need two Rules to make our Wireguard server forward packets properly. Before we do this we should define the IPs of our key interfaces:

Wireguard interfaces (192.168.100.0/24):
- Wireguard Server: 192.168.100.1
- External Host 1: 192.168.100.10
LAN interfaces (192.168.1.0/24):
- Wireguard Server: 192.168.1.1
- LAN Host 2: 192.168.1.2

With those established, here are the iptable Rules we need on our Wireguard server:

In the filter table we need an ACCEPT rule on the FORWARD chain for incoming packets from the Wireguard network through the Wireguard interface

iptables -t filter -A FORWARD -i wg0 -s 192.168.100.0/24 -o eth0 -d 192.168.1.0/24 -j ACCEPT

In the nat table we need a MASQUERADE rule on the POSTROUTING chain to translate the source IP on the forwarded packets from the Laptop’s Wireguard IP to the Wireguard server’s LAN IP

iptables -t nat -A POSTROUTING -s 192.168.100.0/24 -d 192.168.1.0/24 -o eth0 -j MASQUERADE

The forward rule is fairly self-explanatory so we won’t spend any time on it. We need the masquerade rule because if we forward packets from the Wireguard server to a LAN host without it, the hosts won’t know where to respond as they aren’t on the VPN. For the routing path to work, any responses from the non-VPN LAN hosts will have to be routed back through the Wireguard server.

The masquerade rule does exactly what we need. It translates the source IP from the external host to the Wireguard server’s LAN IP on the outgoing requests. The kernel tracks the translation and will reverse it once it receives a response through the same connection. Below are two diagrams to demonstrate the request-response path with and without the rule, and why requests will fail without it:

---
title: Route path without MASQUERADE
---
sequenceDiagram
    box External Host
    participant EC as WG Interface (100.10)
    end
    box Wireguard Server
    participant WS as WG Interface (100.1)
    participant WL as LAN Interface (1.1)
    end
    box LAN Host
    participant N1 as LAN Interface (1.2)
    end
    EC->>WS: Src 100.10
    WS->>WL: Src 100.10 (forward)
    WL->>N1: Src 100.10 (forward)
    N1--xN1: Dest 100.10 (dropped)

---
title: Route path with MASQUERADE
---
sequenceDiagram
    box External Host
    participant EC as WG Interface (100.10)
    end
    box Wireguard Server
    participant WS as WG Interface (100.1)
    participant WL as LAN Interface (1.1)
    end
    box LAN Host
    participant N1 as LAN Interface (1.2)
    end
    EC->>WS: Src 100.10
    WS->>WL: Src 100.10 (forward)
    WL->>N1: Src 1.1 (masq)
    activate WL
    N1-->>WL: Dest 1.1
    deactivate WL
    WL-->>WS: Dest 100.10 (unmasq)
    WS-->>EC: Dest 100.10

And with that, we have a functioning hub-and-spoke Wireguard network.

Wireguard on the router

Eventually I caved and bought a router that supported Wiregaurd natively. No more sshing into my hosts to generate and transfer keys around through the CLI. Instead, the router has a nice UI for generating the key and network IPs. Really, this way makes the most sense as all traffic flows through the gateway anyway, so may as well terminate the Wireguard tunnel at the logical hub. With the new router my architecture looks like this:

---
title: Wireguard server on the gateway
---
flowchart LR
    GW@{ shape: tag-rect, label: "Gateway
    (Wireguard Server)"}
    ED@{ shape: tag-rect, label: "External
    Host 1"} --> GW
    ED2@{ shape: tag-rect, label: "External
    Host 2"} --> GW
    GW -. Forward .-> n1[LAN Host 1]
    GW -. Forward .-> n2[LAN Host 2]
    GW -. Forward .-> n3[LAN Host 3]
    subgraph LAN
        GW
        n1
        n2
        n3
    end

Our most bike wheel looking architecture yet. Mission accomplished.

Wireguard Pt. 1: Introduction and Setup

Wed, 08 Apr 2026 00:00:00 +0000

In the last few months I set up an extremely simple “homelab” so I could have an environment to practice working with various technologies. The lab consists of three old mini Lenovo ThinkCenters connected to a switch. Once these were set up with Ubuntu Server the first thing I wanted was a VPN so I could securely connect to the lab when I was away from my house. The VPN I settled on was Wireguard, and I found the protocol so simple and elegant that I wanted to write a brief intro on the subject. Honestly, this post is a bit of a rip-off from the Wireguard homepage, which is very well written, so check that page out for more information.

What is Wireguard?

Wireguard is a VPN protocol comparable to OpenVPN, but with a emphasis on simplicity. Wireguard has ~4k lines of code, whereas OpenVPN is in the hundreds of thousands. Wireguard has taken off in popularity over the last decade, with managed VPN solutions such as Tailscale built on top of the Wireguard protocol.

How it works

Wireguard runs off a virtual network interface and a config file, sending packets over UDP. It is up to the VPN admin to determine the network’s address space and the IP addresses to designate to each peer in the network. Wireguard is only concerned with sending and receiving encrypted packets over the virtual interface.

Wireguard is based off the concept of Cryptokey Routing. Each peer on the network owns a private and public key pair, where public keys are associated with private network addresses or address ranges. Each interface has an associated config file that contains the interface’s private key, the port it’s listening on, and the IP addresses and public keys of the peers the interface can send traffic to or receive traffic from.

A packet travelling over a Wireguard VPN follows the following process:

Wireguard matches the destination IP to one of the address ranges in its list of peers
Once the destination IP is matched to a peer, the outgoing packet is encrypted with both the peer’s public key and the host’s private key
The encrypted packet is sent over the public network to the peer’s endpoint (public) IP
The destination interface receives the packet, but rejects it if the source private IP is not in the list peer allowed IP ranges
The endpoint IP of the source interface is updated in the destination interface’s peer list if necessary
The packet is decrypted with the private key of the destination interface and public key of the source interface, then consumed by the host machine

I find Wireguard elegant for a couple reasons:

The dual meaning of what an “allowed IP” is. For egress traffic, the allowed IPs acts as a routing table to find the public key to encrypt with, and the destination public endpoint. For ingress traffic, the allowed IPs act as an access control list of source IPs Wireguard can receive traffic from.
As long as the destination’s endpoint IP remains stable, traffic received will automatically update the endpoint IP of the source interface. Only the peer that is generally receiving packets needs to have a stable public IP.

Setting up

Install Wireguard with

sudo apt install wireguard

You’ll need to determine your VPN’s network address. We’ll keep it simple here and use 192.168.99.0/24. We’ll address our own machine as 192.168.99.100 and our secondary machine as 192.168.99.200.

The config file

We’ll start with a skeleton Wireguard config file:

[Interface]
ListenPort = ...
PrivateKey = ...

[Peer]
PublicKey = ...
AllowedIPs = ...
Endpoint = ...

The format of the config file is very simple:

One Interface block for the host.
Many Peer blocks for other peers on the network. In our example we only have one peer.

In the interface block the mandatory entries are:

ListenPort: Port the Wireguard interface listens for traffic on
PrivateKey: The private key for decrypting ingress traffic
Address: The interface’s IP address and the subnet mask

And in the peer block:

PublicKey: The key for encrypting egress traffic to the peer
Endpoint: The public IP address of the peer
AllowedIPs: Means different things for ingress and egress traffic:
- Egress: The range of private IPs that get sent to the peer’s endpoint IP
- Ingress: Acts as an ACL where only traffic from one of the peer allowed IP ranges will be accepted

Generating key pairs

In this example we’ll create two Wireguard interfaces on our machine and test sending traffic between them. Here’s key pair number one:

% wg genkey
EGK2cbXWZ9CitSZiMMASWfJFrsE/Qm/JJMBLFVfohHc=
% echo "EGK2cbXWZ9CitSZiMMASWfJFrsE/Qm/JJMBLFVfohHc=" | wg pubkey
GpxRmzaMJFt7SNythiHaNtP4fKjJ9s9pRRNksQayGgM=

And key pair number two:

% wg genkey
sOK3kcCZ66M5MD1ktyWsekIbdxWTQ32ew1pgQ18ifnE=
% echo "sOK3kcCZ66M5MD1ktyWsekIbdxWTQ32ew1pgQ18ifnE=" | wg pubkey
SikRjPi3wUPoKTT08bC8R4e0fInp/Pdf225IueHqN2w=

We’re going to eventually set up two virtual network interfaces wg1 and wg2. Here’s how the config files for the two interfaces are going to look so far:

# wg1
[Interface]
ListenPort = 51820
PrivateKey = EGK2cbXWZ9CitSZiMMASWfJFrsE/Qm/JJMBLFVfohHc=
Address = 192.168.99.100/24

[Peer]
PublicKey = SikRjPi3wUPoKTT08bC8R4e0fInp/Pdf225IueHqN2w=
AllowedIPs = 192.168.99.200/32
Endpoint = 127.0.0.1:51821

# wg2
[Interface]
ListenPort = 51821
PrivateKey = sOK3kcCZ66M5MD1ktyWsekIbdxWTQ32ew1pgQ18ifnE=
Address = 192.168.99.200/24

[Peer]
PublicKey = GpxRmzaMJFt7SNythiHaNtP4fKjJ9s9pRRNksQayGgM=
AllowedIPs = 192.168.99.100/32
Endpoint = 127.0.0.1:51820

So we’ve set up each interface to have

Its own private key
A unique port to listen for traffic on
Its IP address and network address space
The peer interface’s private IP and public key
The peer’s public endpoint IP to send encrypted traffic to

51820 is the typical port Wireguard listens for traffic on. Since we’re going to be running two interfaces on the same machine, they’ll need to listen on unique ports, so 51821 seemed as good of a port as any other.

Creating the interfaces

Now that the config files are generated, we need interfaces to point them at. I’m only going to run through the exercise for wg1 but we’ll need wg2 as well to test connectivity within the network.

I’m running this on Ubuntu Server 24, so I’m going to use the ip command for setting up these interfaces.

First we’re going to create the virtual network interface:

% ip link add dev wg1 type wireguard

After this we need to assign the wg1 config file to interface we just created. One way would be to save the above configs in two separate files and assign them each to an interface with wg setconf wg1 <wg1-filename.conf>. Another would be to just create the wg1.conf file in /etc/wireguard/wg1.conf.

Now that the interface is configured we can bring it up with

% ip link set up dev wg1

Now let’s confirm the interface is configured correctly. Run sudo wg show wg1 and you should see something like this:

interface: wg1
  public key: GpxRmzaMJFt7SNythiHaNtP4fKjJ9s9pRRNksQayGgM=
  private key: (hidden)
  listening port: 51820

peer: SikRjPi3wUPoKTT08bC8R4e0fInp/Pdf225IueHqN2w=
  endpoint: 127.0.0.1:51821
  allowed ips: 192.168.99.200/32

When you run ip -4 addr show you should also see a wg1 interface similar to this:

wg1: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1420 qdisc noqueue state UNKNOWN group default qlen 1000
    inet 192.168.99.100/24 scope global wg1
       valid_lft forever preferred_lft forever

The UP in <POINTOPOINT,NOARP,UP,LOWER_UP> confirms that the interface is running.

Testing the connection

We’re now good to go. Test the interface and test the connection from 1 to 2 with % ping 192.168.99.200. You should get something like this:

PING 192.168.99.200 (192.168.99.200): 56 data bytes
bytes from 192.168.99.200: icmp_seq=0 ttl=64 time=40.424 ms
bytes from 192.168.99.200: icmp_seq=1 ttl=64 time=394.618 ms
bytes from 192.168.99.200: icmp_seq=2 ttl=64 time=176.697 ms
bytes from 192.168.99.200: icmp_seq=3 ttl=64 time=404.156 ms
--- 192.168.99.200 ping statistics ---
packets transmitted, 4 packets received, 0.0% packet loss

Success! That’s all there is to it. Wireguard is an extremely simple VPN protocol that’s perfect for a homelab.

Replacing tmux splits with shell job control in zsh

Fri, 28 Nov 2025 00:00:00 +0000

The more comfortable I get in tmux and the terminal the more averse I become to having more than two windows, and especially more than two panes in a window. At some point we’ve all been in this situation:

Maybe in the top split you’re running vim, bottom-right has some kind of server process, and bottom-left is an open terminal for running commands. It’s annoying that when the top pane is focused the cursor’s behaviour when navigating down a pane isn’t immediately obvious.

Shell job control

The concept of job control has been a feature of Unix shells for decades. In the same way you can press Ctrl-C in the shell to terminate the current process with SIGINT, Ctrl-Z will suspend the current process by sending a SIGTSTP signal. Try it by running some process – say man ls. By entering Ctrl-Z you’ll exit the open man pager process, but unlike Ctrl-C the process is only suspended. You can bring it back to the foreground by entering fg, or resume it in the background with bg (when that’s relevant).

Try it out yourself by opening man pages on a couple programs (say ls and grep), then typing Ctrl-Z when inside them. If you do that and then run jobs in the terminal, you should get the following output:

[1]  - suspended  man ls
[2]  + suspended  man grep

You can resume any of these with fg %<number>. The + and - stand for the current and previous shell jobs, and you can foreground those with fg %+ and fg %- as well.

ZLE and custom widgets

ZLE stands for Zsh Line Editor. Modern shells come with a line editor component which allows the modification of text on the command line. The bash equivalent to ZLE would be readline. Without a line editor, features in the shell like completions, cursor movement, history search, etc. wouldn’t be available. Text input would go directly to the shell’s prompt as raw text.

ZLE allows line editing with “widgets”. Widgets are just shell functions that take some action on the command line. There are a set of standard widgets (see the Standard Widgets sections in man zshzle), and some come mapped to a set of default keybinds. For example, Ctrl-B is mapped to backward-char moving the cursor back one character. There are a different set of maps when using the shell in the non-default vi mode, but we won’t cover that here. You can view all the current keybinds by running bindkey.

The feature we’ll use offered by ZLE but not included in readline is user-defined widgets. ZLE allows assigning any shell function to a widget with zle -N. We can then bind that widget to a mapping using bindkey <mapping> <widget>.

Job control mappings

Now we have the tools we need to really make switching between suspended processes convenient. We’ll add the following mappings which allow us to view, kill, and switch between jobs easily:

Map	Shell command
`^J^J`	`jobs`
`^J^M`	`fg %+`
`^J^N`	`fg %-`
`^J<num>`	`fg %<num>`
`^J^K<num>`	`kill %<num>`

I like ^J as a prefix because its default is redundant, as ^M does the exact same thing.

To add these, in our .zshrc we need to define the function and widget, then assign the widget to the keybind. For the view jobs widget:

jobs_widget() { echo ""; jobs; zle reset-prompt; }
zle -N jobs_widget
bindkey '^J^J' jobs_widget

We define the function, add it as a widget, and bind the widget to a keymap. echo "" and zle reset-prompt in the function definition are optional and just for display purposes.

All other maps are for foregrounding or killing the job by its number. For the current job we can do:

fg_current_widget() { zle -I; fg %+; }
kill_job_current_widget() { kill %+ && fg %+; }
zle -N fg_current_widget
zle -N kill_job_current_widget
bindkey '^J^M' fg_current_widget
bindkey '^J^K^M' kill_job_current_widget

…or whatever keymaps you’d like. You can repeat for previous job (-) as well.

Note: we run zle -I before calling fg in our foregrounding widget because I found some strange behaviour where ^Z wasn’t recognized if I opened some file with less, suspended it, and then resumed it again. Apparently when using custom widgets the terminal state can become out of sync with the underlying shell state if zsh doesn’t detect it needs a refresh. zle -I essentially just forces a redraw.

Lastly we can define fg and kill commands for job indexes 1-9. Unfortunately I wasn’t aware of a clean way to dynamically define these widget names, so I just went with a few evals in a loop to keep things DRY:

for i in {1..9}; do
    eval "fg_${i}_widget() { zle -I; fg %${i}; }"
    eval "kill_job_${i}_widget() { kill %${i} && fg %${i}; }"
    eval "zle -N fg_${i}_widget"
    eval "zle -N kill_job_${i}_widget"
    eval "bindkey '^J${i}' fg_${i}_widget"
    eval "bindkey '^J^K${i}' kill_job_${i}_widget"
done

Hacky but it does the trick.

Conclusion

Adding these maps has drastically cut down on my usage of splits, and I find it a much smoother workflow. The maps for fg %+ and fg %- are particularly handy. I still love using tmux for all the other features it provides – and sometimes you really do need a second terminal – but it’s nice using native shell features when possible.

Ditching the Vim fuzzy finder plugin part 2: :grep

Wed, 03 Sep 2025 00:00:00 +0000

This post is a continuation of my last post on ditching the Vim fuzzy finder plugin. In that post I covered file name search with :find and :buffers. In this post I will cover file content search with :grep.

With :grep we take a fundamentally different approach because we are not immediately navigating to the top result, but sending all results to the quickfix list. Everything we do in this post will be rooted in the qflist.

If you followed my last post you should have already installed fzf. The second external program you’ll need to follow along here is ripgrep, which is a grep alternative that ignores .gitignored files by default. If wanted a solution with less external dependencies, you could adapt my config to use GNU grep (usually installed by default) and the matchfuzzy() builtin instead of fzf.

:grep in a nutshell

Vim has two flavours of grep: :vimgrep and :grep. :vimgrep is the internal Vim option for grepping, whereas :grep is a command that relies on an external program (in our case rg). The command called in the shell when we call :grep is defined by ‘grepprg’. Let’s set ours like so:

set grepprg=rg\ --vimgrep\ --hidden\ -g\ '!.git/*'

This is actually close to the Neovim default, which uses ripgrep automatically if you have it installed. I just like ignoring gitignored files as a matter of preference.

So to use :grep it’s :grep and any arguments provided are passed to the grepprg under the hood. You could narrow search down to a certain directory with :grep <pattern> mydir/. You could also pass extra flags or options to rg. Anything you want to do.

When you execute :grep, by default a pager of the results are shown, you hit ENTER and the editor jumps to the first match. To ignore the pager output, you can run it with :sil grep. To prevent the default jump, run grep with a bang: :grep!.

:grep mappings

A fundamental aspect of :grep and ripgrep is the ability to match based on a regex pattern. However, I find myself reaching for :grep mostly to search for fixed strings, and usually don’t get too complex with the regex patterns. I usually use it as a quick navigation tool to search for the simplest substring possible to get me to what I’m looking for.

There is one exception to this rule: greedy wildcards. Sometimes I can get the best match possible if I search for two different substrings that exist on the same line. Greedy wildcard match is .* in ripgrep, and with this knowledge we can make some solid :grep mappings:

nnoremap <leader>g :grep ''<left>
nnoremap <leader>G :grep <C-R><C-W><cr>
cnoremap <C-space> .*
"nvim only
cnoremap <A-9> \(
cnoremap <A-0> \)

The <A-9> and <A-0> mappings are for escaping open and close brackets in regex – a common search pattern for me, though the mappings don’t seem to work in Vim. The <leader>G map is for grepping for the word under the cursor – a very useful command.

Fuzzy filtering the quickfix list

Now we look into fuzzy matching our :greps. What the fuzzy finder plugins often do is have a second fuzzy match filter you can apply to your grep results. So you run your live grep, hit some kind of keymap, then type your fuzzy match pattern and the grep results are refiltered and sorted.

Vim does have a built in way to regex filter quickfix lists with :Cfilter, which is something you can check out. It’s a plugin that comes with Vim that you source with :packadd cfilter. The nice part is the command also filters by file path. Read about it at :h cfilter.

But we’re trying to do fuzzy matching here, so let’s make a command similar to :Cfilter and call it :Cfuzzy. We can define the command with some mappings like so:

nnoremap <leader>cf :Cfilter<space> 
nnoremap <leader>cz :Cfuzzy<space> 
nnoremap <leader>co :colder<space> 
nnoremap <leader>cn :cnewer<space> 

command! -nargs=1 Cfuzzy call FuzzyFilterQf(<f-args>)

function! FuzzyFilterQf(...) abort
    call setqflist(matchfuzzy(getqflist(), join(a:000, " "), {'key': 'text'}))
endfunction

The FuzzyFilterQf() function accepts any number of arguments and joins them in a single string, allowing us to use :Cfuzzy without having to escape spaces. You’ll notice matchfuzzy() gets used internally, which is the built-in Vim fuzzy matching function. I also added a map for :Cfilter (because why not) and maps for :colder and :cnewer, because you might want to undo or redo the filtering of your quickfix list.

:grep and fuzzy filter in a single command

I have found it very useful to :grep for a pattern and then fuzzy match it all in one step. I call the command Zgrep:

nnoremap <leader>z :Zgrep<space>
"nvim only
cnoremap <A-space> \<space>

command! -nargs=+ -complete=file_in_path Zgrep call FuzzyFilterGrep(<f-args>)

function! FuzzyFilterGrep(query, path=".") abort
    exe "grep! '" .. a:query .. "' " .. a:path
    let sort_query = substitute(a:query, '\.\*', '', 'g')
    let sort_query = substitute(sort_query, '\\\(.\)', '\1', 'g')
    call FuzzyFilterQf(sort_query)
    cfirst
    copen
endfunction

It’s a little rough around the edges, but the process is:

:grep for some provided pattern (optionally in some subdirectory)
Attempt to “de-regexify” the provided pattern
Fuzzy filter the qflist based on the new pattern

I find this command works best for matching a few short substrings. Say in a python project I want to find a class Event, but there are many other classes like class EventAction, class EventLog, etc. If I do :Zgrep cl.*Ev, I’ll grep for all these class definitions, then match on the most concise one (class Event). I use this workflow regularly and it feels very smooth.

I am sure a lot of improvements could be made here. My attempt to remove regex is very simple, just removing greedy wildcards and backslashes (generally all the regex I use for :grep). The function also takes exactly one or two arguments, so you’ll have to escape any spaces in the pattern (nvim mapping provided for this). If you don’t find yourself grepping within a directory much you could remove the path argument and accept any number with ..., then join them like I did in FuzzyFilterQf(). Whatever works best for you.

Note that on nvim 0.11 the matchfuzzy() results are not as good as the fzf output. However, there have been some recent improvements to matchfuzzy() which are not yet on stable Neovim (as of this writing), but will be in 0.12. I didn’t find the same algorithm issues on Vim 9.1.

Fuzzy matching your entire working directory

Let’s take this a step further. Why not skip the whole :grep process and just fuzzy match on every line in your working directory? The command would be this:

rg --column --hidden -g '!.git/*' . | fzf --filter=<pattern> \
    --delimiter : --nth 4..

…adapted from this GitHub answer from the author of fzf.

There’s actually a good reason this wasn’t my first recommendation: this is a very expensive operation. If you’re searching for too general a pattern or in even a moderate sized directory, this command will be extremely slow.

However, I think this approach is still worth exploring, because it is very convenient when used properly. We’ll just temporarily change our grepprg to have rg pipe into fzf, then run grep normally:

" WARNING: slow!
nnoremap <leader>Z :Fzfgrep<space>

command! -nargs=+ -complete=file_in_path Fzfgrep call FzfGrep(<f-args>)

function! FzfGrep(query, path=".")
    let oldgrepprg = &grepprg
    let &grepprg = "rg --column --hidden -g '!.git/*' . " 
        \.. a:path .. " \\| fzf --filter='$*' --delimiter : --nth 4.."
    exe "grep " .. a:query
    let &grepprg = oldgrepprg
endfunction

This command has the same issue with escaping spaces because of the one or two arguments, but you may want limit this to subdirectories enough that it’s worth it. Again, whatever you want to do with it.

Putting it all together

Here is all the code from part 1 and part 2 of my post, implementing both file name and file content fuzzy matching:

packadd cfilter

set wildmenu
set wildmode=noselect:longest:lastused,full
set grepprg=rg\ --vimgrep\ --hidden\ -g\ '!.git/*'
if executable('fd') && executable('fzf')
    set findfunc=FuzzyFindFunc
endif

nnoremap <leader>f :find<space>
nnoremap <leader>F :vert sf<space>
nnoremap <leader>b :b<space>
nnoremap <leader>d :Findqf<space>
nnoremap <leader>g :grep ''<left>
nnoremap <leader>G :grep <C-R><C-W><cr>
nnoremap <leader>z :Zgrep<space>
nnoremap <leader>Z :Fzfgrep<space>
nnoremap <leader>cf :Cfilter<space> 
nnoremap <leader>cz :Cfuzzy<space> 
nnoremap <leader>co :colder<space> 
nnoremap <leader>cn :cnewer<space> 
cnoremap <C-space> .*
"nvim only
cnoremap <A-9> \(
cnoremap <A-0> \)
cnoremap <A-space> \<space>

command! -nargs=+ -complete=file_in_path Findqf call FdSetQuickfix(<f-args>)
command! -nargs=1 Cfuzzy call FuzzyFilterQf(<f-args>)
command! -nargs=+ -complete=file_in_path Zgrep call FuzzyFilterGrep(<f-args>)
command! -nargs=+ -complete=file_in_path Fzfgrep call FzfGrep(<f-args>)

function! FuzzyFilterGrep(query, path=".") abort
    exe "grep! '" .. a:query .. "' " .. a:path
    let sort_query = substitute(a:query, '\.\*', '', 'g')
    let sort_query = substitute(sort_query, '\\\(.\)', '\1', 'g')
    call FuzzyFilterQf(sort_query)
    cfirst
    copen
endfunction

function! FuzzyFilterQf(...) abort
    call setqflist(matchfuzzy(getqflist(), join(a:000, " "), {'key': 'text'}))
endfunction

function! FzfGrep(query, path=".")
    let oldgrepprg = &grepprg
    let &grepprg = "rg --column --hidden -g '!.git/*' . " 
        \.. a:path .. " \\| fzf --filter='$*' --delimiter : --nth 4.."
    exe "grep " .. a:query
    let &grepprg = oldgrepprg
endfunction

function! FuzzyFindFunc(cmdarg, cmdcomplete)
    return systemlist("fd --hidden . \| fzf --filter='" 
        \.. a:cmdarg .. "'")
endfunction

function! FdSetQuickfix(...) abort
    let fdresults = systemlist("fd -t f --hidden " .. join(a:000, " "))
    if v:shell_error
        echoerr "Fd error: " .. fdresults[0]
        return
    endif
    call setqflist(map(fdresults, {_, val -> 
        \{'filename': val, 'lnum': 1, 'text': val}}))
    copen
endfunction

About 65 lines. Since adopting this approach I have never once reached for a fuzzy finder plugin, and file navigation is totally second nature. I hope your experience is the same!

Ditching the Vim fuzzy finder plugin part 1: :find

Tue, 02 Sep 2025 00:00:00 +0000

if you’re moderately acquainted with (n)vim you will have heard of the group of plugins called “fuzzy finders”. They’re very useful tools for searching for and selecting an entry from an arbitrary list of strings using a fuzzy matching algorithm. They can be used for a wide array of different useful searches, but when I used one most of my searches essentially boiled down to:

Searching for files by name
Searching through files by line contents

I will spend the next two posts giving you options for accomplishing the above two tasks using strictly native Vim features, along with three external terminal programs. In this post I will be covering file name search (1).

Why do this?

Fuzzy finders are very nice plugins, and I won’t pretend my solutions are going to be as pretty. These plugins can also do a lot more than search through file names and contents. I personally didn’t utilize the other functionality much, but if you do you’re likely not going to do away with your plugin.

The glaring thing left out of my native replacement is live feedback of query results on each key press, though I do a good job getting close to that. From a strict speed perspective I doubt there are improvments here either, but usually the difference will be negligible. Maybe I’m not exactly selling my case here, but what I do know is since moving off fzf.vim I never miss having a fuzzy finder.

Here are my main reasons for moving off these plugins:

There is a certain satisfaction you get learning and using native Vim features. What you take from it feels more transferrable because you are learning the actual tool and not some ancillary plugin.
There is less external code to rely on, and your config will feel less like a house of cards. You may have more lines of code in your .vimrc, but you’re removing code that was previously abstracted away from you.
It is more in line with the Unix philosophy of “doing one thing and doing it well”. You allow Vim to stay as a text editor and use other programs to handle other functionality (like search).

If you don’t care about these things then this probably isn’t the post for you.

Tools you’ll need

For file name search you’ll need two external programs:

fd: a simpler alternative to find for searching files
fzf: a command line fuzzy finder

It also wouldn’t hurt to install ripgrep now, but it’s not yet necessary.

I am on nvim 0.11.3, the stable Neovim version as of this writing. I didn’t do a ton of testing but I believe all of this should work on newer Vim versions that include ‘findfunc’. You could avoid using fzf altogether here if you adapted my findfunc to use matchfuzzy() (the built-in Vim fuzzy matching function) instead of piping into fzf. I’ll continue with fzf here because I find I get better matches with it (on nvim 0.11.3 at least).

Let’s get to it!

Searching file names with :find

:find is the command we’ll use to do file name fuzzy finding. If you’re not familiar, :find is similar to :edit, but it searches for files based on the list of directories in your ‘path’ setting (which you can read about at :h 'path').

The new option that makes :find so much more powerful is the ‘findfunc’ option. You can set your findfunc to a funcref, and :find will call that function instead of its default behaviour. The function is used both when invoking :find or getting completion matches for :find. The first argument of the callback is the current :find argument, and the second is a boolean indicating if the call is for getting completion matches.

If we really want to ditch our fuzzy finder, there’s some minimal functionality we want out of :find:

Search the entire cwd, ignoring .gitignored files
Match on the full path, not just the file name
Use fuzzy matching, not exact pattern matching

Amazingly, we can get this all with one simple command in our findfunc:

fd --hidden . | fzf --filter=<pattern>

We pipe all the files in our repo into fzf, then let fzf return the results fuzzy ranked based on our pattern. Now let’s adapt the command to Vim and put it inside our findfunc:

function! FuzzyFindFunc(cmdarg, cmdcomplete)
    return systemlist("fd --hidden . \| fzf --filter='" 
        \.. a:cmdarg .. "'")
endfunction

if executable('fd') && executable('fzf')
    set findfunc=FuzzyFindFunc
endif

Then we’ll add a couple mappings for quick finding:

nnoremap <leader>f :find<space>
nnoremap <leader>F :vert sf<space>

It’s that easy! You’ll notice that we never once had to mess with our ‘path’, which can be a finnicky option to get right. We allow fd to ignore sensical paths itself when searching, as it ignores .gitignored files and directories by default. If you want to add some paths to ignore for :find, you can add an .fdignore file to your working directory.

Disclaimer: The command is going to be quite slow if you’re running it from somewhere with a lot of files like your home directory, especially with the inclusion of hidden files. We’re recursively piping every file and folder from the cwd down into fzf. If you’re typically working out of a large directory, I’d recommend ditching fzf and sending the pattern directly to fd. You lose fuzzy finding but can use regex with fd instead, and the performance boost will be well worth it.

Getting the best :find feedback we can

As mentioned above, We don’t get live feedback with this method like we would with a plugin, but we can do pretty good with ‘wildchar’ command mode completion.

You can read :h findfunc, but the second findfunc arg cmdcomplete is for determining if the call is to show completion options, so we’ve already got that out of the box. What we want here is a good ‘wildmode’ setting.

wildmode is just the completion mode used when you hit your command mode completion key (<tab> by default). :find will be a lot cleaner when you set it like so in your .vimrc:

set wildmenu
set wildmode=noselect:longest,full

The wildmode options work similarly to their counterparts in ‘completeopt’. “noselect” shows the completion options in a popup menu when you trigger a completion, but won’t select the first option like the default “full” setting does. Only on the next trigger will we select the next completion item via the “full” after the comma. wildmode options separated by commas dictate the behaviour for each subsequent completion trigger. Go read :h wildmode for all the details.

We’ll append “longest” to noselect because these are our options for all command mode completion triggers, and it sucks to have to trigger twice when not using :find. It’s a nice compromise because I rarely get a match on the “:longest” bit when using :find because the fuzzy matching returns so many candidates.

If you want to explore true autocomplete options for command mode, check out this similar post on using :find for fuzzy finding files. The author takes it a little further by using wildtrigger() with an autocmd for triggering the completion menu with noselect on every key press. It’s a pretty complex lua setup and I wanted to keep mine a little simpler, but you can look at that if you want to add some interactivity to the :find command.

Send files to the quickfix list

Commonly in fuzzy finder plugins there will be a map to add the results of the search to the quickfix list. We can do that with a function, command and mapping:

function! FdSetQuickfix(...) abort
    let fdresults = systemlist("fd -t f --hidden " .. join(a:000, " "))
    if v:shell_error
        echoerr "Fd error: " .. fdresults[0]
        return
    endif
    call setqflist(map(fdresults, {_, val -> 
        \{'filename': val, 'lnum': 1, 'text': val}}))
    copen
endfunction

command! -nargs=+ -complete=file_in_path Findqf call FdSetQuickfix(<f-args>)

nnoremap <leader>d :Findqf<space>

You can run :Findqf and pass any arguments you want to fd, similarly to how :grep works. This will only match on exact regex matches instead of fuzzy scores.

Bonus: most recently used files via :buffers

While not directly related to :find, I wanted to mention one more powerful navigation tool in the :buffers command. We can emulate another fuzzy finder feature: navigating through most recently used buffers. With our current wildmode setting, triggering a completion for the :buffers command shows the current list of buffers in order of buffer index – not particularly useful. What we’re really looking for is the “lastused” wildmode option. Let’s add it to the wildmode we set earlier:

set wildmode=noselect:longest:lastused,full

As documented in :h wildmode, if we trigger a completion on a buffer name, lastused will sort buffers by last time used. We can add a simple mapping:

nnoremap <leader>b :b<space>

…and now when we tab complete :buffers our top suggestions will be our most recently used files.

Conclusion

Putting it all together, here’s all our :find and :buffers config:

set wildmenu
set wildmode=noselect:longest:lastused,full
if executable('fd') && executable('fzf')
    set findfunc=FuzzyFindFunc
endif

nnoremap <leader>f :find<space>
nnoremap <leader>F :vert sf<space>
nnoremap <leader>b :b<space>
nnoremap <leader>d :Findqf<space>
command! -nargs=+ -complete=file_in_path Findqf call FdSetQuickfix(<f-args>)

function! FuzzyFindFunc(cmdarg, cmdcomplete)
    return systemlist("fd --hidden . \| fzf --filter='" 
        \.. a:cmdarg .. "'")
endfunction

function! FdSetQuickfix(...) abort
    let fdresults = systemlist("fd -t f --hidden " .. join(a:000, " "))
    if v:shell_error
        echoerr "Fd error: " .. fdresults[0]
        return
    endif
    call setqflist(map(fdresults, {_, val -> 
        \{'filename': val, 'lnum': 1, 'text': val}}))
    copen
endfunction

Not bad for a solid replacement of some major fuzzy finder functionality!

That’s all I’ve got for now. This post got long enough that I will break :grep into a part 2 post in the coming days. If I didn’t convince you to ditch fzf.vim or telescope hopefully you learned something at the very least!

File navigation with the Vim arglist

Wed, 28 May 2025 00:00:00 +0000

One of the hardest things to wrap your head around when starting out in Vim is how to navigate files efficiently. A specific situation that can be frustrating is when you’re navigating often between 3 or 4 files. You may navigate away from those files but regularly return to them. If you’re doing something like iterating over a long quickfix list, or following a chain of several function definitions, using the jumplist to navigate back can be tedious. You could search through your buffer list, but if you have lots of open buffers in a code base with many similarly named files this might not be very efficient. Maybe you’ve tried using global marks, but with too many files the cognitive load of recalling which mark letter you want is inconvenient.

There’s one more tool you can try! Let me introduce the Vim argument list.

The argument list: a low level tool

The argument list is a fairly low level, rough around the edges Vim feature. Opening :h arglist the first thing you’ll see is how it’s meant to provide navigation between files when you open multiple on launch. This is one way the arglist can be used, though not the most compelling way. For demo purposes, let’s generate an arglist this way when launching Vim. Run the following command:

vim file1.txt file2.txt file3.txt

Now once vim is open, if you run :arg you should see the following in the command line:

[file1.txt] file2.txt file3.txt

Our first argument list. The filename wrapped in square brackets is the current arglist file. The current arglist file is unrelated to the file you are currently editing, and the selected index will not change as you change files in the normal ways. The index only changes when you move it explicitly with some command like :next, :prev, or :argu, for example. This is a bit unintuitive at first but starts to make sense with more reps.

You can add files to the arglist once you’re in Vim with :arge or :arga. The commands take a count and a name argument with the count representing the arglist index for the new file. You can do things like :$arga % to add the current buffer to the end of the list, or :arga *.txt to add several files at once. :argu used with a count is for switching to the file at the count’th index, or with no count to the current arglist file. :next and :prev will go to the next or previous file, and also take a count. Starting at Neovim 0.11 they also have built in [a and ]a mappings (as well as [A and ]A for :first and :last), taken from the vim-unimpaired plugin.

Now for the enhancements. The arglist commands on their own are not efficient enough to justify using them over a plugin with similar functionality like Harpoon or Marks.nvim, so we need to add some mappings to get a smoother experience.

The first noticeable issue is the lack of feedback when using the arglist. I want to be able to view its current state easily, and when I navigate with :next or :prev I want some visual feedback that shows the state of the arglist after the change. It makes iterating over the arglist feel super snappy, taking less mental overhead than a global mark.

Getting good feedback with the arglist takes some massaging, because everything gets displayed through the command line. We’ll start with a simple mapping for viewing the state of the arglist that demonstrates this below.

nnoremap <F2> <C-L><cmd>args<cr>

Simple enough – the only problem is if there is no current arglist, :args won’t have any effect, but we still want some visual feedback for our command. Redrawing the screen before running :args emulates the behaviour of :args printing nothing when no arglist exists.

We’ll now add the [a, ]a, [A, and ]A vim-unimpaired mappings. Even if you’re running Neovim >= 0.11, we’ll enhance default versions of these like so:

nnoremap [a <cmd>exe v:count1 .. 'N'<bar>args<cr><esc>
nnoremap ]a <cmd>exe v:count1 .. 'n'<bar>args<cr><esc>
nnoremap [A <cmd>first<bar>args<cr><esc>
nnoremap ]A <cmd>last<bar>args<cr><esc>

We’re going to the next or previous arglist file, but then printing the list afterwards. This way when you hit [a or ]a you can see the result of your command and if you need to iterate again. I’ve added <esc> to the end of the command because if the list is long enough to span multiple lines we don’t want the dreaded “Hit ENTER” behvaiour of the pager, so we’ll skip it in those cases.

One annoying thing about the [a and ]a mappings is that they don’t wrap when at the end or beginning of the list. If we want to get really fancy we can create our own :next and :prev commands that do that with a function like so:

nnoremap [a <cmd>call NavArglist(v:count1 * -1)<bar>args<cr><esc>
nnoremap ]a <cmd>call NavArglist(v:count1)<bar>args<cr><esc>

function! NavArglist(count)
    let arglen = argc()
    if arglen == 0
        return
    endif
    let next = fmod(argidx() + a:count, arglen)
    if next < 0
        let next += arglen
    endif
    exe float2nr(next + 1) .. 'argu'
endfunction

In NavArglist We use Vim builtins like argc() to get the length of the arglist and argidx() to get the current arglist index. Then we can use modulo division with the passed count to navigate to the new index after wrapping.

Lastly, we want to be able to jump to an arglist file by index. We can do that with the following command:

nnoremap <expr> ga ":<C-U>" .. (v:count > 0 ? v:count : "") .. 
    \"argu\|args<cr><esc>"

With [count]ga we jump to the arglist file at the count’th index, then print the arglist afterwards. The most useful part of the command is the count is optional, and without one you’ll jump to the current arglist file.

Improving argument list modification

Now we’ll get to modifying the arglist. The behaviour of typing something like :arga otherfile.txt to add a file I’m not currently editing isn’t something I ever find myself reaching for. Most of the utility here is adding the file you’re currently editing that you know you’ll keep returning to. We’ll do that like so:

nnoremap <leader>aa <cmd>$arge %<bar>argded<bar>args<cr>

Again, what makes this so much better than a global mark is we don’t have to come up with a mark letter. It’s always going to be <leader>aa. With global marks usually what I want is to be marking the file, not the cursor position, and that is what the arglist does. When navigating to an arglist file the cursor goes back to its previous position.

To break down our command a bit, :$arge % adds the current file to the end of the arglist and edits it. Since we’re just using the current file, it doesn’t much matter if we use :arge or :arga. The argded part is because arga and arge do not prevent duplicates. argded simply removes any duplicates from the list, so we’re just ensuring that we can run <leader>aa as many times as we want on a buffer without adding multiple entries. Finally we’ll add in args again like with other commands.

Next is the delete and clear commands:

nnoremap <leader>ad <cmd>argd %<bar>args<cr>
nnoremap <leader>ac <cmd>%argd<cr><C-L>

The delete command isn’t much different from the add command. The clear command is similar, but % in this context is just a range shortcut for 1,$, meaning delete all files (see :h range). Again we add <C-L> to show nothing after the list has been cleared.

Other argument list enhancements

Vim’s statusline has a nice integration with the arglist. I personally use the default statusline shown in :h statusline with one small tweak:

set statusline=%<%f\ %h%m%r%=%-13a%-13.(%l,%c%V%)\ %P

All I’ve added from the default is the %-13a which shows the argument list status in relation to the current file. If you’re editing file 1 of 3 in the arglist, (1 of 3) will show in the statusline. If the current arglist index is at 1, but that isn’t the file you’re currently editing, this will show as ((1) of 3).

Lastly, if you’re like me you might use tabs as separate workspaces in Vim. In these cases it’s convenient to work with a separate arglist per tab. For this you can use local argument lists (see :h arglocal). These are created on a per-window basis. If you know you’re always going to want tabs to have their own arglists, you can add the following autocommand (Neovim only):

autocmd vimrc TabNewEntered * argl|%argd

This way, every time you enter a new tab, you’ll immediately create a fresh local arglist for the first window that’s opened. Local arglists are per window, but if you split that window, the same arglist will be used in the split. In this way you can keep using the same list within the tab. argl|%argd makes a local copy of the global argument list, and then immediately clears it, giving you a new empty arglist in your new tab.

Final thoughts

I think the argument list is generally under-utilized, but with the few enhancements I mentioned it becomes a powerful bookmarking system and navigation tool between a small set of files within Vim. I’d encourage anyone to try it before reaching for one of the more popular bookmarking plugins, as it may do everything you need on its own. It’s surprising how often Vim has a native solution for something you’d think could only be solved with a plugin!

Neovim in <50 lines

Fri, 14 Mar 2025 00:00:00 +0000

Neovim configs have a tendency to go off the rails. I think some amount of this has existed for a long time with Vim, but with Neovim it feels particularly exaggerated. At this point the giant bloated configs have become a part of the Neovim culture. To me it seems we’ve strayed pretty far from the minimalist philosophy of Vim once configs start requiring nested file structures and lazy-loaded plugins and whatever else is getting cooked up lately.

One side-effect of using more plugins is with each one you add, you get further abstracted away from using the base tool. When I started out on nvim I was pretty plugin happy, and there were things I would download plugins for that I didn’t even realize you could do natively. There’s something powerful about having command of as much of the base editor as possible. You can take those skills with you to pretty much any machine, and even if you don’t have your perfect config set up you’ll still feel like you know your way around.

I try to be as minimalist as possible without taking it so far that I’m sacrificing productivity. To me there are a few major modern IDE features that I think are huge enhancements to the development experience:

Inline linting
LSP completions & jump to definition
Auto-formatting
Fuzzy searching (both for file names and file contents)

Obviously the list is up for debate, but I feel good about these as a core set of productivity boosters. In this post, I’m going to walk through how you can get each of these with the minimal possible config. I think we can do it in less than 50 lines. I’ll use Python as the language for my example setup, and macOS for my operating system, though with any *nix system it will look very similar besides the fact I’m using brew for installing system packages. Let’s get to it.

Getting a package manager

This is a prerequisite for our setup. Neovim does have a built in packages system that you could explore with :h packages if you wanted to go that route. What I don’t like about this system is the packages you’re using aren’t specified anywhere in your configs. Instead, any plugins end up in your data directory only. This makes package management bit harder with version control, so we’ll go with a 3rd party option.

The simplest package manager I’ve found is paq-nvim. Install it like so from the command line with one command:

$ git clone --depth=1 https://github.com/savq/paq-nvim.git \
    "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/paqs/start/paq-nvim

Then we just need to make sure we have a neovim config folder with

$ mkdir -p ~/.config/nvim

Next, create a file called init.lua in that directory and put the following lines at the top:

require("paq")({
    "savq/paq-nvim"
})

We have now a package manager. If you close and reopen Neovim and you should have a variety of :Paq* commands available to you. All of your future packages will go inside that initial setup call, which should stay at the top of the file. The format for adding packages is <GitHub Org>/<GitHub Repo>. Using :PaqList will show you what packages you have installed, and :PaqSync will both clean packages that have been removed and install new ones.

Linting & LSP features

This one is a lot easier than you’d think with nvim-lspconfig. All nvim-lspconfig does is provide a simplified way to set up the native LSP client for a large set of popular LSPs. The full list of linters and formatters it supports can be found here.

First let’s add nvim-lspconfig to our packages:

require("paq")({
    "savq/paq-nvim",
    "neovim/nvim-lspconfig"
})

We’re going to use pyright here for LSP features and completions, and ruff for linting. We’ll set those up like so:

local lspconfig = require("lspconfig")
local lsps = { "pyright", "ruff" }
for _, lsp in pairs(lsps) do
    local setup = {}
    lspconfig[lsp].setup(setup)
end

All we’re doing here is defining the LSPs we want to look for, and then setting them up for use in Neovim. We loop over our list of LSPs and call setup on each one to initialize it. Each LSP has different configuration options that can be set, found in the LSP’s documentation. To modify our code to allow custom configurations for different LSPs, we’d simply add conditional logic in the for loop that adds entries to the setup table based on the current LSP name we’re iterating over.

To be clear here, nvim-lspconfig does not install the LSPs for you. You need to do that yourself. This part is heavily dependent on what LSPs & linters you’re using, but most I’ve used have been quite simple to install. For pyright & ruff, there are a few ways you can handle this. The simplest way would be to run:

$ brew install pyright ruff

…and the servers should be automatically be added to your $PATH and detected by Neovim. If you have Node installed on your system already I prefer to install pyright with npm install -g pyright. The brew install will install node as a dependency, which can override the default node version that is already set with nvm. For ruff, I prefer to install into the venv of the specific Python project I’m working on, but a global install works too. If you install into a venv, you just have to make sure the virtual environment is activated before you open Neovim so Neovim can find it.

LSP completions

Surprise, this is already done! Neovim has a built in completion type called “omni completion” that the LSP will hook into by default if it’s set up. You can read about it at :h compl-omni. When in insert mode, you can trigger it with <C-X><C-O>. To see the full list of completions available with <C-X>, check out :h ins-completion. The Neovim docs even give you a way you could upgrade this to autocomplete as you type, which you can see at :h compl-autocomplete.

Formatting

For formatting we’ll use a plugin called Conform. Formatting works very similarly to the LSP in that you just need your formatter in your $PATH and Conform will pick it up.

First, of course, add stevearc/conform.nvim to your paq setup. I won’t run you through that one again.

Next we need to setup Conform. We can use the snippet below at the bottom of our init.lua file.

require("conform").setup({
    formatters_by_ft = {
        python = { "ruff_organize_imports", "ruff_format" },
    },
    format_after_save = {},
})

Take a look at all the valid formatting commands here. Luckily, ruff has a built-in formatter, so we don’t need to install any extra packages. You’ll notice two separate ruff commands – one organizes imports and one runs the ruff formatter. We’ve also set up Conform to automatically format on save.

On to the next…

Fuzzy finding

Fuzzy searching is the most efficient way to jump between files in Neovim. Instead of navigating through a traditional file tree (which there is one built in), you’ll find it’s usually faster to search your working directory for the file name instead. The fuzzy finder will live update as you type, and usually within a few keystrokes you’ll get to the file you’re looking for. The plugin we’ll use for this not only allows searching file names, but also allows searches on the contents of files in your project.

We’ll use a plugin called fzf-vim for this one, which is a Vim wrapper of the CLI application fzf. To start, we need to add these two packages to paq: junegunn/fzf and junegunn/fzf.vim, in that order.

Fzf-vim interfaces with fzf in the terminal via Neovim terminal mode. To make this work, we’ll need a few applications installed to our system:

$ brew install fzf # the main fzf app
$ brew install ripgrep # for searching the contents of files
$ brew install bat # for syntax highlighting in fzf

Fzf is a tool you will use enough that it’s worth having a couple keymaps for the main commands. Put the following right underneath your paq setup:

vim.g.mapleader = " "
vim.keymap.set("n", "<leader>f", ":Files!<cr>")
vim.keymap.set("n", "<leader>g", ":RG!<cr>")

In Vim, “leader” is a user defined key that is commonly used as a prefix for custom keymaps. It’s there so we have a way to easily set keymaps without worrying about overwriting the many default ones Vim comes with. We’ve set it to the space bar here, which is a common leader key. Now <space>f will allow us to fuzzy search file names, and <space>g will search file contents!

A few options

That’s all our plugins. There’s just a couple of key options worth changing and then we’re off to the races. Add these right below your paq setup:

vim.opt.tabstop = 4
vim.opt.shiftwidth = 4
vim.opt.number = true
vim.opt.relativenumber = true
vim.opt.smartindent = true

Here we’re doing a few things:

Setting Neovim’s tabs and indents to 4 spaces, overriding the somewhat antiquated default of 8 spaces
Adding relative numbers (very useful for jumps), but still have regular line numbers turned on if relative numbers are switched off
Allow Neovim to intelligently indent newlines based on context

Bringing it all together

You’ve made it to the end. Quit and reopen Neovim, then run PaqInstall and your setup is complete! Let’s take a look at our init.lua file after all this:

require("paq")({
    "savq/paq-nvim",
    "neovim/nvim-lspconfig",
    "stevearc/conform.nvim",
    "junegunn/fzf",
    "junegunn/fzf.vim"
})

vim.opt.tabstop = 4
vim.opt.shiftwidth = 4
vim.opt.relativenumber = true
vim.opt.number = true
vim.opt.smartindent = true

vim.g.mapleader = " "
vim.keymap.set("n", "<leader>f", ":Files!<cr>")
vim.keymap.set("n", "<leader>g", ":RG!<cr>")

local lspconfig = require("lspconfig")
local lsps = { "pyright", "ruff" }
for _, lsp in pairs(lsps) do
    local setup = {}
    lspconfig[lsp].setup(setup)
end

require("conform").setup({
    formatters_by_ft = {
        python = { "ruff_organize_imports", "ruff_format" },
    },
    format_after_save = {},
})

Less than 50 lines, just like we said. About half that actually! That’s pretty good. Don’t forget the system packages we installed! Below is every command we ran in the terminal:

$ git clone --depth=1 https://github.com/savq/paq-nvim.git \
    "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/paqs/start/paq-nvim
$ brew install pyright ruff
$ brew install fzf ripgrep bat

This is not the end

I am under no illusion that this is the perfect config, or that your workflow couldn’t be improved by a few extra plugins. My personal config is ~100 lines where I have some additional keymaps set up, a few of the default vim options changed and a couple more plugins installed. The point here is to show how powerful Neovim can be out of the box. This is a very functional setup that you can easily build upon. It doesn’t require 15 files and 40 plugins to set up a great dev environment – the base editor is pretty damn good.

Happy vimming!

jk's blog

Wireguard Pt. 2: Hub and Spoke with iptables

Hub and spoke networking

Kernel forwarding

iptables

Applying iptables rules to our Wireguard server

Wireguard on the router

Wireguard Pt. 1: Introduction and Setup

What is Wireguard?

How it works

Setting up

The config file

Generating key pairs

Creating the interfaces

Testing the connection

Replacing tmux splits with shell job control in zsh

Shell job control

ZLE and custom widgets

Job control mappings

Conclusion

Ditching the Vim fuzzy finder plugin part 2: :grep

:grep in a nutshell

:grep mappings

Fuzzy filtering the quickfix list

:grep and fuzzy filter in a single command

Fuzzy matching your entire working directory

Putting it all together

Ditching the Vim fuzzy finder plugin part 1: :find

Why do this?

Tools you’ll need

Searching file names with :find

Getting the best :find feedback we can

Send files to the quickfix list

Bonus: most recently used files via :buffers

Conclusion

File navigation with the Vim arglist

The argument list: a low level tool

Improving argument list navigation

Improving argument list modification

Other argument list enhancements

Final thoughts

Neovim in <50 lines

Getting a package manager

Linting & LSP features

LSP completions

Formatting

Fuzzy finding

A few options

Bringing it all together

This is not the end