Saving and committing

A ledger is years of careful records in a text file. The best safety net for that is a Git history: every change recorded, reversible, with a date and a description. Beancount Desktop makes it effortless — saving creates the commit.

This applies equally to ⌘S in the editor, to the transaction dialog and to importing drafts from the iPhone.

Setting it up

There is nothing to set up, and you do not need to know Git. The app carries its own.

• Your ledger already has a Git repository: the app uses it as it is. Open the ledger by choosing the repository’s folder.
• It does not have one: when you open the ledger, the app starts one in its folder — a hidden .git folder — with everything in it as the first commit, Start the history of the ledger, and tells you it did. It only does this when the main file sits at the top of the folder you chose; otherwise History offers Start History, for when you want it.

Choose the right folder

The app only sees the folder you chose. If your ledger lives in a subfolder of a Git repository and you choose that subfolder, the app cannot see the repository above it and starts a second, separate history inside. Choose the repository’s folder instead. And keep your ledger in a folder of its own: if you chose a broad folder such as Documents with the main file at its top, the first commit would take in everything there.

Commits carry the name and email in Settings ▸ Git: your Mac account’s name and no email, unless you change them. The app never asks who you are in the middle of a save.

What happens when you save

1. The file is always saved. Whatever happens next, your change is on disk. (First, the app checks that the file was not modified by another program in the meantime.)
2. The ledger is reloaded and errors are marked in the editor.
3. If it is safe, a commit is made, and a toast appears at the bottom of the window:

✓ Committed  a1b2c3d  Add 2 transactions      Edit Message…   Undo   ×

The toast stays for about seven seconds:

• Edit Message… turns it into a text field. Type a better message and press Return; the commit is reworded. The toast waits while you type.
• Undo removes the commit but keeps your change in the file, as uncommitted.
• × dismisses it.

Both actions only work while that commit is still the latest one. If something else committed in between, they do nothing rather than touch the wrong commit.

The commit message

The message is written for you, from what changed in the ledger:

You did	Message
Added three transactions and a balance	Add 3 transactions and 1 balance
Removed a note	Remove 1 note
Changed an amount, fixed a typo	Edit 2026.beancount

Under that first line, the message details the changes file by file (2026.beancount: +3 transactions, +1 balance).

What goes into the commit

Everything that changed in the ledger’s folder (respecting .gitignore), not only the file you saved. The repository belongs to the ledger, and partial commits would leave it permanently “dirty”. When the app asks first, it lists exactly which files will go in.

When the app asks first

The commit is only automatic when it is clearly safe. Otherwise a Commit Changes sheet shows the reason, an editable message and the list of files, with two buttons: Commit and Don’t Commit (the file stays saved either way).

Situation	What you see
The save left Beancount errors	“Saved with 2 Beancount errors. Commit anyway?” If you do, the message gets a Beancount-Errors: 2 trailer, so that state is easy to find later.
There were already uncommitted changes when you opened the ledger	“Some of these changes were made outside the app. Review them before committing.” Those changes are not the app’s, so the first commit of the session is yours to review. After it, commits are automatic again.
Automatic commits are off	The sheet appears on every save.
Detached HEAD	“HEAD is detached, so commits are not made automatically.”
A merge or rebase is in progress	No commit at all: “A merge or rebase is in progress. Finish it before committing.”

Committing by hand

File ▸ Commit… (⌥⌘C), also a button in History, opens the same sheet for whatever is uncommitted. It is available whenever the repository has changes — yours or not.

Turning it off

Settings ▸ Git ▸ Commit automatically when saving. With it off, saving shows the Commit sheet each time; choose Don’t Commit to just save, and commit by hand when you like.

What the app does not do

• No push, no pull. The app never talks to a remote. To back up or sync the repository, push from Terminal or your Git client.
• It uses its own Git, with its own settings. Your ~/.gitconfig does not apply; the repository’s own configuration (.git/config) does. Hooks run, but only with the system’s tools (/usr/bin, /bin): a hook that needs something installed with Homebrew fails. Commits are not signed with GPG or SSH keys.

Keep generated files out

If your ledger’s folder holds files that change by themselves — for example the __pycache__ of your plugins — add them to .gitignore. Otherwise they show up as changes “made outside the app” and the app will keep asking before committing.