{ "version": "https://jsonfeed.org/version/1", "title": "Tyler Cipriani: blog", "home_page_url": "https://tylercipriani.com/blog/", "feed_url": "https://tylercipriani.com/blog/index.json", "items": [ { "id": "https://tylercipriani.com/blog/2026/04/24/on-the-software-supply-chain-doom-spiral/", "title": "GitHub Actions and consequences", "url": "https://tylercipriani.com/blog/2026/04/24/on-the-software-supply-chain-doom-spiral/", "author": { "name": "Tyler Cipriani" }, "tags": [ "computing" ], "date_published": "2026-04-24T20:54:04Z", "date_modified": "2026-04-26T19:29:35Z", "content_html": "\n

Hackers are pwning packages at an exhausting clip.

\n

In late February, a hackerbot AI1 yoinked the release key\nfor a single project. Within a month, fifty-ish other projects had cred\nstealers. Each infected repo swiped credentials for the next.

\n

This spate of supply-chain hacks started from a well-known GitHub\nActions trap. A trap that AI can exploit or push us into.

\n
\n

GitHub Actions are a trap

\n

Trivy is an open-source security scanner. But if you used Trivy in\nlate March, you had a bad time.

\n

On March 19th, hackers pushed a version of Trivy that tried to\nsmuggle secrets from anywhere it ran. Trivy cited a “misconfiguration”\nin their continuous integration (CI) system, GitHub Actions.

\n

But the exploit was less a misconfiguration and more a GitHub Actions\ntrap.

\n
\n\n
Admiral Ackbar warning about the trap in\nGitHub Actions
\n
\n

Here’s a simplified version of how Trivy got pwnd2:

\n
# INSECURE. DO NOT USE.\non:\n pull_request_target\n\njobs:\n check:\n steps:\n - uses: action/checkout@deadbeefdeadbeefdeadbeefdeadbeefdeadbeef\n with:\n ref: refs/pull/${{ github.event.pull_request.number }}/merge\n - uses: ./.github/actions/setup-go\n - uses: some/go-static-analysis@c0ffeec0ffeec0ffeec0ffeec0ffeec0ffeec0ff
\n

At first glance, this code looks fine:

\n\n

But this code is a verbatim antipattern from a 2021 GitHub blog post\ntitled “preventing\npwn requests”:

\n
\n

if the pull_request_target workflow only […] runs\nuntrusted code but doesn’t reference any secrets, is it still\nvulnerable?

\n

Yes it is

\n

– GitHub\nSecurity Lab

\n
\n

The problem is pull_request_target:

\n\n

Setting the persist-credentials parameter to\nfalse has been an open issue in GitHub Actions since\n2021.

\n
\n
\n

Your $HOME is a crime scene

\n

Once hackers had Trivy’s keys, they published a new version of Trivy\nto steal more keys.

\n

LiteLLM used Trivy in their CI. The same CI they used to publish code\nto PyPI, the Python software registry. When LiteLLM’s CI ran the\ncompromised Trivy, hackers nabbed their publishing key.

\n

And on March 24th, when Callum McMahon fired up his IDE, his MacBook\nfroze. And that’s how he discovered the\nLiteLLM hijack.

\n

McMahon’s MacBook was flailing at bad code that hackers snuck into\nLiteLLM. And the bad code trying to steal credentials:

\n\n

Files that are typically strewn around $HOME\ndirectories, full of tokens and keys, often unencrypted.

\n
\n
\n

AI and the supply chain doom spiral

\n

We’ve dealt with problems like unencrypted credentials, unpinned\ndependencies, and CI footguns forever.

\n

But AI has accelerated everything, including repeating\nsecurity mistakes.

\n

On the day of the Trivy compromise, I asked Claude, “how do I scan\ndocker registry images for security vulnerabilities?”

\n

The reply, in part:

\n
CI/CD Integration Example (GitHub Actions with Trivy)\n\n    - name: Scan image for vulnerabilities\n      uses: aquasecurity/trivy-action@master
\n

Broken in two ways:

\n
    \n
  1. Unpinned references – master is a reference that\nchanges all the time. If hackers zombify the repo, I’d be the first\nvictim.
    2. \n
  2. Active vulnerability – No mention whatsoever of the CVE posted\nthat day. I never asked, so Claude never checked.
    3. \n
\n

Meanwhile, Vercel’s CEO has attributed his company’s recent data\nbreach to a hacker that was “accelerated\nby AI.” And Anthropic’s latest hype tour includes briefing\nthe US Federal Reserve Chair about vulnerabilities unearthed by\ntheir frontier model.

\n

Bad guys with LLMs get superpowers. Good guys with LLMs fall prey to\nmid-2010’s CI problems.

\n

And the same tool that can root out 27-year-old\nsecurity problems in OpenBSD, will still tell you to pin your GitHub\nactions to @master.

\n
\n
\n
\n
    \n

  1. Or somone calling themselves\nhackerbot-claw, at any rate.↩︎

    2. \n

  2. My GitHub Actions example is a\nsimpler verison of the action removed in aquasecurity/trivy\n#10259.↩︎

    3. \n
\n
\n" }, { "id": "https://tylercipriani.com/blog/2025/08/15/git-lfs/", "title": "The future of large files in Git is Git", "url": "https://tylercipriani.com/blog/2025/08/15/git-lfs/", "author": { "name": "Tyler Cipriani" }, "tags": [ "computing" ], "date_published": "2025-08-15T19:55:33Z", "date_modified": "2025-08-15T20:05:00Z", "content_html": "\n

If Git had a nemesis, it’d be large files.

\n

Large files bloat Git’s storage, slow down git clone,\nand wreak havoc on Git forges.

\n

In 2015, GitHub released Git LFS—a Git extension that hacked around\nproblems with large files. But Git LFS added new complications and\nstorage costs.

\n

Meanwhile, the Git project has been quietly working on large files.\nAnd while LFS ain’t dead yet, the latest Git release shows the path\ntowards a future where LFS is, finally, obsolete.

\n\n

What you can do today: replace Git LFS with Git partial clone

\n

Git LFS works by storing large files outside your repo.

\n

When you clone a project via LFS, you get the repo’s history and\nsmall files, but skip large files. Instead, Git LFS downloads only the\nlarge files you need for your working copy.

\n

In 2017, the Git project introduced partial clones\nthat provide the same benefits as Git LFS:

\n
\n

Partial clone allows us to avoid downloading [large binary assets]\nin advance during clone and fetch operations and thereby reduce\ndownload times and disk usage.

\n

– Partial Clone Design Notes, git-scm.com

\n
\n

Git’s partial clone and LFS both make for:

\n
    \n
  1. Small checkouts – On clone, you get the latest copy\nof big files instead of every copy.
    2. \n
  2. Fast clones – Because you avoid downloading large\nfiles, each clone is fast.
    3. \n
  3. Quick setup – Unlike shallow clones, you get the\nentire history of the project—you can get to work right away.
    4. \n
\n

What is a partial clone?

\n

A Git partial clone is a clone with a --filter.

\n

For example, to avoid downloading files bigger than 100KB, you’d\nuse:

\n
git clone --filter='blobs:size=100k' <repo>
\n

Later, Git will lazily download any files over 100KB you need for\nyour checkout.

\n

By default, if I git clone a repo with many revisions of\na noisome 25 MB PNG file, then cloning is slow and the checkout is\nobnoxiously large:

\n
$ time git clone https://github.com/thcipriani/noise-over-git\nCloning into '/tmp/noise-over-git'...\n...\nReceiving objects: 100% (153/153), 1.19 GiB\n\nreal 3m49.052s
\n

Almost four minutes to check out a single 25MB file!

\n
$ du --max-depth=0 --human-readable noise-over-git/.\n1.3G noise-over-git/.\n$ ^ 🤬
\n

And 50 revisions of that single 25MB file eat 1.3GB of space.

\n

But a partial clone side-steps these problems:

\n
$ git config --global alias.pclone 'clone --filter=blob:limit=100k'\n$ time git pclone https://github.com/thcipriani/noise-over-git\nCloning into '/tmp/noise-over-git'...\n...\nReceiving objects: 100% (1/1), 24.03 MiB\n\nreal 0m6.132s\n$ du --max-depth=0 --human-readable noise-over-git/.\n49M noise-over-git/\n$ ^ 😻 (the same size as a git lfs checkout)
\n

My filter made cloning 97% faster (3m 49s → 6s), and it reduced my\ncheckout size by 96% (1.3GB → 49M)!

\n

But there are still some caveats here.

\n

If you run a command that needs data you filtered out, Git will need\nto make a trip to the server to get it. So, commands like\ngit diff, git blame, and\ngit checkout will require a trip to your Git host to\nrun.

\n

But, for large files, this is the same behavior as Git LFS.

\n

Plus, I can’t remember the last time I ran git blame on\na PNG 🙃.

\n\n
\n

Why go to the trouble? What’s wrong with Git LFS?

\n

Git LFS foists Git’s problems with large files onto users.

\n

And the problems are significant:

\n\n
\n
\n

The future: Git large object promisors

\n

Large files create problems for Git forges, too.

\n

GitHub and GitLab put limits on file size2\nbecause big files cost more money to host. Git LFS keeps server-side\ncosts low by offloading large files to CDNs.

\n

But the Git project has a new solution.

\n

Earlier this year, Git merged a new feature: large object\npromisers. Large object promisors aim to provide the same\nserver-side benefits as LFS, minus the hassle to users.

\n
\n

This effort aims to especially improve things on the server side, and\nespecially for large blobs that are already compressed in a binary\nformat.

\n

This effort aims to provide an alternative to Git LFS

\n

– Large Object Promisors, git-scm.com

\n
\n

What is a large object promisor?

\n

Large object promisors are special Git remotes that only house large\nfiles.

\n

In the bright, shiny future, large object promisors will work like\nthis:

\n
    \n
  1. You push a large file to your Git host.
    2. \n
  2. In the background, your Git host offloads that large file to a large\nobject promisor.
    3. \n
  3. When you clone, the Git host tells your Git client about the\npromisor.
    4. \n
  4. Your client will clone from the Git host, and automagically nab\nlarge files from the promisor remote.
    5. \n
\n

But we’re still a ways off from that bright, shiny future.

\n

Git large object promisors are still a work in progress. Pieces of\nlarge object promisors merged to Git in March of\n2025. But there’s more to do\nand open\nquestions yet to answer.

\n

And so, for today, you’re stuck with Git LFS for giant files. But\nonce large object promisors see broad adoption, maybe GitHub will let\nyou push files bigger than 100MB.

\n
\n
\n

The future of large files in Git is Git.

\n

The Git project is thinking hard about large files, so you don’t have\nto.

\n

Today, we’re stuck with Git LFS.

\n

But soon, the only obstacle for large files in Git will be your\nhalf-remembered, ominous hunch that it’s a bad idea to stow your MP3\nlibrary in Git.

\n
\n
\n

Edited by Refactoring\nEnglish

\n
\n
\n
\n
\n
    \n

  1. Later, other Git forges made their own\nLFS servers. Today, you can push to multiple Git forges or use an\nLFS transfer agent, but all this makes set up harder for contributors.\nYou’re pretty much locked-in unless you put in extra effort to get\nunlocked.↩︎

    2. \n

  2. File size limits: 100MB\nfor GitHub, 100MB\nfor GitLab.com↩︎

    3. \n
\n
\n" }, { "id": "https://tylercipriani.com/blog/2025/05/21/git-commits/", "title": "Per-project git commit templates", "url": "https://tylercipriani.com/blog/2025/05/21/git-commits/", "author": { "name": "Tyler Cipriani" }, "tags": [ "computing" ], "date_published": "2025-05-21T19:22:45Z", "date_modified": "2025-06-02T23:05:20Z", "content_html": "
\n

People should try to compare the quality of the kernel git logs with\nsome other projects, and cry themselves to sleep.

\n

– Linus Torvalds

\n
\n

I’ll never remember your project’s commit guidelines.

\n

Every project insists on something different:

\n\n

But git\ncommit templates help. Commit templates provide a scaffold for\ncommit messages, offering documentation where you need it: inside the\neditor where you’re writing your commit message.

\n
\n

What is a git commit template?

\n

When you type git commit, git pops open your text\neditor1. Git can pre-fill your editor with a\ncommit template—it’s like a form you fill out.

\n

Creating a commit template is simple.

\n\n
git config --global \\\n commit.template '~/.config/git/message.txt'
\n

My\ndefault template packs everything I know about writing a commit.

\n
\n
\n

Project-specific templates with IncludeIf

\n

The real magic of commit templates is you can have different\ntemplates for each project.

\n

Different projects can use different templates with git’s\nincludeIf configuration setting.2

\n

Large projects, such as the\nLinux kernel, git,\nand MediaWiki,\nhave their own commit guidelines.

\n

For Wikimedia work, I stow git repos in\n~/Projects/Wikimedia and at the bottom of my global git\nconfig (~/.config/git/config) I have:

\n
[includeIf "gitdir:~/Projects/Wikimedia/**"]\n    path = ~/.config/git/config.wikimedia
\n

In config.wikimedia, I point to my Wikimedia-specific\ncommit template. I also override other git config settings like my\nuser.email or core.hooksPath.

\n
\n
\n

An example: my global template

\n

My default commit template contains three sections:

\n
    \n
  1. Subject – 50 characters or less, capitalized, no end\npunctuation.
    2. \n
  2. Body – Wrap at 72 characters with a blank line separating it from\nthe subject.
    3. \n
  3. Trailers – Standard formats with a blank line separating them from\nthe body.
    4. \n
\n

In each section, I added pointers for both format3 and\ncontent.

\n

For the header, the guidance is quick:

\n
\n# 50ch. wide ----------------------------- SUBJECT\n#                                                |\n#     "If applied, this commit will..."          |\n#                                                |\n#     Change / Add / Fix                         |\n#     Remove / Update / Document                 |\n#                                                |\n# ------- ↓ LEAVE BLANK LINE ↓ ---------- /SUBJECT\n
\n

For the body, I remind myself to answer basic questions:

\n
# 72ch. wide ------------------------------------------------------ BODY\n#                                                                      |\n#     - Why should this change be made?                                |\n#       - What problem are you solving?                                |\n#       - Why this solution?                                           |\n#     - What's wrong with the current code?                            |\n#     - Are there other ways to do it?                                 |\n#     - How can the reviewer confirm it works?                         |\n#                                                                      |
\n

And that’s it, except for git trailers.

\n
\n
\n

The twisty maze of git trailers

\n

My template has a section for trailers used by the projects I work\non.

\n
#     TRAILERS                                                         |\n#     --------                                                         |\n#     (optional) Uncomment as needed.                                  |\n#     Leave a blank line before the trailers.                          |\n#                                                                      |\n# Bug: #xxxx\n# Acked-by: Example User <user@example.com>\n# Cc: Example User <user@example.com>\n# Co-Authored-by: Example User <user@example.com>\n# Requested-by: Example User <user@example.com>\n# Reported-by: Example User <user@example.com>\n# Reviewed-by: Example User <user@example.com>\n# Suggested-by: Example User <user@example.com>\n# Tested-by: Example User <user@example.com>\n# Thanks: Example User <user@example.com>
\n

These trailers serve as useful breadcrumbs of documentation. Git can\nparse them using standard commands.

\n

For example, if I wanted a tab-separated list of commits and their\nrelated tasks, I could find Bug trailers using\ngit log:

\n
$ TAB=%x09\n$ BUG_TRAILER='%(trailers:key=Bug,valueonly=true,separator=%x2C )'\n$ SHORT_HASH=%h\n$ SUBJ=%s\n$ FORMAT="${SHORT_HASH}${TAB}${BUG_TRAILER}${TAB}${SUBJ}"\n$ git log --topo-order --no-merges \\\n --format="$FORMAT"\nd2b09deb12f T359762 Rewrite Kurdish (ku) Latin to Arabic converter\n28123a6a262 T332865 tests: Remove non-static fallback in HookRunnerTestBase\n4e919a307a4 T328919 tests: Remove unused argument from data provider in PageUpdaterTest\nbedd0f685f9 objectcache: Improve `RESTBagOStuff::handleError()`\n2182a0c4490 T393219 tests: Remove two data provider in RestStructureTest
\n
\n
\n

Stop remembering commit message guidelines

\n

Git commit templates free your brain from remembering what to write,\nallowing you to focus on the story you need to tell.

\n

Save your brain for what it’s good at.

\n
\n
\n
\n
    \n

  1. Starting with\ncore.editor in your git config, $VISUAL or\n$EDITOR in your shell, finally falling back to\nvi.↩︎

    2. \n

  2. You could also set it inside a repo’s\n.git/config, includeIf is useful if you have\nmultiple repos with the same standards under one directory.↩︎

    3. \n

  3. All cribbed from Tim\nPope↩︎

    4. \n
\n
\n" }, { "id": "https://tylercipriani.com/blog/2025/03/05/boox-go-10-3-review/", "title": "Boox Go 10.3, two months in", "url": "https://tylercipriani.com/blog/2025/03/05/boox-go-10-3-review/", "author": { "name": "Tyler Cipriani" }, "tags": [ "computing" ], "date_published": "2025-03-05T03:41:36Z", "date_modified": "2025-03-13T23:11:42Z", "content_html": "
\n

[The] Linux kernel uses GPLv2, and if you distribute GPLv2 code, you\nhave to provide a copy of the source (and modifications) once\nsomeone asks for it. And now I’m asking nicely for you to do so\n🙂

\n

– Joga, bbs.onyx-international.com

\n
\n
\n\n
Boox in split screen, typewriter\nmode
\n
\n

In January, I bought a Boox Go 10.3—a 10.3-inch, 300-ppi, e-ink\nAndroid tablet.

\n

After two months, I use the Boox daily—it’s replaced my planner,\nnotebook, countless PDF print-offs, and the good parts of my phone.

\n

But Boox’s parent company, Onyx, is sketchy.

\n

I’m conflicted. The Boox Go is a beautiful, capable tablet that I use\nevery day, but I recommend avoiding as long as Onyx continues to\ndisregard the rights of its users.

\n
\n

How I’m using my Boox

\n
\n\n
My e-ink floor desk
\n
\n

Each morning, I plop down in front of my MagicHold\nlaptop stand and journal on my Boox with Obsidian.

\n

I use Syncthing to back up my planner and sync my Zotero library between my Boox and\nlaptop.

\n

In the evening, I review my PDF planner\nand plot for tomorrow.

\n

I use these apps:

\n\n

Before buying the Boox, I considered a reMarkable.

\n

The reMarkable\nPaper Pro has a beautiful color screen with a frontlight, a nice\npen, and a “type\nfolio,” plus it’s certified by the Calm\nTech Institute.

\n

But the reMarkable is a distraction-free e-ink tablet. Meanwhile, I\nneed distraction-lite.

\n
\n
\n

What I like

\n\n
\n
\n

What I dislike

\n
\n\n
I filmed myself typing at 240fps, each\nframe is 4.17ms. Boox’s typing latency is between 150ms and 275ms at the\nfastest refresh rate inside Obsidian.
\n
\n\n
\n\n
The horror of the default\npen
\n
\n\n

Onyx

\n

The Chinese company behind Boox, Onyx International, Inc., runs the\nservers where the Boox routes telemetry. I block this traffic with Pi-Hole2.

\n
\n\n
pihole-ing whatever telemetry Boox\ncollects
\n
\n

I inspected this traffic via Mitm\nproxy—most traffic was benign, though I never opted into sending any\ntelemetry (nor am I logged in to a Boox account). But it’s also an\nAndroid device, so it’s feeding telemetry into Google’s gaping maw,\ntoo.

\n

Worse, Onyx is flouting the terms\nof the GNU Public License, declining to release Linux kernel\nmodifications to users. This is anathema to me—GPL\nviolations are tantamount to theft.

\n

Onyx’s disregard for user rights makes me regret buying the Boox.

\n
\n
\n

Verdict

\n

I’ll continue to use the Boox and feel bad about it. I hope my\ndigging in this post will help the next person.

\n

Unfortunately, the e-ink tablet market is too niche to support the\nkind of solarpunk future I’d always imagined.

\n

But there’s an opportunity for an open, Linux-based tablet to\ndominate e-ink. Linux is playing catch-up on phones with PostmarketOS.\nMeanwhile, the best e-ink tablets have to offer are old, unupdateable\nversions of Android, like the OS on the Boox.

\n

In the future, I’d love to pay a license- and privacy-respecting\ncompany for beautiful, calm technology and recommend their product to\neveryone. But today is not the future.

\n
\n
\n
\n
    \n

  1. I go back and forth between “Waking\nUp” and “Calm”↩︎

    2. \n

  2. Using github.com/JordanEJ/Onyx-Boox-Blocklist↩︎

    3. \n
\n
\n" }, { "id": "https://tylercipriani.com/blog/2024/10/24/plain-text-accounting/", "title": "Eventually consistent plain text accounting", "url": "https://tylercipriani.com/blog/2024/10/24/plain-text-accounting/", "author": { "name": "Tyler Cipriani" }, "date_published": "2024-10-24T00:37:44Z", "date_modified": "2024-11-13T02:16:50Z", "content_html": "\n
\n\n
Spending for October, generated by piping\nhledger → R
\n
\n

Over the past six months, I’ve tracked my money with hledger—a plain text\ndouble-entry accounting system written in Haskell. It’s been\nsurprisingly painless.

\n

My previous attempts to pick up real accounting tools\nfloundered. Hosted tools are privacy nightmares, and my stint with GnuCash didn’t last.

\n

But after stumbling on Dmitry Astapov’s “Full-fledged\nhledger” wiki1, it\nclicked—eventually consistent accounting. Instead of\nmodeling your money all at once, take it one hacking session at a\ntime.

\n
\n

It should be easy to work towards eventual consistency. […] I should\nbe able to [add financial records] bit by little bit, leaving things\nhalf-done, and picking them up later with little (mental) effort.

\n

– Dmitry Astapov, Full-Fledged Hledger

\n
\n
\n

Principles of my system

\n

I’ve cobbled together a system based on these principles:

\n\n
\n
\n

Learn hledger in five minutes

\n

hledger concepts are heady, but its use is simple. I\ndivide the core concepts into two categories:

\n\n

Transactions move money between accounts:

\n
2024-01-01 Payday\n    income:work      $-100.00\n    assets:checking   $100.00
\n

This transaction shows that on Jan 1, 2024, money moved from\nincome:work into assets:checking—Payday.

\n

The sum of each transaction should be $0. Money comes from somewhere,\nand the same amount goes somewhere else—double-entry accounting. This is\npowerful technology—it makes mistakes impossible to ignore.

\n

Journal files are text files containing one or more\ntransactions:

\n
2024-01-01 Payday\n    income:work              $-100.00\n    assets:checking           $100.00\n2024-01-02 QUANSHENG UVK5\n    assets:checking          $-29.34\n    expenses:fun:radio        $29.34
\n

Rules files transform CSVs into journal files via\nregex matching.

\n

Here’s a CSV from my bank:

\n
Transaction Date,Description,Category,Type,Amount,Memo\n09/01/2024,DEPOSIT Paycheck,Payment,Payment,1000.00,\n09/04/2024,PizzaPals Pizza,Food & Drink,Sale,-42.31,\n09/03/2024,Amazon.com*XXXXXXXXY,Shopping,Sale,-35.56,\n09/03/2024,OBSIDIAN.MD,Shopping,Sale,-10.00,\n09/02/2024,Amazon web services,Personal,Sale,-17.89,
\n

And here’s a checking.rules to transform that CSV into a\njournal file so I can use it with hledger:

\n
# checking.rules\n# --------------\n# Map CSV fields → hledger fields[0]\nfields date,description,category,type,amount,memo,_\n# `account1`: the account for the whole CSV.[1]\naccount1    assets:checking\naccount2    expenses:unknown\nskip 1\n\ndate-format %m/%d/%Y\ncurrency $\n\nif %type Payment\n    account2 income:unknown\nif %category Food & Drink\n    account2 expenses:food:dining\n\n# [0]: <https://hledger.org/hledger.html#field-names>\n# [1]: <https://hledger.org/hledger.html#account-field>
\n

With these two files (checking.rules and\n2024-09_checking.csv), I can make the CSV into a\njournal:

\n
$ > 2024-09_checking.journal \\\n    hledger print \\\n    --rules-file checking.rules \\\n    -f 2024-09_checking.csv\n$ head 2024-09_checking.journal\n2024-09-01 DEPOSIT Paycheck\n    assets:checking        $1000.00\n    income:unknown        $-1000.00\n\n2024-09-02 Amazon web services\n    assets:checking          $-17.89\n    expenses:unknown          $17.89
\n

Reports are interesting ways to view transactions\nbetween accounts.

\n

There are registers, balance sheets, and income statements:

\n
$ hledger incomestatement \\\n    --depth=2 \\\n    --file=2024-09_bank.journal\n\nRevenues:\n               $1000.00 income:unknown\n-----------------------\n               $1000.00\n\n\nExpenses:\n                 $42.31 expenses:food\n                 $63.45 expenses:unknown\n-----------------------\n                $105.76\n-----------------------\nNet:            $894.24
\n

At the beginning of September, I spent $105.76 and made\n$1000, leaving me with $894.24.

\n

But a good chunk is going to the default expense account,\nexpenses:unknown. I can use the\nhleger aregister to see what those transactions are:

\n
$ hledger areg expenses:unknown \\\n    --file=2024-09_checking.journal \\\n    -O csv | \\\n  csvcut -c description,change | \\\n  csvlook\n| description              | change |\n| ------------------------ | ------ |\n| OBSIDIAN.MD              |  10.00 |\n| Amazon web services      |  17.89 |\n| Amazon.com*XXXXXXXXY     |  35.56 |\nl
\n

Then, I can add some more rules to my\nchecking.rules:

\n
if OBSIDIAN.MD\n    account2 expenses:personal:subscriptions\nif Amazon web services\n    account2 expenses:personal:web:hosting\nif Amazon.com\n    account2 expenses:personal:shopping:amazon
\n

Now, I can reprocess my data to get a better picture of my\nspending:

\n
$ > 2024-09_bank.journal \\\n    hledger print \\\n    --rules-file bank.rules \\\n    -f 2024-09_bank.csv\n$ hledger bal expenses \\\n    --depth=3 \\\n    --percent \\\n    -f 2024-09_checking2.journal\n              30.0 %  expenses:food:dining\n              33.6 %  expenses:personal:shopping\n               9.5 %  expenses:personal:subscriptions\n              16.9 %  expenses:personal:web\n--------------------\n             100.0 %
\n

For the Amazon.com purchase, I lumped it into the\nexpenses:personal:shopping account. But I could dig\ndeeper—download my\norder history from Amazon and categorize that spending.

\n

This is the power of working bit-by-bit—the data guides you to the\nnext, deeper rabbit hole.

\n
\n
\n

Goals and non-goals

\n

Why am I doing this? For years, I maintained a monthly spreadsheet of\naccount balances. I had a balance sheet. But I still had questions.

\n
\n\n
Spending over six months, generated by\npiping hledger → gnuplot
\n
\n

Before diving into accounting software, these were my goals:

\n\n

Non-goals—these are the parts I never cared\nabout:

\n\n

hledger can track all these things. My setup is flexible\nenough to support them someday. But that’s unimportant to me right\nnow.

\n
\n
\n

Monthly maintenance

\n

I spend about an hour a month checking in on my money Which frees me\nto spend time making fancy charts—an activity I perversely\nenjoy.

\n
\n\n
Income vs. Expense, generated by piping\nhledger → gnuplot
\n
\n

Here’s my setup:

\n
$ tree ~/Documents/ledger\n.\n├── export\n│   ├── 2024-balance-sheet.txt\n│   └── 2024-income-statement.txt\n├── import\n│   ├── in\n│   │   ├── amazon\n│   │   │   └── order-history.csv\n│   │   ├── credit\n│   │   │   ├── 2024-01-01_2024-02-01.csv\n│   │   │   ├── ...\n│   │   │   └── 2024-10-01_2024-11-01.csv\n│   │   └── debit\n│   │       ├── 2024-01-01_2024-02-01.csv\n│   │       ├── ...\n│   │       └── 2024-10-01_2024-11-01.csv\n│   └── journal\n│       ├── amazon\n│       │   └── order-history.journal\n│       ├── credit\n│       │   ├── 2024-01-01_2024-02-01.journal\n│       │   ├── ...\n│       │   └── 2024-10-01_2024-11-01.journal\n│       └── debit\n│           ├── 2024-01-01_2024-02-01.journal\n│           ├── ...\n│           └── 2024-10-01_2024-11-01.journal\n├── rules\n│   ├── amazon\n│   │   └── journal.rules\n│   ├── credit\n│   │   └── journal.rules\n│   ├── debit\n│   │   └── journal.rules\n│   └── common.rules\n├── 2024.journal\n├── Makefile\n└── README
\n

Process:

\n
    \n
  1. Import – download a CSV for the month from each\naccount and plop it into\nimport/in/<account>/<dates>.csv
    2. \n
  2. Make – run make
    3. \n
  3. Squint – Look at git diff; if it looks\ngood, git add . && git commit -m \"💸\" otherwise\nreview hledger areg to see details.
    4. \n
\n

The Makefile generates everything under\nimport/journal:

\n\n

I include all the journal files in the 2024.journal with\nthe line: include ./import/journal/*/*.journal

\n

Here’s the Makefile:

\n
SHELL := /bin/bash\nRAW_CSV = $(wildcard import/in/**/*.csv)\nJOURNALS = $(foreach file,$(RAW_CSV),$(subst /in/,/journal/,$(patsubst %.csv,%.journal,$(file))))\n\n.PHONY: all\nall: $(JOURNALS)\n hledger is -f 2024.journal > export/2024-income-statement.txt\n hledger bs -f 2024.journal > export/2024-balance-sheet.txt\n\n.PHONY clean\nclean:\n rm -rf import/journal/**/*.journal\n\nimport/journal/%.journal: import/in/%.csv\n @echo "Processing csv $< to $@"\n @echo "---"\n @mkdir -p $(shell dirname $@)\n @hledger print --rules-file rules/$(shell basename $$(dirname $<))/journal.rules -f "$<" > "$@"
\n

If I find anything amiss (e.g., if my balances are different than\nwhat the bank tells me), I look at hleger areg. I may tweak\nmy rules or my CSVs and then I run\nmake clean && make and try again.

\n

Simple, plain text accounting made simple.

\n

And if I ever want to dig deeper, hledger’s docs have more to\nteach. But for now, the balance of effort vs. reward is perfect.

\n
\n
\n
\n
    \n

  1. while reading a blog post from Jonathan Dowland↩︎

    2. \n

  2. Note, this is covered by full-fledged\nhledger – Investements↩︎

    3. \n

  3. Also covered in full-fledged\nhledger – Tax returns↩︎

    4. \n
\n
\n" } ] }