Ever had that moment where you upgrade a tool, open your project, and suddenly half your configuration is unreadable? Maybe it's a binary .dat file from a build tool that changed its serialization format. Maybe it's a proprietary project file that the new version "migrated" into something your teammates on the old version can't open.

I've been dealing with this exact problem for over eight years across different stacks, and I keep arriving at the same conclusion: plain text is the most resilient data format we have, and the further you stray from it, the more pain you're signing up for.

The Root Cause: Format Coupling

The core issue isn't that tools upgrade. It's that binary and proprietary formats create tight coupling between your data and a specific version of a specific tool.

Here's what typically happens:

1. Tool version 2.x writes config in a binary format
2. Tool version 3.x changes the internal schema
3. Your CI pipeline, your coworker's machine, or your Docker image is still on 2.x
4. Everything breaks, and nobody knows why until someone diffs the tool versions

You can't git diff a binary file. You can't grep through it. You can't hand-edit it when things go sideways at 2 AM during an incident. The format itself becomes a liability.

Plain text formats — YAML, JSON, TOML, INI, even raw .conf files — don't have this problem. They're version-agnostic by nature. A text file written in 1994 is still perfectly readable today.

Step 1: Audit Your Non-Text Dependencies

Before you can fix the problem, you need to find it. Run a quick audit of your project directory to identify binary config and data files:

# Find files that git considers binary in your repo
git grep -Il '' -- ':/' | sort > /tmp/text_files.txt
git ls-files -- ':/' | sort > /tmp/all_files.txt
comm -23 /tmp/all_files.txt /tmp/text_files.txt

This gives you a list of every file git treats as binary. Some of these are fine (images, compiled assets). But if you see config files, lock files, or data files in that list, those are your risk points.

Another quick check — look for files that have changed but produce useless diffs:

# Show files where git diff produces "Binary files differ"
git log --oneline --diff-filter=M --name-only HEAD~20..HEAD | \
  sort -u | while read f; do
    git diff HEAD~1 -- "$f" 2>/dev/null | grep -q "Binary files" && echo "$f"
  done

Every file that shows up here is a file you can't meaningfully review in a pull request. That should worry you.

Step 2: Convert What You Can

A surprising number of tools support plain text alternatives that people just don't use because the binary format is the default.

SQLite databases used as config stores — I've seen projects use SQLite for settings when a simple JSON or TOML file would do. If you're not querying the data relationally, you don't need a database file.

import json
import sqlite3

def migrate_settings_to_json(db_path: str, json_path: str):
    """Pull key-value settings out of SQLite into a plain JSON file."""
    conn = sqlite3.connect(db_path)
    cursor = conn.execute("SELECT key, value FROM settings")
    settings = {row[0]: row[1] for row in cursor.fetchall()}
    conn.close()

    with open(json_path, "w") as f:
        json.dump(settings, f, indent=2)  # human-readable, diffable, greppable

Protobuf or MessagePack for local config — These are great for network serialization where performance matters. They're terrible for config files that humans need to read and edit. Swap them for TOML or YAML.

IDE project files — Many IDEs generate binary or XML-heavy project files. Most modern ones also support simpler formats. VS Code's settings.json is a good example of getting this right — it's just JSON, and it diffs cleanly.

Step 3: Enforce Plain Text at the Boundary

Once you've converted what you can, prevent regression. Add a pre-commit hook that flags new binary files:

#!/usr/bin/env bash
# .git/hooks/pre-commit — warn on new binary files

binary_files=$(git diff --cached --diff-filter=A --name-only | while read f; do
    # check if file is binary using the file command
    mime=$(file --brief --mime-encoding "$f" 2>/dev/null)
    if [[ "$mime" == "binary" ]]; then
        echo "$f"
    fi
done)

if [[ -n "$binary_files" ]]; then
    echo "WARNING: New binary files detected:"
    echo "$binary_files"
    echo ""
    echo "If these are config/data files, consider using a plain text format."
    echo "To proceed anyway, use: git commit --no-verify"
    exit 1
fi

This doesn't block images or compiled assets from people who know what they're doing, but it does force a conversation when someone adds a new binary config file.

Step 4: Structure Your Plain Text for Longevity

Plain text alone isn't enough. You need plain text that's structured well enough to survive the next decade. A few principles I've learned the hard way:

• Pick a format with a spec. TOML has a spec. YAML has a spec. Your custom key=value format does not. When your parsing breaks, a spec gives you something to point to.
• Avoid format features you don't need. YAML's anchors, aliases, and type coercion have caused more bugs than they've saved keystrokes. Use the simplest subset that does the job.
• Include comments. One of the biggest advantages of plain text config is that you can explain why a setting exists, right next to the setting itself. Use that.
• One concern per file. A single config.yaml with 400 lines covering database, auth, logging, and feature flags is going to cause merge conflicts constantly. Split it.

# database.toml — connection settings for the primary datastore
# Last reviewed: 2026-03-15

[connection]
host = "localhost"
port = 5432
name = "appdb"

# Pool size tuned after load testing in Q1.
# Going above 25 caused connection timeouts on the read replicas.
pool_size = 20
pool_timeout = 30

That file is readable by any TOML parser in any language, by any version of any tool, and by any human with a text editor. Try saying that about a binary config blob.

Why This Matters More Than You Think

Plain text isn't just about readability. It's about operational resilience.

When something goes wrong in production, your first instinct is to look at what changed. If your config is in plain text, git log -p tells you exactly what changed, when, and who did it. If it's binary, you're guessing.

Plain text files are also trivially composable. You can cat them together, sed them in a pipeline, template them with envsubst, validate them with a JSON schema. The entire Unix philosophy was built on the assumption that data flows as text between small programs. When you fight that assumption, you're fighting decades of tooling.

And here's the longevity argument that really convinced me: I can still read every plain text file I created in college. I cannot say the same for my Word documents, my old Keynote files, or the project files from any IDE I used before 2015.

Prevention: Questions to Ask Before Adding a New Format

Before you introduce any new file format to a project, ask these three questions:

• Can I diff it? If git diff produces gibberish, that's a code review problem waiting to happen.
• Can I read it without the tool that created it? If the tool disappears tomorrow, can you still access your data?
• Can I edit it with a text editor in an emergency? When the GUI is down and the CLI is broken, vim is still there.

If the answer to any of these is no, you need a very good reason to use that format. "It's the default" is not a good reason.

Plain text has survived every technology shift of the last fifty years — mainframes, PCs, the web, mobile, cloud, containers. It'll survive whatever comes next. Your binary config format probably won't. Choose accordingly.