File structure
Files
Now you have a working instance of Beancount pre-filled with some example data and, presumably, some idea of Beancount basics. Maybe you also took a look at and explored the Fava interface.
These are the files as defined by the Lazy Beancount structure:
$ tree data
data
├── beancount_import_data
│ ├── monzo
│ ├── revolut_eur
│ ├── revolut_gbp
│ ├── revolut_usd
│ ├── wise_eur
│ ├── wise_gbp
│ └── wise_usd
├── beancount_import_output
│ ├── accounts.bean
│ ├── balance_accounts.bean
│ ├── ignored.bean
│ ├── prices.bean
│ └── transactions.bean
├── prices
│ ├── prices-2024-01-03.gen.bean
│ └── prices-2024-07-25.gen.bean
├── totals
│ ├── initial.gen.bean
│ ├── update-2024-01-05.gen.bean
│ ├── update-2024-01-12.gen.bean
├── accounts.bean
├── accounts.gen.bean
├── accounts_config.yml
├── beangrow-simple.config
├── commodities.bean
├── dashboards.yaml
├── docker-compose.yaml
├── importers_config.yml
├── main.bean
├── manual_transactions.bean
├── prices.bean
└── prices_config.yml
main.bean is an entry point of your Beancount setup. It contains configuration and also glues all other *.bean files together.
commodities.bean defines configuration of currencies, stocks, actuall commodities and such. How to use it will be described in more detail later.
Files under prices/ directory contain data about commodities prices and will be mostly semi-automatically fetched.
accounts.gen.bean andaccounts.bean have a list of all your accounts. The first one is auto-generated and will be described in the next section. The various types of accounts are Assets, Liabilities, Expenses, Income and Equity.
- Assets and Liabilities accounts will be introduced in the Stage I
- Expenses and Income in the Stage II
- Equity accounts are mostly used for technical purposes
Most YAML files are used to configure Lazy Beancount, except dashboards.yaml which is used to configure fava-dashboards (which you should adjust for your needs) and docker-compose.yaml that defines Docker configuration (and you likely don’t need to modify it).
Account names
In the account names, only the first word is significant as it defines type of the account. All other words in the name are meaningful only to you (and not the system), so feel free to make your own conventions. The special symbol : is used as a separator and using it will affect how your accounts are displayed in various textual and graphic hierarchies. Also accounts with the same prefix will be easier to group together using various filters.
If you want to rename accounts later, it will be just a search/replace operation in your file repository. Alternatively, you can also map account names permanently or on demand (without modifying any data) using the rename_accounts plugin. Plugins make it flexible like this.
How to migrate an existing Beancount setup
It should be pretty straightforward. You are not required to use any of the additional features but you can start benefitting from them both immediately and eventually. You can also use your own account naming and other conventions but then you’ll probably want to modify dashboards.yaml and other configs.
Probably the easiest path to start would be to include your ledger somewhere in the middle of main.bean and merge all the config-related instructions from it into main.bean making sure there are no conflicts/inconsistencies. As with pretty much everything else in this guide, you can leave data as it is and only use new libraries for adding new data, or migrate your old data in steps and at your leisure.