Here are things you can do with it that have nothing to do with CI.

How it works in 30 seconds

A workflow is a YAML file in .github/workflows/. It has:

• triggers (on:): a push, a new issue, a schedule, a button click
• jobs that run on a fresh virtual machine
• steps, each either a shell command or a reusable action

That’s it. Anything you can script, you can trigger.

1. Host a website

This blog is built by Actions. Every push to main builds the site with Hugo and publishes it to GitHub Pages. No server, no bill.

on:
  push:
    branches: [main]

The official actions/upload-pages-artifact and actions/deploy-pages actions do the publishing.

2. Run things on a schedule

Actions supports cron:

on:
  schedule:
    - cron: "0 14 * * 1"   # every Monday at 14:00 UTC
  workflow_dispatch:        # plus a manual "Run" button

Uses: nightly data scrapes, weekly reports, checking whether a website is up, rebuilding a site so “posted 3 days ago” stays accurate.

Know this:

• Times are in UTC.
• Scheduled runs can start late when GitHub is busy, sometimes by many minutes. Don’t use it for anything that must happen at an exact second.
• In public repos, scheduled workflows are automatically disabled after 60 days without repository activity. GitHub emails you first.

3. Keep a file updated automatically

A workflow can edit files and commit them back. For example, a profile README that always lists your latest blog posts:

permissions:
  contents: write

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: ./scripts/update-readme.sh
      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add README.md
          git diff --cached --quiet || git commit -m "Update latest posts"
          git push

The git diff --cached --quiet || part only commits if something actually changed, so you don’t get empty commits.

4. Manage issues and pull requests

• Auto-label PRs by which files they touch (actions/labeler).
• Welcome first-time contributors with a friendly comment.
• Close stale issues after a period of inactivity (actions/stale). Use gently; closing people’s issues automatically can feel rude.
• Enforce PR title formats for changelogs.

Triggers like issues, issue_comment, and pull_request make this easy.

5. Build a ChatOps bot

A workflow can react to comments. Someone types /deploy staging on a PR, and a workflow checks their permissions and runs the deploy. Check the comment author’s permission level before doing anything, or anyone on the internet can trigger it.

6. Watch other things on the internet

A scheduled job can:

• check whether your site returns 200 and open an issue if not
• check whether a dependency released a new version
• watch a page for changes and notify you

GitHub isn’t built for real-time monitoring, but for “check once an hour and tell me,” it’s plenty.

7. Trigger workflows from outside GitHub

With repository_dispatch, anything that can send an HTTP request with a GitHub token can start a workflow: a script on your server, a webhook from another service, a phone shortcut. The token needs write access to the repo, so treat it like a password.

on:
  repository_dispatch:
    types: [rebuild-site]

8. Generate release artifacts

Build binaries for Windows, macOS, and Linux in parallel with a matrix, then attach them to a GitHub Release automatically when you push a version tag.

on:
  push:
    tags: ["v*"]

Things you should know

Least privilege. Set permissions: explicitly in every workflow. Give each workflow only what it needs.

Secrets and forks. Workflows triggered by pull requests from forks don’t get your secrets, on purpose. Be very careful with the pull_request_target trigger: it runs with your secrets and write permissions, and if it checks out and runs the fork’s code, a stranger’s PR can steal your secrets.

Pin actions. A third-party action is someone else’s code running with your permissions. Pin it to a full commit hash rather than a tag if you don’t fully trust the author:

- uses: some-author/some-action@8f4b7f84864484a7bf31766abe9204da3cbe65b3

Free isn’t unlimited. Public repos get free minutes on standard runners. Private repos get a monthly allowance, then usage is billed. Check the current limits before you build something heavy.

Closing thought

Think of every repo as coming with a small, free, scriptable computer that listens for events. CI is one thing you can do with it. Your imagination and the terms of service are the rest.

Let’s take it apart.

Setup

Make a throwaway repo so we can poke at it safely:

mkdir git-internals && cd git-internals
git init -b main
echo "hello" > hello.txt
git add hello.txt
git commit -m "first commit"

Now look inside:

ls .git

You’ll see things like HEAD, config, index, objects/, and refs/. We’ll go through the important ones.

Objects: the actual data

Git stores everything as objects in .git/objects. There are four kinds:

• blob: the contents of a file (just the bytes, no name)
• tree: a directory listing (names, permissions, and pointers to blobs and other trees)
• commit: a snapshot (a pointer to one tree, parent commits, author, message)
• tag: an annotated tag (a pointer to an object, plus a message)

Every object is named by the hash of its contents. That’s why Git is called a content-addressable store: the address is the content’s fingerprint.

Finding our file

Ask Git what hash “hello\n” would get as a blob:

echo "hello" | git hash-object --stdin

ce013625030ba8dba906f756967f9e9ca394464a

You’ll get this exact hash on any machine, in any repo. Same content, same hash, always.

Now find it on disk. Git splits the hash: the first two characters are a folder, the rest is the file name:

ls .git/objects/ce/

There it is. The file is zlib-compressed, so cat shows garbage. Git can read it for us:

git cat-file -t ce0136   # type
git cat-file -p ce0136   # contents

blob
hello

Or decompress it yourself with Python to see the raw format:

python3 -c "import zlib,sys; print(zlib.decompress(open(sys.argv[1],'rb').read()))" .git/objects/ce/013625030ba8dba906f756967f9e9ca394464a

b'blob 6\x00hello\n'

That’s the entire format: the type, a space, the size in bytes, a null byte, then the content. The hash is SHA-1 of exactly that string.

Walking from a commit down to a file

Start at the latest commit:

git cat-file -p HEAD

tree aaa96ced2d9a1c8e72c56b253a0e2fe78393feb7
author ...
committer ...

first commit

Follow the tree:

git cat-file -p aaa96c

100644 blob ce013625030ba8dba906f756967f9e9ca394464a    hello.txt

That’s the whole chain: commit → tree → blob. A commit doesn’t store differences; it points to a full snapshot. Git saves space because unchanged files keep the same hash, so every commit just points to the same blob again.

(Your commit hash will differ from mine, because a commit includes your name and the exact time. The tree and blob hashes will match, because they depend only on file names and contents.)

Refs: names for hashes

Nobody wants to type 40-character hashes. Refs are files that hold them:

cat .git/refs/heads/main

That’s it. A branch is a text file containing a commit hash. Creating a branch is writing one small file. That’s why branches in Git are so cheap.

And HEAD?

cat .git/HEAD

ref: refs/heads/main

HEAD usually points to a branch, which points to a commit. When you’re in “detached HEAD” state, HEAD contains a commit hash directly instead.

If a branch seems to be missing from refs/heads, check .git/packed-refs. Git bundles refs into that one file to save space.

Packfiles: how Git stays small

Storing every version of every file as a separate compressed object would get big. So Git periodically packs objects into .git/objects/pack/, storing similar objects as deltas (differences) against each other.

git gc
git count-objects -v

Loose objects disappear into a .pack file with a matching .idx index. To peek inside:

git verify-pack -v .git/objects/pack/pack-*.idx | head

Interesting detail: this is the only place Git uses deltas. Your history is modeled as snapshots; deltas are just a storage optimization underneath.

The index: the staging area is a file

git add writes to .git/index, a binary file listing what the next commit will contain. You can see it in readable form:

git ls-files --stage

100644 ce013625030ba8dba906f756967f9e9ca394464a 0	hello.txt

The staging area isn’t a concept. It’s a file.

The reflog: your safety net

Every time HEAD or a branch moves, Git writes a line to .git/logs/:

git reflog

This is how you recover from almost anything: a bad reset, a deleted branch, a rebase gone wrong. Find the hash from before the mistake and:

git branch rescue <hash>

Unreachable objects are only deleted by garbage collection after a grace period (two weeks by default for loose objects). Reflog entries last 90 days, but only 30 for commits that are no longer on any branch, which is what a bad reset or rebase leaves behind. You have time.

Build a commit with no porcelain

For the grand finale, make a commit using only low-level commands:

echo "built by hand" | git hash-object -w --stdin
# note the hash, then:
git update-index --add --cacheinfo 100644 <blob-hash> handmade.txt
git write-tree
# note the tree hash, then:
git commit-tree <tree-hash> -p HEAD -m "a commit made by hand"
# note the commit hash, then:
git update-ref refs/heads/main <commit-hash>

Run git log. Your hand-built commit is there, indistinguishable from any other. (git status will call handmade.txt deleted, because so far the file only exists in the repo. git restore handmade.txt writes it out.) Every friendly Git command is built from pieces like these.

Things you should know

• Don’t edit .git by hand in real repos. Explore in a throwaway one.
• SHA-256 repos exist. Git supports git init --object-format=sha256, which gives 64-character hashes. The structure is the same.
• Refs won’t always be files. Git 3.0 will switch new repos to the reftable format, and you can try it today with git init --ref-format=reftable. There, branches live in binary tables under .git/reftable/, and .git/HEAD just says ref: refs/heads/.invalid. Commands like git branch and git rev-parse work the same either way.
• Hashes include everything. Change one byte of a file, one character of a commit message, or a timestamp, and the hash changes, along with every commit after it. That’s why rewriting history changes all later commit IDs.

Closing thought

Once you’ve seen that a branch is a text file and a commit is a pointer to a snapshot, most of Git’s “weird” behavior stops being weird. It’s a database. Now you can read it.

You could read them all. Or you could let Git find the guilty one in about nine steps.

The idea: binary search through history

git bisect takes two points: a commit where things were good and one where they’re bad. It checks out the commit halfway between and asks you which it is. Then it throws away the half that can’t contain the bug and repeats.

Each step halves the search. 400 commits takes at most 9 steps. 10,000 commits takes at most 14.

Manual bisect

git bisect start
git bisect bad                 # the current commit is broken
git bisect good v2.3.0         # this tag was fine

Git checks out a commit in the middle and tells you roughly how many steps are left. Test it, then tell Git:

git bisect good    # this one works
# or
git bisect bad     # this one is broken

Repeat until Git prints:

a1b2c3d is the first bad commit

When you’re done, go back to where you started:

git bisect reset

You can also give both endpoints up front:

git bisect start HEAD v2.3.0

The real magic: git bisect run

If you can write a script that tells good from bad, Git will do the whole search without you:

git bisect start HEAD v2.3.0
git bisect run ./check.sh

Git checks out each candidate commit, runs your script, and reads its exit code:

Your test suite is often the script already:

git bisect run pytest tests/test_login.py
git bisect run cargo test parse_header
git bisect run npm test

Writing a good check script

The script should test only the bug you’re hunting. A full test suite may fail for unrelated reasons partway through history.

#!/bin/sh
# check.sh: exit 0 if the bug is absent, 1 if present, 125 if we can't tell

# If it doesn't build, we can't test this commit. Skip it.
make >/dev/null 2>&1 || exit 125

# The actual check
./app --version | grep -q "expected output" && exit 0 || exit 1

A few tips:

• Use 125 for “can’t test.” Commits that don’t compile, or that predate the feature entirely, should be skipped, not marked bad. Otherwise Git blames the wrong commit.
• Keep the script outside the repo, or untracked. Bisect checks out old commits, and an old commit might not have your script, or might have an older version of it.
• Make it fast. It runs once per step.
• Make it deterministic. A flaky test sends the search in the wrong direction and gives a confident, wrong answer.

Useful extras

Skip a commit by hand:

git bisect skip

See or replay the session. If you mark a commit wrong, save the log, edit out the mistake, and replay it:

git bisect log > bisect.log
# edit bisect.log
git bisect reset
git bisect replay bisect.log

Visualize what’s left:

git bisect visualize --oneline

Hunt for things that aren’t bugs. “Good” and “bad” are just labels. You can rename them:

git bisect start --term-old=fast --term-new=slow
git bisect fast v2.3.0
git bisect slow HEAD

Now you can find the commit where something got slow, or the commit where a feature first appeared.

Ignore merged-in side branches. On a repo with many merges, --first-parent only follows the main line of history:

git bisect start --first-parent

Things you should know

• Bisect needs a clean working tree. Commit or stash your changes first.
• It finds the first bad commit, not the cause. Sometimes the “first bad commit” just exposed a bug that was already there. Read the diff before blaming anyone.
• Small commits make bisect better. If the guilty commit changed 3,000 lines, knowing which commit it was doesn’t help much. Another reason to commit in small, focused steps.

Closing thought

The next time you catch yourself scrolling through git log trying to guess when something broke, stop. Write a ten-line script, run git bisect run, and go get a coffee.

Most people do one of these:

• git stash, switch branches, fix, switch back, git stash pop, pray.
• Commit a “WIP” mess they’ll have to clean up later.
• Clone the whole repo again into another folder.

There’s a better option that has been in Git since 2015: worktrees.

What a worktree is

A normal repo has one working directory: the folder where your files live. A worktree is an extra working directory attached to the same repo. Each one can have a different branch checked out, and they all share the same history, objects, and remotes.

It’s like a second clone, except:

• It’s instant. Nothing is downloaded or copied.
• It uses almost no extra disk space for history.
• A commit made in one worktree is immediately visible from the others.

The basics

Create a worktree for an existing branch:

git worktree add ../myproject-hotfix hotfix

Now ../myproject-hotfix is a full working folder with the hotfix branch checked out. Your original folder is untouched, half-finished feature and all.

Create a worktree and a new branch at the same time:

git worktree add -b fix-login ../myproject-fix-login main

That makes a new branch fix-login starting from main, checked out in a new folder.

See all your worktrees:

git worktree list

When you’re done, remove it:

git worktree remove ../myproject-hotfix

If you deleted a worktree folder by hand instead, clean up Git’s records of it:

git worktree prune

Daily uses

Emergency fixes without disruption. The scenario above. Your feature work stays exactly where you left it.

Reviewing a pull request while you keep working. Check out the PR branch in its own worktree, run it, test it, and delete the folder when you’re done.

Comparing behavior side by side. Run the old version and the new version at the same time in two terminals.

Long builds. Kick off a slow build or test suite in one worktree and keep coding in another. Your edits won’t change files out from under the running build.

Running AI coding agents in parallel. Give each agent its own worktree so they don’t overwrite each other’s changes.

Things you should know

One branch, one worktree. Git won’t let you check out the same branch in two worktrees at once, because commits in one would confuse the other. If you try, you’ll get an error. (There’s a --force flag, but you almost never want it.)

Some things are shared, some aren’t. Commits, branches, tags, remotes, config, and the stash are shared across all worktrees. The working files, the index (staging area), and HEAD are per-worktree.

Untracked files don’t come along. A new worktree starts clean. Your .env, node_modules, or build folders from the main worktree won’t be there. You’ll need to reinstall dependencies or copy config.

Keep worktrees outside the main folder. Putting a worktree inside your main working directory makes tools, file watchers, and searches see duplicate files. A sibling folder (../project-something) is the usual convention.

Lock worktrees on removable drives. If a worktree lives on a USB drive or network share that isn’t always mounted, lock it so prune doesn’t delete its records:

git worktree lock ../usb-worktree --reason "on external drive"

A bare-repo trick

Some people go further: they clone a repo as bare (no working files at all) and do everything through worktrees:

git clone --bare git@github.com:you/project.git project/.bare
cd project
echo "gitdir: ./.bare" > .git
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch
git worktree add main
git worktree add feature-x

The git config line matters. A bare clone doesn’t set up remote-tracking branches, so without it, git fetch quietly never updates them.

Now every branch you work on is a tidy subfolder of project/. It takes a little getting used to, but it makes “which branch am I on?” a question your file manager answers.

Closing thought

git stash is fine for thirty seconds. For anything longer, stop juggling and give each branch its own folder.

Here’s the detail that stuck with me: when a volunteer like that heads out, nobody writes down that they went. There’s no dispatcher, no roster, no log. If they stop answering their phone, nothing notices. Eventually, someone realizes they haven’t heard from them in a while.

One dispatcher, interviewed afterward by disaster researchers, described trying to keep track of who was out on a boat and who had come back, and asking the question nobody could answer: “can we account for everyone?”

So my teammate and I built an app that answers it. If you go out and stop checking in, it notices. And if you stay quiet long enough, it files a report about you, at the last place anyone knew you were, so someone can come find you.

It’s called DiresQ. We built the first version in a single 14-hour night for Katy Youth Hacks 2026, the first hackathon either of us had ever entered. Then we kept building it and entered it in four more. It placed 3rd in the Software Development track at Reverie Hacks 2026, an online hackathon with more than 2,100 participants and 423 submitted projects.

But placing isn’t the interesting part. The interesting part is the three times our own code lied to us, and looked completely fine doing it.

Five responders on scene. One goes quiet. At fifteen minutes the board turns red, and the report on the right files itself.

Every disaster app tracks the disaster

Crowdsourced flood maps show where the water is. Social media shows who’s asking for help. Agencies have dispatch systems, but only for their own people: on a roster, carrying a radio, answering to an incident commander.

A neighbor with a boat is none of those things. Every tool we looked at mapped the incident. We couldn’t find one that kept a list of the people walking into it.

Here’s DiresQ in about sixty seconds:

1. A neighbor’s street is flooding. She files a report: “Water rising, 2 trapped.” It lands at the top of the feed, reading 0 responding.
2. You have a boat. You see her report sitting above one that already has six people on it, so you join hers and type how long before anyone should start worrying about you: “30 min.” Your row on the accountability board turns blue.
3. You arrive and mark yourself on scene. Your row turns green. It’s worse than she said, so you tag the report needs more help, and it climbs the feed.
4. Then you go into a flooded house and stop checking in. Thirty minutes pass. Your row turns red, showing your last known position and how long since anyone heard from you.
5. Fifteen minutes after that, the server stops waiting for someone to notice. It files a new report, about you, at your last known position.

Nobody had to notice you went quiet. That’s the product. Everything else is how you get there.

But the first version we designed would have made things worse.

Our first design was wrong

We started with the obvious model: dispatch. One responder claims one report, it’s locked, and nobody else can take it. No two people driving to the same address.

Then we read about Kathmandu in 2015 and Mexico City in 1985. In both, huge numbers of volunteers converged on a few highly visible collapse sites, while sites nearby had nobody at all. People dug at the building that was on television.

The real failure in a disaster isn’t two people going to the same address. It’s six hundred people going to the same address while the street two blocks over has no one. A claim lock fights the wrong problem, and sometimes a collapse genuinely needs forty people.

So we deleted it. Any number of people can join any report. Instead of preventing convergence, DiresQ makes it visible:

• Every report shows how many people are already on it.
• People on scene can say “we need more” or “we’re overstaffed,” and the feed reorders so the next person goes where the help isn’t.
• When people on scene disagree, the most cautious answer wins. An optimistic report should never be able to drown out a call for help.
• A report nobody is going to sorts above one that’s merely short-handed. A gap is worse than a queue.

That was the design. Building it was a different story.

The first night, on two clocks

The first version was built for Katy Youth Hacks, in one 14-hour window. For me, it ran from 6pm to 8am. For my teammate, Skythe, the same fourteen hours ran from 8am to 10pm. We were building the same app at opposite ends of the day. We met on the Coding for Teens Discord server, if you’re looking for a teammate of your own.

It was also my first time being part of a real team, and it felt like a preview of an actual software job. We started with a call to introduce ourselves and plan, then hung up and got to work. From there it was a steady stream of DMs, with a quick call every so often to check in. And in between came those long stretches where you just lock in and code for hours.

The first time the app actually worked was amazing. But it didn’t feel like a finish line. It felt like the start of a fire. It felt good, and I immediately wanted more.

We split the code by folder, not by feature. Skythe owned the frontend: the page templates and styles. I owned the backend: the Flask app, the database schema, and the API. The one rule: new files are free, but editing someone else’s needs a message first. We changed code in parallel all night and never once had a merge conflict.

We did have one very strange commit. At some point that night, a single commit touched 39 files, added 10,462 lines, deleted 10,462 lines, and changed nothing at all. We develop on Windows and deploy on Linux, and every line ending in the repo had silently flipped. The fix was a file most repos don’t have: .gitattributes. (I liked it enough to write a whole post about it.)

We also leaned on four small libraries I’d written and published to PyPI before the hackathon: timefuzz turns “back in a couple hours” into a real deadline, vitalscore runs the START triage protocol, pygeospy does the map math, and patchnotes checks our changelog on every push.

By 8am, the git log had 65 commits from that night, and the repo had 12,579 lines of code.

Then our plan fell apart, and it was my fault.

The plan didn’t survive contact

The plan said the backend would put up fake “stub” API endpoints in the first hour, so the frontend could build against them without waiting.

The stubs were my job. I never wrote them. I was building the interesting part instead.

Skythe didn’t wait, which was the right call. The git log tells the story: Skythe’s first commit landed at 6:05pm my time, and by the time my first backend commit showed up at 7:40pm, there were already five complete pages in the repo, built as server-rendered templates that don’t need the API at all. That turned out to be the better design: the whole app works with JavaScript switched off. That’s exactly what you want from a tool for the worst day of someone’s life, running on an old phone with one bar of signal.

What it cost us was agreement. With no stubs and no conversation, we each guessed at the other’s names, and three came out different:

The frontend’s names won all three times, because Skythe’s templates were real, working software and my schema was still a document nobody had run.

The lesson I took: unblock other people before you build your favorite part. Fifteen minutes agreeing on names would have saved every one of those mismatches.

And then the code started lying to us.

Lie #1: the classifier that scored 100%

Someone filing a report at 2am from a flooded house gets asked to pick a severity from a dropdown. They don’t know. They’re scared, and they aren’t trained.

So DiresQ suggests one. I hand-wrote a small naive Bayes classifier, trained on 55 hand-labeled example reports. It reads your description, suggests a priority, and shows you the exact words that drove the decision. It runs in about a tenth of a millisecond with no network, and the moment you touch the dropdown yourself, it stops touching it.

We tested it the obvious way first: run it over its training data. It scored 100%.

That number was worthless. It had simply memorized its 55 examples. So we measured it properly: hold one report out, train on the other 54, predict the one it had never seen, and repeat that 55 times.

Nine points better than guessing, and wrong in the worst possible direction. “Child not breathing properly” came back MEDIUM. “Gas smell, whole street evacuating” came back LOW.

The fix was a list of the phrases the START triage protocol treats as immediate, which took it to 75%. That measurement now runs on every push, and the build fails if it ever drops below 68%. It’s still wrong one time in four, which is survivable only because it’s a suggestion in a dropdown you control, not a decision.

Of everything that weekend, this is what taught me the most: not building the model, but learning how to test one. Working out why it scored 100%, fixing it, and publishing both numbers instead of the flattering one.

Then we found a subtler lie. A report typed in Spanish, “mi madre no puede respirar” (“my mother can’t breathe”), came back LOW, 51% confident. Naive Bayes can’t say “I don’t know.” When every word is unfamiliar, it falls back to its base rates and outputs a label that looks like knowledge. Katy, Texas, where we set our demo, is more than a quarter Hispanic or Latino, so that isn’t a hypothetical. Now, when the model doesn’t recognize the wording, it gives no suggestion and says why.

Why not just use an AI model? Three reasons, in order:

1. It has to explain itself. The words DiresQ shows you are the actual math behind the decision, not a separately generated explanation that could disagree with it.
2. It has to be honest about being wrong. A confident paragraph from a language model is much harder to doubt, and confidently wrong sends boats to the wrong street.
3. It has to work with the cell towers down. No download, no API key, no network. So the same trained model runs on the phone, too.

(We did use AI tools while building DiresQ, for code and documentation. There’s just none inside the product.)

Putting the model on the phone led to the strangest bug of the whole project. We’ll get there. First, the alarm.

Lie #2: the alarm that could die quietly

The dead man’s switch, the part that files a report when you go quiet, started life as a background timer inside the app.

Then we thought about what happens when a background timer crashes: nothing. No error on screen. The board keeps rendering, every row stays green, and green reads as “everyone’s fine” when it really means “nobody’s checking.”

So we deleted the timer. DiresQ never stores whether someone is overdue. It works that out fresh every time someone loads the board, and runs the escalation check at the same moment. There’s nothing to forget to start, and nothing that can silently die.

That left one honest dependency: if nobody has the board open, nothing gets checked. So the board shows when the check last ran, “checked 2s ago,” and turns amber if it ever stops. The thing that notices when people go quiet won’t go quiet without saying so. (There’s also a command you can run on a schedule, so the alarm doesn’t depend on someone having a tab open.)

That became the theme of the whole project: the failure that matters is the one that leaves no trace.

Lie #3: bugs that looked like working features

Every bug below passed its tests, threw no errors, and looked fine. We only found them by using the code for real.

• Error messages that went nowhere. The backend reported errors in five places, like a wrong password, but no page ever displayed them. A rejected form just sat there looking frozen.
• A required field that wasn’t. The report form required hidden latitude and longitude fields. Browsers skip validation on hidden fields, so a report submitted without a map pin saved with no location: invisible on the map, forever.
• A database that broke on the second run. A table added late got created but never dropped, so rebuilding an existing database stopped halfway and left it in pieces. Every test passed, because tests start from an empty database, and empty is the one case that always works.
• A phishing hole we built by accident. After you logged in, the app sent you to whatever address the link’s ?next= parameter said. So a link to our real login page, on our real domain, could hand you straight to someone else’s site. The tests only checked that logging in redirected you, which it did.
• A map that would run whatever people typed. Report titles went into the map’s pop-ups as raw HTML. A title containing the right HTML, like an image tag with an error handler, would have run its code in the browser of everyone who opened the map. We caught it at 4:36am and rebuilt the pop-ups so that text is only ever treated as text.
• A security check that searched nothing. Our CI scanned for hardcoded secrets. The fix landed four minutes after the scan did: a quoting mistake in the YAML crashed it before it searched a single file, and the failure looked like any other. We rewrote it in Python and tested it against a deliberately leaky file to prove it catches real ones.

And the strangest one, from putting the classifier on the phone. We ran every example through both versions, Python on the server and JavaScript in the browser, with a test that fails on any disagreement. It found a bug within minutes: the words shown behind a suggestion were sorted by floating-point noise, because Python and V8 (the JavaScript engine in Chrome and Node) round logarithms differently in the very last bit. That bug had been in the Python since day one. With only one implementation, it was invisible.

The things we refused to build

A tool that looks like an emergency service can do real harm by looking more capable than it is. So we wrote down everything DiresQ doesn’t do, and put that list inside the app.

• No identity verification. Anyone can sign up. Doing it properly needs real ID checks, and there’s no honest weekend version. A fake check, like email confirmation, would be worse than nothing, because it looks like verification without being it.
• No calling 911. DiresQ never contacts emergency services or implies that it has. The worst failure would be someone filing a report and believing help is on the way.
• No radio, yet. A check-in packs into 22 signed bytes, small enough for a LoRa long-range radio, with a replay counter so a captured packet can’t simply be sent again. There’s even a gateway script to forward packets to the server. What doesn’t exist is the radio: we don’t have the hardware, and untested code isn’t a feature. It’s a file that looks like one.

DiresQ has never been used in a real disaster, and it shouldn’t be until someone who does this professionally has taken it apart.

It wasn’t one night

The 14 hours were only Katy Youth Hacks. That wanting-more feeling from the first night never went away: we kept building DiresQ and entered it in four more hackathons: STEMist Hacks IV, Reverie Hacks, the Girls In STEM Global Hackathon, and the CSC Summer Impactathon. Here’s roughly what the git log says, in my time zone:

The hours run from the first commit to the last in each session, so the real total is higher: reading, testing, and filming between commits don’t show up. Even so, that’s about 39 hours of commits over just over four days: 147 commits (plus five setup commits from the week before), four tagged releases, and a docs site that rebuilds itself from the repo on every push. The test suite grew from 344 tests in our Katy Youth Hacks submission to 606 test functions. GitHub Actions has run 288 times so far, mostly the tests, the security scan, and the changelog check that run on every push.

Here’s what those extra hours bought:

• It works with no signal. Reports and check-ins save to your phone first and send themselves when you reconnect. Each one gets its ID before the first attempt, so a phone that dies mid-send can’t file the same emergency twice.
• It passed an accessibility audit. A WCAG 2.1 AA audit found 22 issues across four passes, six of them critical. We fixed all 22, and a test holds each fix in place.
• It turned into a paper. By the third evening, we realized the interesting claim wasn’t the app. It was the gap. So we read the research to check whether the gap was real, going back to the primary sources. One commit message from that night: “Read the 1957 original instead of citing it secondhand.” That reading became an eleven-page preprint, which says plainly that DiresQ has no users, no deployment, and no evaluation.
• It learned to be filmed. The dead man’s switch only does something after fifteen minutes of silence, which makes for a terrible demo video. So DiresQ got a scaled clock: at 60x speed, a responder goes overdue five seconds after the page loads, and the report about them arrives fifteen seconds after that. It’s the exact same escalation code, and a banner on screen admits that time is sped up.

Then we entered Reverie Hacks 2026.

3rd place

I found out in the middle of a marine biology lecture. We got a two-minute break to drink some water and rest our brains, I checked my phone, and there was a DM from Skythe: we’d placed.

I was freaking out internally. All I wanted to do was watch the hackathon’s showcase video on YouTube, check Discord, check Devpost, check everything. Instead, I had to sit through the rest of the lecture.

The second it ended, it all hit me, and every hour felt worth it. I even told my parents, even though they don’t understand any of the coding and tech stuff.

Reverie Hacks drew more than 2,100 participants and 423 submitted projects across six tracks. DiresQ took 3rd place in the Software Development track. Not bad for a project that started as our first hackathon ever.

What the judges said

Two judges scored DiresQ out of 105 points. One gave it 96, the other 94.

The first judge summed up the project better than I could. The strongest part, they wrote, wasn’t the amount of functionality but the reasoning behind it: “the team repeatedly identifies dangerous failure modes, measures them, and designs around them.” That’s the whole project in one sentence.

The bonus points stand out, too. The rubric told judges that the bonus was reserved for the rare project that goes beyond it, and that most projects should get zero, by design. Both judges gave DiresQ some: 3 points and 4. The second judge’s reason was how complete and disciplined the whole project was for our level.

They also read the code, not just the writeup. The second judge noted the exact commit they reviewed, which was the last one we pushed, and admitted to getting through about half the files.

The criticism was fair, too:

• It’s unproven. Both judges pointed out that DiresQ has never been used in a real disaster, learned from only 55 examples, and relies on self-reported locations. The first judge noted that being upfront about those limits made the submission more credible, but also means its real-world effectiveness is still unproven.
• The writeup was ahead of the interface. The second judge found that some flows we described, like joining a report and voting on staffing, looked rougher in the actual app than in our writeup. That’s a fair hit.
• Scale isn’t solved. Moderation, identity checks, and hosting costs at scale are all written down, but none of them are solved. Sustainability was our lowest-scoring category on both sheets.

Both criticisms point to the same next step, and it isn’t a feature. It’s talking to people who have actually coordinated volunteers in a disaster, to find out whether the gap we designed for is as real as it looks from the research.

What I’d tell myself before the next hackathon

• Name your dependencies out loud. If someone is waiting on you, that’s the first thing you do, not a line in a planning doc.
• Agree on names and shapes in writing before you start. It takes fifteen minutes.
• Write the first test early. Ours found two real bugs within minutes of existing.
• Test on a database that already has data in it. Empty is the one case that always works.
• Treat 100% as a warning, not a result. Measure the clever version before you keep it.
• Write your limitations while you build. It’s the only time you actually remember what you decided not to handle.
• Don’t let the writeup get ahead of the interface. A judge will open the app and check.

Try it

• Live demo: diresq.onrender.com. Sign in as londo with the password diresq. It’s on a free tier, so the first load can take about a minute to wake up.
• Demo video: YouTube
• Docs: skythe7.github.io/DiresQ
• Code: github.com/Skythe7/DiresQ
• Devpost: DiresQ on Devpost

Built by Skythe (frontend) and me (backend).

Closing thought

Back to that dispatcher’s question: can we account for everyone?

With DiresQ, the answer is either yes, or a red row with a name, a last known position, and a report that’s already been filed.

Nobody has to notice you went quiet.

The archbishop’s answer: yes. As far as the Church was concerned, alligator counted as seafood.

He wasn’t the first religious authority to get a question like that. Over the centuries, priests, bishops, and theologians have been asked to rule on beavers, muskrats, capybaras, and a goose that medieval Europeans believed grew on driftwood.

People have been arguing about where “meat” ends and “fish” begins for about two thousand years.

I’ve been living on that line for eight.

The short version of me

I’m a pescatarian. For more than eight years, I haven’t eaten meat or poultry: no beef, no pork, no chicken, no turkey. I do eat fish, seafood, eggs, and dairy. Sushi is my second-favorite food on Earth.

Spoiler: my own reasons ended up closer to a Chinese philosopher who lived 2,300 years ago, and who once got into an argument about whether fish are happy, than to any bishop’s.

But first: almost every major religion has drawn this line too, and their reasons are stranger than mine.

Christianity was a fish religion from the start

Jesus’s first disciples were fishermen. The miracle of the loaves and fishes fed thousands. In the Gospel of Luke, the resurrected Jesus proves he isn’t a ghost by eating a piece of broiled fish. Early Christians even adopted the fish as a symbol: the Greek word for fish, ichthys, doubles as an acronym for “Jesus Christ, Son of God, Savior.”

So when the Church began setting fast days when meat was forbidden, fish was never on the chopping block. In the 1200s, Thomas Aquinas explained why. The flesh of land animals was richer and more pleasurable, so it was more likely to stir up exactly the appetites fasting was meant to tame. Fish was lighter, humbler food.

Today’s rule works the same way. Catholics 14 and older skip meat on Ash Wednesday and the Fridays of Lent, and “meat” means the flesh of land animals like cows, pigs, and chickens. Fish, shellfish, and cold-blooded animals don’t count.

In medieval Europe, fast days covered a huge chunk of the calendar. That created enormous demand for fish, which helped build entire fishing economies. It also created enormous demand for loopholes.

Is a beaver a fish?

According to a much-repeated story, in the 1600s the Bishop of Quebec asked theologians whether beaver could be eaten on fast days. Beavers spend their lives in the water and have scaly tails. The verdict: close enough to a fish.

It didn’t stop there:

• Muskrat: in parts of southeast Michigan, Catholics have long been allowed to eat muskrat on Lenten Fridays, a tradition going back to French settlers along the Detroit River.
• Capybara: in Venezuela, capybara is a traditional Lenten dish, backed by a legend that the Vatican once classified the world’s largest rodent as a fish.
• Alligator: see above. Louisiana, 2010.
• Barnacle geese: these geese breed in the Arctic, so medieval Europeans never saw them nest. The popular explanation was that they grew out of barnacles on driftwood. If they came from the sea, they were fish, and fair game on fast days. Pope Innocent III is said to have shut that one down in 1215.

The pattern is always the same: if it lives in water, somebody will argue it’s a fish.

And in 1962, that same fasting rule accidentally created one of the most famous sandwiches in fast food.

The burger that lost to a fish sandwich

Lou Groen ran a McDonald’s in a heavily Catholic part of Cincinnati. Every Friday, his sales collapsed, because his customers went to the fish place down the road.

So he invented a battered fish sandwich and pitched it to Ray Kroc, the head of McDonald’s. Kroc had his own meatless idea: the Hula Burger, a slice of grilled pineapple with cheese on a bun.

They made a bet. Both sandwiches would go on sale one Friday, and whichever sold more would stay on the menu. According to McDonald’s lore, the Hula Burger got crushed.

The Filet-O-Fish went national in 1965. McDonald’s has said Lent is still the sandwich’s busiest season. A Catholic fasting rule from the Middle Ages is the reason it exists.

Meanwhile, the Orthodox Church read the same Bible and took the salmon off the menu too. But not the shrimp.

Shrimp: yes. Salmon: no.

Eastern Orthodox Christians fast even harder, and their line lands somewhere completely different.

During strict fasts like Great Lent, Orthodox Christians traditionally give up meat, dairy, eggs, and fish with backbones. But shrimp, squid, octopus, and other shellfish are allowed, because they’re considered “bloodless” invertebrates. Fish itself comes back only on a couple of feast days, like Palm Sunday.

So a Catholic during Lent can eat salmon but not chicken. An Orthodox Christian during Lent can eat shrimp but not salmon.

And in Jewish law, shrimp is off the menu entirely. The same rules explain why your bagel works.

Why your bagel works

Kosher law draws its line with a physical test: fish must have fins and scales (Leviticus 11). That rules out shellfish, catfish, eels, and more.

And kosher fish belongs to a special category: pareve, meaning neither meat nor dairy. Kosher law forbids mixing meat and dairy, but fish is fine with dairy. That’s why lox and cream cheese on a bagel is a Jewish deli classic, while a real cheeseburger could never be kosher.

(Fish and meat are kept apart, though: the Talmud warns against eating them together, and the Shulchan Aruch, the standard code of Jewish law, made that a rule.)

Islamic law has fish rules too, and one of them makes fish the easiest meal on the menu.

The easiest halal meal on the menu

The Quran explicitly permits food from the sea. Unlike land animals, fish don’t need ritual slaughter to be halal. So for Muslims in places where halal meat is hard to find, fish is often the easy option.

The schools of Islamic law still draw the line in different places. Most Sunni schools allow nearly all seafood. The Hanafi school generally limits it to fish, with debate over shrimp. Shia law allows fish with scales, plus shrimp, but not other shellfish.

Further east, the story involves a god who took the form of a fish, and an emperor who shocked his country by eating beef.

A fish god and a beef-eating emperor

In Hindu tradition, the first avatar of the god Vishnu is Matsya, a fish, who warns Manu, the first man, of a great flood and tows his boat to safety. Many Hindus are vegetarian, but not everywhere. In Bengal, fish is so central that even many Brahmin families, who are often strictly vegetarian elsewhere in India, eat it, and a decorated whole fish is a traditional gift at Bengali weddings.

Buddhism’s first precept is to refrain from taking life, but Buddhist traditions apply it to food very differently. Many East Asian Buddhist monks are strictly vegetarian, and Japanese Zen temple cooking, shojin ryori, uses no meat or fish at all. In Theravada tradition, monks eat whatever they’re given as alms, including meat, as long as the animal wasn’t killed specifically for them.

Japan is the most dramatic example of a whole country living near the pescatarian line. In 675, Emperor Tenmu restricted eating cattle, horses, dogs, monkeys, and chickens during part of the year. Over the following centuries, under Buddhist influence, livestock mostly disappeared from the Japanese table, and fish moved to the center of it. (Hunted game never vanished completely.) Even whales were widely treated as fish; the Japanese character for “whale” is still written with the fish radical.

Then, in 1872, Emperor Meiji publicly ate beef, a signal that the old taboo was over. Modern Japanese beef dishes like sukiyaki grew out of that change.

So why am I a pescatarian?

Here’s what surprised me when I started digging: none of these traditions agree on where the line goes. Beaver is fish in one place, salmon is off-limits in another, and shrimp is either the safest or the most forbidden thing on the menu depending on who you ask. The line between meat and fish isn’t found in nature. People draw it.

Here’s where I drew mine.

The short answer: I want to cause less suffering than I otherwise would, in a way I can actually keep up for decades.

It didn’t start there, though. It started with how I felt. Eating meat left me sluggish, and I wanted to get fitter, so I tried going pescatarian the way an athlete tries anything: as an experiment. It stuck. Health got me in the door, and over eight years the reasons have grown well past my own body.

My ethics don’t come down to one master rule. I weigh several things at once: not causing harm, taking care of my own health, being fair, keeping the commitments I make. Reducing suffering gets the most weight. And food is where that gets concrete, every single day. Cutting out meat and poultry removes the biggest share of the suffering my diet would otherwise cause, especially from industrial farming of land animals, which has well-documented welfare problems.

I tried going further

I’ve done stretches as a full vegetarian and as a vegan, each for less than a year. Both times, I came back to pescatarian.

What brought me back was several things at once. I trained better with fish in my diet. Covering the nutrients that are hard to get without animal foods, like B12 and omega-3s, took constant planning. And eating out, family meals, and travel turned into daily negotiations. Together, they made it a diet I was fighting instead of living with.

The way I see it, a diet I can keep for decades does more good than a perfect one I quit after six months. Pescatarian is where the weighing lands for me. It’s a considered compromise, not a claim to purity.

It’s also a practical one. Seafood provides vitamin B12, which plants don’t provide on their own, so vegans generally need supplements or fortified foods. And fatty fish is one of the best sources of the omega-3 fats EPA and DHA.

Which brings me back to that philosopher.

What an ancient book about fish taught me

His name was Zhuangzi, and the book of stories and arguments that carries his name, the Zhuangzi, is one of the two great classics of Daoist philosophy. It’s the philosophy that shapes how I think about all of this. Daoist philosophy doesn’t tell you what to eat. It’s about moving with the natural grain of things instead of forcing them.

And conveniently for this post, it’s full of fish.

It opens with a fish that becomes a bird

The very first story in the Zhuangzi is about an enormous fish in the northern sea, named Kun, that transforms into an enormous bird, named Peng, and flies south.

Remember the barnacle goose, the bird medieval Europe thought came from the sea? Zhuangzi got there first, and on purpose. One of his big ideas is that the categories we sort the world into are ours, not the world’s. Fish, bird, meat, not-meat: useful labels, not laws of nature. Every beaver ruling above proves his point.

The happiness of fish

In another story, Zhuangzi and his friend Huizi are walking across a bridge over the Hao River. Zhuangzi looks down at the minnows darting around and says they look happy.

Huizi objects: you’re not a fish, so how could you know what fish feel? Zhuangzi turns it around: you’re not me, so how do you know what I know? They go back and forth, and the argument never really resolves.

That’s exactly where I am on the hardest question people ask me: “Fish are animals too, so why eat them?” Scientists and philosophers still debate how fish experience pain, and I can’t settle it from a bridge. I don’t claim eating fish is harmless. I claim it’s a smaller harm than the alternative I was choosing between, and that the uncertainty is a reason to eat fish with care: responsibly sourced, not wasted, not taken for granted.

Cook Ding and the grain of things

Here’s an irony I love: one of the most famous stories in the Zhuangzi is about a butcher. Cook Ding carves an ox so skillfully, following the natural gaps between the joints, that his knife stays sharp for nineteen years. Everyone else hacks through bone and needs a new blade every month.

The point isn’t about meat. It’s about attention. Cook Ding doesn’t force anything; he pays close enough attention to find the way through. That’s what I’m aiming for at the table: not a list of forbidden foods, but noticing where my food comes from and what it cost.

Don’t poke the small fish

The Daodejing, the other great Daoist classic, has a famous line: ruling a big country is like cooking a small fish. Keep poking at it, and it falls apart.

That’s how I think about nutrition. I track what I eat, but tracking is for noticing real gaps, not for turning every meal into an exam. Poke too much and the whole thing falls apart.

Wu wei: the diet you don’t have to force

Daoism’s central idea is wu wei, usually translated as “effortless action” or “non-forcing.” It doesn’t mean doing nothing. It means acting in a way that fits, so you’re not white-knuckling your way through life.

Diets that last are the ones that stop feeling like willpower. Eight years in, this one doesn’t feel like a rule I’m obeying. It’s just how I eat.

Living on the line: the practical stuff

These are the questions friends actually ask.

Do you get enough protein? Easily. Fish, eggs, dairy, beans, lentils, and tofu cover it.

What about everything else? I track my nutrition in Cronometer, which breaks food down into individual vitamins and minerals, so I know instead of guessing. When you cut out meat, the ones worth watching are iron, zinc, B12, and omega-3s. Seafood happens to be great for all four: oysters and clams for iron and zinc, fatty fish for B12 and omega-3s. Fatty fish and seafood are also some of the few good food sources of vitamin D and iodine. (I’m not a doctor or dietitian. If you’re changing how you eat in a big way, talk to one.)

Is it actually healthier? Maybe. Seventh-day Adventists, many of whom are vegetarian for religious reasons, are some of the most studied eaters on the planet. The Adventist Health Study-2 followed tens of thousands of members, and it’s where pescatarians came out ahead of vegans and vegetarians. Here’s how each diet did against meat eaters in two of its analyses, one on death from any cause and one on colorectal cancer:

The death-rate analysis followed 73,308 people for about six years, and the cancer one followed 77,659 people for about seven. The gaps between the three diets fall within the study’s margin of error, so read it as fish eaters edging ahead, not a knockout.

Two big British studies, with no religious angle at all, also found fish eaters doing better than meat eaters. EPIC-Oxford followed about 48,000 people for 18 years, and fish eaters had a 13% lower rate of heart disease than meat eaters. UK Biobank followed almost half a million people for 11 years, and fish eaters had a 10% lower risk of cancer overall than regular meat eaters. In those two, vegetarians did better on some measures and worse on others (EPIC-Oxford found a higher stroke rate for them), so no single study settles which diet wins.

The catch: these are all observational studies, so they can’t prove the diet caused those results. Adventists as a group also don’t smoke and rarely drink, and even after researchers adjust for things like that, people who choose a diet like this can differ in ways a study can’t fully measure. It’s not proof, but it’s not nothing.

What about mercury? This is the real homework. Mercury builds up in big, long-lived predator fish, so I pay attention to which fish, not just how much. The FDA’s list of fish to avoid, written for pregnant people and young kids, includes king mackerel, marlin, orange roughy, shark, swordfish, bigeye tuna, and tilefish from the Gulf of Mexico. For fish that are low in mercury and high in omega-3s, remember SMASH: salmon, mackerel (Atlantic, not king), anchovies, sardines, and herring.

Isn’t sushi full of tuna? Yes, and the big sushi tunas, like bigeye and bluefin, are some of the higher-mercury fish. I love tuna nigiri, so I just don’t make it the whole meal. Salmon, yellowtail, and shrimp are right there.

Is eating out hard? Not really. My three favorite cuisines are Mexican, sushi, and Indian, and they happen to be three of the easiest. Fish tacos and bean burritos, sushi, and Indian food, which has one of the deepest vegetarian traditions in the world. The one trap in Mexican food: refried beans are sometimes made with lard, and rice is sometimes cooked in chicken broth. It’s worth asking.

Where does meat hide? Gelatin in gummy candy and marshmallows (it usually comes from pigs or cows). Chicken broth in soups, rice, and risotto. Lard in tortillas and pie crusts. And one that goes the other way: Worcestershire sauce and Caesar dressing usually contain anchovies. Vegetarians have to skip them. Pescatarians don’t.

The honest criticisms

“Fish are animals too.” Yes. See the happy fish above: eating fish isn’t harmless. It’s a different place to draw the line, and after everything in this post, I’m clearly not the only one who drew it there.

“Is fish better for the environment than chicken?” Honestly, not automatically. Beef has a far bigger climate footprint than almost anything else, so cutting red meat is the big win. But farmed fish and chicken often land in a similar range, and beans, lentils, and tofu are generally the lowest of all.

“What about overfishing?” It’s real. The Monterey Bay Aquarium’s Seafood Watch rates seafood by how sustainably it’s caught or farmed, and the MSC (wild) and ASC (farmed) labels mark certified sources. Farmed mussels and oysters are some of the most sustainable seafood there is. They’re filter feeders, so they don’t even need to be fed.

If you’re thinking about trying it

• Start with a swap, not a rule. Replace one meat meal a week with fish or beans and see how it goes.
• Learn five meals you love. Diets fail when every meal feels like a sacrifice.
• Track for a few weeks. It shows you real gaps instead of vague worries. Then stop poking the fish.
• Rotate your fish. Lean on the SMASH fish, and go easy on the big predators.
• Don’t be preachy. Zhuangzi has a line about fish stranded on dry land when the springs dry up, keeping each other alive by spitting on each other, and how much better it would be if they could just forget each other in the rivers and lakes. Nobody wants to be spat on at dinner. When people ask, answer. When they don’t, eat your fish tacos in peace.

Closing thought

The Zhuangzi has one more fish story, and it’s my favorite.

A fish trap exists to catch fish. Once you’ve caught the fish, you can forget the trap. Words exist to catch meaning. Once you’ve caught the meaning, you can forget the words.

“Pescatarian” is a fish trap. It’s a handy word for ordering at a restaurant, or for a blog title. But every tradition in this post drew its line somewhere different: fins and scales, warm blood and cold, backbones, whatever the local bishop decided about beavers. The word matters less than what’s underneath it: paying attention to what’s on your plate, and what it cost.

I drew my line eight years ago, and it’s held.

And for the record: even with an archbishop’s blessing, I’m not eating the alligator.

What it is

.gitattributes is a plain text file that assigns attributes to paths. Each line is a pattern followed by one or more attributes:

*.sh    text eol=lf
*.png   binary
docs/** linguist-documentation

The patterns work much like .gitignore, with two catches. Negation (!pattern) isn’t allowed. And a directory pattern like vendor/ does not apply to the files inside it, so you need vendor/**.

Each attribute can be in one of four states:

• Set: text
• Unset: -text
• Set to a value: eol=lf
• Unspecified: !text, which resets it to as if you never mentioned it

Where it lives

Git reads attributes from several places, from highest priority to lowest:

1. .git/info/attributes: local to your clone and never committed. Good for personal rules.
2. .gitattributes files in the repo. A file in a subdirectory overrides one in a parent directory.
3. Your global file (set with core.attributesFile, usually ~/.config/git/attributes).
4. The system-wide file.

When a file behaves strangely, ask Git what it thinks:

git check-attr -a path/to/file

1. End the line-ending wars

This is the reason most people should add a .gitattributes today. Windows uses CRLF, everything else uses LF, and without rules you end up with diffs where every line “changed.”

* text=auto
*.sh  text eol=lf
*.bat text eol=crlf
*.ps1 text eol=crlf

text=auto lets Git detect text files and store them with LF in the repo. The eol= rules pin specific file types, which matters for shell scripts that break with CRLF and batch files that expect it.

Know this: adding these rules doesn’t fix files that are already committed. Run this once and commit the result:

git add --renormalize .

To see the current line-ending state of every file:

git ls-files --eol

2. Mark binaries as binary

*.png  binary
*.jpg  binary
*.zip  binary

binary is a built-in macro that expands to -text -diff -merge. Git won’t try to convert line endings, show a text diff, or attempt a text merge. That last one saves you from corrupted files after a merge that “succeeded.”

3. Hunk headers that actually help

When you run git diff, each hunk starts with a line like @@ -12,7 +12,8 @@, followed by some context Git guessed at. Often that guess is useless. Tell Git the language and it names the enclosing function or class instead:

*.py   diff=python
*.rs   diff=rust
*.go   diff=golang
*.java diff=java
*.md   diff=markdown
*.tex  diff=tex

These drivers are built in. There’s nothing to install. The Markdown one shows the nearest heading, which is great for docs.

4. Diff files that aren’t text

With a textconv driver, Git runs a command that turns a binary file into text, then diffs that text.

*.png  diff=exif
*.pdf  diff=pdf
*.docx diff=docx

git config --global diff.exif.textconv exiftool
git config --global diff.docx.textconv "pandoc --from=docx --to=plain"

Git appends the file path to the command, and the command must print text to stdout. exiftool and pandoc already do that. pdftotext doesn’t; by default it writes a .txt file next to the input. Wrap it in a tiny script:

#!/bin/sh
# save as ~/bin/pdf2txt and chmod +x it
pdftotext -layout "$1" -

git config --global diff.pdf.textconv pdf2txt

Now git diff on an image shows which metadata changed, and git log -p on a Word doc or PDF shows actual prose changes. Add git config --global diff.pdf.cachetextconv true so Git doesn’t reconvert unchanged files every time.

5. Silence noise you don’t care about

package-lock.json -diff
Cargo.lock        -diff
*.min.js          -diff

The files are still tracked and versioned normally. git diff just prints “Binary files differ” instead of four thousand lines of dependency churn.

6. Merge strategies per file

CHANGELOG.md  merge=union

union keeps the lines from both sides instead of creating a conflict. It’s perfect for append-only files like changelogs or lists of contributors. It’s dangerous for anything where order or structure matters, like code or JSON.

You can also keep your own version of a file on merge:

config/local.yml merge=ours

git config merge.ours.driver true

Know this: a merge driver only runs when both branches changed the file. If only the other branch touched it, Git takes their version cleanly and your driver never runs. Plenty of people have been surprised by this.

7. Clean and smudge filters

This is the most powerful feature in the file. A filter has two halves:

• clean runs when a file is staged, transforming the working copy into what gets stored.
• smudge runs on checkout, transforming the stored version back into your working copy.

*.ipynb filter=nbstrip

git config filter.nbstrip.clean "jupyter nbconvert --clear-output --to notebook --stdout --stdin"
git config filter.nbstrip.smudge cat
git config filter.nbstrip.required true

Now notebook outputs never get committed, but you keep them locally.

Real-world tools built on filters:

• Git LFS stores large files elsewhere and commits small pointers: *.psd filter=lfs diff=lfs merge=lfs -text
• git-crypt transparently encrypts files in the repo and decrypts them on checkout
• nbstripout does the notebook trick above

Know this: filter definitions live in Git config, not in the repo. .gitattributes only says “use the filter named X.” Every person who clones the repo has to set up the filter themselves. This is on purpose: if a repo could define commands that run automatically on checkout, cloning a stranger’s repo would be a security risk. Document your filters in the README.

8. Shape your release archives

git archive builds a tarball or zip of your repo. Attributes control what goes in it:

tests/         export-ignore
.github/       export-ignore
.gitattributes export-ignore
VERSION        export-subst

export-ignore leaves files out of release archives. GitHub’s “Download ZIP” and release source tarballs respect this too. It’s also one of the few attributes where a directory pattern like tests/ works, because git archive checks each directory as it walks the tree.

export-subst expands placeholders at archive time. Put this in VERSION:

$Format:%H$ $Format:%cd$

The archive will contain the real commit hash and date.

9. The GitHub extras

GitHub reads a set of linguist-* attributes that change how your repo is displayed:

vendor/**      linguist-vendored
dist/**        linguist-generated
docs/**        linguist-documentation
*.nx           linguist-language=Rust
scripts/*.txt  linguist-detectable

• linguist-vendored and linguist-documentation exclude files from the language bar.
• linguist-generated also collapses those files in pull request diffs. For generated code, lockfiles, or build output, this makes reviews much faster.
• linguist-language fixes misdetection, or lets a custom language borrow another’s highlighting.
• linguist-detectable forces a language to count toward the stats when it normally wouldn’t.

10. Lesser-known attributes

whitespace sets per-file rules for what git diff --check flags:

*.md whitespace=-trailing-space
*.py whitespace=trailing-space,tab-in-indent

Markdown uses two trailing spaces as a line break, so you don’t want those flagged there.

working-tree-encoding stores UTF-16 files as UTF-8 in the repo so they diff properly, then converts them back on checkout:

*.ps1 working-tree-encoding=UTF-16LE eol=crlf

Only use it on files that really are UTF-16. With this line, git add refuses a .ps1 saved with a byte order mark (declare UTF-16LE-BOM for those) and one saved as UTF-8, which is what most editors write today.

-delta skips delta compression for huge binaries that don’t compress well anyway, which speeds up packing:

*.mp4 -delta

ident expands $Id$ in a file to $Id: <blob hash>$ on checkout. It’s old-school, but handy for embedding a file’s exact version.

lockable works with Git LFS file locking. Files are checked out read-only until you lock them, which prevents two people from editing the same unmergeable file:

*.psd lockable

11. Macros

In the top-level .gitattributes only, you can define your own bundles of attributes:

[attr]lockfile -diff linguist-generated

package-lock.json lockfile
yarn.lock         lockfile
Cargo.lock        lockfile

One name, one place to change it later.

Know this: don’t put merge=ours in a macro like this. When both branches add a dependency, the merge succeeds without a conflict and the lockfile quietly loses the other branch’s entries. Regenerate lockfiles after a merge instead.

A sane starter file

If you take one thing from this post, drop this into your next project:

# Normalize line endings
* text=auto

# Scripts that care about endings
*.sh  text eol=lf
*.bat text eol=crlf
*.ps1 text eol=crlf

# Better diff hunk headers
*.py diff=python
*.md diff=markdown
*.rs diff=rust

# Binaries
*.png binary
*.jpg binary
*.gif binary
*.ico binary
*.zip binary
*.pdf binary

# Quiet noisy files
*.lock            -diff
package-lock.json -diff

# Keep release archives clean
.github/        export-ignore
.gitattributes  export-ignore

Closing thought

.gitignore tells Git what to leave out. .gitattributes tells Git how to understand everything you keep. It’s a few lines of text that fix line-ending chaos, make diffs readable, prevent merge disasters, and shape what your users download. Most repos never touch it. Now yours can.