Next: , Previous: Basic options, Up: Options


2.3.2 Report filtering

These options change which transactions affect the outcome of a report, in ways other than just using regular expressions:

--current(-c) displays only entries occurring on or before the current date.

--begin DATE (-b DATE) constrains the report to entries on or after DATE. Only entries after that date will be calculated, which means that the running total in the balance report will always start at zero with the first matching entry. (Note: This is different from using --display to constrain what is displayed).

--end DATE (-e DATE) constrains the report so that entries on or after DATE are not considered. The ending date is inclusive.

--period STR (-p STR) sets the reporting period to STR. This will subtotal all matching entries within each period separately, making it easy to see weekly, monthly, quarterly, etc., transaction totals. A period string can even specify the beginning and end of the report range, using simple terms like “last june” or “next month”. For more using period expressions, see Period expressions.

--period-sort EXPR sorts the transactions within each reporting period using the value expression EXPR. This is most often useful when reporting monthly expenses, in order to view the highest expense categories at the top of each month:

     ledger -M --period-sort -At reg ^Expenses

--cleared (-C) displays only transactions whose entry has been marked “cleared” (by placing an asterix to the right of the date).

--uncleared (-U) displays only transactions whose entry has not been marked “cleared” (i.e., if there is no asterix to the right of the date).

--real (-R) displays only real transactions, not virtual. (A virtual transaction is indicated by surrounding the account name with parentheses or brackets; see the section on using virtual transactions for more information).

--actual (-L) displays only actual transactions, and not those created due to automated transactions.

--related (-r) displays transactions that are related to whichever transactions would otherwise have matched the filtering criteria. In the register report, this shows where money went to, or the account it came from. In the balance report, it shows all the accounts affected by entries having a related transaction. For example, if a file had this entry:

     2004/03/20 Safeway
         Expenses:Food                       $65.00
         Expenses:Cash                       $20.00
         Assets:Checking                    $-85.00

And the register command was:

     ledger -r register food

The following would be output, showing the transactions related to the transaction that matched:

     2004/03/20 Safeway              Expenses:Cash               $-20.00      $-20.00
                                     Assets:Checking              $85.00       $65.00

--budget is useful for displaying how close your transactions meet your budget. --add-budget also shows unbudgeted transactions, while --unbudgeted shows only those. --forecast is a related option that projects your budget into the future, showing how it will affect future balances. See Budgeting and forecasting.

--limit EXPR (-l EXPR) limits which transactions take part in the calculations of a report.

--amount EXPR (-t EXPR) changes the value expression used to calculate the “value” column in the register report, the amount used to calculate account totals in the balance report, and the values printed in the equity report. See Value expressions.

--total EXPR (-T EXPR) sets the value expression used for the “totals” column in the register and balance reports.