- Stuff

NVIM: Writing Complex Macros / Transforms in Lua

2026-09-06T00:00:00+00:00

(Neo)Vim's macro system is a very powerful tool for quickly applying a sequence of transformations over and over again. The upcoming native multicursor support in neovim is also shaping up to be an extremely ergonomic and intuitive way of performing large, bulk edits very quickly.

However, in some rare cases, I find myself wanting a more generic way of expressing such text tranforms, with support for conditionals and logic. Something such as:

If a given line contains the substring "XYZ" do one set of transformations, if it contains "ABC" do another set of transformations, and if it contains "123" delete it altogether. </blockquote>

This is especially the case when writing RTL in (System)Verilog, where I often find myself needing to do structured and systematic text transformations.

Fortunately, neovim is configured and scripted in Lua, which makes this rather simple to implement.

This blog post contains a short guide on how to write transforms as lua functions, explains how to register them as bindings or commands, and includes a few real-life examples of such transforms that I have found useful at the end.

Wrapper Functions</h2>

I rely on two simple helper functions in my neovim configuration.

The first, given a Lua text-transform function that both accepts and returns a list(-like table) of lines, returns a function which grabs the current selection, applies the transform function, and replaces the current selection with its output:

-- Wrap a text-transformation function to make it simple to register</span></span>
-- it as a visual mode text-transform mapping.</span></span>
function</span> visual_process_selection_lines</span>(processing_func)</span></span>
  return function</span>()</span></span>
    -- Retrieve selected lines:</span></span>
    local</span> pos1</span> =</span> vim.</span>fn</span>.</span>getpos</span>(</span>"v"</span>)</span></span>
    local</span> pos2</span> =</span> vim.</span>fn</span>.</span>getpos</span>(</span>"."</span>)</span></span>
    local</span> lines</span> =</span> vim.</span>fn</span>.</span>getregion</span>(pos1, pos2, { type</span> =</span> "V" </span>})</span></span>
</span>
    -- Process selected lines using the provided function:</span></span>
    local</span> processed_lines</span> =</span> processing_func</span>(lines)</span></span>
</span>
    -- Determine buffer and (ordered) line range selected for replacement:</span></span>
    local</span> bufn</span> =</span> vim.</span>api</span>.</span>nvim_get_current_buf</span>()</span></span>
    local</span> line_first</span> =</span> math.min</span>(pos1[</span>2</span>], pos2[</span>2</span>])</span></span>
    local</span> line_last</span> =</span> math.max</span>(pos1[</span>2</span>], pos2[</span>2</span>])</span></span>
</span>
    -- Replace selected lines:</span></span>
    vim.</span>api</span>.</span>nvim_buf_set_lines</span>(bufn, line_first</span> -</span> 1</span>, line_last, </span>false</span>, processed_lines)</span></span>
</span>
    -- Exit visual mode:</span></span>
    local</span> keys</span> =</span> vim.</span>api</span>.</span>nvim_replace_termcodes</span>(</span>"<ESC>"</span>, </span>true</span>, </span>false</span>, </span>true</span>)</span></span>
    vim.</span>api</span>.</span>nvim_feedkeys</span>(keys, </span>"m"</span>, </span>false</span>)</span></span>
  end</span></span>
end</span></span></code></pre>
The second, again given a Lua text-transform function that both accepts and
returns a list(-like table) of lines, returns a function that accepts an opts</code>
table as given to a nvim_create_user_command</code> callback, and again grabs the
current selection, applies the transform function, and replaces the current
selection with its output:</p>
-- Wrap a text-transformation function to make it simple to register</span></span>
-- it as a text-transforming user command.</span></span>
function</span> cmd_process_selection_lines</span>(processing_func)</span></span>
  return function</span>(opts)</span></span>
    -- Get the range from the command (line1 and line2 are 1-indexed)</span></span>
    local</span> line_start</span> =</span> opts.</span>line1</span></span>
    local</span> line_end</span> =</span> opts.</span>line2</span></span>
</span>
    -- Retrieve selected lines (nvim_buf_get_lines uses 0-indexed, exclusive end)</span></span>
    local</span> bufn</span> =</span> vim.</span>api</span>.</span>nvim_get_current_buf</span>()</span></span>
    local</span> lines</span> =</span> vim.</span>api</span>.</span>nvim_buf_get_lines</span>(bufn, line_start</span> -</span> 1</span>, line_end, </span>false</span>)</span></span>
</span>
    -- Process selected lines using the provided function</span></span>
    local</span> processed_lines</span> =</span> processing_func</span>(lines)</span></span>
</span>
    -- Replace selected lines (nvim_buf_set_lines uses 0-indexed)</span></span>
    vim.</span>api</span>.</span>nvim_buf_set_lines</span>(bufn, line_start</span> -</span> 1</span>, line_end, </span>false</span>, processed_lines)</span></span>
  end</span></span>
end</span></span></code></pre>Example: Line Numbers</h2>
Using the utility functions above, we can take any Lua function that accepts
and returns a list(-like table) of strings, and easily register it as a
visual-mode mapping and user command to apply it to any text we are editing.
For example, consider the short example function below, which prepends a line-number
to each input line:</p>
local function</span> prepend_line_no</span>(lines)</span></span>
  local</span> result</span> =</span> {}</span></span>
  for</span> idx, line</span> in</span> ipairs</span>(lines) </span>do</span></span>
    table.insert</span>(result, idx</span> ..</span> " | " </span>..</span> line)</span></span>
  end</span></span>
  return</span> result</span></span>
end</span></span></code></pre>
We can register this function as a visual mode mapping and user command
as follows:</p>
vim.</span>keymap</span>.</span>set</span>(</span>"v"</span>, </span>"gQ"</span>, </span>visual_process_selection_lines</span>(prepend_line_no), {</span></span>
  desc</span> =</span> "Prepend line numbers"</span>,</span></span>
  silent</span> =</span> true</span>,</span></span>
  noremap</span> =</span> true</span>,</span></span>
})</span></span>
vim.</span>api</span>.</span>nvim_create_user_command</span>(</span></span>
  "PrependLineNos"</span>,</span></span>
  cmd_process_selection_lines</span>(prepend_line_no),</span></span>
  { range</span> =</span> true</span>, desc</span> =</span> "Prepend line numbers" </span>}</span></span>
)</span></span></code></pre>
Now, by selecting any text in visual mode and pressing gQ</code> or typing :'<,'>PrependLineNos</code>,
we can quickly and conveniently apply our prepend_line_no</code> function:</p>
Before:</p>
This is a sample piece</span></span>
of input text with no</span></span>
particular meaning.</span></span></code></pre>
After:</p>
1 | This is a sample piece</span></span>
2 | of input text with no</span></span>
3 | particular meaning.</span></span></code></pre>Example: Flip (System)Verilog Port Directions</h2>
I most commonly find myself writing and using such text transforms when
writing RTL code in a language like SystemVerilog.</p>
For example, I often find myself having to change the direction of module
port declarations when routing signals through a hierarchy of modules.
This involves inverting the port direction (input</code> <-> output</code>), and adjusting
the port suffix (*_i</code> <-> *_o</code>, *_ni</code> <-> *_no</code>, ...).</p>
The following Lua function describes this transformation:</p>
function</span> sv_flip_input_output</span>(lines)</span></span>
  local</span> result</span> =</span> {}</span></span>
</span>
  for</span> _, line</span> in</span> ipairs</span>(lines) </span>do</span></span>
    local</span> modified_line</span> =</span> line</span></span>
</span>
    -- Check if line contains input or output (ignoring leading whitespace)</span></span>
    local</span> trimmed</span> =</span> line</span>:</span>match</span>(</span>"^%s*(.-)%s*$"</span>)</span></span>
</span>
    if</span> trimmed</span>:</span>match</span>(</span>"^input%s"</span>) </span>then</span></span>
      -- Replace input with output</span></span>
      modified_line</span> =</span> line</span>:</span>gsub</span>(</span>"(%s*)input(%s)"</span>, </span>"%1output%2"</span>)</span></span>
      modified_line</span> =</span> modified_line</span>:</span>gsub</span>(</span>"_i(%s*[,%s])"</span>, </span>"_o%1"</span>)</span></span>
      modified_line</span> =</span> modified_line</span>:</span>gsub</span>(</span>"_i$"</span>, </span>"_o"</span>)</span></span>
      modified_line</span> =</span> modified_line</span>:</span>gsub</span>(</span>"_ni(%s*[,%s])"</span>, </span>"_no%1"</span>)</span></span>
      modified_line</span> =</span> modified_line</span>:</span>gsub</span>(</span>"_ni$"</span>, </span>"_no"</span>)</span></span>
    elseif</span> trimmed</span>:</span>match</span>(</span>"^output%s"</span>) </span>then</span></span>
      -- Replace output with input</span></span>
      modified_line</span> =</span> line</span>:</span>gsub</span>(</span>"(%s*)output(%s)"</span>, </span>"%1input%2"</span>)</span></span>
      modified_line</span> =</span> modified_line</span>:</span>gsub</span>(</span>"_o(%s*[,%s])"</span>, </span>"_i%1"</span>)</span></span>
      modified_line</span> =</span> modified_line</span>:</span>gsub</span>(</span>"_o$"</span>, </span>"_i"</span>)</span></span>
      modified_line</span> =</span> modified_line</span>:</span>gsub</span>(</span>"_no(%s*[,%s])"</span>, </span>"_ni%1"</span>)</span></span>
      modified_line</span> =</span> modified_line</span>:</span>gsub</span>(</span>"_no$"</span>, </span>"_ni"</span>)</span></span>
    end</span></span>
</span>
    table.insert</span>(result, modified_line)</span></span>
  end</span></span>
</span>
  return</span> result</span></span>
end</span></span></code></pre>
Consider the following example input:</p>
input</span> logic clk_i,</span></span>
input</span> logic rst_ni,</span></span>
// === I$ interface ==</span></span>
input</span> logic icache_ready_i,</span></span>
output</span> icache_req_t icache_req_o,</span></span>
input</span> icache_rsp_t icache_rsp_i,</span></span>
// === Instr. Queue interface ==</span></span>
input</span> logic insn_q_ready_i, </span>// A trailing comment!</span></span>
output</span> logic [Param.MAX_INSN_PER_FETCH</span>-</span>1</span>:</span>0</span>] insn_q_entry_valid_o,</span></span></code></pre>
After applying the transform above, we are left with:</p>
output</span> logic clk_o,</span></span>
output</span> logic rst_no,</span></span>
// === I$ interface ==</span></span>
output</span> logic icache_ready_o,</span></span>
input</span> icache_req_t icache_req_i,</span></span>
output</span> icache_rsp_t icache_rsp_o,</span></span>
// === Instr. Queue interface ==</span></span>
output</span> logic insn_q_ready_o, </span>// A trailing comment!</span></span>
input</span> logic [Param.MAX_INSN_PER_FETCH</span>-</span>1</span>:</span>0</span>] insn_q_entry_valid_i,</span></span></code></pre>Example: (System)Verilog Module Instantiation</h2>
As a more complex (but very useful!) example, consider the task
of instantiating a module in SystemVerilog.</p>

For the non-hardware people reading this:</p>
A module declaration roughly corresponds to a function declaration, while
a module instantiation roughly corresponds to a function call.</p>
In SystemVerilog, such modules tend to have many ports (function arguments),
and the syntax for declaring and instantiating (calling) a module is very
different.</p>
</blockquote>
Consider the following simple module declaration:</p>
module</span> gshare</span> #(</span></span>
  parameter</span> fe2_cfg_t Cfg,</span></span>
  parameter</span> type ft_t,</span></span>
  parameter</span> type ftq_entry_t,</span></span>
  parameter</span> type gshare_state_info_t,</span></span>
  parameter</span> type bp_train_info_t,</span></span>
  parameter</span> type ghist_update_t</span></span>
) (</span></span>
  input</span> logic clk_i,</span></span>
  input</span> logic rst_ni,</span></span>
  // Prediction Inputs:</span></span>
  input</span> logic [Cfg.VLEN</span>-</span>1</span>:</span>0</span>] addr_i,</span></span>
  input</span> [Cfg.GSHARE_HIST_LEN</span>-</span>1</span>:</span>0</span>] ghist_i,</span></span>
  // Prediction:</span></span>
  output</span> gshare_state_info_t state_o,</span></span>
  output</span> logic pred_taken_o,</span></span>
  output</span> logic hit_o,</span></span>
  // BP Training info input:</span></span>
  input</span> logic bp_train_info_valid_i,</span></span>
  input</span> bp_train_info_t bp_train_info_i,</span></span>
  input</span> [Cfg.GSHARE_HIST_LEN</span>-</span>1</span>:</span>0</span>] bp_train_ghist_i</span></span>
);</span></span></code></pre>
My module instantiation macro, whose full code you can find
here</a>,
converts such a declaration into an (almost) fully-formed module
instantiation:</p>
module</span> gshare</span> #(</span></span>
  .Cfg( ),</span></span>
  .ft_t( ),</span></span>
  .ftq_entry_t( ),</span></span>
  .gshare_state_info_t( ),</span></span>
  .bp_train_info_t( ),</span></span>
  .ghist_update_t( )</span></span>
) (</span></span>
  .clk_i( ),</span></span>
  .rst_ni( ),</span></span>
  // Prediction Inputs:</span></span>
  .addr_i( ),</span></span>
  .ghist_i( ),</span></span>
  // Prediction:</span></span>
  .state_o( ),</span></span>
  .pred_taken_o( ),</span></span>
  .hit_o( ),</span></span>
  // BP Training info input:</span></span>
  .bp_train_info_valid_i( ),</span></span>
  .bp_train_info_i( ),</span></span>
  .bp_train_ghist_i( )</span></span>
);</span></span></code></pre>
This allows me to quickly copy the module declaration to the place I want to
instantiate it, and do the bulk of the tedious editing with a single mapping.</p>
You can find the full transform function to achieve this
here</a>.</p>
Changes</h2>

2026-09-08</code>:

Simplified + renamed visual_process_selection</code> to visual_process_selection_lines</code>. Thanks justinmk</a>!</li>
</ul>
</li>
</ul>



Progressive encoding and decoding of 'repeated' protobuffer fields.
2026-01-24T00:00:00+00:00

This post assumes a basic familiarity with the user-facing aspects of
Google's open-source protobuffer</a> suite.</p>
In short, protobuffer allows you to define a set of messages which you
would like to exchange using a simple DSL in a .proto</code> file.
Using this description, the protoc</code> compiler (or a number of alternative
implementations) can generate encoders and decoders for these messages
in a large number of different programming languages (see
here</a> and
here</a>),
all of which share a common binary message ("wire") format.</p>
If you are curious, have a look at protobuf.dev</a> for
documentation and tutorials.</p>
</blockquote>
Motivation: Interfacing with Perfetto</h2>
I have found Google's Perfetto</em></a> trace viewer to be a really
useful tool to visualize arbitrary time-based traces by converting them
into the protobuffer-based format that Perfetto uses.
This is how both Tonbandgerät</a> and
CircumSpect</a> work.</p>
In particular, Perfetto traces are a very long sequence of individual TracePacket</code>
messages, which describe the tracks and the events on them.
What follows below is a greatly simplified version of this TracePacket</code>
message. The full definition can be found in the Perfetto source code
here</a>.</p>
message</span> TracePacket</span> {</span></span>
  optional uint64</span> timestamp</span> =</span> 8</span>;</span></span>
  oneof</span> data {</span></span>
    // Different types of trace packet contents</span></span>
    // ...</span></span>
    TrackEvent</span> track_event</span> =</span> 11</span>;</span></span>
    // ...</span></span>
    TrackDescriptor</span> track_descriptor</span> =</span> 60</span>;</span></span>
    // ...</span></span>
  }</span></span>
}</span></span></code></pre>The Challenge: Sequential encoding and decoding</h2>
Especially with CircumSpect, the traces I am generating quickly reach into the
millions of TracePacket</code> messages, and upwards of a gigabyte in size.
This becomes problematic because of the fact that to bundle all these messages
into a single file, Perfetto uses a parent Trace</code> message, which contains all
TracePacket</code>s as a repeated field - the protobuffer equivalent of an array:</p>
message</span> Trace</span> {</span></span>
  repeated TracePacket</span> packet</span> =</span> 1</span>;</span></span>
}</span></span></code></pre>
Unlike in zero-copy frameworks such as Cap'n Proto</a>,
protobuffer's serialised format does not double as an in-memory representation.
Therefore, all serialisation and deserialisation operations move and convert
data between a binary buffer containing the wire representation and an
in-memory data structure with which the program interacts.</p>
In short, this means that to serialise a large Trace</code>, the full trace needs
to be in an in-memory representation.
This struct can then be serialised to the binary wire format by the protobuffer
library.
For reference, this looks roughly like the following:</p>
// Pseudo-rust :)</span></span>
pub struct</span> Trace</span> {</span></span>
    packet</span>:</span> Vec</span><</span>TracePacket</span>>,</span></span>
}</span></span>
</span>
pub fn</span> collect_trace</span>(</span>..</span>) {</span></span>
    let mut</span> trace</span> =</span> Trace</span>::</span>new</span>();</span></span>
</span>
    while</span> not_finished</span>() {</span></span>
        let</span> pkt</span>:</span> TracePacket</span> =</span> collect_trace_packet</span>();</span></span>
        trace</span>.</span>packet</span>.</span>push</span>(pkt);</span></span>
    }</span></span>
</span>
    trace</span>.</span>serialise_to_file</span>(</span>"trace.pftrace"</span>);</span></span>
}</span></span></code></pre>
For a large stream of TracePacket</code>s reaching into the gigabytes, this requires
an incredible amount of memory, or is outright impossible.
Rather, it would be much better if TracePacket</code>s could be written to disk
continuously as they are generated.</p>
Because CircumSpect can post-process traces after they are recorded, I also run
into this problem in the opposite direction:
Instead of having to load a whole trace into memory by deserialising a complete
file into a Trace</code> struct, I would much prefer to be able to read individual
packets, process them, and write them back out to disk.</p>
This is not directly supported by most protobuffer libraries.</p>
Protobuffer wire format</h2>
To understand how difficult this would be to achieve, we have to have a look at
how a message containing a single repeated message field is serialised.
Fortunately, the protobuf wire format for a simple message like Trace</code> is
not all that complicated!</p>
What follows below is an overview of the aspects of protobuffer encoding that
are relevant for achieving this "streaming" encoding and decoding of a Trace</code>
message.
If you want more detailed information, have a look at the
official documentation</a>.</p>
VARINTs</h3>
At the heart of protobuffer encoding sit variable-length ("varlen") encoded
64-bit integers, referred to as varints</em>.</p>
This is an optimization that builds on the observation that in many applications,
while it is beneficial to support full 32- or 64-bit numbers, most of the time only
small numbers are used.
For example, in protobuffer messages, tags all the way up to

 $2^{29} - 1<&#x2F;script> are supported, while the majority of messages have fewer than 100 fields. If protobuffer were to use a fixed 32-bit field for encoding all tags, most messages would contain a large number of redundant zeros.<&#x2F;p> <p>Instead, varints enable us to encode an unsigned number <script type="math&#x2F;tex">N<&#x2F;script> using <script type="math&#x2F;tex">\max{\left\lparen \left\lceil \frac{\log_2(N)}{7} \right\rceil, 1 \right\rparen}<&#x2F;script> bytes. This system trades a shorter average message length for a longer worst-case message size, assuming a relatively high frequency of small values. For example, any value less than or equal to 127 can be encoded in a single byte, while the value <script type="math&#x2F;tex">2^{32}-1<&#x2F;script> requires 5 bytes instead of the usual 4.<&#x2F;p> <p>This is achieved by first splitting the value into 7-bit septets which are each encoded, starting with the least significant septet, as an 8-bit value consisting of the septet in the lower bits, and a control bit in the most significant bit position. This control bit is set to <code>1<&#x2F;code> if there are more non-zero bits to follow, or <code>0<&#x2F;code> if this is the last septet with non-zero bits and all following bits should be assumed to be zero.<&#x2F;p> <p>For example, consider the 32-bit value <code>0x5<&#x2F;code>. With the scheme above, it is encoded as a single byte:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span> +---&gt; First 7 bits<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> ___|___<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>00000101<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>|<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>+--&gt; No more bits to follow.<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>The value <code>0xFF<&#x2F;code> requires more than seven bits and therefore is split into two bytes:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span> +---&gt; First 7 bits +---&gt; Next 7 bits<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> ___|___ ___|___<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>11111111 00000001<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>| |<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>+--&gt; More bits to follow. +--&gt; No more bits to follow.<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre><h3 id="basic-message-structure">Basic message structure<&#x2F;h3> <p>A protobuffer message is serialised as a simple sequence of key-value pairs, with the key being used to identify both which field in the message is to follow, and which encoding scheme it uses.<&#x2F;p> <p>A field is identified using the "field number" which is specified in the message description for every field, while the following encoding schemes are supported:<&#x2F;p> <table><thead><tr><th>ID<&#x2F;th><th>Name<&#x2F;th><th>Used for<&#x2F;th><&#x2F;tr><&#x2F;thead><tbody> <tr><td>0<&#x2F;td><td><code>VARINT<&#x2F;code><&#x2F;td><td><code>int32<&#x2F;code>, <code>int64<&#x2F;code>, <code>uint32<&#x2F;code>, <code>uint64<&#x2F;code>, <code>sint32<&#x2F;code>, <code>sint64<&#x2F;code>, <code>bool<&#x2F;code>, <code>enum<&#x2F;code><&#x2F;td><&#x2F;tr> <tr><td>1<&#x2F;td><td><code>I64<&#x2F;code><&#x2F;td><td><code>fixed64<&#x2F;code>, <code>sfixed64<&#x2F;code>, <code>double<&#x2F;code><&#x2F;td><&#x2F;tr> <tr><td>2<&#x2F;td><td><code>LEN<&#x2F;code><&#x2F;td><td><code>string<&#x2F;code>, <code>bytes<&#x2F;code>, embedded messages, packed repeated fields<&#x2F;td><&#x2F;tr> <tr><td>5<&#x2F;td><td><code>I32<&#x2F;code><&#x2F;td><td><code>fixed32<&#x2F;code>, <code>sfixed32<&#x2F;code>, <code>float<&#x2F;code><&#x2F;td><&#x2F;tr> <&#x2F;tbody><&#x2F;table> <p><small>Table taken from the official protobuffer docs: <a rel="external" href="https:&#x2F;&#x2F;protobuf.dev&#x2F;programming-guides&#x2F;encoding&#x2F;#cheat-sheet">protobuf.dev&#x2F;programming-guides&#x2F;encoding<&#x2F;a><&#x2F;small><&#x2F;p> <p>These two values are combined into a single 32-bit value, with the lower 3 bits containing the encoding scheme, and all other bits containing the field number:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="c"><span class="giallo-l"><span>(field_number <&#x2F;span><span style="color: #D73A49;">&lt;&lt;<&#x2F;span><span style="color: #005CC5;"> 3<&#x2F;span><span>)<&#x2F;span><span style="color: #D73A49;"> |<&#x2F;span><span> encoding_id<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>This 32-bit key is then encoded using the varlen scheme discussed above, and immediately followed by the encoded field value.<&#x2F;p> <p>For example, consider a message with the following structure:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="proto"><span class="giallo-l"><span style="color: #D73A49;">message<&#x2F;span><span style="color: #6F42C1;"> Msg<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> uint64<&#x2F;span><span> data<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 1<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Assume we want to encode an instance of <code>Msg<&#x2F;code> with a value of <code>42<&#x2F;code> for the <code>data<&#x2F;code> field:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="json"><span class="giallo-l"><span>{<&#x2F;span><span style="color: #005CC5;"> &quot;data&quot;<&#x2F;span><span>:<&#x2F;span><span style="color: #005CC5;"> 42<&#x2F;span><span> }<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Serialised, it looks as follows:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span>0x08 0x2a<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>The data field has a field number of <code>1<&#x2F;code> and its <code>uint64<&#x2F;code> data type, as is listed in the table above, is encoded using varint encoding which has an encoding id of <code>0<&#x2F;code>. Therefore, the key value is <code>key = (1 &lt;&lt; 3) | 0 = 0x08<&#x2F;code>, which is varlen-encoded as <code>0x08<&#x2F;code>, since it is less than <code>128<&#x2F;code>. The value of <code>42<&#x2F;code> (<code>0x2a<&#x2F;code> in hex) is also directly encoded as <code>0x2a<&#x2F;code> using the varlen scheme, as it too is less than <code>128<&#x2F;code>.<&#x2F;p> <h3 id="nested-messages">Nested messages<&#x2F;h3> <p>Now consider a new message type <code>Parent<&#x2F;code>, which contains a single <code>Msg<&#x2F;code> field with a field number of <code>1<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="proto"><span class="giallo-l"><span style="color: #D73A49;">message<&#x2F;span><span style="color: #6F42C1;"> Msg<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> uint64<&#x2F;span><span> data<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 1<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">message<&#x2F;span><span style="color: #6F42C1;"> Parent<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> Msg<&#x2F;span><span> child<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 1<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>In protobufs, such "embedded" messages are encoded using the <code>LEN<&#x2F;code> scheme listed in the table above, which has an ID of <code>2<&#x2F;code>. Quite simply, after the key value, the length of the encoded child message in bytes is first serialised as a varlen-encoded value, followed by the normal encoding of the child message.<&#x2F;p> <p>For example, consider an instance of <code>Parent<&#x2F;code>, which contains a <code>Msg<&#x2F;code> instance with <code>data = 42<&#x2F;code> as above in its <code>child<&#x2F;code> field:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="json"><span class="giallo-l"><span>{<&#x2F;span><span style="color: #005CC5;"> &quot;child&quot;<&#x2F;span><span>: {<&#x2F;span><span style="color: #005CC5;"> &quot;data&quot;<&#x2F;span><span>:<&#x2F;span><span style="color: #005CC5;"> 42<&#x2F;span><span> } }<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>From above, we know that such a <code>Msg<&#x2F;code> is encoded as <code>0x08 0x2a<&#x2F;code>, which is of length 2, giving us the following encoding for <code>Parent<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span>KEY LEN CHILD.....<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>0x0A 0x02 0x08 0x2a<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>The field <code>child<&#x2F;code> has a field number of 1 and a <code>LEN<&#x2F;code> encoding scheme, which is of ID <code>2<&#x2F;code>, giving us a key value of <code>key = (1 &lt;&lt; 3) | 2 = 0x0A<&#x2F;code>. As both the key value and length are again less than <code>128<&#x2F;code>, their varlen representation is equal to their one-byte value.<&#x2F;p> <h3 id="repeated-fields">Repeated Fields<&#x2F;h3> <p>Finally, let&#x27;s have a look at how repeated fields - the protobuffer equivalent of arrays - are encoded.<&#x2F;p> <blockquote class="markdown-alert-caution"> <p>Note that there are two encoding schemes for repeated fields, which are used based on the type of the field that is being repeated. I will not discuss the "packed" scheme, which is used for simple scalar values and also uses a <code>LEN<&#x2F;code>-style encoding, in this post. In older versions of protobuffer, this "packed" scheme was opt-in, but in more modern versions it is the default for simple repeated scalars!<&#x2F;p> <&#x2F;blockquote> <p>Consider the following set of definitions, where the <code>MultiParent<&#x2F;code> message can contain multiple <code>Msg<&#x2F;code> children:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="proto"><span class="giallo-l"><span style="color: #D73A49;">message<&#x2F;span><span style="color: #6F42C1;"> Msg<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> uint64<&#x2F;span><span> data<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 1<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">message<&#x2F;span><span style="color: #6F42C1;"> MultiParent<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> repeated Msg<&#x2F;span><span> children<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 1<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Let&#x27;s have a look at how a <code>MultiParent<&#x2F;code> containing two <code>data = 42<&#x2F;code> children would be encoded:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="json"><span class="giallo-l"><span>{<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #005CC5;"> &quot;children&quot;<&#x2F;span><span>: [<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> {<&#x2F;span><span style="color: #005CC5;"> &quot;data&quot;<&#x2F;span><span>:<&#x2F;span><span style="color: #005CC5;"> 42<&#x2F;span><span> },<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> {<&#x2F;span><span style="color: #005CC5;"> &quot;data&quot;<&#x2F;span><span>:<&#x2F;span><span style="color: #005CC5;"> 42<&#x2F;span><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> ]<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Quite simply, for repeated embedded messages, protobuffer repeats another key-value pair with the same field number. We already know that a single embedded <code>Msg<&#x2F;code> with <code>data = 42<&#x2F;code> is encoded as <code>0x0A 0x02 0x08 0x2A<&#x2F;code>, so the <code>MultiParent<&#x2F;code> above is encoded as:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span>KEY LEN CHILD..... KEY LEN CHILD.....<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>0x0A 0x02 0x08 0x2a 0x0A 0x02 0x08 0x2a<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>|- 1st Child --------| |- 2nd Child --------|<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <blockquote class="markdown-alert-tip"> <p>This is as deep as we will go into protobuffer encoding in this post. If you want to go deeper, have a look at the <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;protocolbuffers&#x2F;protoscope&#x2F;tree&#x2F;main"><code>protoscope<&#x2F;code><&#x2F;a> tool and textual representation, which is a very useful higher-level representation of raw, binary, key-value protobuffer messages.<&#x2F;p> <&#x2F;blockquote> <h2 id="putting-it-together">Putting it together<&#x2F;h2> <p>Armed with this basic understanding of the protobuffer wire format, and a <code>protoc<&#x2F;code>-generated (or equivalent) encoder and decoder of the inner <code>TracePacket<&#x2F;code> message, we can now encode and decode a large <code>Trace<&#x2F;code> one <code>TracePacket<&#x2F;code> at a time by doing a bit of manual legwork.<&#x2F;p> <p>Notably, the <code>Trace<&#x2F;code> message with which we started this post is incredibly similar to the <code>MultiParent<&#x2F;code> example above: A message with a single, repeated, embedded message field with field number <code>1<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="proto"><span class="giallo-l"><span style="color: #D73A49;">message<&#x2F;span><span style="color: #6F42C1;"> Trace<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> repeated TracePacket<&#x2F;span><span> packet<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 1<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>This means that a Perfetto trace is simply a sequence of the following for each <code>TracePacket<&#x2F;code>:<&#x2F;p> <ul> <li>The byte <code>0x0A<&#x2F;code>, which is the varlen-encoded form of the key for a field tag number 1 encoded with the <code>LEN<&#x2F;code> scheme: <code>(1 &lt;&lt; 3) | 2 = 0x0A<&#x2F;code>.<&#x2F;li> <li>The length of the serialized <code>TracePacket<&#x2F;code> in bytes, in varlen-encoded form.<&#x2F;li> <li>The serialized <code>TracePacket<&#x2F;code>.<&#x2F;li> <&#x2F;ul> <h3 id="progressive-serialisation-appending">Progressive Serialisation&#x2F;Appending<&#x2F;h3> <p>This makes progressive serialisation of a <code>Trace<&#x2F;code> quite easy to do, because we can use the <code>protoc<&#x2F;code> generated encoding routine for an individual <code>TracePacket<&#x2F;code>, and concatenate them together into a correctly formatted trace by prepending each trace packet with a <code>0x0A<&#x2F;code> and the length of the <code>TracePacket<&#x2F;code> in bytes, as a varlen-encoded value.<&#x2F;p> <p>For example, in Rust using the <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;tokio-rs&#x2F;prost"><code>prost<&#x2F;code><&#x2F;a> protobuffer library, this would look roughly as follows:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="rust"><span class="giallo-l"><span style="color: #6A737D;">&#x2F;&#x2F;&#x2F; Encode a u64 as a protobuffer-style varint, appended into the provided buffer.<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">pub fn<&#x2F;span><span style="color: #6F42C1;"> encode_varint<&#x2F;span><span>(<&#x2F;span><span style="color: #D73A49;">mut<&#x2F;span><span> v<&#x2F;span><span style="color: #D73A49;">:<&#x2F;span><span style="color: #6F42C1;"> u64<&#x2F;span><span>, buf<&#x2F;span><span style="color: #D73A49;">: &amp;mut<&#x2F;span><span style="color: #6F42C1;"> Vec<&#x2F;span><span>&lt;<&#x2F;span><span style="color: #6F42C1;">u8<&#x2F;span><span>&gt;) {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> loop<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> septet<&#x2F;span><span style="color: #D73A49;">:<&#x2F;span><span style="color: #6F42C1;"> u8<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> (v<&#x2F;span><span style="color: #D73A49;"> &amp;<&#x2F;span><span style="color: #005CC5;"> 0x7F<&#x2F;span><span>)<&#x2F;span><span style="color: #D73A49;"> as<&#x2F;span><span style="color: #6F42C1;"> u8<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> v<&#x2F;span><span style="color: #D73A49;"> &gt;&gt;=<&#x2F;span><span style="color: #005CC5;"> 7<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> ctrl_bit<&#x2F;span><span style="color: #D73A49;"> = if<&#x2F;span><span> v<&#x2F;span><span style="color: #D73A49;"> ==<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><span> {<&#x2F;span><span style="color: #005CC5;"> 0_<&#x2F;span><span style="color: #6F42C1;">u8<&#x2F;span><span> }<&#x2F;span><span style="color: #D73A49;"> else<&#x2F;span><span> {<&#x2F;span><span style="color: #005CC5;"> 0x80_<&#x2F;span><span style="color: #6F42C1;">u8<&#x2F;span><span> };<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> buf<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">push<&#x2F;span><span>(septet<&#x2F;span><span style="color: #D73A49;"> |<&#x2F;span><span> ctrl_bit);<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if<&#x2F;span><span> v<&#x2F;span><span style="color: #D73A49;"> ==<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&#x2F;&#x2F;&#x2F; Append a TracePacket to the provided buffer, which contains an already encoded Trace message,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&#x2F;&#x2F;&#x2F; or is empty.<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">pub fn<&#x2F;span><span style="color: #6F42C1;"> append_trace_packet<&#x2F;span><span>(pckg<&#x2F;span><span style="color: #D73A49;">: &amp;<&#x2F;span><span style="color: #6F42C1;">TracePacket<&#x2F;span><span>, buf<&#x2F;span><span style="color: #D73A49;">: &amp;mut<&#x2F;span><span style="color: #6F42C1;"> Vec<&#x2F;span><span>&lt;<&#x2F;span><span style="color: #6F42C1;">u8<&#x2F;span><span>&gt;)<&#x2F;span><span style="color: #D73A49;"> -&gt;<&#x2F;span><span style="color: #6F42C1;"> anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">Result<&#x2F;span><span>&lt;()&gt; {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;"> &#x2F;&#x2F; Key: field 1, LEN encoding = (1 &lt;&lt; 3) | 2<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6F42C1;"> encode_varint<&#x2F;span><span>(<&#x2F;span><span style="color: #005CC5;">0x0A<&#x2F;span><span>, buf);<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;"> &#x2F;&#x2F; Length:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6F42C1;"> encode_varint<&#x2F;span><span>(pckg<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">encoded_len<&#x2F;span><span>()<&#x2F;span><span style="color: #D73A49;"> as<&#x2F;span><span style="color: #6F42C1;"> u64<&#x2F;span><span>, buf);<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;"> &#x2F;&#x2F; Embedded Message:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> pckg<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">encode<&#x2F;span><span>(buf)<&#x2F;span><span style="color: #D73A49;">?<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6F42C1;"> Ok<&#x2F;span><span>(())<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <blockquote class="markdown-alert-tip"> <p>The <code>prost<&#x2F;code> library provides builtin functions for the varlen-encoding of the message length, which is implemented manually above for illustration.<&#x2F;p> <p>See <a rel="external" href="https:&#x2F;&#x2F;docs.rs&#x2F;prost&#x2F;latest&#x2F;prost&#x2F;trait.Message.html#method.encode_length_delimited"><code>Message::encode_length_delimited()<&#x2F;code><&#x2F;a>, and <a rel="external" href="https:&#x2F;&#x2F;docs.rs&#x2F;prost&#x2F;latest&#x2F;prost&#x2F;fn.encode_length_delimiter.html"><code>encode_length_delimiter()<&#x2F;code><&#x2F;a>. For decoding, have a look at <a rel="external" href="https:&#x2F;&#x2F;docs.rs&#x2F;prost&#x2F;latest&#x2F;prost&#x2F;trait.Message.html#method.decode_length_delimited"><code>Message::decode_length_delimited()<&#x2F;code><&#x2F;a>, and <a rel="external" href="https:&#x2F;&#x2F;docs.rs&#x2F;prost&#x2F;latest&#x2F;prost&#x2F;fn.decode_length_delimiter.html"><code>decode_length_delimiter()<&#x2F;code><&#x2F;a>.<&#x2F;p> <&#x2F;blockquote> <h3 id="progressive-deserialisation">Progressive Deserialisation<&#x2F;h3> <p>For decoding, we similarly skip the <code>0x0A<&#x2F;code> byte, decode the varlen-encoded length field, and then pass that number of bytes to the protobuffer-generated <code>TracePacket<&#x2F;code> decoder.<&#x2F;p> <blockquote class="markdown-alert-caution"> <p>Parsing the length of the embedded message to determine which range of bytes makes up one <code>TracePacket<&#x2F;code> is absolutely necessary. Protobuffer&#x27;s wire format is not self-delimiting, so if you try to decode a nested message without trimming away the bytes of successive messages, decoding will produce garbage data.<&#x2F;p> <p>You also cannot simply search for all <code>0x0A<&#x2F;code> bytes and assume that they delimit individual <code>TracePacket<&#x2F;code> messages: Encoded nested messages can contain arbitrary bytes, including <code>0x0A<&#x2F;code>.<&#x2F;p> <&#x2F;blockquote> <p>In Rust this would look roughly as follows:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="rust"><span class="giallo-l"><span style="color: #6A737D;">&#x2F;&#x2F;&#x2F; Attempt to &quot;consume&quot; the first byte from the buffer and advance the pointer.<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">pub fn<&#x2F;span><span style="color: #6F42C1;"> consume_byte<&#x2F;span><span>(buf<&#x2F;span><span style="color: #D73A49;">: &amp;mut &amp;<&#x2F;span><span>[<&#x2F;span><span style="color: #6F42C1;">u8<&#x2F;span><span>])<&#x2F;span><span style="color: #D73A49;"> -&gt;<&#x2F;span><span style="color: #6F42C1;"> Option<&#x2F;span><span>&lt;<&#x2F;span><span style="color: #6F42C1;">u8<&#x2F;span><span>&gt; {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if<&#x2F;span><span> buf<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">is_empty<&#x2F;span><span>() {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span style="color: #6F42C1;"> None<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> (byte, rest)<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> buf<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">split_at<&#x2F;span><span>(<&#x2F;span><span style="color: #005CC5;">1<&#x2F;span><span>);<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> *<&#x2F;span><span>buf<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> rest;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6F42C1;"> Some<&#x2F;span><span>(byte[<&#x2F;span><span style="color: #005CC5;">0<&#x2F;span><span>])<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&#x2F;&#x2F;&#x2F; Decode a protobuffer-style varint from the provided buffer into a u64.<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">pub fn<&#x2F;span><span style="color: #6F42C1;"> decode_varint<&#x2F;span><span>(buf<&#x2F;span><span style="color: #D73A49;">: &amp;mut &amp;<&#x2F;span><span>[<&#x2F;span><span style="color: #6F42C1;">u8<&#x2F;span><span>])<&#x2F;span><span style="color: #D73A49;"> -&gt;<&#x2F;span><span style="color: #6F42C1;"> anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">Result<&#x2F;span><span>&lt;<&#x2F;span><span style="color: #6F42C1;">u64<&#x2F;span><span>&gt; {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let mut<&#x2F;span><span> v<&#x2F;span><span style="color: #D73A49;">:<&#x2F;span><span style="color: #6F42C1;"> u64<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let mut<&#x2F;span><span> offs<&#x2F;span><span style="color: #D73A49;">:<&#x2F;span><span style="color: #6F42C1;"> usize<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> loop<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span style="color: #6F42C1;"> Some<&#x2F;span><span>(byte)<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #6F42C1;"> consume_byte<&#x2F;span><span>(buf)<&#x2F;span><span style="color: #D73A49;"> else<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span style="color: #6F42C1;"> Err<&#x2F;span><span>(<&#x2F;span><span style="color: #6F42C1;">anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">anyhow!<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;Unterminated varint&quot;<&#x2F;span><span>));<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> };<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> septet<&#x2F;span><span style="color: #D73A49;">:<&#x2F;span><span style="color: #6F42C1;"> u8<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> byte<&#x2F;span><span style="color: #D73A49;"> &amp;<&#x2F;span><span style="color: #005CC5;"> 0x7F<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> ctrl_bit<&#x2F;span><span style="color: #D73A49;">:<&#x2F;span><span style="color: #6F42C1;"> u8<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> byte<&#x2F;span><span style="color: #D73A49;"> &amp;<&#x2F;span><span style="color: #005CC5;"> 0x80<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span> v<&#x2F;span><span style="color: #D73A49;"> |=<&#x2F;span><span> (septet<&#x2F;span><span style="color: #D73A49;"> as<&#x2F;span><span style="color: #6F42C1;"> u64<&#x2F;span><span>)<&#x2F;span><span style="color: #D73A49;"> &lt;&lt;<&#x2F;span><span> offs;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> offs<&#x2F;span><span style="color: #D73A49;"> +=<&#x2F;span><span style="color: #005CC5;"> 7<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if<&#x2F;span><span> ctrl_bit<&#x2F;span><span style="color: #D73A49;"> ==<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> break<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if<&#x2F;span><span> offs<&#x2F;span><span style="color: #D73A49;"> &gt;=<&#x2F;span><span style="color: #005CC5;"> 70<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span style="color: #6F42C1;"> Err<&#x2F;span><span>(<&#x2F;span><span style="color: #6F42C1;">anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">anyhow!<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;Varint too long&quot;<&#x2F;span><span>));<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6F42C1;"> Ok<&#x2F;span><span>(v)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&#x2F;&#x2F;&#x2F; Decode a TracePacket from the beginning of the provided buffer containing an encoded Trace message,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&#x2F;&#x2F;&#x2F; returning the packet and the offset of the next TracePacket in the buffer.<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">pub fn<&#x2F;span><span style="color: #6F42C1;"> decode_next_trace_packet<&#x2F;span><span>(buf<&#x2F;span><span style="color: #D73A49;">: &amp;mut &amp;<&#x2F;span><span>[<&#x2F;span><span style="color: #6F42C1;">u8<&#x2F;span><span>])<&#x2F;span><span style="color: #D73A49;"> -&gt;<&#x2F;span><span style="color: #6F42C1;"> anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">Result<&#x2F;span><span>&lt;(<&#x2F;span><span style="color: #6F42C1;">TracePacket<&#x2F;span><span>,<&#x2F;span><span style="color: #6F42C1;"> usize<&#x2F;span><span>)&gt; {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> len_orig<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> buf<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">len<&#x2F;span><span>();<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;"> &#x2F;&#x2F; Decode &amp; validate key<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> key<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #6F42C1;"> decode_varint<&#x2F;span><span>(buf)<&#x2F;span><span style="color: #D73A49;">?<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if<&#x2F;span><span> key<&#x2F;span><span style="color: #D73A49;"> !=<&#x2F;span><span style="color: #005CC5;"> 0x0A<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span style="color: #6F42C1;"> Err<&#x2F;span><span>(<&#x2F;span><span style="color: #6F42C1;">anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">anyhow!<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;Incorrect Key Byte&quot;<&#x2F;span><span>));<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;"> &#x2F;&#x2F; Decode &amp; validate length<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> len<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #6F42C1;"> decode_varint<&#x2F;span><span>(buf)<&#x2F;span><span style="color: #D73A49;">?<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if<&#x2F;span><span> len<&#x2F;span><span style="color: #D73A49;"> ==<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span style="color: #6F42C1;"> Err<&#x2F;span><span>(<&#x2F;span><span style="color: #6F42C1;">anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">anyhow!<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;Incorrect Len (zero)&quot;<&#x2F;span><span>));<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if<&#x2F;span><span> len<&#x2F;span><span style="color: #D73A49;"> &gt;<&#x2F;span><span> (buf<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">len<&#x2F;span><span>()<&#x2F;span><span style="color: #D73A49;"> as<&#x2F;span><span style="color: #6F42C1;"> u64<&#x2F;span><span>) {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span style="color: #6F42C1;"> Err<&#x2F;span><span>(<&#x2F;span><span style="color: #6F42C1;">anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">anyhow!<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;Incorrect Len (more than remaining bytes)&quot;<&#x2F;span><span>));<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;"> &#x2F;&#x2F; Decode next &quot;len&quot; bytes using TracePacket::decode()<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> (<&#x2F;span><span style="color: #D73A49;">mut<&#x2F;span><span> buf_packet, buf_rest)<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> buf<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">split_at<&#x2F;span><span>(len<&#x2F;span><span style="color: #D73A49;"> as<&#x2F;span><span style="color: #6F42C1;"> usize<&#x2F;span><span>);<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> *<&#x2F;span><span>buf<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> buf_rest;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> let<&#x2F;span><span> pckg<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #6F42C1;"> TracePacket<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">decode<&#x2F;span><span>(<&#x2F;span><span style="color: #D73A49;">&amp;mut<&#x2F;span><span> buf_packet)<&#x2F;span><span style="color: #D73A49;">?<&#x2F;span><span>;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if !<&#x2F;span><span>buf_packet<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">is_empty<&#x2F;span><span>() {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span style="color: #6F42C1;"> Err<&#x2F;span><span>(<&#x2F;span><span style="color: #6F42C1;">anyhow<&#x2F;span><span style="color: #D73A49;">::<&#x2F;span><span style="color: #6F42C1;">anyhow!<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;Incorrect Len (bytes left after decode)&quot;<&#x2F;span><span>));<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6F42C1;"> Ok<&#x2F;span><span>((pckg, len_orig<&#x2F;span><span style="color: #D73A49;"> -<&#x2F;span><span> buf<&#x2F;span><span style="color: #D73A49;">.<&#x2F;span><span style="color: #6F42C1;">len<&#x2F;span><span>()))<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre><h3 id="complete-example">Complete Example<&#x2F;h3> <p>For a complete working example including a few tests, feel free to have a look at <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;schilkp&#x2F;protobuffer_repeat_streaming_example">this<&#x2F;a> repository.<&#x2F;p> </article> <article> <h1>Working with external warnings and diagnostics in NVIM</h1> <p>2026-01-20T00:00:00+00:00</p> <p>While most modern programming languages feature very advanced editor integrations especially through LSP server implementations, VLSI, RTL, and (System)Verilog tooling is always a bit ... <em>different<&#x2F;em>.<&#x2F;p> <p>Fortunately, these tools are not inherently bad, but rather a little more old-fashioned. This means that while they might not be as straightforward to use, the tools and techniques for an efficient workflow are already out there.<&#x2F;p> <p>In particular, I was interested in being able to quickly see and navigate to all the numerous warnings and errors they produce directly in neovim.<&#x2F;p> <p>I will use <a rel="external" href="https:&#x2F;&#x2F;www.veripool.org&#x2F;verilator&#x2F;">verilator<&#x2F;a> - an open-source SystemVerilog simulator that works by transpiling RTL models to C++ code - as an example for this post, but these same tools and techniques apply to everything from commercial simulators and backend tools to any tool that generates errors and warnings that are attached to a file location.<&#x2F;p> <h2 id="the-quickfix-list">The Quickfix List<&#x2F;h2> <p>As is so often the case, this exact feature is already supported in (neo)vim without any external plugins.<&#x2F;p> <p>In fact, for a simple C project using a <code>Makefile<&#x2F;code>, you don&#x27;t even have to configure anything! The command <code>:make<&#x2F;code> will cause vim to call <code>make<&#x2F;code> with no arguments, capture its output and parse it into the so-called quickfix list, which you can open with <code>:cwindow<&#x2F;code>:<&#x2F;p> <br> <div style="text-align: center;"> <a href="make_qf.png"> <&#x2F;a> <br> <p>Errors produced by <code>:make<&#x2F;code> in the quickfix list.<&#x2F;p> <&#x2F;div> <br> <p>As you scroll through the quickfix list, vim will automatically jump to the location of the errors and warnings. Even without opening the quickfix list, you can jump between entries using <code>:cn<&#x2F;code> and <code>:cp<&#x2F;code>.<&#x2F;p> <p>For more information about the quickfix list, see <a rel="external" href="https:&#x2F;&#x2F;neovim.io&#x2F;doc&#x2F;user&#x2F;quickfix.html"><code>:h quickfix<&#x2F;code><&#x2F;a>.<&#x2F;p> <h3 id="the-makeprg-option-and-cfile">The <code>makeprg<&#x2F;code> option and <code>cfile<&#x2F;code><&#x2F;h3> <p>The <code>:make<&#x2F;code> command and quickfix list, despite its name, is not limited to Makefiles and their output. The <code>makeprg<&#x2F;code> option controls which command is invoked when <code>:make<&#x2F;code> is called. For example, the following will cause it to run <code>cargo build<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span>:<&#x2F;span><span style="color: #D73A49;">set<&#x2F;span><span style="color: #005CC5;"> makeprg<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span>cargo<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> build<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Any arguments you provide to the <code>:make<&#x2F;code> command will be appended to the end of <code>makeprg<&#x2F;code>, unless the <code>$*<&#x2F;code> placeholder is used to specify where exactly the arguments should be inserted:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span>:<&#x2F;span><span style="color: #D73A49;">set<&#x2F;span><span style="color: #005CC5;"> makeprg<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span>make<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> $*<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> verilate<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>:make MYDEFINE<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span style="color: #005CC5;">1<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>make MYDEFINE<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span style="color: #005CC5;">1<&#x2F;span><span> verilate<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>The <code>%<&#x2F;code> placeholder will be replaced with the path of the current file, which is particularly useful for single-file linters or scripts:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span>:<&#x2F;span><span style="color: #D73A49;">set<&#x2F;span><span style="color: #005CC5;"> makeprg<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span>shellcheck<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; or<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>:<&#x2F;span><span style="color: #D73A49;">set<&#x2F;span><span style="color: #005CC5;"> makeprg<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span>python<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>For long-running compilations and programs, running them directly in vim can be a bit cumbersome. In such cases, the <code>:cfile<&#x2F;code> command can be used to read program output that has been written to a file:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span>:cfile program_output.log<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>The content will be used to populate the quickfix list just like the output of the <code>:make<&#x2F;code> command.<&#x2F;p> <p>For more information see <a rel="external" href="https:&#x2F;&#x2F;neovim.io&#x2F;doc&#x2F;user&#x2F;options.html#&#x27;makeprg&#x27;"><code>:h makeprg<&#x2F;code><&#x2F;a> and <a rel="external" href="https:&#x2F;&#x2F;neovim.io&#x2F;doc&#x2F;user&#x2F;quickfix.html#%3Acfile"><code>:h cfile<&#x2F;code><&#x2F;a>.<&#x2F;p> <h3 id="the-errorformat-option">The <code>errorformat<&#x2F;code> option<&#x2F;h3> <p>The <code>errorformat<&#x2F;code> option, in turn, contains one or more regex-like parsing rules used to extract the source code location and other metadata from the <code>:make<&#x2F;code> output or <code>:cfile<&#x2F;code>.<&#x2F;p> <p>For example, consider the output of the aforementioned <code>verilator<&#x2F;code> tool:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span>%Warning-DECLFILENAME: looong_path&#x2F;tc_clk.sv:11:8: Filename &#39;tc_clk&#39; does not match MODULE name: &#39;tc_clk_and2&#39;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>%Error-PINCONNECTEMPTY: other_path&#x2F;trip_counter.sv:43:10: Instance pin connected by name with empty reference: &#39;overflow_o&#39;<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>A parsing rule consists of literal text and <code>%<&#x2F;code>-prefixed placeholders. For the above, a basic rule might look something like this:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span>:<&#x2F;span><span style="color: #D73A49;">set<&#x2F;span><span style="color: #005CC5;"> errorformat<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span>%%%t%*[a-zA-Z]-%*[^:]:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:%c:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>It consists of the following components:<&#x2F;p> <table><thead><tr><th>Component<&#x2F;th><th>Function<&#x2F;th><&#x2F;tr><&#x2F;thead><tbody> <tr><td><code>%%<&#x2F;code><&#x2F;td><td>Matches a single <code>%<&#x2F;code> character.<&#x2F;td><&#x2F;tr> <tr><td><code>%t<&#x2F;code><&#x2F;td><td>Matches a single character which determines the error type. (<strong>E<&#x2F;strong>rror, <strong>W<&#x2F;strong>arning, <strong>I<&#x2F;strong>nfo, <strong>N<&#x2F;strong>ote)<&#x2F;td><&#x2F;tr> <tr><td><code>%*[a-zA-Z]<&#x2F;code><&#x2F;td><td>Matches one or more lower or uppercase letters. This "consumes" the rest of E<strong>rror<&#x2F;strong>, W<strong>arning<&#x2F;strong>, I<strong>nfo<&#x2F;strong>, or N<strong>ote<&#x2F;strong>.<&#x2F;td><&#x2F;tr> <tr><td><code>-<&#x2F;code><&#x2F;td><td>Matches a single <code>-<&#x2F;code> character.<&#x2F;td><&#x2F;tr> <tr><td><code>%*[^:]<&#x2F;code><&#x2F;td><td>Matches one or more characters that are not a <code>:<&#x2F;code>.<&#x2F;td><&#x2F;tr> <tr><td><code>:<&#x2F;code><&#x2F;td><td>Matches a single <code>:<&#x2F;code> character.<&#x2F;td><&#x2F;tr> <tr><td><code>\ <&#x2F;code><&#x2F;td><td>Matches a single space (<code> <&#x2F;code>).<&#x2F;td><&#x2F;tr> <tr><td><code>%f<&#x2F;code><&#x2F;td><td>Matches a file path.<&#x2F;td><&#x2F;tr> <tr><td><code>%l<&#x2F;code><&#x2F;td><td>Matches a line number.<&#x2F;td><&#x2F;tr> <tr><td><code>%c<&#x2F;code><&#x2F;td><td>Matches a column number.<&#x2F;td><&#x2F;tr> <tr><td><code>%m<&#x2F;code><&#x2F;td><td>Matches an error message (a string).<&#x2F;td><&#x2F;tr> <&#x2F;tbody><&#x2F;table> <p><a rel="external" href="https:&#x2F;&#x2F;neovim.io&#x2F;doc&#x2F;user&#x2F;quickfix.html#error-file-format"><code>:h error-file-format<&#x2F;code><&#x2F;a> contains documentation about how <code>errorformat<&#x2F;code> strings are interpreted, including many more placeholders and tools. Consider also having a look at existing compiler plugins as a reference (see below).<&#x2F;p> <blockquote class="markdown-alert-note"> <p>The above <code>errorformat<&#x2F;code> does not cover all possible verilator warnings and errors. See below for a more complete implementation that handles warnings without error code and without column.<&#x2F;p> <&#x2F;blockquote> <h3 id="compiler-plugins">Compiler Plugins<&#x2F;h3> <p>(Neo)vim ships a set of pre-configured <code>makeprg<&#x2F;code> and <code>errorformat<&#x2F;code> values for a number of common compilers and tools. These take the form of so-called compiler plugins.<&#x2F;p> <p>For a list of built-in compiler plugins, have a look at the <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;neovim&#x2F;neovim&#x2F;tree&#x2F;master&#x2F;runtime&#x2F;compiler"><code>runtime&#x2F;compiler<&#x2F;code><&#x2F;a> folder of the (neo)vim source tree. For a list of compiler plugins available in your current (neo)vim instance you can run:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span>:<&#x2F;span><span style="color: #D73A49;">for<&#x2F;span><span> f <&#x2F;span><span style="color: #D73A49;">in<&#x2F;span><span style="color: #6F42C1;"> globpath<&#x2F;span><span>(<&#x2F;span><span style="color: #005CC5;">&amp;rtp<&#x2F;span><span>,<&#x2F;span><span style="color: #032F62;"> &#39;compiler&#x2F;*.vim&#39;<&#x2F;span><span>,<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><span>,<&#x2F;span><span style="color: #005CC5;"> 1<&#x2F;span><span>) | <&#x2F;span><span style="color: #005CC5;">echo<&#x2F;span><span style="color: #6F42C1;"> fnamemodify<&#x2F;span><span>(f,<&#x2F;span><span style="color: #032F62;"> &#39;:t:r&#39;<&#x2F;span><span>) | <&#x2F;span><span style="color: #D73A49;">endfor<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>In typical vim fashion, the set of compiler plugins spans from slightly older tools, such as different <code>fortran<&#x2F;code> flavours, to slightly more modern tools such as <code>gleam-build<&#x2F;code>.<&#x2F;p> <p>A few that might be of interest:<&#x2F;p> <ul> <li><code>cargo<&#x2F;code> and <code>rustc<&#x2F;code> for rust development.<&#x2F;li> <li><code>eslint<&#x2F;code> and <code>tsc<&#x2F;code> for webdev.<&#x2F;li> <li><code>tex<&#x2F;code> and <code>typst<&#x2F;code> for typesetting.<&#x2F;li> <&#x2F;ul> <p>And even <code>modelsim_vcom<&#x2F;code>, which is the VHDL compiler in ModelSim!<&#x2F;p> <p>It is worth having a look at the content of the compiler plugin file for a tool you are intending to use. Many of them feature extra options and settings you can control via global variables. For example, to determine the exact flags with which <code>cargo<&#x2F;code> is called, the <code>cargo<&#x2F;code> compiler plugin considers the <code>g:cargo_makeprg_params<&#x2F;code> global:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; runtime&#x2F;compiler&#x2F;cargo.vim:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">if<&#x2F;span><span style="color: #6F42C1;"> exists<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&#39;g:cargo_makeprg_params&#39;<&#x2F;span><span>)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #005CC5;"> execute<&#x2F;span><span style="color: #032F62;"> &#39;CompilerSet makeprg=cargo\ &#39;<&#x2F;span><span style="color: #6F42C1;">.escape<&#x2F;span><span>(g:cargo_makeprg_params,<&#x2F;span><span style="color: #032F62;"> &#39; \|&quot;&#39;<&#x2F;span><span>).<&#x2F;span><span style="color: #032F62;">&#39;\ $*&#39;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">else<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> CompilerSet <&#x2F;span><span style="color: #005CC5;">makeprg<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span>cargo<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> $*<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">endif<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre><h3 id="custom-compiler-plugins-verilator">Custom Compiler Plugins: Verilator<&#x2F;h3> <p>If you find yourself often parsing the output of a tool that is not yet included in (neo)vim&#x27;s list of built-in compiler plugins, consider adding a custom compiler plugin in your configuration.<&#x2F;p> <p>On Linux, new compiler plugins should be placed in <code>$XDG_CONFIG_HOME&#x2F;nvim&#x2F;compiler&#x2F;<&#x2F;code>, while overrides to existing compiler plugins go in <code>$XDG_CONFIG_HOME&#x2F;nvim&#x2F;after&#x2F;compiler&#x2F;<&#x2F;code>.<&#x2F;p> <p>For example, on my machine, to create a new <code>verilator<&#x2F;code> compiler plugin, I create <code>~&#x2F;.config&#x2F;nvim&#x2F;compiler&#x2F;verilator.vim<&#x2F;code> with the following content:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; ~&#x2F;.config&#x2F;nvim&#x2F;compiler&#x2F;verilator.vim:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Verilator warnings always start with &quot;%Error&quot; or &quot;%Warning&quot;, optionally directly<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; followed by an error code. If a location is known, it may be given with or<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; without column number. Examples of errors:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; &quot;%Warning: ..msg..&quot;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; &quot;%Error-DECLFORMAT: myfile:1: ..msg..&quot;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; &quot;%Error-PINCONNECT: myfile:1:2: ..msg..&quot;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>CompilerSet <&#x2F;span><span style="color: #005CC5;">errorformat<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span>%%%t%*[a-zA-Z]-%*[^:]:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:%c:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> \<&#x2F;span><span>%%%t%*[a-zA-Z]-%*[^:]:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> \<&#x2F;span><span>%%%t%*[a-zA-Z]:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:%c:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> \<&#x2F;span><span>%%%t%*[a-zA-Z]:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m,<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>See <a rel="external" href="https:&#x2F;&#x2F;neovim.io&#x2F;doc&#x2F;user&#x2F;usr_41.html#write-compiler-plugin"><code>:h write-compiler-plugin<&#x2F;code><&#x2F;a> for more info.<&#x2F;p> <blockquote class="markdown-alert-note"> <p>Unfortunately, the <code>%*[^:]<&#x2F;code> pattern used to match the error code causes it to not be shown in the quickfix list. Parsing it as a module (<code>%o<&#x2F;code>) will make it visible in the quickfix list, but hide the file name:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span>CompilerSet <&#x2F;span><span style="color: #005CC5;">errorformat<&#x2F;span><span style="color: #D73A49;">=<&#x2F;span><span>%%%t%*[a-zA-Z]-%o:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:%c:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> \<&#x2F;span><span>%%%t%*[a-zA-Z]-%o:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> \<&#x2F;span><span>%%%t%*[a-zA-Z]:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:%c:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> \<&#x2F;span><span>%%%t%*[a-zA-Z]:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %f:%l:<&#x2F;span><span style="color: #D73A49;">\<&#x2F;span><span> %m,<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre><&#x2F;blockquote> <h2 id="diagnostics">Diagnostics<&#x2F;h2> <p>If you instead prefer to display external warnings and errors as in-line diagnostics in the same style as LSP servers, that is also an option, but requires a bit of lua scripting.<&#x2F;p> <h3 id="the-vim-diagnostic-api">The <code>vim.diagnostic<&#x2F;code> API<&#x2F;h3> <p>To display a set of diagnostics, first create a namespace to contain them:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span style="color: #D73A49;">local<&#x2F;span><span> my_namespace<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> vim.<&#x2F;span><span style="color: #6F42C1;">api<&#x2F;span><span>.<&#x2F;span><span style="color: #005CC5;">nvim_create_namespace<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;my_namespace&quot;<&#x2F;span><span>)<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Next, configure how the diagnostics in this namespace should be displayed:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span>vim.<&#x2F;span><span style="color: #6F42C1;">diagnostic<&#x2F;span><span>.<&#x2F;span><span style="color: #005CC5;">config<&#x2F;span><span>({<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> virtual_text<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> true<&#x2F;span><span>,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> signs<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> true<&#x2F;span><span>,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> underline<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> true<&#x2F;span><span>,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> update_in_insert<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> false<&#x2F;span><span>,<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}, my_namespace)<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Collect all your diagnostics for a given buffer into a table, and use <code>vim.diagnostic.set()<&#x2F;code> to display them:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span style="color: #D73A49;">local<&#x2F;span><span> bufnr<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">local<&#x2F;span><span> diagnostics<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> bufnr<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> bufnr, <&#x2F;span><span style="color: #6A737D;">-- buffer<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> lnum<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 10<&#x2F;span><span>, <&#x2F;span><span style="color: #6A737D;">-- line number<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> col<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> 0<&#x2F;span><span>, <&#x2F;span><span style="color: #6A737D;">-- column<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> severity<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> vim.<&#x2F;span><span style="color: #6F42C1;">diagnostic<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">severity<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">WARN<&#x2F;span><span>, <&#x2F;span><span style="color: #6A737D;">-- severity<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> message<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #032F62;"> &quot;Something went wrong!&quot;<&#x2F;span><span>, <&#x2F;span><span style="color: #6A737D;">-- message<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> }<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>vim.<&#x2F;span><span style="color: #6F42C1;">diagnostic<&#x2F;span><span>.<&#x2F;span><span style="color: #005CC5;">set<&#x2F;span><span>(my_namespace, bufnr, diagnostics, {})<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>To remove all diagnostics, including before you re-apply a new set, use <code>vim.diagnostic.reset()<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span>vim.<&#x2F;span><span style="color: #6F42C1;">diagnostic<&#x2F;span><span>.<&#x2F;span><span style="color: #005CC5;">reset<&#x2F;span><span>(my_namespace)<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre><h3 id="implementation">Implementation<&#x2F;h3> <p>With this, you can write a lua function that parses any external source and displays them as nvim diagnostics.<&#x2F;p> <p>Have a look at the documentation of the tool you are using - many feature an option for generating the diagnostics information in a machine readable format. Verilator, for instance, can be instructed to write all errors and warnings to a JSON file with standard SARIF formatting:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #6F42C1;">verilator<&#x2F;span><span style="color: #005CC5;"> --diagnostics-sarif --diagnostics-sarif-output<&#x2F;span><span style="color: #032F62;"> log.json<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>In addition to seeing the errors inline, I like to use the excellent <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;folke&#x2F;trouble.nvim">trouble.nvim<&#x2F;a> to also show a quickfix-like pane with all diagnostics. If you prefer to use the quickfix list, you can also programmatically insert the diagnostics there.<&#x2F;p> <p>This approach, while a little bit more work, has the advantage of being extremely flexible. For example, for my verilator output parsing, I added simple reload and filtering capabilities:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span style="color: #6A737D;">&quot; Parse + display verilator diagnostics file:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>:VerilatorDiag log.json<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Reload diagnostics file:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>:VerilatorDiag<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Only display diagnostics that contain the string &quot;frontend&quot;, and remove any<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; &quot;UNOPTFLAT&quot; and &quot;UNUSEDSIGNAL&quot; diagnostics:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>:VerilatorDiagFilter frontend -UNOPTFLAT -UNUSEDSIGNAL<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">&quot; Reset&#x2F;clear the diagnostics:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>:VerilatorDiagReset<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>A self-contained verilator sarif output parser and diagnostic generator with filtering as described above can be found <a href="https:&#x2F;&#x2F;schilk.co&#x2F;blog&#x2F;nvim-external-diagnostics&#x2F;verilator-sarif-parser&#x2F;">here<&#x2F;a>.<&#x2F;p> <h2 id="notes-resources">Notes &amp; Resources<&#x2F;h2> <p>You can find my complete setup in my neovim configuration <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;schilkp&#x2F;dot&#x2F;tree&#x2F;main&#x2F;neovim&#x2F;.config&#x2F;nvim&#x2F;lua&#x2F;schilk&#x2F;utils&#x2F;file_diagnostics">here<&#x2F;a>.<&#x2F;p> <h2 id="changes">Changes<&#x2F;h2> <ul> <li><code>2026-08-12<&#x2F;code>: <ul> <li>Fixed small bugs in the sample implementation of <code>M.filter_check<&#x2F;code><&#x2F;li> <&#x2F;ul> <&#x2F;li> <li><code>2026-08-13<&#x2F;code>: <ul> <li>Fixed <code>Changes<&#x2F;code> section and moved verilator sarif parser to dedicated page.<&#x2F;li> <&#x2F;ul> <&#x2F;li> <&#x2F;ul> </article> <article> <h1>Managing project-specific NVIM configuration</h1> <p>2026-01-19T00:00:00+00:00</p> <h2 id="one-size-fits-not-quite-all">One size fits not quite all<&#x2F;h2> <p>While my <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;schilkp&#x2F;dot&#x2F;tree&#x2F;main&#x2F;neovim&#x2F;.config&#x2F;nvim">neovim configuration<&#x2F;a> works out of the box for most of the projects I work on, I have increasingly encountered situations where I need to adjust certain aspects on a per-project basis.<&#x2F;p> <p>For example, while doing some work with LLVM, I wanted to make use of the MLIR and TableGen LSP servers. While I could install these on my machine and add them to my main neovim configuration, it is in many ways much better to use the specific binaries built from the LLVM tree I am currently editing - that way any changes I make to, for example, an MLIR dialect, are immediately available in the MLIR LSP after a quick re-compile.<&#x2F;p> <p>There is nothing stopping me from adding such edge-case checks to my main configuration - but that does not scale nicely and inevitably leaves behind a whole bunch of configuration snippets I don&#x27;t actively use, yet don&#x27;t want to delete in case I go back to a project in the future. I would much prefer a strategy that allows me to keep such per-project configuration with the actual project.<&#x2F;p> <p>As with anything related to neovim configuration there are about 50 different ways this can be achieved, and because neovim is usually configured with executable code instead of declarative config files, there are a few gotchas that might not be immediately obvious. Therefore I thought it might be useful to quickly write up how the setup I landed on works, and my thoughts behind why I built it in this way.<&#x2F;p> <h2 id="notable-built-in-features-plugins">Notable built-in features &amp; plugins<&#x2F;h2> <p>First, a quick overview of some built-in features and plugins that are related to this subject:<&#x2F;p> <h3 id="neo-vim-s-exrc-option">(Neo)Vim&#x27;s <code>exrc<&#x2F;code> option<&#x2F;h3> <p>The <code>exrc<&#x2F;code> option is the historical solution to this problem, dating all the way back to <code>vi<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="viml"><span class="giallo-l"><span style="color: #D73A49;">set<&#x2F;span><span style="color: #005CC5;"> exrc<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>On startup, when this option is set, vim will look for a <code>.vimrc<&#x2F;code> or <code>.exrc<&#x2F;code> vimscript file in the current directory, while neovim will look for a <code>.nvimrc<&#x2F;code> or <code>.exrc<&#x2F;code> vimscript file, or a <code>.nvim.lua<&#x2F;code> lua script file. If one such file is found, after the system and main user configuration is loaded, (neo)vim will <code>:source<&#x2F;code> this file, executing whatever code it contains.<&#x2F;p> <blockquote class="markdown-alert-caution"> <p>Without any additional security mechanism, this option will execute arbitrary code when opening your editor without any prompt or confirmation. NeoVim features some mitigation to make this less risky - see below.<&#x2F;p> <&#x2F;blockquote> <p>Have a look at <a rel="external" href="https:&#x2F;&#x2F;neovim.io&#x2F;doc&#x2F;user&#x2F;options.html#&#x27;exrc&#x27;"><code>:h exrc<&#x2F;code><&#x2F;a> for more information.<&#x2F;p> <h3 id="neovim-s-trust-list">NeoVim&#x27;s <code>:trust<&#x2F;code> list<&#x2F;h3> <p>As executing arbitrary code when opening your editor in some repository you just cloned from the internet is not an amazing idea, neovim introduced <code>vim.secure.read()<&#x2F;code> and the associated <code>trust<&#x2F;code> list in <code>v0.9.0<&#x2F;code> (released in 2022 - <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;neovim&#x2F;neovim&#x2F;commit&#x2F;f1922e78a1df1b1d32779769432fb5586edf5fbb"><code>f1922e7<&#x2F;code><&#x2F;a>).<&#x2F;p> <p>When attempting to read a file for the first time using <code>vim.secure.read()<&#x2F;code>, neovim will prompt the user to view the file and explicitly trust it:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span>:lua vim.secure.read(&quot;README.md&quot;)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>exrc: Found untrusted code. To enable it, choose (v)iew then run `:trust`:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>&#x2F;home&#x2F;schilkp&#x2F;repos&#x2F;schilkp.github.io&#x2F;README.md<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>[i]gnore, (v)iew, (d)eny:<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Only if the user actually marks the file as trusted, will the content be read.<&#x2F;p> <p>The location and name of the file, a sha256 hash of its content, and the user decision will be stored in the <code>trust<&#x2F;code> list, located at <code>$XDG_STATE_HOME&#x2F;nvim&#x2F;trust<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span>d84ce812f0b22bf6fd2502d9deadbeef2229931192efef1abc0002091b40 &#x2F;home&#x2F;schilkp&#x2F;repos&#x2F;schilkp.github.io&#x2F;README.md<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>! &#x2F;home&#x2F;schilkp&#x2F;Downloads&#x2F;random_project&#x2F;sketchy_file_i_dont_trust.lua<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>After it has been trusted, successive secure reads of this file will complete without a user prompt, unless the file content or location has changed. In neovim, <code>vim.secure.read()<&#x2F;code> is used for reading the content of any file discovered and sourced through the <code>exrc<&#x2F;code> option mechanism, making it significantly less reckless (<a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;neovim&#x2F;neovim&#x2F;commit&#x2F;294910a1ffd11bea0081c2b92632628ef0462eb1"><code>294910a<&#x2F;code><&#x2F;a>).<&#x2F;p> <p>See <a rel="external" href="https:&#x2F;&#x2F;neovim.io&#x2F;doc&#x2F;user&#x2F;lua.html#vim.secure"><code>:h vim.secure<&#x2F;code><&#x2F;a> for more information.<&#x2F;p> <h3 id="a-long-list-of-plugins">A long list of plugins<&#x2F;h3> <p>Per-project configuration is a common need, and there are also quite a few plugins available to help you manage it, including <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;tpope&#x2F;vim-projectionist"><code>tpope&#x2F;vim-projectionist<&#x2F;code><&#x2F;a>, <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;klen&#x2F;nvim-config-local"><code>klen&#x2F;nvim-config-local<&#x2F;code><&#x2F;a>, and <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;direnv&#x2F;direnv.vim"><code>direnv&#x2F;direnv<&#x2F;code><&#x2F;a>.<&#x2F;p> <h2 id="my-setup">My setup<&#x2F;h2> <p>With the <code>vim.secure.read()<&#x2F;code> mechanism, the <code>exrc<&#x2F;code> option in neovim is already fairly close to what I want. Its one major limitation for my use is that it is sourced <em>after<&#x2F;em> my main configuration and therefore after all plugins are configured and loaded. This makes it tricky to do things like adding new plugins, or disabling LSP servers and features that my main configuration enables - by the time a <code>.nvim.lua<&#x2F;code> file is sourced, all this is already done.<&#x2F;p> <p>For a similar reason, using one of the many plugins is also not so attractive, as I ideally want my local configuration to be available before my plugin manager sources all plugins.<&#x2F;p> <p>Instead, I opted to implement a simple version of the <code>exrc<&#x2F;code> option directly in my configuration:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span style="color: #6A737D;">--- local_config.lua<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">local<&#x2F;span><span> M<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> {}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span>M.<&#x2F;span><span style="color: #6F42C1;">CONFIG_FILE_NAMES<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> { <&#x2F;span><span style="color: #032F62;">&quot;.schilk.nvim.lua&quot; <&#x2F;span><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">--- Look for local config file<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">function<&#x2F;span><span style="color: #6F42C1;"> M<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">lookup<&#x2F;span><span>()<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> for<&#x2F;span><span> _, filename<&#x2F;span><span style="color: #D73A49;"> in<&#x2F;span><span style="color: #005CC5;"> ipairs<&#x2F;span><span>(M.<&#x2F;span><span style="color: #6F42C1;">CONFIG_FILE_NAMES<&#x2F;span><span>) <&#x2F;span><span style="color: #D73A49;">do<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> filename<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> vim.<&#x2F;span><span style="color: #6F42C1;">fn<&#x2F;span><span>.<&#x2F;span><span style="color: #005CC5;">findfile<&#x2F;span><span>(filename, <&#x2F;span><span style="color: #032F62;">&quot;.;&quot;<&#x2F;span><span>)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if<&#x2F;span><span> filename<&#x2F;span><span style="color: #D73A49;"> ~=<&#x2F;span><span style="color: #032F62;"> &quot;&quot; <&#x2F;span><span style="color: #D73A49;">then<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><span> vim.<&#x2F;span><span style="color: #6F42C1;">fn<&#x2F;span><span>.<&#x2F;span><span style="color: #005CC5;">fnamemodify<&#x2F;span><span>(filename, <&#x2F;span><span style="color: #032F62;">&quot;:p&quot;<&#x2F;span><span>)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> end<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> end<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">end<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">--- Find &amp; load local config file<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">function<&#x2F;span><span style="color: #6F42C1;"> M<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">source<&#x2F;span><span>()<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> local<&#x2F;span><span> file<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> M.<&#x2F;span><span style="color: #005CC5;">lookup<&#x2F;span><span>()<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if not<&#x2F;span><span> file<&#x2F;span><span style="color: #D73A49;"> or<&#x2F;span><span> file<&#x2F;span><span style="color: #D73A49;"> ==<&#x2F;span><span style="color: #032F62;"> &quot;&quot; <&#x2F;span><span style="color: #D73A49;">then<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> end<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> local<&#x2F;span><span> content<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> vim.<&#x2F;span><span style="color: #6F42C1;">secure<&#x2F;span><span>.<&#x2F;span><span style="color: #005CC5;">read<&#x2F;span><span>(file) <&#x2F;span><span style="color: #6A737D;">--[[@as string|nil]]<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if not<&#x2F;span><span> content<&#x2F;span><span style="color: #D73A49;"> then<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> vim.<&#x2F;span><span style="color: #005CC5;">notify<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;[local_config]: local config file found but not trusted!&quot;<&#x2F;span><span>, vim.<&#x2F;span><span style="color: #6F42C1;">log<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">levels<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">WARN<&#x2F;span><span>)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> end<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> local<&#x2F;span><span> config_fn, err_load<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> loadstring<&#x2F;span><span>(content, <&#x2F;span><span style="color: #032F62;">&quot;@&quot; <&#x2F;span><span style="color: #D73A49;">..<&#x2F;span><span> file)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if not<&#x2F;span><span> config_fn<&#x2F;span><span style="color: #D73A49;"> then<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> vim.<&#x2F;span><span style="color: #005CC5;">notify<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;[local_config]: failed to load local config file: &quot; <&#x2F;span><span style="color: #D73A49;">..<&#x2F;span><span> err_load, vim.<&#x2F;span><span style="color: #6F42C1;">log<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">levels<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">ERROR<&#x2F;span><span>)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> end<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> local<&#x2F;span><span> success, err_call<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> pcall<&#x2F;span><span>(config_fn)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> if not<&#x2F;span><span> success<&#x2F;span><span style="color: #D73A49;"> then<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> vim.<&#x2F;span><span style="color: #005CC5;">notify<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;[local_config]: failed to load local config file: &quot; <&#x2F;span><span style="color: #D73A49;">..<&#x2F;span><span> err_call, vim.<&#x2F;span><span style="color: #6F42C1;">log<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">levels<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">ERROR<&#x2F;span><span>)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> return<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> end<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span> vim.<&#x2F;span><span style="color: #005CC5;">notify<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;[local_config]: loaded local config file&quot;<&#x2F;span><span>, vim.<&#x2F;span><span style="color: #6F42C1;">log<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">levels<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">INFO<&#x2F;span><span>)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">end<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">return<&#x2F;span><span> M<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>This module looks for a file called <code>.schilk.nvim.lua<&#x2F;code> in the current or any parent directories. If one is found the <code>vim.secure.read()<&#x2F;code> function is used to load it, allowing me to manually review and approve the content before it is actually sourced.<&#x2F;p> <p>In my main <code>init.lua<&#x2F;code>, I can then use this module even before my plugin manager <code>lazy<&#x2F;code> is initialized:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span style="color: #6A737D;">-- init.lua<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #005CC5;">require<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;local_config&quot;<&#x2F;span><span>).<&#x2F;span><span style="color: #005CC5;">source<&#x2F;span><span>()<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>Because I want the <code>vim.notify<&#x2F;code> status messages to show up in the notification feed of the <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;j-hui&#x2F;fidget.nvim"><code>fidget<&#x2F;code><&#x2F;a> plugin instead of the default nvim message list, I tend to wrap the calls to <code>vim.notify<&#x2F;code> above in a <code>vim.defer_fn<&#x2F;code> with a short timeout, to make them appear after the <code>fidget<&#x2F;code> has been loaded:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span style="color: #D73A49;">local function<&#x2F;span><span style="color: #6F42C1;"> defer_notif<&#x2F;span><span>(msg, level)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> vim.<&#x2F;span><span style="color: #005CC5;">defer_fn<&#x2F;span><span>(<&#x2F;span><span style="color: #D73A49;">function<&#x2F;span><span>()<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> vim.<&#x2F;span><span style="color: #005CC5;">notify<&#x2F;span><span>(msg, level)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> end<&#x2F;span><span>, <&#x2F;span><span style="color: #005CC5;">250<&#x2F;span><span>)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">end<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span><&#x2F;code><&#x2F;pre> <p>That workaround is very hacky - I know.<&#x2F;p> <h3 id="local-config-files">Local Config Files<&#x2F;h3> <p>While the config file can contain arbitrary code, most of the time I want to change some setting or behaviour of my main configuration. I do this by storing information in the global <code>_G<&#x2F;code> table, which my main configuration then checks for and applies if it exists. For example, to install an additional plugin, I place one or more <code>lazy<&#x2F;code> plugin specs in <code>_G.SCHILK_LOCAL_PLUGINS<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span style="color: #6A737D;">-- Extra plugins to be inserted into the lazy spec<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #005CC5;">_G<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">SCHILK_LOCAL_PLUGINS<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #032F62;"> &#39;schilkp&#x2F;my_cool_plugin&#39;<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span><&#x2F;code><&#x2F;pre> <p>In my main configuration, I then inject any plugins into the default list of plugin specs before starting the plugin manager.<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="lua"><span class="giallo-l"><span style="color: #D73A49;">local<&#x2F;span><span> plugins<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span> {<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;"> -- ... list of plugins ...<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>}<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #6A737D;">-- Inject local plugins:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #005CC5;">_G<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">SCHILK_LOCAL_PLUGINS<&#x2F;span><span style="color: #D73A49;"> =<&#x2F;span><span style="color: #005CC5;"> _G<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">SCHILK_LOCAL_PLUGINS<&#x2F;span><span style="color: #D73A49;"> or<&#x2F;span><span> {}<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">if<&#x2F;span><span style="color: #005CC5;"> _G<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">SCHILK_LOCAL_PLUGINS<&#x2F;span><span style="color: #D73A49;"> then<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> for<&#x2F;span><span> _, plugin<&#x2F;span><span style="color: #D73A49;"> in<&#x2F;span><span style="color: #005CC5;"> ipairs<&#x2F;span><span>(<&#x2F;span><span style="color: #005CC5;">_G<&#x2F;span><span>.<&#x2F;span><span style="color: #6F42C1;">SCHILK_LOCAL_PLUGINS<&#x2F;span><span>) <&#x2F;span><span style="color: #D73A49;">do<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #005CC5;"> table.insert<&#x2F;span><span>(plugins, plugin)<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;"> end<&#x2F;span><&#x2F;span> <span class="giallo-l"><span style="color: #D73A49;">end<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span style="color: #005CC5;">require<&#x2F;span><span>(<&#x2F;span><span style="color: #032F62;">&quot;lazy&quot;<&#x2F;span><span>).<&#x2F;span><span style="color: #005CC5;">setup<&#x2F;span><span>(plugins)<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre> <p>For reference, here are some of the things which I often do in my local config files:<&#x2F;p> <ul> <li>Install and enable additional plugins, as shown above.<&#x2F;li> <li>Enable additional LSP servers from <code>nvim-lspconfig<&#x2F;code>.<&#x2F;li> <li>Disable LSP servers that I have usually enabled.<&#x2F;li> <li>Configure local, project-specific LSP servers, such as the aforementioned MLIR and TableGen LSPs.<&#x2F;li> <&#x2F;ul> <h3 id="shareability">Shareability<&#x2F;h3> <p>The one big downside of this approach is that it is very tightly coupled to my neovim configuration, and therefore these config files are not very useful to anyone else. Unfortunately, because neovim configurations are all so incredibly different, I don&#x27;t see a great way of changing that.<&#x2F;p> <p>This is reflected in my choice to name the files <code>.schilk.nvim.lua<&#x2F;code>: I doubt anyone else will directly use them.<&#x2F;p> <p>For this reason, I also typically don&#x27;t check them into project git repositories. As I doubt that the LLVM project will be interested in a patch that adds <code>.schilk.nvim.lua<&#x2F;code> to their <code>.gitignore<&#x2F;code>, to avoid having to keep juggling that change around locally, I just ignore these files in all git repos using a global <code>.gitignore<&#x2F;code>:<&#x2F;p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="plain"><span class="giallo-l"><span># ~&#x2F;.gitconfig:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>[core]<&#x2F;span><&#x2F;span> <span class="giallo-l"><span> excludesfile = &#x2F;home&#x2F;schilkp&#x2F;.gitignore_global<&#x2F;span><&#x2F;span> <span class="giallo-l"><&#x2F;span> <span class="giallo-l"><span># ~&#x2F;.gitignore_global:<&#x2F;span><&#x2F;span> <span class="giallo-l"><span>.schilk.nvim.lua<&#x2F;span><&#x2F;span><&#x2F;code><&#x2F;pre><h2 id="notes">Notes<&#x2F;h2> <p>You can find my complete setup directly in my neovim configuration <a rel="external" href="https:&#x2F;&#x2F;github.com&#x2F;schilkp&#x2F;dot&#x2F;blob&#x2F;main&#x2F;neovim&#x2F;.config&#x2F;nvim&#x2F;lua&#x2F;schilk&#x2F;local_config&#x2F;init.lua">here<&#x2F;a>.<&#x2F;p> <h2 id="changes">Changes<&#x2F;h2> <ul> <li><code>2026-03-13<&#x2F;code>: <ul> <li>Fixed the version of <code>nvim<&#x2F;code> in which <code>vim.secure.read()<&#x2F;code> was introduced - thanks, justinmk!<&#x2F;li> <li>Updated the example snippet to use the actual content read by <code>vim.secure.read()<&#x2F;code> instead of just using said function to check if the file is trusted before sourcing from the file.<&#x2F;li> <li>Add explanation about deferred <code>notify<&#x2F;code> calls.<&#x2F;li> <&#x2F;ul> <&#x2F;li> <&#x2F;ul> </article> </main></body></html>$

- Stuff

NVIM: Writing Complex Macros / Transforms in Lua

Changes</h2> 2026-09-08</code>: Simplified + renamed visual_process_selection</code> to visual_process_selection_lines</code>. Thanks justinmk</a>!</li> </ul> </li> </ul>

Progressive encoding and decoding of 'repeated' protobuffer fields.

Changes</h2>

`2026-09-08</code>:Simplified + renamed visual_process_selection</code> to visual_process_selection_lines</code>. Thanks justinmk</a>!</li> </ul> </li> </ul>`