User guide

Accounts

All account names from beancount are also valid in ledger.

However, beancount2ledger allows you to map an account name from beancount to another account name in ledger (for example Assets:My-Bank to Assets:My Bank). This might be useful since beancount is more restrictive regarding account names.

If you want to map account names, add account_map to the config file:

account_map:
  Assets:My-Bank: Assets:My Bank

Auxiliary dates

Beancount currently doesn't support ledger's auxiliary dates (or effective dates; also known as date2 in hledger).

However, beancount2ledger can add auxiliary dates to the ledger output if the information is stored as metadata (either attached to a transaction or a posting). The auxdate variable needs to be defined in the config file, reflecting the key for the metadata information.

For example, given this beancount file:

2020-01-01 open Assets:Test

2020-11-13 * "Auxiliary dates"
  aux-date: 2020-11-11
  Assets:Test                           10.00 EUR
    aux-date: 2020-11-11
  Assets:Test

and this config file:

auxdate: aux-date

the following ledger output will be created:

account Assets:Test

2020-11-13=2020-11-11 * Auxiliary dates
    Assets:Test                         10.00 EUR  ; [=2020-11-11]
    Assets:Test

Output for hledger (using the -f option) uses a date2 tag for postings.

Posting dates (date in hledger) are also supported using the postdate config variable.

Currencies

All currencies from beancount are also valid in ledger, although some have to be quoted to be valid in ledger (TEST1 becomes "TEST1"). Beancount2ledger takes care of this automatically.

If you want to map a beancount currency to another currency name in ledger, you can define currency_map in the config file. For example:

currency_map:
  EUR: "€"

Links

Since links are not supported in ledger or hledger, they are represented as metadata.

Lots

Lots are supported and properly converted.

Beancount2ledger contains some logic to work around a bug in ledger.

This is a valid beancount transaction:

2020-01-01 open Assets:Test

2020-11-13 * "Costs"
  Assets:Test             1 FOO {150.00 EUR}
  Assets:Test             1 FOO {200.00 EUR}
  Assets:Test                   -350.00 EUR

However, loading it in ledger will give the error:

Unbalanced remainder is:
         -350.00 EUR
  1 FOO {150.00 EUR}
  1 FOO {200.00 EUR}
Amount to balance against:
  1 FOO {150.00 EUR}
  1 FOO {200.00 EUR}
Error: Transaction does not balance

This is because ledger doesn't use the cost to balance a transaction when no price is specified. Therefore, beancount2ledger will automatically add a price (in addition to the cost) for ledger output when this is needed.

Since lots are not supported in hledger, beancount will convert costs to prices if there's no price information already.

Metadata

Beancount2ledger will convert metadata correctly.

For ledger output, metadata types other than strings will be converted to typed metadata. Typed metadata is not supported for hledger.

Payee and narration

Unlike beancount, ledger does not differentiate between payee and narration. Therefore, the following syntax is used for ledger's payee field by default:

payee | narration

Alternatively, you can use the payee-meta config variable to store the payee in a custom metadata key.

This is also the syntax used by hledger (where narration is called a note).

Rounding and tolerance

Beancount handles the tolerance differently to ledger and hledger when balancing transactions.

The following beancount transactions are valid:

2010-01-01 open Expenses:Test
2010-01-01 open Assets:Bank

2020-01-10 * "Test"
  Expenses:Test                           4.990 USD
  Assets:Bank                            -4.990 USD

2020-01-10 * "Test: will fail in ledger due to precision of USD"
  Expenses:Test            150.75 THB @ 0.03344 USD
  Assets:Bank                             -5.04 USD

They are valid in beancount because each transaction is processed separately and tested against inferred_tolerance_default.

Ledger and hledger, on the other hand, infer the tolerance based on all past transactions involving the same currency. Since the first transaction uses a precision with 3 digits for USD, the same precision is required for the second transaction. With 3 digits of precision, the second transaction fails to balance because 150.75 * 0.03344 is 5.041 and not 5.04 as specified. Therefore, beancount2ledger will add rounding postings (using the Equity:Rounding account) when needed.

Transaction codes

Ledger's transactions codes are not supported in beancount. However, they can be added from metadata if the code config variable is specified.

For example, given this beancount file:

2020-01-01 open Assets:Test

2020-11-13 * "Code"
  code: 123
  Assets:Test                                  10.00 EUR
  Assets:Test

and this config file:

code: code

the following transaction header will be created:

2020-11-13 * (123) Code