Skip to content

Instantly share code, notes, and snippets.

@simonmichael

simonmichael/Balance.md

Last active March 5, 2021 17:25
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save simonmichael/2f55199007f87a15b91dde64eda0f756 to your computer and use it in GitHub Desktop.
Save simonmichael/2f55199007f87a15b91dde64eda0f756 to your computer and use it in GitHub Desktop.
Download ZIP
draft of balance report types doc
Raw
Balance.md

For simonmichael/hledger#1496

Balance report types

For more flexible reporting, there are three important option groups:

hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...

The first two are the most important: calculation type selects the basic calculation to perform for each table cell, while accumulation type says which postings should be included in each cell's calculation. Typically one or both of these are selected by default, so you don't need to write them explicitly. A valuation type can be added if you want to convert the basic report to value or cost.

Calculation type:
The basic calculation to perform for each table cell. It is one of:

  • --sum : sum the posting amounts (default)
  • --budget : like --sum but also show a goal amount
  • --valuechange : show the change in period-end historical balance values

Accumulation type:
Which postings should be included in each cell's calculation. It is one of:

  • --change : postings from column start to column end, ie within the cell's period. Typically used with --sum to see revenues/expenses. (default for balance, incomestatement)

  • --cumulative : postings from report start to column end, eg to show changes accumulated since the report's start date. Rarely used.

  • --historical/-H : postings from journal start to column end, ie all postings from account creation to the end of the cell's period. Typically used to see historical end balances of assets/liabilities/equity. (default for balancesheet, balancesheetequity, cashflow)

Valuation type:
Which kind of [valuation], [valuation date(s)] and optionally a target [valuation commodity] to use. It is one of:

  • no valuation, show amounts in their original commodities (default)
  • --value=cost[,COMM] : no valuation, show amounts converted to cost
  • --value=then[,COMM] : show value at transaction dates
  • --value=end[,COMM] : show value at period end date(s)
  • --value=now[,COMM] : show value at today's date
  • --value=YYYY-MM-DD[,COMM] : show value at another date

or one of their aliases: --cost/-B, --market/-V or --exchange/-X.

Most combinations of these options should produce reasonable reports, but if you find any that seem wrong or misleading, let us know. Currently these restrictions are applied:

  • --valuechange implies --value=end
  • --cumulative or --historical disables --row-total/-T

Some frequently used combinations/reports are:

  • bal -M revenues expenses
    Show revenues/expenses in each month. Also available as the incomestatement command.

  • bal -M -H assets liabilities
    Show historical asset/liability balances at each month end. Also available as the balancesheet command.

  • bal -M -H assets liabilities equity
    Show historical asset/liability/equity balances at each month end. Also available as the balancesheetequity command.

  • bal -M assets not:receivable
    Show changes to liquid assets in each month. Also available as the cashflow command.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment