Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Notes from the Group
The following notes are extracted from the mailing list and seek to provide some insight until the documentation for 3.0 is written.
May contain numbers or spaces but must be quoted in that case.
If a posting comment is a date (with brackets), it modifies the date for that posting:
2010/02/01 Sample Assets:Bank $400.00 Income:Check $-400.00 ; [2010/01/01]
You can use metadata to override the payee field for individual postings within a transaction: (source)
2010/06/17 Sample Assets:Bank $400.00 Income:Check1 $-100.00 ; Payee: Person One Income:Check2 $-100.00 ; Payee: Person Two Income:Check3 $-100.00 ; Payee: Person Three Income:Check4 $-100.00 ; Payee: Person Four
Metadata are normally strings, but you can create metadata of other types:
2010/06/17 Sample Assets:Bank $400.00 Income:Check1 $-100.00 ; Date:: [2010/09/01] ; Amount:: $100.00
(Note that this
Date tag is not the same as the posting date.)
There are now
pop directives, to apply metadata to a range of transactions (and their postings). For example, if you wanted a conceptual "page" of transactions relating to business trip to Chicago, you could do this:
tag Location: Chicago tag Purpose: Business ... transactions go here pop pop
It would be as if you'd applied "
; Location: Chicago", etc., to every transaction.
'tag("Date") < ' (for typed Date tag) 'commodity(tag("Amount")) == "$"'
Now the following is supported:
ledger [OPTIONS] <COMMAND> <SEARCH-TERMS>
Where COMMAND is any command verb, OPTIONS can occur anywhere, and SEARCH-TERM is one or more of the following:
word search for any account containing 'word' TERM and TERM boolean AND between terms TERM or TERM boolean OR between terms not TERM invert the meaning of the term payee word search for any payee containing 'word' @word shorthand for 'payee word' desc word alternate for 'payee word' note word search for any note containing 'word' &word shorthand for 'note word' tag word search for any metadata tag containing 'word' tag word=value search for any metadata tag containing 'word' whose value contains 'value' %word shorthand for 'tag word' %word=value shorthand for 'tag word=value' meta word alternate for 'tag word' meta word=value alternate for 'tag word=value' expr 'EXPR' apply the given value expression as a predicate '=EXPR' shorthand for 'expr EXPR' \ ( TERMS \ ) group terms; useful if using and/or/not
(That last one should have no space between backslash and parenthesis. The obvious ways to type it in Markdown aren't working.)
So, the example given at the top of this e-mail could now be:
ledger reg food not dining @chang ledger reg food and not dining and not payee chang ledger reg food not dining expr 'payee =~ /chang/'
All three are equivalent.
Checks and Assertions
Use "assert" instead of "check" if you want it to be an error.
These can occur in many places: (source)
; Within an automated transaction, the assert is evaluated every time ; a posting is matched, with the expression context set to the ; matched posting. = Food assert account("Expenses:Food").total >= $100 = expr account =~ /Food/ assert account("Expenses:Food").total >= $100 2010-06-12 Sample Expenses:Food $100 Assets:Checking ; At file scope, the expression is evaluated within "global" scope. assert account("Expenses:Food").total == $100 ; At the top of a transction, the assertion's scope is the ; transaction. After a posting, the scope is that posting. Note ; however that account totals are only adjusted after successful ; parsing of a transaction, which means that all the assertions below ; are true, even though it appears as though the first posting should ; affect the total immediately, which is not the case. 2010-06-12 Sample 2 assert account("Expenses:Food").total == $100 Expenses:Food $50 assert account("Expenses:Food").total == $100 Assets:Checking assert account("Expenses:Food").total == $100
impose sanity limits on transaction amounts, e.g. flag anything £5000 (source)
= true check abs(amount) < 5000
Declare pairs of accounts between which transfers could validly occur (source)
= /Checking/ check account =~ /Expense/ 2010-06-24 Sample Expenses:Food 00 Assets:Checking
(Note however that this currently does not work as
/Checking/ matches the
Assets:Checking posting and thus the value of
account won't be 'Expenses:Food' nor is there any way to get to that other posting if I'm not mistaken.)
next branch there is a new option:
--group=by=EXPR. It causes multiple sub-reports to be generated, one for each varying value of EXPR. In cases where EXPR returns a null, no report is created. For example, you can see multiple register reports for the differing values of the tag
Client -- and only for transactions which have that tag -- using:
ledger reg --group-by='tag("Client")'
Or, see which accounts were involved in transactions with what other accounts:
ledger reg --group-by=account --related --subtotal
In some ways, the use of
--group-by=payee could be emulated with a shell script, for example:
ledger reg -F '%(payee)\n' | sort | \ while read payee ; do \ echo ; echo $payee ; ledger reg payee "/$payee/"; \ done
--group-by option has two main advantages over such methods:
Your data file is only parsed and filtered once, rather than N times.
Ledger knows to ignore null values (which are different from empty strings and zeroes, something the
-Fflag can't tell you).
You can use the option
--group-title-format to apply underscores to the group titles, for example:
--group-title-format='%(value)\n%("-" * 79)\n'
Or you can omit group titles altogether with
--no-titles. Sometimes, the titling can be redundant, while most times it is necessary to make sense of what you're seeing. Note that the
NOTE: the order of budget entries is important. The following budget
~ Monthly Assets Expenses $200.00 Expenses:Food $100.00 Expenses:Health $20.00
is invalid! Any
Expenses:Health posting will match the first
Expenses. The proper budget looks like this:
~ Monthly Expenses:Health $20.00 Expenses:Food $100.00 Expenses $200.00 Assets
To sort budget elements always use reversed order (
sort -r), this assures that child accounts always come before their parents (e.g.