I published a git alias yesterday that does not work. Not because I got it wrong: the version in my repository is correct, and the version on the page was not. Something between the two edited it.

What the reader would have copied

The alias comes from yesterday’s gitconfig post. It splits a working tree into two stashes and puts the staged part back:

stash-unstaged = "!f() { git stash push --staged -m staged; git stash push -u -m rest; git stash pop stash@{1}; }; f"

stash@{1} is the second entry on the stash stack. That is the whole point of the alias. What the published HTML said was stash@1, which is not a stash reference at all. Copy the page, paste it into .gitconfig, run the alias, and git answers error: stash@1 is not a valid reference.

Nothing in my editor showed a problem. The source file was right, the build was green, the page was up.

Why the template engine gets a vote

This blog runs on Roq, a Quarkus static site generator, and it has quarkus.asciidoc.qute=true set. So a page goes through two passes: Asciidoctor turns AsciiDoc into HTML, then Qute processes that HTML as a template. Qute is what expands {site.title} and {page.date} into real values.

Being inside a <pre> tag does not protect anything at that stage. stash@{1} contains what reads as an expression, and the page came back with the braces gone and a bare 1 in their place.

The neighbouring braces in the same line survived:

wta = "!f() { git fetch && git worktree add \"../$1\" \"$1\"; }; f"

Those braces wrap a shell function body, with spaces, quotes and semicolons inside, so they do not read as an expression and came through untouched. That is what makes this failure mode nasty. Braces are everywhere in a config file, and almost all of them come out fine. Only the ones that happen to parse get eaten, so the damage is a single character in one line of an otherwise perfect block.

escape: true is not enough

Roq has a front matter flag for exactly this problem:

escape: true

It was already set on that post. It did not help here. Whatever it covers, a brace followed by a digit is not part of it. The reliable fix is to escape the brace itself in the source: write stash@\{1}, backslash included, and the page shows stash@{1}. It works in a listing block and in prose alike. Fine, once you know. The problem is that you only know after something breaks, and the thing that breaks is on the reader’s machine, not yours.

Verify the artifact, not the source

Reading my .adoc file again would never have caught this. The bug is not in the source, it is in the transformation. The only text that matters is the one that ends up in the reader’s clipboard, so that is the text to check.

For a config file, that check can be exact. Fetch the page, pull the code block out of the HTML, unescape the entities, and hand the result to the tool that is supposed to consume it:

curl -s -o page.html http://localhost:8080/blog/my-gitconfig/

python3 - <<'PY'
import re, html
s = open('page.html').read()
pre = re.findall(r'<pre[^>]*>(.*?)</pre>', s, re.S)[0]
open('rendered.gitconfig','w').write(html.unescape(re.sub('<[^>]+>', '', pre)))
PY

GIT_CONFIG_GLOBAL=rendered.gitconfig git config --global --list

git config --list fails on a malformed line and prints the post-parse value of everything else. On that post it returns 70 entries, so every alias in the published block is proven to parse, and every value is shown after git has stripped its inline comments. That last part caught a second class of bug while I was writing that post: adding # explanation comments after quoted alias values could easily have swallowed a quote, and the listing shows immediately that it did not.

The same shape works beyond git. A published docker-compose.yml can go through docker compose config, JSON through jq ., SQL through the parser, a shell script through bash -n. Any snippet you expect people to copy has some tool that will tell you whether it survived the trip.

The check, generalized

Two habits came out of this.

Escape braces before digits and bare identifiers in anything that ends up on a Qute-rendered page, code block or prose. stash@\{1} in the source, stash@{1} on the page.

And when a post publishes something meant to be copied and run, check the rendered page rather than the file I wrote. Reading the source again proves only that I typed it correctly. Mine was wrong by exactly two characters, which was enough.