Open your ledger

Opening

A ledger is opened by choosing its folder. The app then finds the main file in it — the .beancount (or .bean) file you would pass to bean-check — as the one file at the top of the folder that no other file includes (with more than one candidate, main.beancount wins). If it cannot tell, it asks you to choose the main file. Files the main file pulls in with include come along automatically.

Why a folder and not just the file? The app runs in the macOS sandbox: it can only read what you choose. A ledger is more than its main file — included files, your own plugins, documents and the Git history live around it — so the app asks for the folder once and remembers it.

• If your ledger is in a Git repository, choose the repository’s folder, so the app can see its history.
• Includes, plugins and documents outside the folder you chose cannot be read. Choose the folder that contains all of them.

There are four ways to open a ledger:

• File ▸ Open Ledger… (⌘O) and choose the folder.
• Drop the main .beancount file on the app window. The app then asks for access to the folder around it, already selected: click Allow.
• File ▸ Open Recent, which remembers the last ten ledgers, with their folders.
• Do nothing: on launch the app reopens the last ledger you used.

The app follows a ledger folder that you move or rename. Only if its main file is gone does it say so and forget the ledger: open it again from its new place.

One ledger is open at a time. Opening another one replaces it.

What is remembered per ledger

Each ledger keeps its own saved views, the last file you had open in the editor, and the list of iPhone drafts that were already imported. The period, chart and column choices are remembered too, so the app opens where you left it.

The status dot

At the bottom of the sidebar, next to the ledger’s title (the title option of your ledger, or the file name), a small dot tells you how the last load went. Hover over the title to see the full path of the main file.

Dot	Meaning
Green	Loaded, and Beancount reported no errors.
Orange	Loaded, but Beancount reported errors. The Errors item in the sidebar shows how many; see Errors.
Red	The ledger could not be loaded at all. The main area explains why and offers Try Again.
Gray	Loading.

Errors do not block you. With an orange dot every screen still works, with whatever Beancount could make of the file.

Reloading

The app watches your files. When the main file or any included file changes on disk — because you edited it in another editor, ran a script, or pulled from Git — the ledger is reloaded on its own and every screen refreshes. A small spinner in the toolbar shows while that happens.

You rarely need it, but File ▸ Reload Ledger (⌘R) forces a reload.

If your ledger uses its own Python plugins and you change one of them, the app restarts its engine so the new code is used. It does that on its own too.

Note

If a file changes on disk while you have unsaved edits to that same file in the app’s editor, nothing is overwritten. The editor shows a bar asking what to do: see Edited outside the app.

Next

Take the tour to see where everything is.