Structuring Your Source Tree
There are many ways to structure your ledger transactions in files. The simplest is to put all your transactions in one large file. Many folks do this, and it works fine, especially if you use editor features such as folding to give your file structure while editing.
I personally use one file per real-world account, which looks like:
beancount/
main.bc # includes the other files
accounts/
Assets.Banks.ABCDBank.Checking.bc
Assets.Investments.Taxable.BTrade.bc
Liabilities.Credit-Cards.Blue-Mastercard-0123.bc
This structure:
- provides context when I am editing my source
- makes debugging easy (since most transaction debugging is local to an account)
- eg: when balance assertions fail, per-account source files, including comments where the importer ran helps find duplicate transactions easily
- makes using version control intuitive (if I imported a credit card, I expect only the corresponding file to change)
My importer scripts are aware of this hierarchy:
-
patch to
bean-extractto write to per-account ledger files- if your importer includes the metadata ‘filing_account’, the patch above will file to that account. If not, it will file it to the first posting it finds, which works in 99% of the cases for me
- invoke it like so:
bean-extract -o --dir ${INGEST_OUTPUT} my.import "- I stage it in the
${INGEST_OUTPUT}directory, and append it to my sources once I’ve examined them
- I stage it in the
Use Version Control
Keeping your ledger file(s) under git insures against accidental loss, helps you figure out what has changed recently (eg: right after an import), and helps give you context around past manual changes.
Keep It Simple
Remember: don’t overdo this. Keep things simple. Ask if a certain element of design that is causing complexity, is worth the benefits.
Get To Your Transaction Quickly
Fuzzy Finder and ripgrep, especially in combination with your editor, will let you jump around your source files and very quickly find the transaction, importer config, script, or line of notes you want.