DEV Community: Enrico Testori

Migrating an ancient SVN repo the painful way (tunnel vision included)

Enrico Testori — Thu, 30 Jul 2026 13:50:21 +0000

A while ago I inherited a ticking clock. The old internal server was finally being decommissioned, and sitting on it, alone by that point, like the last tenant of a building scheduled for demolition, was an SVN repository. 82,009 revisions. Fifteen years of commit history. 21 GB on disk. Set up by someone who left the company six years ago and has not been heard from since.

The requirements were simple on paper and annoying in practice. My coworkers (and some internal tools) needed to keep using SVN afterwards (svn switch --relocate and carry on with their lives), so migrating to git was off the table¹. I had to produce a working SVN repository somewhere else, ideally a slimmer one, because fifteen years of history include a couple dozen directories full of large binaries that nobody has needed since approximately the previous geological era.

What follows is the honest, chronological reconstruction of what happened next. I'm writing it as a series of attempts because that's literally what it was: each failure manufactured the problem that the next attempt would heroically fail to solve. And since I'm an engineer before I'm a storyteller, every attempt closes with its lab notes: what I wanted, what I fed in, and what came out. The outcome column is where the comedy lives.

Attempt one: the obvious one

The goal, at the beginning, was simple: get all 82,009 revisions out of that server and onto a disk I controlled. So I started where everyone starts:

svnrdump dump https://svn.server/repo > full.dump

One command, one file, one prayer. I knew it wasn't going to work (~82,000 revisions over a flaky connection means any hiccup sends you back to revision zero), but you have to try the obvious thing first, if only out of respect for tradition.

I let it run overnight. It died at 4 a.m. somewhere in the low thirty-thousands, which I choose to read as the repo setting my expectations early.

Intent: a complete dump of the repository, in a single file.

Input: the repo URL, one svnrdump command, blind optimism.

Outcome: a partial dump (~30k revisions in), one dead process, nothing usable.

Attempt two: divide and conquer

Fine. If the pipe won't survive six hours, don't run a six-hour pipe. The new plan: slice the dump into 2,000-revision chunks, compress each one as it lands, and track progress in a manifest file so the whole thing could resume from the last checkpoint instead of from revision zero:

CHUNK_SIZE=2000

while [ "$CURRENT_START" -lt "$LATEST_REMOTE" ]; do
    END_REV=$((CURRENT_START + CHUNK_SIZE))

    svnrdump dump "$REPO_URL" -r "${RANGE_START}:${END_REV}" | \
    gzip > "${CHUNK_NAME}.tmp"

    # only on success: promote the chunk and checkpoint
    mv "${CHUNK_NAME}.tmp" "$CHUNK_NAME"
    echo "$END_REV" > "$MANIFEST"
done

Note the .tmp dance: a chunk only earns its real name once gzip closes cleanly, so a killed run never leaves a half-written file masquerading as a good one. I was learning. Slowly, and at great cost, but learning.

And it worked. The network could drop, the process could be killed, I could free disk between iterations, and the script just resumed from the manifest. By the end of the day I had, for the first time, a complete dump of the repository: forty-one gzipped chunks covering every revision from zero to 82,009.

The victory lasted about ten minutes: roughly the time it took to run du -sh. The output was too large for the destination server's disk. Which meant I now needed to filter the dump. And that's where the real trouble started, though I didn't know it yet.

Intent: a dump that survives network drops, OOMs and disk-pressure, resumable by construction.

Input: the repo URL, CHUNK_SIZE=2000, one manifest file as checkpoint.

Outcome: complete success, technically: 41 chunks, all revisions present, total size larger than the destination disk. Also, though I didn't know it yet, every chunk was a self-contained time bomb. More on that shortly.

Attempt three: divide, conquer, filter

The natural next move was splicing svndumpfilter exclude into the pipeline, dropping ~20 paths that were no longer needed²: old project archives, documentation builds from 2011, subprojects that had long since been split into their own repos:

EXCLUDES=(
    "/research_project3.1518684973-ver3.9-FINAL.pdf"
    "/P1-P2-Help-Desk(chunking).docx"
    "/com.acme.textprocessing.a"
    "/com.acme.textprocessing.b"
    "/com.acme.textprocessing.c"
    "/com.acme.textprocessing.d"
    "/legacyDoc"
    "/legacy-utils"
    "/customerX"
    # ... ~20 entries total
)

svnrdump dump "$REPO_URL" -r "${RANGE_START}:${END_REV}" | \
    svndumpfilter exclude $EXCLUDE_ARGS | \
    gzip > "${CHUNK_NAME}.tmp"

It failed at the chunk boundaries:

svndumpfilter: E200003: Invalid copy source path '/legacy-utils/trunk/...' for '/SomeOtherProject/trunk/...'

Two discoveries, neither pleasant. First: svndumpfilter matches path prefixes only: no wildcards, no regex, no substring matching. com.acme.textprocessing.a is not considered "inside" com.acme.textprocessing, because SVN treats dots literally, not as directory separators. Second, and much worse: if revision 8,342 copies a file from a path you're excluding to a path you're keeping, the dump stream references a source that no longer exists. svndumpfilter hits it, stops, and provides no --skip-broken-references flag. No recovery, no partial output.

Fifteen years of directory moves, project renames, and module splits meant the copy-from graph was deeply tangled. I could either abandon filtering, or understand the dependency structure well enough to navigate around it.

I chose poorly.

Intent: same resumable chunked dump, minus ~20 directories of dead weight.

Input: the attempt-two pipeline with svndumpfilter exclude spliced in, plus one lovingly curated exclude list.

Outcome: E200003 at chunk boundaries, zero usable output, and two unpleasant facts about svndumpfilter learned the hard way.

Attempt four: the Python era

This was around day three, and the point where a backup migration quietly turned into a software project. The plan: before touching svndumpfilter again, map the entire copy-from graph of the repository and find out, with data rather than hope, whether any exclude set could ever work.

I wrote analyze_svn_chunks.py, a binary-streaming scanner that reads every chunk file's Node-path, Node-copyfrom-path, and Revision-number headers and builds a global map of every copy-from dependency:

REV_RE      = re.compile(rb'^Revision-number:\s*(\d+)$')
NODE_PATH   = re.compile(rb'^Node-path:\s*(.+)$')
NODE_COPYFROM = re.compile(rb'^Node-copyfrom-path:\s*(.+)$')

for chunk in sorted_chunks:
    for line in iter_lines_binary(chunk):
        # track first_seen[path], path_locations, copyfrom_refs...

It was later joined by two reconnaissance siblings: find_copyfrom_prefixes.py, which lists every copy-from source sitting under the prefixes I wanted to exclude, and find_svn_copy_nodes.py, which flags copy nodes that a given include/exclude list would leave orphaned. I was no longer migrating a repository; I was running a small research institute.

The findings: 8,172 unique copy-from sources, summarized in four report files: copyfrom_sources.txt, copyfrom_report.json, missing_sources.txt, and, critically, sources_in_excludes.txt: copy-from paths sitting inside the very directories I wanted to exclude. Dozens of them. There's a special kind of sinking feeling reserved for the moment a tool you wrote outputs formal proof that your plan cannot work. svndumpfilter was structurally incapable of handling this exclude set, full stop.

Fine, I thought: filter later, load first. Except even the unfiltered chunks refused to load into a test repository:

svnadmin: E160020: File already exists: filesystem '...', path '/acmemmf'

The reason, once I dug in: every chunk was self-contained. When a new chunk started at revision 5001, svnrdump re-emitted Node-action: add for every file that already existed in the repository. svnadmin load would see a path it had already created from the previous chunk and crash. So I wrote a second kind of tool, svn_dump_repair.py, to rewrite the duplicate adds into changes, tracking path state in a dictionary shared across all chunks:

def repair_bytes(src, dst, existing=None):
    # existing: cross-chunk shared dict {path(bytes) -> first_rev(bytes)}
    # streaming binary parse, track cur_path/cur_action,
    # if cur_action == b'add' and cur_path in existing:
    #     replace ACTION_ADD with ACTION_CHG

And this is where things got properly worse, because the first version opened the dump with encoding='utf-8', errors='replace'. SVN dump files contain raw binary diffs. The errors='replace' setting silently swapped in replacement characters for invalid bytes. In other words, my repair tool was corrupting the very diffs it was supposed to preserve. Loading the "repaired" chunks gave:

svnadmin: E185001: Svndiff contains a too-large window

There's probably a metaphor in there about fixing things by breaking them harder, but I was too busy to look for it. I rewrote the script to process everything in raw binary mode (rb/wb), touching only the header lines it actually needed to inspect. Binary pass-through for everything else. (The docstring of the final version still carries the scar: "Processes everything in BINARY mode to avoid corrupting SVN diff data.")

Only then did I find the real root cause, and it stung: I wasn't using --incremental. The dump format has no primitive for "the repository already has this path from a previous load." Every chunked dump without --incremental is a self-contained stream that re-describes the entire filesystem state at its starting revision. The first chunk needs a full dump; every subsequent chunk must be --incremental. The 8,172 copy-from sources, the E160020 crashes at chunk boundaries: the same underlying problem wearing different hats. A small zoo of Python scripts, and the fix was a flag.

Intent: first, map the copy-from web to find a viable exclude set; then, bend the chunks until they loaded in sequence.

Input: chunk files + excludes.txt into the analyzer; chunk files + one shared cross-chunk state dict into the repair tool.

Outcome: a JSON file formally proving my filtering plan impossible; a repair tool that first corrupted the data (E185001), then worked, then became unnecessary the moment --incremental entered my life.

Attempt five: things get worse before they get... no, they just get worse

This was day four. Or five. I'd stopped counting, and had started naming scripts things like fix_dump_FINAL.py, which anyone will recognize as a bad omen.

The new, corrected pipeline: first chunk full, every subsequent chunk dumped with --incremental, filtering removed entirely. Surely, surely, loading the unfiltered chunks would now work. It did not:

svnadmin: E160013: File not found: transaction '...', path '/com.acme.esb/...'
svnadmin: E200014: Base checksum mismatch on '/acmemmf/trunk/...'

These were copy-from references pointing at source revisions that weren't present in the chunks loaded so far, because some earlier chunk had failed silently along the way. Files copied from revision 17,711 into revision 66,669, with revision 17,711 nowhere to be found. The chunking strategy wasn't just fragile; it was fragile and quiet about it, which is the worst combination.

Intent: load the unfiltered, properly-incremental chunks and finally have a working local copy.

Input: the fresh --incremental chunk set.

Outcome: E160013 and E200014: references to source revisions that never made it into the dump, courtesy of earlier silent failures.

Attempt six: one dump to rule them all

New strategy, and I want you to know it felt clever at the time: dump the entire repo unfiltered, in one logical pass, with --incremental on everything except the first chunk. Concatenate all chunks locally into a single stream. Then run svndumpfilter exactly once, on the combined file. Two passes, clean separation of concerns. What could possibly…

The concatenated unfiltered dump came out to 23 GB compressed.

I ran the second pass:

zcat filtered_1st_pass.dump.gz | \
    svndumpfilter exclude --drop-empty-revs $EXCL_ARGS | \
    gzip -c > filtered_2nd_pass.dump.gz

And the answer was:

svndumpfilter: E140001: Dumpstream data appears to be malformed

Twenty-three gigabytes of compressed history, and the verdict was: malformed. No offset. No line number. No partial output. No --skip-malformed flag to reach for. The process stopped, took its ball, and went home.

That was the breaking point. I closed the terminal, made a coffee, and admitted to myself that I had just lost a week-long fight against a text file format.

Intent: one complete logical dump, filtered exactly once, clean separation of concerns.

Input: all chunks concatenated into a single 23 GB compressed stream.

Outcome: E140001, no offset, no mercy. One (1) coffee of defeat.

The light at the end of the tunnel was... a tunnel

Defeated people do honest things, so I did what I should have done on day one: I stopped skimming the SVN Book for flags and actually read it. And there it was, sitting in plain sight the whole time: svnsync, SVN's built-in mirroring tool.

svnsync replicates a repository revision by revision over the network using SVN's own protocol. No dump files. No filtering. No manual parsing of Node-copyfrom-path headers. Copy-from references, svn:mergeinfo, property changes. All first-class concepts in the wire protocol, handled natively.

I pointed it at the same https:// endpoint that svnrdump had been talking to all along, and at first it felt like the happy ending. It resumed after connection drops. It chugged along, revision by revision. And then the checksums started failing: about a dozen revisions came out corrupted. I wiped the mirror, retried, and got the same dozen, give or take, and they were always the heavy ones, the revisions carrying the big binaries.

The culprit wasn't SVN. It was Apache. Over https://, Subversion doesn't speak its native protocol at all: it speaks WebDAV/DeltaV through mod_dav_svn, which lives inside an Apache worker process. Every operation becomes an HTTP request with an XML payload, and everything runs under the web server's resource governance: per-process memory limits, request timeouts, MPM tuning. When my sync pushed a multi-hundred-megabyte delta through, the httpd child handling it ballooned, hit its memory ceiling, and died mid-stream. What landed in my mirror was a truncated revision and a checksum mismatch.

The obvious fix was to raise Apache's memory limit and try again. But blindly bumping a limit you don't understand just moves the wall a bit further: the next fatter binary would have found the new ceiling eventually. So I finally used my so-called brain and asked a better question: what is a web server doing in the middle of my data transfer at all?

Because, and this is the part I find genuinely interesting, SVN wasn't born speaking svn://. The project started life as an Apache module; WebDAV was the original transport, and svnserve only arrived later, for people who didn't feel like running an entire web server just to version their code. The two transports are wildly different animals:

	`https://` (mod_dav_svn)	`svn://` (svnserve)
Transport	HTTP requests with XML payloads (WebDAV/DeltaV)	Purpose-built binary protocol over a stateful TCP connection
Server process	Apache worker, subject to its memory and timeout limits	Small dedicated daemon with a modest, predictable footprint
Payload	Native deltas wrapped in HTTP/XML envelopes	Native deltas, streamed as-is
Middlemen	A full web server that may decide your 2 GB delta looks like an attack	None

In short: https:// makes SVN traffic look like web traffic: fantastic for slipping through corporate proxies, terrible for shoveling gigabytes of binary history from A to B. svn:// is the protocol SVN speaks when nobody forces it to wear a costume.

And here's the part that still makes me laugh. As far as I know, this repository has been served through Apache for its entire fifteen-year existence, most of it on a machine considerably weaker than the one it retired from. Which means every single one of those monster binaries went in through the very same web server that was now fainting at the sight of them coming out³. Committing, apparently, was perfectly fine. Reading back was where the web server drew the line.

To be fair, there is a real asymmetry: on commit, the client does the heavy lifting and hands the server a ready-made delta to store; on read, mod_dav_svn has to reconstruct and stream those deltas itself, on its own memory dime. And fifteen years of commits arrived one polite transaction at a time, over a LAN, with nobody in a hurry. I showed up asking for everything, all at once, the digital equivalent of draining a swimming pool through the same straw people had used to fill it.

The catch: the source server didn't expose svn:// to the network. It sat on an internal subnet reachable only through a jump host. But the jump host had SSH, and SSH is the universal solvent:

ssh -L 3690:10.0.0.3:3690 svn-machine

# in another terminal:
svnsync init file:///tmp/svn_dest_repo svn://localhost:3690
svnsync sync file:///tmp/svn_dest_repo

Three commands. I typed them with the confidence of a man who had already been betrayed four times that week, and waited.

It just worked. Revision after revision, ticking upward, unbothered. When the connection dropped (of course it dropped), svnsync sync simply resumed from the last checkpointed revision. The SSH tunnel (-L local_port:remote_host:remote_port) gave me a stable, encrypted pipe through the firewall: localhost:3690 on my machine mapped to 10.0.0.3:3690 on the source, with the jump host doing the routing. The two servers never needed to see each other at all.

The whole 21 GB came across, binaries and all, and this time the verification pass came back clean. All 82,009 revisions, not one byte out of place. The same tool that had mangled a dozen revisions over DAV didn't put a single one wrong over svn://⁴.

Intent: replicate the repository using SVN's own protocol: no dumps, no filters, no text parsing.

Input, take one: svnsync over the existing https:// endpoint → a dozen corrupted revisions, always the heavy ones (Apache OOM mid-delta).

Input, take two: svnsync over svn:// through an SSH tunnel → 82,009 revisions, verification clean, zero corrupted. One week of my life not coming back.

Why the boring tool won

In hindsight, the dump pipeline and svnsync attack the same problem from opposite directions. The pipeline is a serial, single-shot transformation chain: svnrdump reads raw repo data, svndumpfilter removes paths by parsing text, gzip compresses bytes. Each tool speaks a different abstraction level, and any failure anywhere kills the whole operation, usually silently, occasionally at 4 a.m.

svnsync never leaves SVN's own protocol, at least not once you let it use the native one. It negotiates revisions, transfers native deltas, checkpoints atomically. It doesn't parse dump headers because it doesn't need dump headers; it doesn't trip over copy-from references because the protocol resolves them for it. And it resumes, which, for an 82,000-revision transfer, is the entire difference between a tool and a gamble.

Though, as the corrupted dozen taught me, even the right tool needs the right transport. Every layer you stack between the two repositories (HTTP, XML, a web server with opinions about memory) is another place where your data can get quietly truncated.

The irony is not subtle: svnsync is the tool the SVN documentation recommends for mirroring. It was there from the start. I just had to fail with chunked dumps, a growing pile of Python scripts, and a 23 GB malformed file before I was emotionally ready to accept it⁵.

Epilogue

The mirror completed. The old server, at the time of writing, is still standing, but its successor is ready, and keeping it warm until the cutover costs exactly one command: svnsync sync, the very same one, which simply fetches whatever revisions landed in the meantime. Put it in a cron job and the mirror maintains itself while everyone keeps committing to the old repo, blissfully unaware.

Somewhere on a disk there's still a directory of chunked dump files, four Python scripts, and a 23 GB compressed artifact that svndumpfilter once called malformed, none of which I will ever touch again, which is exactly the right fate for tools written in desperation⁶.

I spent a week engineering increasingly elaborate solutions to problems that only existed because of the approach I'd chosen. The answer was never better filtering, better chunking, or better binary parsing. It was to stop fighting the dump format and use the protocol instead.

Also: SSH tunnels are magic, svnsync deserves far more respect than its own documentation gives it, and the next person to commit a multi-gigabyte binary to version control will be judged: silently, professionally, but intensely.

Thanks for ~~dumping~~ reading!

I did explore git briefly, mid-crisis, like a man checking the price of flights during a family dinner. The git-filter-repo tool is vastly better at path-based filtering than anything SVN offers, but the deliverable was a working SVN endpoint. Technical debt, eh? ↩
Yes, one of the files I was trying to exclude was literally named Help-Desk(chunking).docx. Fifteen years in advance, the repo was already mocking my strategy. ↩
The files checked in any time they liked, but they could never leave. ↩
Yes, unfiltered: the poisoned directories came along for the ride. Disk is cheap. My sanity, at that point, was not. ↩
If you're reading this because you're staring down your own ancient SVN migration: try svnsync first. The dump pipeline is a trap. Do not be me. ↩
If there's a silver lining, it's that a week of poking compressed SVN dumps makes you genuinely fluent in zcat, zgrep, zless, gzip -t, and the fine art of binary-safe stream processing. Not skills I wake up wanting to practice, but surprisingly transferable. ↩

How to parse dates with optional parts with Java Instant API

Enrico Testori — Tue, 21 Jul 2026 20:43:12 +0000

Parsing partial dates can be a common challenge in Java programming, and Java 8's Instant API offers a powerful solution.
In this article, we will explore how to effectively parse partial dates using Java 8's Instant API.

Why (or not) parse partial dates?

Isn't parsing "full" dates enough of a headache?
Well, in a perfect world, we may handle only fully written dates and possibly in ISO 8601 but the reality is that neither users nor our data sources do it. Think about it: how many times did you require a user to fill, for example, its birthday with a precision up to a millisecond? I guess never ¹.

There are, of course, many ways to tackle this problem,
one of the easiest being storing the date information with the exact resolution you need, so the omitted part becomes irrelevant.
That's why in the database world we have many ways to store date/time information; for example, let's check Postgres:

TIMESTAMP: the standard timestamp (timezone is assumed to be UTC)
TIMESTAMPZ: stores the timestamp along with timezone information
DATE: only stores date (e.g. 2023-12-31)
TIME: only stores time (e.g. 23:59.999)
TIMEZ: only stores time along with timezone information

So, before over-complicating your parsing logic you should ask yourself: "Is the omitted part in the date/time I'm going to parse relevant? Should it be stored?"

A more practical example

It wouldn't be a complete article if I didn't provide a real-world scenario that I implemented recently.

I was working on a CLI tool that along with other features, can query a database where there are two timestamps columns defined: start_timestamp and end_timestamp that are used to record when a job starts and ends.

The CLI has two arguments to filter over those two columns: --from and --to both of them accepting a date formatted as yyyyMMdd[-HHmmss].

Do you notice there's a part between square brackets? That's the optional part.

The idea of the optional part is that, without adding more arguments to the CLI, a user can query one or more full days if it provides the two arguments with only the mandatory part, or can go more fine-grained if needed (even mixing the formats).

To do it, we have two different argument semantics:

--from: if omitted, the time part should be set to the start of the day which is "all zeroes"
--to: if omitted it should be set to the end of the day which is 23:59:59.999 (Here I haven't used the same format just for clarity)

Different API, different defaults

Before getting to the actual code that solves our problem, let's write down some basic instructions to parse and print dates with Instant and the old Date APIs.

Old Date class

Execute this snippet:

String rawDate = "20231231";
Date date = new SimpleDateFormat("yyyyMMdd").parse(rawDate);

it will output:

Date is Sun Dec 31 00:00:00 CET 2023

The first thing to notice is that the old Date class is already defaulting to "all zeroes".
The second thing is that the output is in CET timezone; this is machine-dependent.

Also, notice there is no explicit "default" concept.

Instant class, attempt #1

Execute this snippet:

String rawDate = "20231231";
Instant instant = DateTimeFormatter.ofPattern("yyyyMMdd").parse(rawDate, Instant::from);

it will give you an exception:

Text '20231231' could not be parsed: Unable to obtain Instant from TemporalAccessor: {},ISO resolved to 2023-12-31 of type java.time.format.Parsed

Why does it fail?

Instant doesn't apply any default implicitly and the string 20231231 only contains information about a date. It doesn’t contain any information about the time of day. As such, there's no sufficient information to create an instance of the Instant class.

Instant class, attempt #2

Now that we know that Instant class wants the parser to explicitly declare defaults, let's execute this code:

String rawDate = "20231231";
Instant instant = new DateTimeFormatterBuilder()
        .appendPattern("yyyyMMdd")
        .parseDefaulting(ChronoField.NANO_OF_DAY, 0)
        .toFormatter()
        .withZone(ZoneId.of("UTC"))
        .parse(rawDate, Instant::from);

System.out.println("Instant is " + instant);

This time it will give you the expected result:

Instant is 2023-12-31T00:00:00Z

Notice that:

parseDefaulting takes a ChronoField and a value. In this example, I've hard-coded a 0, but you should use some meaningful constant; I like to use LocalTime for this.
I also added an explicit timezone (UTC), try to omit it and compare the output (assuming you’re in a different timezone than UTC)

This is almost everything we need to finally parse dates with optional parts.

Instant class with optional parts

With all the information that we have now, it's almost effortless:
all we need is to define the optional part in the pattern string and play with parseDefaulting.

That's what I've come up with to handle the different semantics of --from and --to in my use case:

package com.hypertesto.example;

import java.text.ParseException;
import java.time.Instant;
import java.time.LocalTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatterBuilder;
import java.time.temporal.ChronoField;

public class InstantWithOptionalPartExample {

        public static void main(String[] args) throws ParseException {
        String rawPartialDate = "20231231";
        String rawFullDate = "20231231-121212";

        Instant partialFrom = parseFromArgument(rawPartialDate);
        Instant partialTo = parseToArgument(rawPartialDate);

        Instant fullFrom = parseFromArgument(rawFullDate);
        Instant fullTo = parseToArgument(rawFullDate);

        System.out.println("Partial 'from' argument is " + partialFrom);
        System.out.println("Partial 'to' argument is " + partialTo);

        System.out.println("Full 'from' argument is " + fullFrom);
        System.out.println("Full 'to' argument is " + fullTo);
    }

    public static Instant parseFromArgument(String string) {
        return parseDateWithOptionalPart(string, LocalTime.MIN);
    }

    public static Instant parseToArgument(String string) {
        return parseDateWithOptionalPart(string, LocalTime.MAX);
    }

    private static Instant parseDateWithOptionalPart(String string, LocalTime defaultTime) {
        return new DateTimeFormatterBuilder()
                .appendPattern("yyyyMMdd[-HHmmss]")
                .parseDefaulting(ChronoField.HOUR_OF_DAY, defaultTime.getHour())
                .parseDefaulting(ChronoField.MINUTE_OF_HOUR, defaultTime.getMinute())
                .parseDefaulting(ChronoField.SECOND_OF_MINUTE, defaultTime.getSecond())
                .parseDefaulting(ChronoField.NANO_OF_SECOND, defaultTime.getNano())
                .toFormatter()
                .withZone(ZoneId.of("UTC"))
                .parse(string, Instant::from);
    }
}

I've arranged this example class to be self-explaining, but if you have doubts leave a comment; I'll be happy to clarify!

This is its output:

Partial 'from' argument is 2023-12-31T00:00:00Z
Partial 'to' argument is 2023-12-31T23:59:59.999999999Z
Full 'from' argument is 2023-12-31T12:12:12Z
Full 'to' argument is 2023-12-31T12:12:12.999999999Z

Conclusion

In conclusion, this article has briefly explored the utility and methodology of parsing partial dates using Java 8's Instant API.
Through practical examples, we've seen how parsing partial dates with Instant API is straightforward, provided we have a clean idea of how to handle defaults.

Lastly, remember there isn't only Instant API in modern Java, in fact,
there are LocalDateTime and ZonedDateTimeclasses which are also fine for this kind of processing ².

I hope the article was useful to you, thanks for reading it!

It would be impractical anyway, but I couldn't come up with a better example. ↩
Maybe better for my use case, but I had my reasons to stick with Instant class for that project. ↩

One login to rule them all: centralized auth for internal tools with Caddy

Enrico Testori — Mon, 20 Jul 2026 20:55:42 +0000

I am lazy. Not in the "I don't want to work" sense¹, but in the "I refuse to solve the same problem twice" sense.
So when I found myself looking at a growing collection of internal tools (each one either completely unprotected or with its own half-baked auth bolted on) I decided it was time to stop and fix it properly.

The dream: one login, backed by the identity provider the company already uses, and every new tool just gets two lines in a config file. No user databases to maintain, no password reset flows to implement, no "hey can you add my colleague to the thing".

In our case the company uses Azure AD, so the plan was to put everything behind Caddy and add OAuth2 authentication against the existing Microsoft tenant. This post is about how that works and the two things that needed some extra attention to get right.

Why Caddy

I've been through the nginx phase. The Apache phase. The "let me just write a quick script to renew certificates" phase.
At some point you just want something that works without making you feel like you're filing paperwork.

Caddy hits a sweet spot I haven't found elsewhere: it's simple enough that you can read the whole config and understand it in one sitting,
but complete enough that you rarely need to reach for anything else. The Caddyfile syntax is human-readable by design, and the defaults are sane,
which sounds like a low bar until you've spent an afternoon debugging a cipher suite.

The thing that genuinely removes the most friction though is automatic HTTPS. Point a domain at your server, add it to the Caddyfile,
and Caddy handles the Let's Encrypt certificate negotiation, renewal, and everything in between. No certbot cron jobs, no --nginx flags,
no "oh the cert expired over the weekend" incidents. It just works, and it keeps working.²

The pieces

Caddy as reverse proxy
Caddy-security (also known as AuthCrunch) for authentication and authorization. It plugs directly into Caddy and adds an authentication portal with OAuth2/OIDC support.

Installation

Caddy supports plugins that get compiled directly into the binary. The canonical way to do this is xcaddy, a build tool that fetches
the plugins you want and compiles everything from source. It works, but it requires a Go toolchain on the server, the build takes a
few minutes, and, going back to the laziness point, it's one more thing to maintain.

The alternative is the official download page on the Caddy website. Select your platform, tick the plugins you want, and it hands you a
pre-built binary. That's it. No Go installation, no waiting, no fuss.

Head to the download page, select Linux amd64 (or your platform), add github.com/greenpau/caddy-security, and download. Then install it:

sudo install /path/to/download /usr/bin/caddy

On SELinux-enabled systems (Fedora, RHEL and friends) you also need to label the binary correctly, otherwise systemd will refuse to run it:

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/caddy

Setting up the service

Caddy doesn't run as root. The recommended approach is a dedicated system user with no login shell and a home directory where Caddy
can store certificates and other state:

sudo groupadd --system caddy

sudo useradd --system \
    --gid caddy \
    --create-home \
    --home-dir /var/lib/caddy \
    --shell /usr/sbin/nologin \
    --comment "Caddy web server" \
    caddy

Create the config directory:

sudo mkdir -p /etc/caddy
sudo touch /etc/caddy/Caddyfile
sudo chown -R caddy:caddy /etc/caddy

The official Caddy repository ships a ready-made systemd unit file, so grab that rather than writing one from scratch:

sudo curl -o /etc/systemd/system/caddy.service \
    https://raw.githubusercontent.com/caddyserver/dist/master/init/caddy.service

The relevant bits of the unit file:

[Service]
User=caddy
Group=caddy
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile --force

ExecReload is worth noting: systemctl reload caddy does a graceful config reload without dropping connections.
You'll use this constantly while tweaking the Caddyfile.

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now caddy
sudo systemctl status caddy

Logs go through journald:

journalctl -u caddy -f

How caddy-security works

The plugin introduces three concepts that work together:

Identity provider: where users actually authenticate. In our case Azure AD via OAuth2, but it works with any OIDC-compliant provider or even a local user database if you need a fallback.
Authentication portal: the login page. It ties together one or more identity providers, manages session cookies, and handles the OAuth2 callback. It lives on a dedicated subdomain (e.g. auth.yourdomain.com).
Authorization policy: the bouncer. Applied per-service, it checks whether the current user has the required roles and redirects to the portal if not.

Azure AD setup

Before touching the Caddyfile, register an application in the Azure Portal:

Azure Active Directory → App registrations → New registration
Name: anything sensible
Supported account types: Accounts in this organizational directory only
Redirect URI (Web): https://auth.yourdomain.com/oauth2/azure/authorization-code-callback

Once created, note down the Application (client) ID and Directory (tenant) ID from the Overview page. Then go to Certificates & secrets → New client secret
and copy the Value immediately; it's only shown once.³

Under API permissions add the Microsoft Graph delegated permissions: openid, email, profile, User.Read, and grant admin consent.

The Caddyfile

{
    email your@email.com
    order authenticate before respond
    order authorize before reverse_proxy

    security {
        oauth identity provider azure {
            realm azure
            driver azure
            client_id YOUR_CLIENT_ID
            client_secret YOUR_CLIENT_SECRET
            tenant_id YOUR_TENANT_ID
            scopes openid email profile
            enable logout
        }

        authentication portal myportal {
            crypto default token lifetime 28800
            crypto key sign-verify YOUR_JWT_SECRET
            enable identity provider azure
            cookie domain yourdomain.com
            cookie path /
            cookie lifetime 28800
            cookie samesite lax
            cookie guess domain
            trust login redirect uri domain suffix yourdomain.com path prefix /

            ui {
                links {
                    "My App" https://myapp.yourdomain.com
                }
            }
        }

        authorization policy protected_services {
            set auth url https://auth.yourdomain.com/login
            enable login hint
            allow roles authp/guest user admin
            crypto key verify YOUR_JWT_SECRET
        }
    }
}

auth.yourdomain.com {
    authenticate with myportal
}

# Protected
myapp.yourdomain.com {
    authorize with protected_services
    reverse_proxy 10.0.0.2:8080
}

anothertool.yourdomain.com {
    authorize with protected_services
    reverse_proxy 10.0.0.3:3000
}

Generate the JWT secret with openssl rand -base64 32.

Two things that needed extra attention

Role remapping is broken in recent builds

caddy-security has a transform user directive that lets you promote authenticated users to named roles based on their email domain:

transform user {
    suffix match email @yourdomain.com
    action add role user
}

In theory this is the right tool: map everyone from your organization to the user role, restrict the authorization policy to allow roles
user admin, and anyone outside your tenant gets nothing even if they somehow authenticated. Clean and explicit.

In practice, as of the current build, the transform doesn't reliably fire after an OAuth2 login. Users end up with only the default
authp/guest role regardless of what the transform says, which means a policy that only allows user will lock everyone out; including
the people you just spent an afternoon trying to let in.

The workaround is to allow authp/guest in the authorization policy. It's not as granular as role mapping, but given that the OAuth2
provider is already scoped to a single tenant, any user who successfully authenticates is implicitly trusted, the gatekeeping is happening
at the Azure level anyway.

This does mean that in practice everyone in the same Azure AD tenant gets access to all protected services. For us that's fine: we're a small
team and internal tools are, well, internal. But the building blocks for something more structured are already there: once transform user is
reliable again, you can map roles per email domain, per specific user, or combine multiple policies to restrict individual services to specific
groups. The concept scales, even if the current implementation needs a nudge.

Keep an eye on the issue tracker if fine-grained role mapping matters for your use case.

Cookies and post-login redirects

Two things need to be correct for the flow to work end to end.

The first is cookie scoping. After login, the browser needs to send the access token cookie to all protected subdomains, not just auth.yourdomain.com.
cookie guess domain handles this automatically. Without it, every request to a protected service finds no token and loops back to the login page indefinitely
(which is as fun as it sounds).

A counterintuitive note from the official docs: don't use a leading dot (.yourdomain.com) for cookie domain. Despite being standard practice in most contexts,
the plugin doesn't support it and things break silently.

The second is the post-login redirect. After a successful login you'd expect to land on the page you were originally trying to reach. Without the right
configuration you land on the portal homepage instead, which is anti-climactic. Two things are needed in combination: set auth url must point to /login
explicitly (not just the root domain), and the portal needs to know which redirect destinations are trusted:

trust login redirect uri domain suffix yourdomain.com path prefix /

Without this the portal ignores the redirect_url query parameter entirely.

The final result

The next time someone asks for a new internal tool, the answer is: spin it up, add two lines to the Caddyfile, reload.
No user database, no password reset flow; nothing.

Everyone with a company account can log in, everyone else can't.

I also added enable login hint so in case anyone needs to login after the previous session expired, it will be presented with the Azure AD login page already filled
with the account of the expired session: easy and effecient.

My laziness form is now complete. Larry Wall would be proud.⁴

Well, not only in that sense. ↩
Caddy also gets an A+ on SSL Labs out of the box, in case you needed another reason. ↩
There are two columns: Secret ID (a GUID) and Value (a long random string). You want the Value. Using the ID will give you a cryptic AADSTS7000215 error and a solid fifteen minutes of confusion. ↩
Larry Wall, creator of Perl, listed the three virtues of a programmer as: Laziness, Impatience, and Hubris. Laziness is first. We are vindicated ↩

Adding a custom DeepSeek model in Junie CLI (No YAML demons required)

Enrico Testori — Mon, 20 Jul 2026 12:11:48 +0000

I switched my Junie CLI default model to DeepSeek last month. The reason wasn't philosophical: Claude and GPT are great, but they cost real money when you're hammering a CLI for hours. DeepSeek is cheaper. Sometimes the best technical decision is the one your wallet makes for you.

The switch itself was anticlimactic. There's no junie model add wizard, no guided setup, and the --help output mentions custom models only in passing with a --model flag that reads like an afterthought. What you actually do is drop a JSON file into ~/.junie/models/ and… that's it. Junie picks it up.

This post documents that process: adding deepseek-v4-pro to Junie CLI, using the actual config format running on my machine right now.¹

Why bother?

Before we touch any config, let's answer the obvious: why not just use the built-in providers?

Because in real life we optimize for different things at different times:

You want…	So you reach for…
Latency minimization	a flash/fast variant
Deep refactors with context	a large-context model
Cost control on long sessions	a cheaper provider
Provider redundancy	a backup endpoint
Experimentation	whatever just dropped on HuggingFace

If your tooling lets you swap models cleanly, you gain operational sanity. And operational sanity is underrated.

Prerequisites

Junie CLI installed. You should already have junie on your PATH. Verify:

   junie --help

A DeepSeek API key. Get one from platform.deepseek.com. You'll need to top up credits.
Basic JSON literacy. No YAML, no TOML, no arcane DSL. Just one JSON file. You've got this.

How Junie CLI discovers custom models

Junie looks for model definitions in two default locations:

~/.junie/models/: global, available to all projects
<project>/.junie/models/: per-project overrides

Each model is a single .json file. The filename becomes the model's identifier within Junie. So ~/.junie/models/deepseek.json registers a model called… deepseek. Creative, I know.

You can also point Junie at additional directories with --model-location <path> if you prefer to keep your model configs in a dotfiles repo or shared volume.

Step 1 — Create the model JSON

Create ~/.junie/models/deepseek.json (or <project>/.junie/models/deepseek.json if you want it scoped to a single codebase):

{
  "id": "deepseek-v4-pro",
  "baseUrl": "https://api.deepseek.com/chat/completions",
  "apiType": "OpenAICompletion",
  "apiKey": "sk-your-deepseek-api-key-here",
  "temperature": 0,
  "primaryModel": {
    "id": "deepseek-v4-pro"
  },
  "fasterModel": {
    "id": "deepseek-v4-flash"
  }
}

Let's unpack what each field does:

Field	Purpose
`id`	The primary model identifier. Junie displays this in the model picker and passes it in API requests.
`baseUrl`	The endpoint Junie POSTs to. DeepSeek's API is OpenAI-compatible, so we point it at their chat/completions endpoint.
`apiType`	Tells Junie which request/response format to use. `"OpenAICompletion"` covers OpenAI, DeepSeek, and most compatible providers.
`apiKey`	Your API key. Yes, it's plaintext in a JSON file. We'll talk about this.
`temperature`	Controls response randomness. `0` means deterministic; bump it to `0.3`–`0.7` for more creative output.
`primaryModel.id`	The model ID sent in the API request body. This must match the DeepSeek model name exactly.
`fasterModel`	(Optional) A lighter/faster model for quick tasks like inline autocomplete or summarization.

A stern word about `apiKey`

Yeah, it's sitting there in plaintext. I know. No, Junie doesn't currently read it from an environment variable for custom models². Your options:

Set restrictive file permissions: chmod 600 ~/.junie/models/deepseek.json. At least other users on the system can't read it.
Use a LiteLLM proxy as middleware (see the LiteLLM section below): this keeps the key out of Junie's config entirely.
Accept it and don't commit the file to a public dotfiles repo. You're an adult.

For what it's worth, Junie stores the key in your home directory, which on a single-user development machine is about as secure as any other dotfile with secrets in it. Not ideal, but not the end of the world either³.

Step 2 — Use the model

Once the JSON file is in place, you have three ways to invoke it:

CLI flag (one-off)

  junie --model custom:deepseek "Explain this function."

This will start junie in interactive mode using the custom model defined previously in json configuration.

Interactive mode

Launch Junie interactively, then pick the model from the selector (usually /model or the equivalent model-switching shortcut):

  junie

Your custom deepseek model should appear in the list alongside the built-in providers.

Settings override (persistent default)

Edit ~/.junie/settings.json and add or edit:

{
  "modelForLaunch": "custom:deepseek",
}

Now every session starts with DeepSeek unless you override with --model.

Step 3 — Verify it works

Before trusting it with a 400-line refactor, run a quick sanity check:

junie --model custom:deepseek "Say hello and confirm which model you're running on."

If the response comes back coherent and the logs show deepseek-v4-pro, you're in business. If you get an auth error, double-check:

The API key is correct and has credits
The baseUrl ends with /chat/completions (no trailing slash weirdness)
The primaryModel.id matches exactly what DeepSeek expects

The bottom line

Junie CLI's custom model system is refreshingly straightforward: drop a JSON file in a directory, and you're done. No YAML anchors, no multi-file inheritance chains, no environment-variable indirection puzzles. Just a flat config that tells the CLI where to send requests and which model ID to use.

Is the plaintext API key ideal? No. But with file permissions and/or a LiteLLM proxy, you can mitigate the concern without adding much friction. For single user dev-machines it's a worth tradeoff.

Now go wire up your DeepSeek model and tell it to write you some code. Or a haiku about YAML. Your call.

Thanks for reading!

If you're looking for the accompanying Italian version of this post… there isn't one. Some topics just work better in English, and CLI config files are definitely in that camp. "Drop un JSON nella cartella models" doesn't quite hit the same way. ↩
If you're reading this from the future and Junie does support apiKeyEnv or similar: congratulations, the timeline is better than mine. Please update this post. ↩
"Not the end of the world" is the security posture equivalent of "it compiles, ship it." Take appropriate precautions. ↩

Balancing flexibility and strictness with lenient Duration deserialization in Kotlin

Enrico Testori — Thu, 16 Jul 2026 10:41:53 +0000

I have written before about Kotlin's Duration class, and its blend of technical sophistication and developer friendliness continues to impress. Recently, a unit test highlighted an important distinction in how Kotlin handles duration parsing. The duration string "1s" works perfectly with Duration.parse(), but fails during JSON deserialization when dealing with real-world data.

This apparent inconsistency is actually a deliberate design choice. The Duration.parse() method is flexible by design, while kotlinx.serialization is intentionally strict to enforce standardization.

What happens under the hood?

Examining Kotlin's source code clarifies this behavior. First, let's look at the Duration class itself:

// In Duration.kt
public inline class Duration internal constructor(
    private val rawValue: Long
) : Comparable {
    // ...
    companion object {
        public fun parse(value: String): Duration = try {
            parseDuration(value, strictIso = false)
        } catch (e: IllegalArgumentException) {
            throw IllegalArgumentException(
                "Invalid duration string format: '$value'.", e
            )
        }
    }
}

A few key points stand out in this implementation:

Duration is an inline class with an internal constructor.
This constructor cannot be used for deserialization due to its internal visibility.
The parse() method intentionally accepts non-ISO formats by explicitly setting strictIso = false.

Now, let's look at how kotlinx.serialization handles the Duration class:

internal object DurationSerializer : KSerializer {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("kotlin.time.Duration", PrimitiveKind.STRING)

    override fun serialize(encoder: Encoder, value: Duration) {
        encoder.encodeString(value.toIsoString())
    }

    override fun deserialize(decoder: Decoder): Duration {
        return Duration.parseIsoString(decoder.decodeString())
    }
}

The serializer makes a deliberate choice to use parseIsoString() for deserialization. Instead of relying on the more permissive parse() method, it enforces the ISO-8601 standard for data integrity.

Implementing a lenient custom serializer

Since we cannot change the built-in behavior of kotlinx.serialization—and generally shouldn't, given the importance of enforcing standards in data exchange—we can create our own custom lenient serializer.

internal object LenientDurationSerializer : KSerializer {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("kotlin.time.Duration", PrimitiveKind.STRING)

    override fun deserialize(decoder: Decoder): Duration {
        return Duration.parse(decoder.decodeString())  // Using the lenient parser
    }

    override fun serialize(encoder: Encoder, value: Duration) {
        encoder.encodeString(value.toIsoString())  // Still formal in output using ISO
    }
}

This serializer accepts casual input formats by using parse(), but ensures formal ISO-8601 formatting on output by using toIsoString(). You can apply it to your data classes using the @Serializable annotation:

data class ProcessDuration(
    @Serializable(with = LenientDurationSerializer::class)
    val duration: Duration
)

// Now both these work:
val formal = """{"duration": "PT1S"}"""
val casual = """{"duration": "1s"}"""

This approach adheres to a fundamental principle of data exchange: be flexible in what you accept, but strict in what you produce. Watch how our duration gets standardized during serialization:

// What goes in
{"duration": "1s"}

// What comes out
{"duration": "PT1S"}

Both strings represent the exact same duration, but the output is standardized. When writing data that might be consumed by other systems, enforcing an ISO format is a necessary practice for maintaining a reliable ecosystem.

Standards vs. reality

While enforcing ISO-8601 in serialization is technically correct, real-world data is often much less organized. Anyone who has dealt with dates, times, and durations in production environments knows the variety of formats that can appear.

In a typical production environment, you might encounter:

Natural language timestamps generated by NLP parsing services (e.g., "Last Monday").
Inconsistent timezones represented in various ways such as "GMT+1", "UTC+1", "+0100", or "Europe/Paris".
Varying date formats originating from legacy systems (e.g., "23-11-2023", "11-23-2023", or "2023/11/23").
Raw millisecond values typically found in Java integrations ("5400000ms").
Excessively verbose XML-style durations from older architectures ("P0Y0M0DT1H30M0S").

The variety of time formats is a persistent challenge in software development. While standards like ISO-8601 are crucial for reliable data exchange, being overly rigid can cause integrations to fail. A pragmatic approach requires us to handle the data as it arrives, gracefully converting it into a standardized format for the future.

Conclusion

Dealing with rigid data formats can sometimes feel like P100Y of ISO-litude¹: an endless century of strict parsing errors and isolated systems. However, examining Kotlin's source code reveals the thoughtful design behind its time packages.

By allowing Duration.parse() to welcome various formats for developer convenience, while keeping kotlinx.serialization anchored to ISO standards, the ecosystem strikes a perfect balance. You do not have to be isolated by strict formats; you simply need a custom serializer to bridge the gap between human-friendly inputs and machine-standardized outputs.

For the uninitiated: P100Y is the valid ISO-8601 duration string for exactly 100 years, with apologies to Gabriel García Márquez ;-) ↩

Fish, Foot and beyond: a terminal setup that finally smells right 🐟👣

Enrico Testori — Wed, 15 Jul 2026 06:59:22 +0000

Picture this: there I was, happily using Tilix for my terminal needs on Fedora.
Split panes, dropdown terminal, the whole shebang. Life was good... until it wasn't.
Recent Fedora updates started making Tilix throw tantrums, and suddenly my trusty terminal setup felt like that friend who keeps flaking on plans.

After some soul-searching (and a lot of Reddit threads), I realized I needed to break down my terminal needs: a rock-solid Wayland-native terminal emulator, a shell that wouldn't make me hate scripting, and a multiplexer that could keep up with modern workflows.

Enter the new trio: Foot, Fish, and Zellij. Yes, I know - between Fish and Foot, this setup sounds like it came from a very weird pet shop. But stick with me here!

Sometimes less is more

For terminal emulation I wanted something simple, stable, and Wayland-native. Foot checked all these boxes and then:

is blazing fast thanks to being written in C
is hardware accelerated rendering (hello, smooth scrolling!)
has minimal dependencies (goodbye, random breakages!)
has simple configuration in a single file
has Sixel support for those fancy terminal graphics

Now, I'll be honest - when people talked about "fast terminals," I used to roll my eyes. How fast does a terminal need to be to show some text? Well, turns out I was wonderfully wrong - you don't realize how much terminal lag affects your workflow until you try a faster one.

Life's too short for boring shells!

Remember the first time you saw someone's terminal autocomplete something magical? That's Fish, all day, every day; no hacky setups required.
Here's what made me fall hook, line, and sinker for it:

Fish remembers your commands and suggests them as you type. It's like having a very eager assistant who actually knows what they're doing. Autosuggestions feel like mind-reading!
Colors! So many colors! And they actually mean something (unlike my old prompt that I made pretty but couldn't remember what anything meant)
No more if [ -f something ] syntax that looks like it came from the 80s. Fish makes scripting feel like actual programming

Sure, there's the occasional "this shell script isn't compatible with Fish" moment, but let's be real - when was the last time you looked at a bash script and thought "wow, this is so intuitive"? Fish makes the trade-off simple: give up some backwards compatibility, get a shell that feels like it was actually designed in this century. And for those rare occasions when you really need to run a bash just prefix it with bash and move on with your life.

Getting on the right Foot

First things first - let's get our Foot in the door (sorry, not sorry).
On Fedora, it's as simple as this:

sudo dnf install foot fish zellij

Easy, isn't it?

And of course, CTRL-ALT-T still spawns my terminal - some habits are worth keeping.

Foot configuration

My Foot configuration is straightforward but purposeful. Let's break it down:

[main]
font=JetBrains Mono:size=16
initial-window-mode=fullscreen
shell=/usr/bin/fish

The main section is minimal:

JetBrains Mono because it's a fantastic monospace font with great readability
terminals starts fullscreen because that's what I ended up doing as first action every time I opened a Tilix in my old setup
last but not least, of course, Fish is set as the default shell because that's the whole point of this setup.

[colors]
# A wild variety of Catppuccin Mocha colors...

While I'm unsure about the theme interaction with zellij, it's working fine, and so I'll briefly give an overview of it. I'm using Catppuccin Mocha - a soothing dark theme that's easy on the eyes. It provides:

A dark background (1e1e2e) with light text (cdd6f4) for good contrast
Carefully chosen colors for different terminal elements
Nice selection colors that don't make you squint (I am colorblind myself)
Special colors for search and jump labels that actually stand out

The URLs are highlighted in a gentle blue (89b4fa) - because clickable links should be obvious but not screaming for attention.
Nothing fancy, no transparency effects or padding tweaks - just a clean, functional setup that gets out of your way while being pleasant to look at.

Fish configuration

My Fish config is minimalist but gets the job done. Let's see what's happening here:

set -x ZELLIJ_AUTO_EXIT true
if status is-interactive
    # Commands to run in interactive sessions can go here
    eval (zellij setup --generate-auto-start fish | string collect)
end

The first line sets up Zellij to automatically exit when the last pane closes (as easy as pressing CTRL-D). It's a quality-of-life setting - when you're done with your last terminal window, Zellij closes cleanly instead of hanging around with an empty session.
Then, we check if we're in an interactive shell (as opposed to running a script)
Lastly, we auto-start Zellij using its built-in Fish integration. The string collect bit ensures all the output from the setup command is handled properly

The result? Every time I open Foot, it automatically launches Fish, which automatically starts Zellij. No manual steps, no "oops I forgot to start my multiplexer" moments - everything just flows.
You know those tiny tasks that seem insignificant? "Oh, it's just two keypresses to start Zellij..." But when you do them 20 times a day, those micro-interruptions add up and break your flow. Now my terminal setup just works, and I can focus on what I actually opened the terminal for in the first place.

Zellij configuration

Nothing, it works out of the box! No question asked.

Out of the box, Zellij shows you what shortcuts you can use right in the status bar.
It's a nice way to learn while you work, until your fingers start doing their thing automatically.

A small note about SSH

Here's a little gotcha I discovered when working with remote servers. By default, Foot uses its own terminal type (foot or foot-direct), which is great for local use but can confuse some remote hosts. Adding this tiny bit to my ~/.ssh/config:

Host *
SetEnv TERM=xterm-256color

This tells SSH to identify as the widely-supported xterm-256color when connecting to remote machines.
It's a simple fix that prevents those annoying "unknown terminal type" errors and weird formatting issues when SSHing into servers.
Sure, you lose some of Foot's fancy features on remote connections, but it's a fair trade for having everything just work™ without
having to install terminal definitions on every server you access.

Future experiments: down the Zellij rabbit hole

While this setup is already solid, I've got my eyes on some interesting Zellij possibilities. First up is the SSH client multiplexing - being able to manage multiple SSH connections in a single Zellij session, with each remote server neatly organized in its own space. Gone would be the days of juggling terminal windows trying to find that one production session.

Zellij's plugin system caught my attention too. Since plugins can be written in any language that compiles to WebAssembly, I might try my hand at building something that scratches my own itches - maybe something to streamline my SSH session management or Git workflow. The project is still quite active, so there's room to play around.

I also want to dig into Foot's session management. The idea is to have a single main Foot window that all new terminal instances connect to when I hit my terminal shortcut. Should be doable with Foot's --server mode and some window manager tweaks. That way I could keep my workflow exactly the same but avoid the window clutter.

These might be solutions looking for problems, but hey - isn't that half the fun of terminal customization? Plus, unlike my Tilix tweaking days, if something breaks, my base setup remains rock-solid. Stay tuned for potential updates if any of these experiments turn out particularly useful!

Final considerations

After a few months with this setup, I can't imagine going back. The combination of Foot's speed, Fish's smarts, and Zellij's flexibility has genuinely improved my daily workflow. Sure, it took a bit of tweaking to get everything just right, but that's the beauty of it - each piece is simple enough that customizing doesn't feel like solving a puzzle.

Looking back at my Tilix days, I realize sometimes "just works" beats "works with all the features." This setup is faster, more stable, and honestly, just more enjoyable to use. Plus, there's something satisfying about having a terminal setup that's both modern and respectful of system defaults. If you're on the fence about modernizing your terminal setup, consider this your sign to take the plunge - your future self will thank you.

Oh, and here's a neat thing about this setup: it doesn't touch your system's default shell at all. Bash remains as the system shell, handling all its traditional duties, while Fish only kicks in when you're actually using the terminal interactively. It's like having your cake and eating it too: the system keeps humming along with bash while you get all the nice Fish goodies.

P.S. No Fish were harmed in the making of this terminal setup, though some bad shell scripts were rightfully abandoned.¹

I realized I haven't left any foot notes in a post about Foot. Had to fix that! ↩

DEV Community: Enrico Testori

Migrating an ancient SVN repo the painful way (tunnel vision included)

Attempt one: the obvious one

Attempt two: divide and conquer

Attempt three: divide, conquer, filter

Attempt four: the Python era

Attempt five: things get worse before they get... no, they just get worse

Attempt six: one dump to rule them all

The light at the end of the tunnel was... a tunnel

Why the boring tool won

Epilogue

How to parse dates with optional parts with Java Instant API

Why (or not) parse partial dates?

A more practical example

Different API, different defaults

Old Date class

Instant class, attempt #1

Instant class, attempt #2

Instant class with optional parts

Conclusion

One login to rule them all: centralized auth for internal tools with Caddy

Why Caddy

The pieces

Installation

Setting up the service

How caddy-security works

Azure AD setup

The Caddyfile

Two things that needed extra attention

Role remapping is broken in recent builds

Cookies and post-login redirects

The final result

Adding a custom DeepSeek model in Junie CLI (No YAML demons required)

Why bother?

Prerequisites

How Junie CLI discovers custom models

Step 1 — Create the model JSON

A stern word about apiKey

Step 2 — Use the model

Settings override (persistent default)

Step 3 — Verify it works

The bottom line

Balancing flexibility and strictness with lenient Duration deserialization in Kotlin

What happens under the hood?

Implementing a lenient custom serializer

Standards vs. reality

Conclusion

Fish, Foot and beyond: a terminal setup that finally smells right 🐟👣

Sometimes less is more

Life's too short for boring shells!

Getting on the right Foot

Foot configuration

Fish configuration

Zellij configuration

A small note about SSH

Future experiments: down the Zellij rabbit hole

Final considerations

A stern word about `apiKey`