This page makes examples in the original Ledger documentation alive. You can run any example and observe the result in a command line console. You can type the command again with another parameters and see how Ledger reacts. You can review corresponded data files; you can make any changes in them and you can restore the original state at any time. Everything is alive and everything is safe!
Every example is preceded by Action button. It gives you the options: Run the command; Copy the command text to clipboard; Edit data file in a text editor; Open the folder containing data files and select the file; Revert the data file to the original state. All data files are located in NLedger\Sandbox that is in your Documents folder, so you can safely make any changes in them.
Next: Introduction to Ledger, Previous: (dir), Up: (dir) [Contents][Index]
Ledger is a command-line accounting tool that provides double-entry accounting based on a text journal. It provides no bells or whistles, and returns the user to the days before user interfaces were even a twinkling in their fathers’ CRTs.
Next: Ledger Tutorial, Previous: Top, Up: Top [Contents][Index]
| • Fat-free Accounting: | ||
| • Building the program: | ||
| • Getting help: | ||
| • Third-Party Ledger Tutorials: |
Next: Building the program, Previous: Introduction to Ledger, Up: Introduction to Ledger [Contents][Index]
Ledger is an accounting tool with the moxie to exist. It provides no bells or whistles, and returns the user to the days before user interfaces were even a twinkling in their father’s CRT.
What it does offer is a double-entry accounting journal with all the flexibility and muscle of its modern day cousins, without any of the fat. Think of it as the Bran Muffin of accounting tools.
To use it, you need to start keeping a journal. This is the basis of all accounting, and if you haven’t started yet, now is the time to learn. The little booklet that comes with your checkbook is a journal, so we’ll describe double-entry accounting in terms of that.
A checkbook journal records debits (subtractions, or withdrawals) and credits (additions, or deposits) with reference to a single account: the checking account. Where the money comes from, and where it goes to, are described in the payee field, where you write the person or company’s name. The ultimate aim of keeping a checkbook journal is to know how much money is available to spend. That’s really the aim of all journals.
What computers add is the ability to walk through these postings, and tell you things about your spending habits; to let you devise budgets and get control over your spending; to squirrel away money into virtual savings account without having to physically move money around; etc. As you keep your journal, you are recording information about your life and habits, and sometimes that information can start telling you things you aren’t aware of. Such is the aim of all good accounting tools.
The next step up from a checkbook journal, is a journal that keeps track of all your accounts, not just checking. In such a journal, you record not only who gets paid—in the case of a debit—but where the money came from. In a checkbook journal, it’s assumed that all the money comes from your checking account. But in a general journal, you write postings in two lines: the source account and target account. There must always be a debit from at least one account for every credit made to another account. This is what is meant by “double-entry” accounting: the journal must always balance to zero, with an equal number of debits and credits.
For example, let’s say you have a checking account and a brokerage account, and you can write checks from both of them.  In this general journal you need to record a payment to Pacific Bell for your monthly phone bill, and a transfer (via check) from your brokerage account to your checking account. The Pacific Bell bill is $23.00, let’s say, and you want to pay it from your checking account. In the general journal you need to say where the money came from, in addition to where it’s going to. These transactions might look like this:
9/29 Pacific Bell $23.00 $23.00 Checking $-23.00 0 9/30 Checking $100.00 $100.00 (123) Brokerage $-100.00 0
The posting must balance to $0: $23 went to Pacific Bell, $23 came from Checking. The next entry shows check number 123 written against your brokerage account, transferring money to your checking account. There is nothing left over to be accounted for, since the money has simply moved from one account to another in both cases. This is the basis of double-entry accounting: money never pops in or out of existence; it is always a posting from one account to another.
Keeping a general journal is the same as keeping two separate journals: One for Pacific Bell and one for Checking. In that case, each time a payment is written into one, you write a corresponding withdrawal into the other. This makes it easier to write in a “running balance”, since you don’t have to look back at the last time the account was referenced—but it also means having a lot of journal books, if you deal with multiple accounts.
Here is a good place for an aside on the use of the word “account”. Most private people consider an account to be something that holds money at an institution for them. Ledger uses a more general definition of the word. An account is anywhere money can go. Other finance programs use “categories”, Ledger uses accounts. So, for example, if you buy some groceries at Trader Joe’s, then more groceries at Whole Food Market, you might assign the transactions like this
2011/03/15 Trader Joe's Expenses:Groceries $100.00 Assets:Checking 2011/03/15 Whole Food Market Expenses:Groceries $75.00 Assets:Checking
In both cases the money goes to the ‘Groceries’ account, even though the payees were different. You can set up your accounts in any way you choose.
Enter the beauty of computerized accounting. The purpose of the Ledger program is to make general journal accounting simple, by keeping track of the balances for you. Your only job is to enter the postings. If an individual posting does not balance, Ledger displays an error and indicates the incorrect posting.1
In summary, there are two aspects of Ledger use: updating the journal data file, and using the Ledger tool to view the summarized result of your transactions.
And just for the sake of example—as a starting point for those who want to dive in head-first—here are the journal transactions from above, formatted as the Ledger program wishes to see them:
2004/09/29 Pacific Bell Expenses:Pacific Bell $23.00 Assets:Checking
The account balances and registers in this file, if saved as ledger.dat, could be reported using:
$ ledger -f ledger.dat balance
$-23.00 Assets:Checking $23.00 Expenses:Pacific Bell -------------------- 0
Or
$ ledger -f ledger.dat register checking
04-Sep-29 Pacific Bell Assets:Checking $-23.00 $-23.00
And even:
$ ledger -f ledger.dat register Bell
04-Sep-29 Pacific Bell Expenses:Pacific Bell $23.00 $23.00
An important difference between Ledger and other finance packages is that Ledger will never alter your input file. You can create and edit that file in any way you prefer, but Ledger is only for analyzing the data, not for altering it.
Next: Getting help, Previous: Fat-free Accounting, Up: Introduction to Ledger [Contents][Index]
Ledger is written in ANSI C++, and should compile on any unix platform. The easiest way to build and install ledger is to use the prepared acprep script, that does a lot of the footwork:
# to install missing dependencies ./acprep dependencies # building ledger ./acprep update # to run the actual installation make install
See the ‘help‘ subcommand to ‘acprep‘, which explains some of its many options. You can run ‘make check‘ to confirm the result, and ‘make install‘ to install. If these instructions do not work for you, you can check the ‘INSTALL.md‘ in the source directory for more up to date build instructions.
Next: Third-Party Ledger Tutorials, Previous: Building the program, Up: Introduction to Ledger [Contents][Index]
Ledger has a complete online help system based on GNU Info. This manual
can be searched directly from the command-line using info ledger
,
which will bring up this entire manual in your TTY. Alternatively, the
shorter man page can be accessed from the command-line either via
man ledger
or ledger --help
If you need help on how to use Ledger, or run into problems, you can join the Ledger mailing list at http://groups.google.com/group/ledger-cli.
You can also find help in the #ledger
channel on the IRC server
irc.freenode.net
.
Previous: Getting help, Up: Introduction to Ledger [Contents][Index]
There are plenty of people using Ledger for accounting applications. Some have documented how they use Ledger’s features to solve their accounting problems.
One such tutorial, specifically designed for non-profit charities that seek to use Ledger, can be found at https://k.sfconservancy.org/NPO-Accounting/npo-ledger-cli (with a copy on GitHub also available at https://github.com/conservancy/npo-ledger-cli/). If you’re looking for information about how to use Ledger’s tagging system to handle invoicing, track expenses by program targets, and other such concepts, you might find the tutorial useful. (Some of the auditor reporting scripts that relate to the aforementioned Ledger setup can be found contrib/non-profit-audit-reports/ in Ledger’s own source repository.)
Next: Principles of Accounting with Ledger, Previous: Introduction to Ledger, Up: Top [Contents][Index]
| • Start a Journal File: | ||
| • Run a Few Reports: |
Next: Run a Few Reports, Previous: Ledger Tutorial, Up: Ledger Tutorial [Contents][Index]
A journal is a record of your financial transactions and will be central to using Ledger. For now we just want to get a taste of what Ledger can do. An example journal is included with the source code distribution, called drewr3.dat (see Example Journal File). Copy it someplace convenient and open up a terminal window in that directory.
If you would rather start with your own journal right away please see Keeping a Journal.
Previous: Start a Journal File, Up: Ledger Tutorial [Contents][Index]
| • Balance Report: | ||
| • Register Report: | ||
| • Cleared Report: | ||
| • Using the Windows Command-Line: |
Please note that as a command-line program, Ledger is controlled from your shell. There are several different command shells that all behave slightly differently with respect to some special characters. In particular, the “bash” shell will interpret ‘$’ signs differently than ledger and they must be escaped to reach the actual program. Another example is “zsh”, which will interpret ‘^’ differently than ledger expects. In all cases that follow you should take that into account when entering the command-line arguments as given. There are too many variations between shells to give concrete examples for each.
Next: Register Report, Previous: Run a Few Reports, Up: Run a Few Reports [Contents][Index]
To find the balances of all of your accounts, run this command:
$ ledger -f drewr3.dat balance
Ledger will generate:
$ -3,804.00 Assets $ 1,396.00 Checking $ 30.00 Business $ -5,200.00 Savings $ -1,000.00 Equity:Opening Balances $ 6,654.00 Expenses $ 5,500.00 Auto $ 20.00 Books $ 300.00 Escrow $ 334.00 Food:Groceries $ 500.00 Interest:Mortgage $ -2,030.00 Income $ -2,000.00 Salary $ -30.00 Sales $ -63.60 Liabilities $ -20.00 MasterCard $ 200.00 Mortgage:Principal $ -243.60 Tithe -------------------- $ -243.60
Showing you the balance of all accounts. Options and search terms can pare this down to show only the accounts you want.
A more useful report is to show only your Assets and Liabilities:
$ ledger -f drewr3.dat balance Assets Liabilities
$ -3,804.00 Assets $ 1,396.00 Checking $ 30.00 Business $ -5,200.00 Savings $ -63.60 Liabilities $ -20.00 MasterCard $ 200.00 Mortgage:Principal $ -243.60 Tithe -------------------- $ -3,867.60
Next: Cleared Report, Previous: Balance Report, Up: Run a Few Reports [Contents][Index]
To show all transactions and a running total:
$ ledger -f drewr3.dat register
Ledger will generate:
10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00 Equit:Opening Balances $ -1,000.00 0 10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 Expense:Food:Groceries $ 37.50 $ 75.00 Expense:Food:Groceries $ 37.50 $ 112.50 Expense:Food:Groceries $ 37.50 $ 150.00 Expense:Food:Groceries $ 37.50 $ 187.50 Expense:Food:Groceries $ 37.50 $ 225.00 Assets:Checking $ -225.00 0 10-Dec-28 Acme Mortgage Lia:Mortgage:Principal $ 200.00 $ 200.00 Expe:Interest:Mortgage $ 500.00 $ 700.00 Expenses:Escrow $ 300.00 $ 1,000.00 Assets:Checking $ -1,000.00 0 11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 65.00 Assets:Checking $ -65.00 0 11-Jan-05 Employer Assets:Checking $ 2,000.00 $ 2,000.00 Income:Salary $ -2,000.00 0 (Liabilities:Tithe) $ -240.00 $ -240.00 11-Jan-14 Bank Assets:Savings $ 300.00 $ 60.00 Assets:Checking $ -300.00 $ -240.00 11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ -196.00 Assets:Checking $ -44.00 $ -240.00 11-Jan-25 Bank Assets:Checking $ 5,500.00 $ 5,260.00 Assets:Savings $ -5,500.00 $ -240.00 11-Jan-25 Tom's Used Cars Expenses:Auto $ 5,500.00 $ 5,260.00 Assets:Checking $ -5,500.00 $ -240.00 11-Jan-27 Book Store Expenses:Books $ 20.00 $ -220.00 Liabilities:MasterCard $ -20.00 $ -240.00 11-Dec-01 Sale Asse:Checking:Business $ 30.00 $ -210.00 Income:Sales $ -30.00 $ -240.00 (Liabilities:Tithe) $ -3.60 $ -243.60
To limit this to a more useful subset, simply add the accounts you are interested in seeing transactions for:
$ ledger -f drewr3.dat register Groceries
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 Expense:Food:Groceries $ 37.50 $ 75.00 Expense:Food:Groceries $ 37.50 $ 112.50 Expense:Food:Groceries $ 37.50 $ 150.00 Expense:Food:Groceries $ 37.50 $ 187.50 Expense:Food:Groceries $ 37.50 $ 225.00 11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 290.00 11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ 334.00
Which matches the balance reported for the ‘Groceries’ account:
$ ledger -f drewr3.dat balance Groceries
$ 334.00 Expenses:Food:Groceries
If you would like to find transaction to only a certain payee use ‘payee’ or ‘@’:
$ ledger -f drewr3.dat register payee "Organic"
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 Expense:Food:Groceries $ 37.50 $ 75.00 Expense:Food:Groceries $ 37.50 $ 112.50 Expense:Food:Groceries $ 37.50 $ 150.00 Expense:Food:Groceries $ 37.50 $ 187.50 Expense:Food:Groceries $ 37.50 $ 225.00 Assets:Checking $ -225.00 0
Next: Using the Windows Command-Line, Previous: Register Report, Up: Run a Few Reports [Contents][Index]
A very useful report is to show what your obligations are versus what
expenditures have actually been recorded. It can take several days for
a check to clear, but you should treat it as money spent. The
cleared
report shows just that (note that the
cleared
report will not format correctly for accounts that
contain multiple commodities):
$ ledger -f drewr3.dat cleared
$ -3,804.00 $ 775.00 Assets $ 1,396.00 $ 775.00 10-Dec-20 Checking $ 30.00 0 Business $ -5,200.00 0 Savings $ -1,000.00 $ -1,000.00 10-Dec-01 Equity:Opening Balances $ 6,654.00 $ 225.00 Expenses $ 5,500.00 0 Auto $ 20.00 0 Books $ 300.00 0 Escrow $ 334.00 $ 225.00 10-Dec-20 Food:Groceries $ 500.00 0 Interest:Mortgage $ -2,030.00 0 Income $ -2,000.00 0 Salary $ -30.00 0 Sales $ -63.60 0 Liabilities $ -20.00 0 MasterCard $ 200.00 0 Mortgage:Principal $ -243.60 0 Tithe ---------------- ---------------- --------- $ -243.60 0
The first column shows the outstanding balance, the second column shows the “cleared” balance.
Previous: Cleared Report, Up: Run a Few Reports [Contents][Index]
Using ledger under the windows command shell has one significant limitation. CMD.EXE is limited to standard ASCII characters and as such cannot display any currency symbols other than dollar signs ‘$’.
Next: Keeping a Journal, Previous: Ledger Tutorial, Up: Top [Contents][Index]
Next: Stating where money goes, Previous: Principles of Accounting with Ledger, Up: Principles of Accounting with Ledger [Contents][Index]
Accounting is simply tracking your money. It can range from nothing, and just waiting for automatic overdraft protection to kick in, or not, to a full-blown double-entry accounting system. Ledger accomplishes the latter. With ledger you can handle your personal finances or your business’s. Double-entry accounting scales.
Next: Assets and Liabilities, Previous: Accounting with Ledger, Up: Principles of Accounting with Ledger [Contents][Index]
Accountants will talk of “credits” and “debits”, but the meaning is often different from the layman’s understanding. To avoid confusion, Ledger uses only subtractions and additions, although the underlying intent is the same as standard accounting principles.
Recall that every posting will involve two or more accounts. Money is transferred from one or more accounts to one or more other accounts. To record the posting, an amount is subtracted from the source accounts, and added to the target accounts.
In order to write a Ledger transaction correctly, you must determine where the money comes from and where it goes to. For example, when you are paid a salary, you must add money to your bank account and also subtract it from an income account:
9/29 My Employer Assets:Checking $500.00 Income:Salary $-500.00
Why is the Income a negative figure? When you look at the balance totals for your ledger, you may be surprised to see that Expenses are a positive figure, and Income is a negative figure. It may take some getting used to, but to properly use a general ledger you must think in terms of how money moves. Rather than Ledger “fixing” the minus signs, let’s understand why they are there.
When you earn money, the money has to come from somewhere. Let’s call that somewhere “society”. In order for society to give you an income, you must take money away (withdraw) from society in order to put it into (make a payment to) your bank. When you then spend that money, it leaves your bank account (a withdrawal) and goes back to society (a payment). This is why Income will appear negative—it reflects the money you have drawn from society—and why Expenses will be positive—it is the amount you’ve given back. These additions and subtractions will always cancel each other out in the end, because you don’t have the ability to create new money: it must always come from somewhere, and in the end must always leave. This is the beginning of economy, after which the explanation gets terribly difficult.
Based on that explanation, here’s another way to look at your balance report: every negative figure means that that account or person or place has less money now than when you started your ledger; and every positive figure means that that account or person or place has more money now than when you started your ledger. Make sense?
Next: Commodities and Currencies, Previous: Stating where money goes, Up: Principles of Accounting with Ledger [Contents][Index]
Assets are money that you have, and Liabilities are money that you owe. “Liabilities” is just a more inclusive name for Debts.
An Asset is typically increased by transferring money from an Income account, such as when you get paid. Here is a typical transaction:
2004/09/29 My Employer Assets:Checking $500.00 Income:Salary
Money, here, comes from an Income account belonging to ‘My Employer’, and is transferred to your checking account. The money is now yours, which makes it an Asset.
Liabilities track money owed to others. This can happen when you borrow money to buy something, or if you owe someone money. Here is an example of increasing a MasterCard liability by spending money with it:
2004/09/30 Restaurant Expenses:Dining $25.00 Liabilities:MasterCard
The Dining account balance now shows $25 spent on Dining, and a corresponding $25 owed on the MasterCard—and therefore shown as $-25.00. The MasterCard liability shows up as negative because it offsets the value of your assets.
The combined total of your Assets and Liabilities is your net worth. So to see your current net worth, use this command:
$ ledger balance ^assets ^liabilities
$500.00 Assets:Checking $-25.00 Liabilities:MasterCard -------------------- $475.00
In a similar vein, your Income accounts show up negative, because they transfer money from an account in order to increase your assets. Your Expenses show up positive because that is where the money went to. The combined total of Income and Expenses is your cash flow. A positive cash flow means you are spending more than you make, since income is always a negative figure. To see your current cash flow, use this command:
$ ledger balance ^income ^expenses
$25.00 Expenses:Dining $-500.00 Income:Salary -------------------- $-475.00
Another common question to ask of your expenses is: How much do I spend each month on X? Ledger provides a simple way of displaying monthly totals for any account. Here is an example that summarizes your monthly automobile expenses:
$ ledger -M register -f drewr3.dat expenses:auto
11-Jan-01 - 11-Jan-31 Expenses:Auto $ 5,500.00 $ 5,500.00
This assumes, of course, that you use account names like ‘Expenses:Auto:Gas’ and ‘Expenses:Auto:Repair’.
| • Tracking reimbursable expenses: |
Previous: Assets and Liabilities, Up: Assets and Liabilities [Contents][Index]
Sometimes you will want to spend money on behalf of someone else, which will eventually get repaid. Since the money is still yours, it is really an asset. And since the expenditure was for someone else, you don’t want it contaminating your Expenses reports. You will need to keep an account for tracking reimbursements.
This is fairly easy to do in ledger. When spending the money, spend it to your Assets:Reimbursements, using a different account for each person or business that you spend money for. For example:
2004/09/29 Circuit City Assets:Reimbursements:Company XYZ $100.00 Liabilities:MasterCard
This shows $100.00 spent on a MasterCard at Circuit City, with the expense was made on behalf of Company XYZ. Later, when Company XYZ pays the amount back, the money will transfer from that reimbursement account back to a regular asset account:
2004/09/29 Company XYZ Assets:Checking $100.00 Assets:Reimbursements:Company XYZ
This deposits the money owed from Company XYZ into a checking account, presumably because they paid the amount back with a check.
But what to do if you run your own business, and you want to keep track of expenses made on your own behalf, while still tracking everything in a single ledger file? This is more complex, because you need to track two separate things: 1) The fact that the money should be reimbursed to you, and 2) What the expense account was, so that you can later determine where your company is spending its money.
This kind of posting is best handled with mirrored postings in two different files, one for your personal accounts, and one for your company accounts. But keeping them in one file involves the same kinds of postings, so those are what is shown here. First, the personal transaction, which shows the need for reimbursement:
2004/09/29 Circuit City Assets:Reimbursements:Company XYZ $100.00 Liabilities:MasterCard
This is the same as above, except that you own Company XYZ, and are keeping track of its expenses in the same ledger file. This transaction should be immediately followed by an equivalent transaction, which shows the kind of expense, and also notes the fact that $100.00 is now payable to you:
2004/09/29 Circuit City Company XYZ:Expenses:Computer:Software $100.00 Company XYZ:Accounts Payable:Your Name
This second transaction shows that Company XYZ has just spent $100.00 on software, and that this $100.00 came from Your Name, which must be paid back.
These two transactions can also be merged, to make things a little clearer. Note that all amounts must be specified now:
2004/09/29 Circuit City Assets:Reimbursements:Company XYZ $100.00 Liabilities:MasterCard $-100.00 Company XYZ:Expenses:Computer:Software $100.00 Company XYZ:Accounts Payable:Your Name $-100.00
To “pay back” the reimbursement, just reverse the order of everything, except this time drawing the money from a company asset, paying it to accounts payable, and then drawing it again from the reimbursement account, and paying it to your personal asset account.  The money simply “waited”—in both ‘Assets:Reimbursements:Company XYZ’, and ‘Company XYZ:Accounts Payable:Your Name’—until such time as it could be paid off.
The value of tracking expenses from both sides like that is that you do not contaminate your personal expense report with expenses made on behalf of others, while at the same time making it possible to generate accurate reports of your company’s expenditures. It is more verbose than just paying for things with your personal assets, but it gives you a very accurate information trail.
The advantage to keep these doubled transactions together is that they always stay in sync. The advantage to keeping them apart is that it clarifies the transfer’s point of view. To keep the postings in separate files, just separate the two transactions that were joined above. For example, for both the expense and the pay-back shown above, the following four transactions would be created. Two in your personal ledger file:
2004/09/29 Circuit City Assets:Reimbursements:Company XYZ $100.00 Liabilities:MasterCard $-100.00 2004/10/15 Company XYZ Assets:Checking $100.00 Assets:Reimbursements:Company XYZ $-100.00
And two in your company ledger file:
apply account Company XYZ 2004/09/29 Circuit City Expenses:Computer:Software $100.00 Accounts Payable:Your Name $-100.00 2004/10/15 Company XYZ Accounts Payable:Your Name $100.00 Assets:Checking $-100.00 end apply account
(Note: The apply account
above means that all accounts
mentioned in the file are children of that account. In this case it
means that all activity in the file relates to Company XYZ).
After creating these transactions, you will always know that $100.00 was spent using your MasterCard on behalf of Company XYZ, and that Company XYZ spent the money on computer software and paid it back about two weeks later.
$ ledger balance --no-total
$100.00 Assets:Checking 0 Company XYZ $-100.00 Assets:Checking $100.00 Expenses:Computer:Software $-100.00 Liabilities:MasterCard
Next: Accounts and Inventories, Previous: Assets and Liabilities, Up: Principles of Accounting with Ledger [Contents][Index]
Ledger makes no assumptions about the commodities you use; it only requires that you specify a commodity. The commodity may be any non-numeric string that does not contain a period, comma, forward slash or at-sign. It may appear before or after the amount, although it is assumed that symbols appearing before the amount refer to currencies, while non-joined symbols appearing after the amount refer to commodities. Here are some valid currency and commodity specifiers:
$20.00 ; currency: twenty US dollars 40 AAPL ; commodity: 40 shares of Apple stock 60 DM ; currency: 60 Deutsch Mark £50 ; currency: 50 British pounds 50 EUR ; currency: 50 Euros (or use appropriate symbol)
Ledger will examine the first use of any commodity to determine how that commodity should be printed on reports. It pays attention to whether the name of commodity was separated from the amount, whether it came before or after, the precision used in specifying the amount, whether thousand marks were used, etc. This is done so that printing the commodity looks the same as the way you use it.
An account may contain multiple commodities, in which case it will have separate totals for each. For example, if your brokerage account contains both cash, gold, and several stock quantities, the balance might look like:
$200.00 100.00 AU AAPL 40 BORL 100 FEQTX 50 Assets:Brokerage
This balance report shows how much of each commodity is in your brokerage account.
Sometimes, you will want to know the current street value of your balance, and not the commodity totals. For this to happen, you must specify what the current price is for each commodity. The price can be any commodity, in which case the balance will be computed in terms of that commodity. The usual way to specify prices is with a price history file, which might look like this:
P 2004/06/21 02:18:01 FEQTX $22.49 P 2004/06/21 02:18:01 BORL $6.20 P 2004/06/21 02:18:02 AAPL $32.91 P 2004/06/21 02:18:02 AU $400.00
Specify the price history to use with the --price-db FILE option, with the --market (-V) option to report in terms of current market value:
$ ledger --price-db prices.db -V balance brokerage
The balance for your brokerage account will be reported in US dollars, since the prices database uses that currency.
$40880.00 Assets:Brokerage
You can convert from any commodity to any other commodity. Let’s say you had $5000 in your checking account, and for whatever reason you wanted to know how many ounces of gold that would buy, in terms of the current price of gold:
$ ledger -T "{1 AU}*(O/P{1 AU})" balance checking
Although the total expression appears complex, it is simply saying that the reported total should be in multiples of AU units, where the quantity is the account total divided by the price of one AU. Without the initial multiplication, the reported total would still use the dollars commodity, since multiplying or dividing amounts always keeps the left value’s commodity. The result of this command might be:
14.01 AU Assets:Checking
| • Commodity price histories: | ||
| • Commodity equivalences: |
Next: Commodity equivalences, Previous: Commodities and Currencies, Up: Commodities and Currencies [Contents][Index]
Whenever a commodity is purchased using a different commodity (such as a share of common stock using dollars), it establishes a price for that commodity on that day. It is also possible, by recording price details in a ledger file, to specify other prices for commodities at any given time.  It will always report balances in terms of the commodity total, rather than the current value of those commodities. To enable pricing reports, use one of the commodity reporting options.
Previous: Commodity price histories, Up: Commodities and Currencies [Contents][Index]
Sometimes a commodity has several forms which are all equivalent. An example of this is time. Whether tracked in terms of minutes, hours or days, it should be possible to convert between the various forms. Doing this requires the use of commodity equivalences.
For example, you might have the following two postings, one which transfers an hour of time into a ‘Billable’ account, and another which decreases the same account by ten minutes. The resulting report will indicate that fifty minutes remain:
2005/10/01 Work done for company Billable:Client 1h Project:XYZ 2005/10/02 Return ten minutes to the project Project:XYZ 10m Billable:Client
Reporting the balance for this ledger file produces:
$ ledger --no-total balance Billable Project
50.0m Billable:Client -50.0m Project:XYZ
This example works because ledger already knows how to handle seconds, minutes and hours, as part of its time tracking support. Defining other equivalences is simple. The following is an example that creates data equivalences, helpful for tracking bytes, kilobytes, megabytes, and more:
C 1.00 Kb = 1024 b C 1.00 Mb = 1024 Kb C 1.00 Gb = 1024 Mb C 1.00 Tb = 1024 Gb
Each of these definitions correlates a commodity (such as ‘Kb’) and a default precision, with a certain quantity of another commodity. In the above example, kilobytes are reported with two decimal places of precision and each kilobyte is equal to 1024 bytes.
Equivalence chains can be as long as desired. Whenever a commodity would report as a decimal amount (less than ‘1.00’), the next smallest commodity is used. If a commodity could be reported in terms of a higher commodity without resulting to a partial fraction, then the larger commodity is used.
Next: Understanding Equity, Previous: Commodities and Currencies, Up: Principles of Accounting with Ledger [Contents][Index]
Since Ledger’s accounts and commodity system is so flexible, you can have accounts that don’t really exist, and use commodities that no one else recognizes. For example, let’s say you are buying and selling various items in EverQuest, and want to keep track of them using a ledger. Just add items of whatever quantity you wish into your EverQuest account:
9/29 Get some stuff at the Inn Places:Black's Tavern -3 Apples Places:Black's Tavern -5 Steaks EverQuest:Inventory
Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The amounts are negative, because you are taking from Black’s Tavern in order to add to your Inventory account. Note that you don’t have to use ‘Places:Black's Tavern’ as the source account. You could use ‘EverQuest:System’ to represent the fact that you acquired them online. The only purpose for choosing one kind of source account over another is to generate more informative reports later on. The more you know, the better the analysis you can perform.
If you later sell some of these items to another player, the transaction would look like:
10/2 Sturm Brightblade EverQuest:Inventory -2 Steaks EverQuest:Inventory 15 Gold
Now you’ve turned 2 steaks into 15 gold, courtesy of your customer, Sturm Brightblade.
$ ledger balance EverQuest
3 Apples 15 Gold 3 Steaks EverQuest:Inventory
Next: Dealing with Petty Cash, Previous: Accounts and Inventories, Up: Principles of Accounting with Ledger [Contents][Index]
The most confusing transaction in any ledger will be your equity account—because starting balances can’t come out of nowhere.
When you first start your ledger, you will likely already have money in some of your accounts. Let’s say there’s $100 in your checking account; then add a transaction to your ledger to reflect this amount. Where will the money come from? The answer: your equity.
10/2 Opening Balance Assets:Checking $100.00 Equity:Opening Balances
But what is equity? You may have heard of equity when people talked about house mortgages, as “the part of the house that you own”. Basically, equity is like the value of something. If you own a car worth $5000, then you have $5000 in equity in that car. In order to turn that car (a commodity) into a cash flow, or a credit to your bank account, you will have to debit the equity by selling it.
When you start a ledger, you probably already have a net worth. Your net worth is your current equity. By transferring the money in the ledger from your equity to your bank accounts, you are crediting the ledger account based on your prior equity. That is why, when you look at the balance report, you will see a large negative number for Equity that never changes: Because that is what you were worth (what you debited from yourself in order to start the ledger) before the money started moving around.
Clear as mud? Keep thinking about it. Until you figure it out, put
not Equity
at the end of your balance command, to remove the
confusing figure from the total.
Next: Working with multiple funds and accounts, Previous: Understanding Equity, Up: Principles of Accounting with Ledger [Contents][Index]
Something that stops many people from keeping a ledger at all is the insanity of tracking small cash expenses. They rarely generate a receipt, and there are often a lot of small postings, rather than a few large ones, as with checks.
One solution is: don’t bother. Move your spending to a debit card, but in general ignore cash. Once you withdraw it from the ATM, mark it as already spent to an ‘Expenses:Cash’ category:
2004/03/15 ATM Expenses:Cash $100.00 Assets:Checking
If at some point you make a large cash expense that you want to track, just move the amount of the expense from ‘Expenses:Cash’ into the target account:
2004/03/20 Somebody Expenses:Food $65.00 Expenses:Cash
This way, you can still track large cash expenses, while ignoring all of the smaller ones.
Previous: Dealing with Petty Cash, Up: Principles of Accounting with Ledger [Contents][Index]
There are situations when the accounts you’re tracking are different between your clients and the financial institutions where money is kept. An example of this is working as the treasurer for a religious institution. From the secular point of view, you might be working with three different accounts:
From a religious point of view, the community expects to divide its resources into multiple “funds”, from which it makes purchases or reserves resources for later:
The problem with this kind of setup is that, when you spend money, it comes from two or more places at once: the account and the fund. And yet, the correlation of amounts between funds and accounts is rarely one-to-one. What if the school fund has ‘$500.00’, but ‘$400.00’ of that comes from Checking, and ‘$100.00’ from Savings?
Traditional finance packages require that the money reside in only one place. But there are really two “views” of the data: from the account point of view and from the fund point of view—yet both sets should reflect the same overall expenses and cash flow. It’s simply where the money resides that differs.
This situation can be handled in one of two ways. The first is using virtual postings to represent the fact that money is moving to and from two kind of accounts at the same time:
2004/03/20 Contributions Assets:Checking $500.00 Income:Donations 2004/03/25 Distribution of donations [Funds:School] $300.00 [Funds:Building] $200.00 [Assets:Checking] $-500.00
The use of square brackets in the second transaction ensures that the virtual postings balance to zero. Now money can be spent directly from a fund at the same time as money is drawn from a physical account:
2004/03/25 Payment for books (paid from Checking) Expenses:Books $100.00 Assets:Checking $-100.00 (Funds:School) $-100.00
The use of round brackets creates a virtual posting without ensuring a balance to zero. When reports are generated, by default they’ll appear in terms of the funds. In this case, you will likely want to mask out your ‘Assets’ account, because otherwise the balance won’t make much sense:
$ ledger --no-total bal not ^Assets
$100.00 Expenses:Books $400.00 Funds $200.00 Building $200.00 School $-500.00 Income:Donations
If the --real option is used, the report will be in terms of the real accounts:
$ ledger --real --no-total bal
$400.00 Assets:Checking $100.00 Expenses:Books $-500.00 Income:Donations
If more asset accounts are needed as the source of a posting, just list them as you would normally, for example:
2004/03/25 Payment for books (paid from Checking) Expenses:Books $100.00 Assets:Checking $-50.00 Liabilities:Credit Card $-50.00 (Funds:School) $-100.00
The second way of tracking funds is to use transaction codes. In this respect the codes become like virtual accounts that embrace the entire set of postings. Basically, we are associating a transaction with a fund by setting its code. Here are two transactions that deposit money into, and spend money from, the ‘Funds:School’ fund:
2004/03/25 (Funds:School) Donations Assets:Checking $100.00 Income:Donations 2004/03/25 (Funds:Building) Donations Assets:Checking $20.00 Income:Donations 2004/04/25 (Funds:School) Payment for books Expenses:Books $50.00 Assets:Checking
Note how the accounts now relate only to the real accounts, and any balance or register reports will reflect this. That the transactions relate to a particular fund is kept only in the code.
How does this become a fund report? By using the --payee=code option, you can generate a register report where the payee for each posting shows the code. Alone, this is not terribly interesting; but when combined with the --by-payee (-P) option, you will now see account subtotals for any postings related to a specific fund. So, to see the current monetary balances of all funds, the command would be:
$ ledger --payee=code -P reg ^Assets
04-Mar-25 Funds:Building Assets:Checking $20.00 $20.00 04-Mar-25 Funds:School Assets:Checking $50.00 $70.00
Or to see a particular fund’s expenses, the ‘School’ fund in this case:
$ ledger --payee=code -P reg ^Expenses and code School
04-Apr-25 Funds:School Expenses:Books $50.00 $50.00
Both approaches yield different kinds of flexibility, depending on how you prefer to think of your funds: as virtual accounts, or as tags associated with particular transactions. Your own tastes will decide which is best for your situation.
Next: Transactions, Previous: Principles of Accounting with Ledger, Up: Top [Contents][Index]
The most important part of accounting is keeping a good journal. If you have a good journal, tools can be written to work whatever mathematical tricks you need to better understand your spending patterns. Without a good journal, no tool, however smart, can help you.
The Ledger program aims at making journal transactions as simple as possible. Since it is a command-line tool, it does not provide a user interface for keeping a journal. If you require an user interface to maintain journal transactions GnuCash is a good alternative.
If you are not using GnuCash, but a text editor to maintain your journal, read on. Ledger has been designed to make data transactions as simple as possible, by keeping the journal format easy, and also by automagically determining as much information as possible based on the nature of your transactions.
For example, you do not need to tell Ledger about the accounts you use. Any time Ledger sees a posting involving an account it knows nothing about, it will create it2. If you use a commodity that is new to Ledger, it will create that commodity, and determine its display characteristics (placement of the symbol before or after the amount, display precision, etc.) based on how you used the commodity in the posting.
Next: Starting up, Previous: Keeping a Journal, Up: Keeping a Journal [Contents][Index]
Here is the Pacific Bell example from above, given as a Ledger posting, with the addition of a check number:
9/29 (1023) Pacific Bell Expenses:Utilities:Phone $23.00 Assets:Checking $-23.00
As you can see, it is very similar to what would be written on paper, minus the computed balance totals, and adding in account names that work better with Ledger’s scheme of things. In fact, since Ledger is smart about many things, you don’t need to specify the balanced amount, if it is the same as the first line:
9/29 (1023) Pacific Bell Expenses:Utilities:Phone $23.00 Assets:Checking
For this transaction, Ledger will figure out that $-23.00 must come from ‘Assets:Checking’ in order to balance the transaction.
Also note the structure of the account entries. There is an implied hierarchy established by separating with colons (see Structuring your Accounts).
The format is very flexible and it isn’t necessary that you indent and space out things exactly as shown. The only requirements are that the start of the transaction (the date typically) is at the beginning of the first line of the transaction, and the accounts are indented by at least one space. If you omit the leading spaces in the account lines Ledger will generate an error. There must be at least two spaces, or a tab, between the amount and the account. If you do not have adequate separation between the amount and the account Ledger will give an error and stop calculating.
Next: Structuring your Accounts, Previous: The Most Basic Entry, Up: Keeping a Journal [Contents][Index]
Unless you have recently arrived from another planet, you already have a financial state. You need to capture that financial state so that Ledger has a starting point.
At some convenient point in time you knew the balances and outstanding obligation of every financial account you have. Those amounts form the basis of the opening entry for ledger. For example if you chose the beginning of 2011 as the date to start tracking finances with ledger, your opening balance entry could look like this:
2011/01/01 * Opening Balance Assets:Joint Checking $800.14 Assets:Other Checking $63.44 Assets:Savings $2805.54 Assets:Investments:401K:Deferred 100.0000 VIFSX @ $80.5227 Assets:Investments:401K:Matching 50.0000 VIFSX @ $83.7015 Assets:Investments:IRA 250.0000 VTHRX @ $20.5324 Liabilities:Mortgage $-175634.88 Liabilities:Car Loan $-3494.26 Liabilities:Visa -$1762.44 Equity:Opening Balances
There is nothing special about the name “Opening Balances” as the payee of the account name, anything convenient that you understand will work.
Next: Commenting on your Journal, Previous: Starting up, Up: Keeping a Journal [Contents][Index]
There really are no requirements for how you do this, but to preserve your sanity we suggest some very basic structure to your accounting system.
At the highest level you have five sorts of accounts:
Starting the structure off this way will make it simpler for you to get answers to the questions you really need to ask about your finances.
Beneath these top level accounts you can have any level of detail you desire. For example, if you want to keep specific track of how much you spend on burgers and fries, you could have the following:
Expenses:Food:Hamburgers and Fries
Next: Currency and Commodities, Previous: Structuring your Accounts, Up: Keeping a Journal [Contents][Index]
Comments are generally started using a ‘;’. However, in order to increase compatibility with other text manipulation programs and methods, four additional comment characters are valid if used at the beginning of a line: ‘#’, ‘|’, and ‘*’ and ‘%’.
Block comments can be made by use comment
... end
comment
.
; This is a single line comment, # and this, % and this, | and this, * and this. comment This is a block comment with multiple lines end comment
There are several forms of comments within a transaction, for example:
; this is a global comment that is not applied to a specific transaction ; it can start with any of the five characters but is not included in the ; output from 'print' or 'output' 2011/12/11 Something Sweet ; German Chocolate Cake ; :Broke Diet: Expenses:Food $10.00 ; Friends: The gang Assets:Credit Union:Checking
The first comment is global and Ledger will not attach it to any specific transactions. The comments within the transaction must all start with ‘;’ and are preserved as part of the transaction. The ‘:’ indicates meta-data and tags (see Metadata).
Next: Keeping it Consistent, Previous: Commenting on your Journal, Up: Keeping a Journal [Contents][Index]
Ledger is agnostic when it comes to how you value your accounts. Dollars, Euros, Pounds, Francs, Shares etc. are all just “commodities”. Holdings in stocks, bonds, mutual funds and other financial instruments can be labeled using whatever is convenient for you (stock ticker symbols are suggested for publicly traded assets).3
For the rest of this manual, we will only use the word “commodities” when referring to the units on a transaction value.
This is fundamentally different than many common accounting packages, which assume the same currency throughout all of your accounts. This means if you typically operate in Euros, but travel to the US and have some expenses, you would have to do the currency conversion before you made the entry into your financial system. With ledger this is not required. In the same journal you can have entries in any or all commodities you actually hold. You can use the reporting capabilities to convert all commodities to a single commodity for reporting purposes without ever changing the underlying entry.
For example, the following entries reflect transactions made for a business trip to Europe from the US:
2011/09/23 Cash in Munich Assets:Cash €50.00 Assets:Checking $-66.00 2011/09/24 Dinner in Munich Expenses:Business:Travel €35.00 Assets:Cash
This says that $66.00 came out of checking and turned into 50 Euros. The implied exchange rate was $1.32. Then 35.00 Euros were spent on Dinner in Munich.
Running a ledger balance report shows:
$ ledger -f example.dat bal
$-66.00 €15.00 Assets €15.00 Cash $-66.00 Checking €35.00 Expenses:Business:Travel -------------------- $-66.00 €50.00
The top two lines show my current assets as $-66.00 in checking (in this very short example I didn’t establish opening an opening balance for the checking account) and €15.00. After spending on dinner I have €15.00 in my wallet. The bottom line balances to zero, but is shown in two lines since we haven’t told ledger to convert commodities.
| • Naming Commodities: | ||
| • Buying and Selling Stock: | ||
| • Fixing Lot Prices: | ||
| • Complete control over commodity pricing: |
Next: Buying and Selling Stock, Previous: Currency and Commodities, Up: Currency and Commodities [Contents][Index]
Commodity names can have any character, including white-space. However, if you include white-space or numeric characters, the commodity name must be enclosed in double quotes ‘"’:
1999/06/09 ! Achat Actif:SG PEE STK 49.957 "Arcancia Équilibre 454" Actif:SG PEE STK $-234.90 2000/12/08 ! Achat Actif:SG PEE STK 215.796 "Arcancia Équilibre 455" Actif:SG PEE STK $-10742.54
Next: Fixing Lot Prices, Previous: Naming Commodities, Up: Currency and Commodities [Contents][Index]
Buying stock is a typical example that many will use that involves multiple commodities in the same transaction. The type of the share (AAPL for Apple Inc.) and the share purchase price in the currency unit you made the purchase in ($ for AAPL). Yes, the typical convention is as follows:
2004/05/01 Stock purchase Assets:Broker 50 AAPL @ $30.00 Expenses:Broker:Commissions $19.95 Assets:Broker $-1,519.95
This assumes you have a brokerage account that is capable of managing both liquid and commodity assets. Now, on the day of the sale:
2005/08/01 Stock sale Assets:Broker -50 AAPL {$30.00} @ $50.00 Expenses:Broker:Commissions $19.95 Income:Capital Gains $-1,000.00 Assets:Broker $2,480.05
You can, of course, elide the amount of the last posting. It is there for clarity’s sake.
The ‘{$30.00}’ is a lot price. You can also use a lot date, ‘[2004/05/01]’, or both, in case you have several lots of the same price/date and your taxation model is based on longest-held-first.
Next: Complete control over commodity pricing, Previous: Buying and Selling Stock, Up: Currency and Commodities [Contents][Index]
Commodities that you keep in order to sell at a later time have a variable value that fluctuates with the market prices. Commodities that you consume should not fluctuate in value, but stay at the lot price they were purchased at. As an extension of “lot pricing”, you can fix the per-unit price of a commodity.
For example, say you buy 10 gallons of gas at $1.20. In future “value” reports, you don’t want these gallons reported in terms of today’s price, but rather the price when you bought it. At the same time, you also want other kinds of commodities—like stocks— reported in terms of today’s price.
This is supported as follows:
2009/01/01 Shell Expenses:Gasoline 11 GAL {=$2.299} Assets:Checking
This transaction actually introduces a new commodity, ‘GAL {=$2.29}’, whose market value disregards any future changes in the price of gasoline.
If you do not want price fixing, you can specify this same transaction in one of two ways, both equivalent (note the lack of the equal sign compared to the transaction above):
2009/01/01 Shell Expenses:Gasoline 11 GAL {$2.299} Assets:Checking 2009/01/01 Shell Expenses:Gasoline 11 GAL @ $2.299 Assets:Checking
There is no difference in meaning between these two forms. Why do both exist, you ask? To support things like this:
2009/01/01 Shell Expenses:Gasoline 11 GAL {=$2.299} @ $2.30 Assets:Checking
This transaction says that you bought 11 gallons priced at $2.299 per gallon at a cost to you of $2.30 per gallon. Ledger auto-generates a balance posting in this case to Equity:Capital Losses to reflect the 1.1 cent difference, which is then balanced by Assets:Checking because its amount is null.
Previous: Fixing Lot Prices, Up: Currency and Commodities [Contents][Index]
Ledger allows you to have very detailed control over how your commodities are valued. You can fine tune the results given using the --market or --exchange COMMODITY options. There are now several points of interception; you can specify the valuation method:
market
.
Fixated pricing (such as ‘{=$20}’) still plays a role in this scheme. As far as valuation goes, it’s shorthand for writing ‘((s,d,t -> market($20,d,t)))’.
A valuation function receives three arguments:
source
A string identifying the commodity whose price is being asked for (example: ‘EUR’).
date
The reference date the price should be relative.
target
A string identifying the “target” commodity, or the commodity the returned price should be in. This argument is null if --market was used instead of --exchange COMMODITY.
The valuation function should return an amount. If you’ve written your function in Python, you can return something like ‘Amount("$100")’. If the function returns an explicit value, that value is always used, regardless of the commodity, the date, or the desired target commodity. For example,
define myfunc_seven(s, d, t) = 7 EUR
In order to specify a fixed price, but still valuate that price into the target commodity, use something like this:
define myfunc_five(s, d, t) = market(5 EUR, d, t)
The value
directive sets the valuation used for all commodities
used in the rest of the data stream. This is the fallback, if nothing
more specific is found.
value myfunc_seven
You can set a specific valuation function on a per-commodity basis. Instead of defining a function, you can also pass a lambda.
commodity $ value s, d, t -> 6 EUR
Each account can also provide a default valuation function for any commodities transferred to that account.
account Expenses:Food5 value myfunc_five
The metadata field ‘Value’, if found, overrides the valuation function on a transaction-wide or per-posting basis.
= @XACT and Food ; Value:: 8 EUR (Equity) $1 = @POST and Dining (Expenses:Food9) $1 ; Value:: 9 EUR
Lastly, you can specify the valuation function/value for any specific amount using the ‘(( ))’ commodity annotation.
2012-03-02 KFC Expenses:Food2 $1 ((2 EUR)) Assets:Cash2 2012-03-03 KFC Expenses:Food3 $1 ; Value:: 3 EUR Assets:Cash3 2012-03-04 KFC ; Value:: 4 EUR Expenses:Food4 $1 Assets:Cash4 2012-03-05 KFC Expenses:Food5 $1 Assets:Cash5 2012-03-06 KFC Expenses:Food6 $1 Assets:Cash6 2012-03-07 KFC Expenses:Food7 1 CAD Assets:Cash7 2012-03-08 XACT Expenses:Food8 $1 Assets:Cash8 2012-03-09 POST Expenses:Dining9 $1 Assets:Cash9
$ ledger reg -V food
12-Mar-02 KFC Expenses:Food2 2 EUR 2 EUR 12-Mar-03 KFC Expenses:Food3 3 EUR 5 EUR 12-Mar-04 KFC Expenses:Food4 4 EUR 9 EUR 12-Mar-05 KFC Expenses:Food5 $1 $1 9 EUR 12-Mar-06 KFC Expenses:Food6 $1 $2 9 EUR 12-Mar-07 KFC Expenses:Food7 1 CAD $2 1 CAD 9 EUR 12-Mar-08 XACT Expenses:Food8 $1 $3 1 CAD 9 EUR
Next: Journal Format, Previous: Currency and Commodities, Up: Keeping a Journal [Contents][Index]
Sometimes Ledger’s flexibility can lead to difficulties. Using a freeform text editor to enter transactions makes it easy to keep the data, but also easy to enter accounts or payees inconsistently or with spelling errors.
In order to combat inconsistency you can define allowable accounts and payees. For simplicity, create a separate text file and define accounts and payees like
account Expenses account Expenses:Utilities
Using the --strict option will cause Ledger to complain if any accounts are not previously defined:
$ ledger bal --strict Warning: "FinanceData/Master.dat", line 6: Unknown account 'Liabilities:Tithe Owed' Warning: "FinanceData/Master.dat", line 8: Unknown account 'Liabilities:Tithe Owed' Warning: "FinanceData/Master.dat", line 15: Unknown account 'Allocation:Equities:Domestic'
If you have a large Ledger register already created use the
accounts
command to get started:
$ ledger accounts >> Accounts.dat
You will have to edit this file to add the account
directive in
front of every line.
Next: Converting from other formats, Previous: Keeping it Consistent, Up: Keeping a Journal [Contents][Index]
The ledger file format is quite simple, but also very flexible. It supports many options, though typically the user can ignore most of them. They are summarized below.
| • Transactions and Comments: | ||
| • Command Directives: |
Next: Command Directives, Previous: Journal Format, Up: Journal Format [Contents][Index]
The initial character of each line determines what the line means, and how it should be interpreted. Allowable initial characters are:
NUMBER
A line beginning with a number denotes a transaction. It may be followed by any number of lines, each beginning with white-space, to denote the transaction’s account postings. The format of the first line is:
DATE[=EDATE] [*|!] [(CODE)] DESC
If ‘*’ appears after the date (with optional effective date), it
indicates the transaction is “cleared”, which can mean whatever the
user wants it to mean. If ‘!’ appears after the date, it
indicates the transaction is “pending”; i.e., tentatively cleared
from the user’s point of view, but not yet actually cleared. If
a CODE
appears in parentheses, it may be used to indicate
a check number, or the type of the posting. Following these is the
payee, or a description of the posting.
The format of each following posting is:
ACCOUNT AMOUNT [; NOTE]
The ACCOUNT
may be surrounded by parentheses if it is a virtual
posting, or square brackets if it is a virtual posting that
must balance. The AMOUNT
can be followed by a per-unit
posting cost, by specifying @ AMOUNT
, or a complete
posting cost with @@ AMOUNT
. Lastly, the NOTE
may
specify an actual and/or effective date for the posting by using
the syntax [ACTUAL_DATE]
or [=EFFECTIVE_DATE]
or
[ACTUAL_DATE=EFFECTIVE_DATE]
(see Virtual postings).
P
Specifies a historical price for a commodity. These are usually found in a pricing history file (see the --download (-Q) option). The syntax is:
P DATE SYMBOL PRICE
=
An automated transaction. A value expression must appear after the equal sign.
After this initial line there should be a set of one or more postings, just as if it were a normal transaction. If the amounts of the postings have no commodity, they will be applied as multipliers to whichever real posting is matched by the value expression (see Automated Transactions).
~
A periodic transaction. A period expression must appear after the tilde.
After this initial line there should be a set of one or more postings, just as if it were a normal transaction.
; # % | *
A line beginning with a semicolon, pound, percent, bar or asterisk indicates a comment, and is ignored. Comments will not be returned in a “print” response.
indented ;
If the semicolon is indented and occurs inside a transaction, it is parsed as a persistent note for its preceding category. These notes or tags can be used to augment the reporting and filtering capabilities of Ledger.
Previous: Transactions and Comments, Up: Journal Format [Contents][Index]
beginning of line
Command directives must occur at the beginning of a line. Use of ‘!’ and ‘@’ is deprecated.
account
Pre-declare valid account names. This only has an effect if
--strict or --pedantic is used (see below). The
account
directive supports several optional sub-directives, if
they immediately follow the account directive and if they begin with
whitespace:
account Expenses:Food note This account is all about the chicken! alias food payee ^(KFC|Popeyes)$ check commodity == "$" assert commodity == "$" eval print("Hello!") default
The note
sub-directive associates a textual note with the
account. This can be accessed later using the note
value
expression function in any account context.
The alias
sub-directive, which can occur multiple times, allows
the alias to be used in place of the full account name anywhere that
account names are allowed.
The payee
sub-directive, which can occur multiple times,
provides regexes that identify the account if that payee is
encountered and an account within its transaction ends in the name
"Unknown". Example:
2012-02-27 KFC Expenses:Unknown $10.00 ; Read now as "Expenses:Food" Assets:Cash
The check
and assert
directives warn or raise an error
(respectively) if the given value expression evaluates to false within
the context of any posting.
The eval
directive evaluates the value expression in the
context of the account at the time of definition. At the moment this
has little value.
The default
directive specifies that this account should be
used as the “balancing account” for any future transactions that
contain only a single posting.
apply account
Sets the root for all accounts following this directive. Ledger supports a hierarchical tree of accounts. It may be convenient to keep two “root accounts”. For example you may be tracking your personal finances and your business finances. In order to keep them separate you could preface all personal accounts with ‘personal:’ and all business accounts with ‘business:’. You can easily split out large groups of transactions without manually editing them using the account directive. For example:
apply account Personal 2011/11/15 Supermarket Expenses:Groceries $ 50.00 Assets:Checking
Would result in all postings going into ‘Personal:Expenses:Groceries’ and ‘Personal:Assets:Checking’ until an ‘end apply account’ directive was found.
apply fixed
A fixed block is used to set fixated prices (see Fixated prices and costs) for a series of transactions. It’s purely a typing saver, for use when entering many transactions with fixated prices.
Thus, the following:
apply fixed CAD $0.90 2012-04-10 Lunch in Canada Assets:Wallet -15.50 CAD Expenses:Food 15.50 CAD 2012-04-11 Second day Dinner in Canada Assets:Wallet -25.75 CAD Expenses:Food 25.75 CAD end apply fixed
is equivalent to this:
2012-04-10 Lunch in Canada Assets:Wallet -15.50 CAD {=$0.90} Expenses:Food 15.50 CAD {=$0.90} 2012-04-11 Second day Dinner in Canada Assets:Wallet -25.75 CAD {=$0.90} Expenses:Food 25.75 CAD {=$0.90}
alias
Define an alias for an account name. If you have a deeply nested tree of accounts, it may be convenient to define an alias, for example:
alias Dining=Expenses:Entertainment:Dining alias Checking=Assets:Credit Union:Joint Checking Account 2011/11/28 YummyPalace Dining $10.00 Checking
The aliases are only in effect for transactions read in after the alias
is defined and are affected by account
directives that precede
them.
$ ledger bal --no-total ^Exp
$10.00 Expenses:Entertainment:Dining
With the option --recursive-aliases, aliases can refer to other aliases, the following example produces exactly the same transactions and account names as the preceding one:
alias Entertainment=Expenses:Entertainment alias Dining=Entertainment:Dining alias Checking=Assets:Credit Union:Joint Checking Account 2011/11/30 ChopChop Dining $10.00 Checking
$ ledger balance --no-total --recursive-aliases ^Exp
$10.00 Expenses:Entertainment:Dining
The option --no-aliases completely disables alias expansion. All accounts are read verbatim as they are in the ledger file.
assert
An assertion can throw an error if a condition is not met during Ledger’s run.
assert <VALUE EXPRESSION BOOLEAN RESULT>
bucket
Defines the default account to use for balancing transactions.
Normally, each transaction has at least two postings, which must
balance to zero. Ledger allows you to leave one posting with no
amount and automatically balance the transaction in the
posting. The bucket
allows you to fill in all postings and
automatically generate an additional posting to the bucket account
balancing the transaction. If any transaction is unbalanced, it
will automatically be balanced against the bucket
account.
The following example sets ‘Assets:Checking’ as the bucket:
bucket Assets:Checking 2011/01/25 Tom's Used Cars Expenses:Auto $ 5,500.00 2011/01/27 Book Store Expenses:Books $20.00 2011/12/01 Sale Assets:Checking:Business $ 30.00
capture
Directs Ledger to replace any account matching a regex with the given account. For example:
capture Expenses:Deductible:Medical Medical
Would cause any posting with ‘Medical’ in its name to be replaced with ‘Expenses:Deductible:Medical’.
Ledger will display the mapped payees in print
and
register
reports.
check
A check issues a warning if a condition is not met during Ledger’s run.
check <VALUE EXPRESSION BOOLEAN RESULT>
comment
Start a block comment, closed by end comment
.
commodity
Pre-declare commodity names. This only has an effect if --strict or --pedantic is used (see below).
commodity $ commodity CAD
The commodity
directive supports several optional
sub-directives, if they immediately follow the commodity directive
and—if they are on successive lines—begin with whitespace:
commodity $ note American Dollars format $1,000.00 nomarket alias USD default
The note
sub-directive associates a textual note with the
commodity. At present this has no value other than documentation.
The format
sub-directive gives you a way to tell Ledger how to
format this commodity. In the future, using this directive will disable
Ledger’s observation of other ways that commodity is used, and will
provide the “canonical” representation.
The nomarket
sub-directive states that the commodity’s price
should never be auto-downloaded.
The alias
sub-directive states that any commodity matching this
symbol is to use the commodity declared in this block.
The default
sub-directive marks this as the “default” commodity.
define
Allows you to define value expressions for future use. For example:
define var_name=$100 2011/12/01 Test Expenses (var_name*4) Assets
The posting will have a cost of $400.
end
Closes block commands like apply
or comment
.
expr
include
Include the stated file as if it were part of the current file. The file name can contain a wildcard (‘*’) to refer to multiple files (e.g. ‘bank/*.ledger’).
payee
The payee
directive supports two optional sub-directives, if they
immediately follow the payee directive and—if it is on a successive
line—begins with whitespace:
payee KFC alias KENTUCKY FRIED CHICKEN uuid 2a2e21d434356f886c84371eebac6e44f1337fda
The alias
sub-directive provides a regex which, if it matches
a parsed payee, the declared payee name is substituted:
2012-02-27 KENTUCKY FRIED CHICKEN ; will be read as being 'KFC'
The uuid
sub-directive specifies that a transaction with exactly
the uuid given should have the declared payee name substituted:
2014-05-13 UNHELPFUL PAYEE ; will be read as being 'KFC' ; UUID: 2a2e21d434356f886c84371eebac6e44f1337fda
Ledger will display the mapped payees in print
and
register
reports.
apply tag
Allows you to designate a block of transactions and assign the same tag to all. Tags can have values and may be nested.
apply tag hastag apply tag nestedtag: true 2011/01/25 Tom's Used Cars Expenses:Auto $ 5,500.00 ; :nobudget: Assets:Checking 2011/01/27 Book Store Expenses:Books $20.00 Liabilities:MasterCard end apply tag 2011/12/01 Sale Assets:Checking:Business $ 30.00 Income:Sales end apply tag
is the equivalent of:
2011/01/25 Tom's Used Cars ; :hastag: ; nestedtag: true Expenses:Auto $ 5,500.00 ; :nobudget: Assets:Checking 2011/01/27 Book Store ; :hastag: ; nestedtag: true Expenses:Books $20.00 Liabilities:MasterCard 2011/12/01 Sale ; :hastag: Assets:Checking:Business $ 30.00 Income:Sales
tag
Pre-declares tag names. This only has an effect if --strict or --pedantic is used (see below).
tag Receipt tag CSV
The tag
directive supports two optional sub-directives, if they
immediately follow the tag directive and—if on a successive
line—begin with whitespace:
tag Receipt check value =~ /pattern/ assert value != "foobar"
The check
and assert
sub-directives warn or error
(respectively) if the given value expression evaluates to false within
the context of any use of the related tag. In such a context,
“value” is bound to the value of the tag (which may be something else
but a string if typed metadata is used!). Such checks or assertions are
not called if no value is given.
test
This is a synonym for comment
and must be closed by an
end
tag.
year
Denotes the year used for all subsequent transactions that give a date
without a year. The year should appear immediately after the
directive, for example: year 2004
. This is useful at the
beginning of a file, to specify the year for that file. If all
transactions specify a year, however, this command has no effect.
The following single letter commands may be at the beginning of a line alone, for backwards compatibility with older Ledger versions.
A
See bucket.
Y
See year.
N SYMBOL
Indicates that pricing information is to be ignored for a given symbol, nor will quotes ever be downloaded for that symbol. Useful with a home currency, such as the dollar ‘$’. It is recommended that these pricing options be set in the price database file, which defaults to ~/.pricedb. The syntax for this command is:
N SYMBOL
D AMOUNT
Specifies the default commodity to use, by specifying an amount in the
expected format. The xact
command will use this commodity as
the default when none other can be determined. This command may be used
multiple times, to set the default flags for different commodities;
whichever is seen last is used as the default commodity. For example,
to set US dollars as the default commodity, while also setting the
thousands flag and decimal flag for that commodity, use:
D $1,000.00
C AMOUNT1 = AMOUNT2
Specifies a commodity conversion, where the first amount is given to be equivalent to the second amount. The first amount should use the decimal precision desired during reporting:
C 1.00 Kb = 1024 bytes
I, i, O, o, b, h
These four relate to timeclock support, which permits Ledger to read timelog files. See timeclock’s documentation for more info on the syntax of its timelog files.
Next: Archiving Previous Years, Previous: Journal Format, Up: Keeping a Journal [Contents][Index]
There are numerous tools to help convert various formats to a Ledger file. Most banks will generate a comma separated values file that can easily be parsed into Ledger format using one of those tools. Some of the most popular tools are:
ledger convert download.csv
hledger -f checking.csv print
icsv2ledger
csvToLedger
CSV2Ledger
Directly pulling information from banks is outside the scope of Ledger’s function.
Previous: Converting from other formats, Up: Keeping a Journal [Contents][Index]
After a while, your journal can get to be pretty large. While this will not slow down Ledger—it’s designed to process journals very quickly—things can start to feel “messy”; and it’s a universal complaint that when finances feel messy, people avoid them.
Thus, archiving the data from previous years into their own files can
offer a sense of completion, and freedom from the past. But how to
best accomplish this with the ledger program? There are two commands
that make it very simple: print
, and equity
.
Let’s take an example file, with data ranging from year 2000 until
2004. We want to archive years 2000 and 2001 to their own file,
leaving 2002–2004 in the current file. So, use print
to
output all the earlier transactions to a file called
ledger-old.dat:
$ ledger -f ledger.dat -b 2000 -e 2002 print > ledger-old.dat
Note that -e limits output to transactions before the date specified.
To delete older data from the current ledger file, use print
again, this time specifying year 2002 as the starting date:
$ ledger -f ledger.dat -b 2002 print > x $ mv x ledger.dat
However, now the current file contains only postings from 2002 onward, which will not yield accurate present-day balances, because the net income from previous years is no longer being tallied. To compensate for this, we must append an equity report for the old ledger at the beginning of the new one:
$ ledger -f ledger-old.dat equity > equity.dat $ cat equity.dat ledger.dat > x $ mv x ledger.dat $ rm equity.dat
Now the balances reported from ledger.dat are identical to what they were before the data was split.
How often should you split your ledger? You never need to, if you don’t want to. Even eighty years of data will not slow down ledger much, and that’s just using present day hardware! Or, you can keep the previous and current year in one file, and each year before that in its own file. It’s really up to you, and how you want to organize your finances. For those who also keep an accurate paper trail, it might be useful to archive the older years to their own files, then burn those files to a CD to keep with the paper records—along with any electronic statements received during the year. In the arena of organization, just keep in mind this maxim: Do whatever keeps you doing it.
Next: Building Reports, Previous: Keeping a Journal, Up: Top [Contents][Index]
Next: Eliding amounts, Previous: Transactions, Up: Transactions [Contents][Index]
The most basic form of transaction is:
2012-03-10 KFC Expenses:Food $20.00 Assets:Cash $-20.00
This transaction has a date, a payee or description, a target account (the first posting), and a source account (the second posting). Each posting specifies what action is taken related to that account.
A transaction can have any number of postings:
2012-03-10 KFC Expenses:Food $20.00 Assets:Cash $-10.00 Liabilities:Credit $-10.00
Next: Auxiliary dates, Previous: Basic format, Up: Transactions [Contents][Index]
The first thing you can do to make things easier is elide amounts. That is, if exactly one posting has no amount specified, Ledger will infer the inverse of the other postings’ amounts:
2012-03-10 KFC Expenses:Food $20.00 Assets:Cash $-10.00 Liabilities:Credit ; same as specifying $-10
If the other postings use multiple commodities, Ledger will copy the empty posting N times and fill in the negated values of the various commodities:
2012-03-10 KFC Expenses:Food $20.00 Expenses:Tips $2.00 Assets:Cash EUR -10.00 Assets:Cash GBP -10.00 Liabilities:Credit
This transaction is identical to writing:
2012-03-10 KFC Expenses:Food $20.00 Expenses:Tips $2.00 Assets:Cash EUR -10.00 Assets:Cash GBP -10.00 Liabilities:Credit $-22.00 Liabilities:Credit EUR 10.00 Liabilities:Credit GBP 10.00
Next: Codes, Previous: Eliding amounts, Up: Transactions [Contents][Index]
You can associate a second date with a transaction by following the primary date with an equals sign:
2012-03-10=2012-03-08 KFC Expenses:Food $20.00 Assets:Cash $-20.00
What this auxiliary date means is entirely up to you. The only use Ledger has for it is that if you specify --aux-date, then all reports and calculations (including pricing) will use the auxiliary date as if it were the primary date.
Next: Transaction state, Previous: Auxiliary dates, Up: Transactions [Contents][Index]
A transaction can have a textual “code”. This has no meaning and is only displayed by the print command. Checking accounts often use codes like DEP, XFER, etc., as well as check numbers. This is to give you a place to put those codes:
2012-03-10 (#100) KFC Expenses:Food $20.00 Assets:Checking
Next: Transaction notes, Previous: Codes, Up: Transactions [Contents][Index]
A transaction can have a “state”: cleared, pending, or uncleared. The default is uncleared. To mark a transaction cleared, put an asterisk ‘*’ after the date, before the code or payee:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash
To mark it pending, use a ‘!’:
2012-03-10 ! KFC Expenses:Food $20.00 Assets:Cash
What these mean is entirely up to you. The --cleared option limits reports to only cleared items, while --uncleared shows both uncleared and pending items, and --pending shows only pending items.
I use cleared to mean that I’ve reconciled the transaction with my bank statement, and pending to mean that I’m in the middle of a reconciliation.
When you clear a transaction, that’s really just shorthand for clearing all of its postings. That is:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash
Is the same as writing:
2012-03-10 KFC * Expenses:Food $20.00 * Assets:Cash
You can mark individual postings as cleared or pending, in case one “side” of the transaction has cleared, but the other hasn’t yet:
2012-03-10 KFC Liabilities:Credit $100.00 * Assets:Checking
Next: Metadata, Previous: Transaction state, Up: Transactions [Contents][Index]
After the payee, and after at least one tab or two spaces (or a space and a tab), which Ledger calls a “hard separator”, you may introduce a note about the transaction using the ‘;’ character:
2012-03-10 * KFC ; yum, chicken... Expenses:Food $20.00 Assets:Cash
Notes can also appear on the next line, so long as that line begins with whitespace:
2012-03-10 * KFC ; yum, chicken... ; and more notes... Expenses:Food $20.00 Assets:Cash 2012-03-10 * KFC ; just these notes... Expenses:Food $20.00 Assets:Cash
A transaction’s note is shared by all its postings. This becomes significant when querying for metadata (see below). To specify that a note belongs only to one posting, place it after a hard separator after the amount, or on its own line preceded by whitespace:
2012-03-10 * KFC Expenses:Food $20.00 ; posting #1 note Assets:Cash ; posting #2 note, extra indentation is optional
Next: Virtual postings, Previous: Transaction notes, Up: Transactions [Contents][Index]
One of Ledger’s more powerful features is the ability to associate typed metadata with postings and transactions (by which I mean all of a transaction’s postings). This metadata can be queried, displayed, and used in calculations.
The are two forms of metadata: plain tags, and tag/value pairs.
| • Metadata tags: | ||
| • Metadata values: | ||
| • Typed metadata: |
Next: Metadata values, Previous: Metadata, Up: Metadata [Contents][Index]
To tag an item, put any word not containing whitespace between two colons inside a comment:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash ; :TAG:
You can gang up multiple tags by sharing colons:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash ; :TAG1:TAG2:TAG3:
| • Payee metadata tag: |
Previous: Metadata tags, Up: Metadata tags [Contents][Index]
“Payee” is a special metadata field. If set on a posting, it will be
used as the payee name for that posting. This affects the
register
report, the payees
report, and the
--by-payee option.
This is useful when for example you deposit 4 checks at a time to the bank. On the bank statement, there is just one amount ‘$400’, but you can specify from whom each check came, as shown by example below:
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
When reporting with
$ ledger reg
it appears as:
10-Jun-17 Sample Assets:Bank $400.00 $400.00 Person One Income:Check1 $-100.00 $300.00 Person Two Income:Check2 $-100.00 $200.00 Person Three Income:Check3 $-100.00 $100.00 Person Four Income:Check4 $-100.00 0
This shows that they are all in the same transaction (which is why the date is not repeated), but they have different payees now.
If using the --strict or --pedantic options, you must declare this tag to avoid warnings and errors.
The payee name used with the tag is not enforced by the --check-payees option, due to a bug: https://github.com/ledger/ledger/issues/556.
Next: Typed metadata, Previous: Metadata tags, Up: Metadata [Contents][Index]
To associate a value with a tag, use the syntax “Key: Value”, where the value can be any string of characters. Whitespace is needed after the colon, and cannot appear in the Key:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash ; MyTag: This is just a bogus value for MyTag
Previous: Metadata values, Up: Metadata [Contents][Index]
If a metadata tag ends in ::, its value will be parsed as a value expression and stored internally as a value rather than as a string. For example, although I can specify a date textually like so:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash ; AuxDate: 2012/02/30
This date is just a string, and won’t be parsed as a date unless its value is used in a date-context (at which time the string is parsed into a date automatically every time it is needed as a date). If on the other hand I write this:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash ; AuxDate:: [2012/02/30]
Then it is parsed as a date only once, and during parsing of the journal file, which would let me know right away that it is an invalid date.
Next: Expression amounts, Previous: Metadata, Up: Transactions [Contents][Index]
Ordinarily, the amounts of all postings in a transaction must balance to zero. This is non-negotiable. It’s what double-entry accounting is all about! But there are some tricks up Ledger’s sleeve...
You can use virtual accounts to transfer amounts to an account on the sly, bypassing the balancing requirement. The trick is that these postings are not considered “real”, and can be removed from all reports using --real.
To specify a virtual account, surround the account name with parentheses:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash (Budget:Food) $-20.00
If you want, you can state that virtual postings should balance against one or more other virtual postings by using brackets (which look “harder”) rather than parentheses:
2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash [Budget:Food] $-20.00 [Equity:Budgets] $20.00
Next: Balance verification, Previous: Virtual postings, Up: Transactions [Contents][Index]
An amount is a numerical figure with a commodity, but it can also be any value expression. To indicate this, surround the amount expression with parentheses:
2012-03-10 * KFC Expenses:Food ($10.00 + $20.00) ; Ledger adds it up for you Assets:Cash
Next: Posting cost, Previous: Expression amounts, Up: Transactions [Contents][Index]
| • Balance assertions: | ||
| • Balance assignments: | ||
| • Resetting a balance: | ||
| • Balancing transactions: |
If at the end of a posting’s amount (and after the cost too, if there is one) there is an equals sign, then Ledger will verify that the total value for that account as of that posting matches the amount specified. See --permissive option to relax the balance assertions checks.
There are two forms of this features: balance assertions, and balance assignments.
Next: Balance assignments, Previous: Balance verification, Up: Balance verification [Contents][Index]
A balance assertion has this general form:
2012-03-10 KFC Expenses:Food $20.00 Assets:Cash $-20.00 = $500.00
This simply asserts that after subtracting $20.00 from Assets:Cash, that the resulting total matches $500.00. If not, it is an error.
The assertion has an effect only on the specified commodity. If an account has multiple commodities, then only the one asserted is verified:
2012-03-10 KFC New York Expenses:Food $20.00 Assets:Cash $-20.00 = $500.00 2012-03-11 KFC Montreal Expenses:Food 15.00 CAD Assets:Cash -15.00 CAD = $500.00
In this case, the amount in USD of cash (which has not changed) is validated. Nothing is asserted about the current amount of Canadian dollars in ‘Asset:Cash’.
The only value that can be asserted without a commodity is ‘0’. This results in a cross-commodities assertion, which makes it possible to assert that an account is totally empty.
2012-03-09 Fill Wallet Revenue $20.00 Revenue 15.00 CAD Assets:Cash 2012-03-10 KFC New York Expenses:Food $20.00 Assets:Cash $-20.00 2012-03-11 KFC Montreal Expenses:Food 15.00 CAD Assets:Cash -15.00 CAD = 0
The last transaction will assert that we are out of cash of any sort.
Next: Resetting a balance, Previous: Balance assertions, Up: Balance verification [Contents][Index]
A balance assignment has this form:
2012-03-10 KFC Expenses:Food $20.00 Assets:Cash = $500.00
This sets the amount of the second posting to whatever it would need to be for the total in ‘Assets:Cash’ to be $500.00 after the posting. If the resulting amount is not $-20.00 in this case, it is an error.
Next: Balancing transactions, Previous: Balance assignments, Up: Balance verification [Contents][Index]
Say your book-keeping has gotten a bit out of date, and your Ledger balance no longer matches your bank balance. You can create an adjustment transaction using balance assignments:
2012-03-10 Adjustment Assets:Cash = $500.00 Equity:Adjustments
Since the second posting is also null, its value will become the inverse of whatever amount is generated for the first posting.
This is the only time in ledger when more than one posting’s amount may be empty—and then only because it’s not truly empty, it is indirectly provided by the balance assignment’s value.
Previous: Resetting a balance, Up: Balance verification [Contents][Index]
As a consequence of all the above, consider the following transaction:
2012-03-10 My Broker [Assets:Brokerage] = 10 AAPL
What this says is: set the amount of the posting to whatever value is needed so that ‘Assets:Brokerage’ contains 10 AAPL. Then, because this posting must balance, ensure that its value is zero. This can only be true if Assets:Brokerage does indeed contain 10 AAPL at that point in the input file.
A balanced virtual transaction is used simply to indicate to Ledger that this is not a “real” transaction. It won’t appear in any reports anyway (unless you use a register report with --empty).
Next: Explicit posting costs, Previous: Balance verification, Up: Transactions [Contents][Index]
When you transfer a commodity from one account to another, sometimes it gets transformed during the transaction. This happens when you spend money on gas, for example, which transforms dollars into gallons of gasoline, or dollars into stocks in a company.
In those cases, Ledger will remember the “cost” of that transaction for you, and can use it during reporting in various ways. Here’s an example of a stock purchase:
2012-03-10 My Broker Assets:Brokerage 10 AAPL Assets:Brokerage:Cash $-500.00
This is different from transferring 10 AAPL shares from one account to another, in this case you are exchanging one commodity for another. The resulting posting’s cost is $50.00 per share.
Next: Posting cost expressions, Previous: Posting cost, Up: Transactions [Contents][Index]
You can make any posting’s cost explicit using the ‘@’ symbol after the amount or amount expression:
2012-03-10 My Broker Assets:Brokerage 10 AAPL @ $50.00 Assets:Brokerage:Cash $-500.00
When you do this, since Ledger can now figure out the balancing amount from the first posting’s cost, you can elide the other amount:
2012-03-10 My Broker Assets:Brokerage 10 AAPL @ $50.00 Assets:Brokerage:Cash
| • Primary and secondary commodities: |
Previous: Explicit posting costs, Up: Explicit posting costs [Contents][Index]
It is a general convention within Ledger that the “top” postings in a transaction contain the target accounts, while the final posting contains the source account. Whenever a commodity is exchanged like this, the commodity moved to the target account is considered “secondary”, while the commodity used for purchasing and tracked in the cost is “primary”.
Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @ AMOUNT", the commodity used in the second amount is marked “primary”.
The only meaning a primary commodity has is that the --market (-V) flag will never convert a primary commodity into any other commodity. --exchange COMMODITY (-X) still will, however.
Next: Total posting costs, Previous: Explicit posting costs, Up: Transactions [Contents][Index]
Just as you can have amount expressions, you can have posting expressions:
2012-03-10 My Broker Assets:Brokerage 10 AAPL @ ($500.00 / 10) Assets:Brokerage:Cash
You can even have both:
2012-03-10 My Broker Assets:Brokerage (5 AAPL * 2) @ ($500.00 / 10) Assets:Brokerage:Cash
Next: Virtual posting costs, Previous: Posting cost expressions, Up: Transactions [Contents][Index]
The cost figure following the ‘@’ character specifies the per-unit price for the commodity being transferred. If you’d like to specify the total cost instead, use ‘@@’:
2012-03-10 My Broker Assets:Brokerage 10 AAPL @@ $500.00 Assets:Brokerage:Cash
Ledger reads this as if you had written:
2012-03-10 My Broker Assets:Brokerage 10 AAPL @ ($500.00 / 10) Assets:Brokerage:Cash
Next: Commodity prices, Previous: Total posting costs, Up: Transactions [Contents][Index]
Normally whenever a commodity exchange like this happens, the price of the exchange (such as $50 per share of AAPL, above) is recorded in Ledger’s internal price history database. To prevent this from happening in the case of an exceptional transaction, surround the ‘@’ or ‘@@’ with parentheses:
2012-03-10 My Brother Assets:Brokerage 1000 AAPL (@) $1 Income:Gifts Received
Next: Prices versus costs, Previous: Virtual posting costs, Up: Transactions [Contents][Index]
When a transaction occurs that exchanges one commodity for another, Ledger records that commodity price not only within its internal price database, but also attached to the commodity itself. Usually this fact remains invisible to the user, unless you turn on --lot-prices to show these hidden price figures.
For example, consider the stock sale given above:
2012-03-10 My Broker Assets:Brokerage 10 AAPL @ $50.00 Assets:Brokerage:Cash
The commodity transferred into ‘Assets:Brokerage’ is not actually 10 AAPL, but rather 10 AAPL {$50.00}. The figure in braces after the amount is called the “lot price”. It’s Ledger’s way of remembering that this commodity was transferred through an exchange, and that $50.00 was the price of that exchange.
This becomes significant if you later sell that commodity again. For example, you might write this:
2012-04-10 My Broker Assets:Brokerage:Cash Assets:Brokerage -10 AAPL @ $75.00
And that would be perfectly fine, but how do you track the capital gains on the sale? It could be done with a virtual posting:
2012-04-10 My Broker Assets:Brokerage:Cash Assets:Brokerage -10 AAPL @ $75.00 (Income:Capital Gains) $-250.00
But this gets messy since capital gains income is very real, and not quite appropriate for a virtual posting.
Instead, if you reference that same hidden price annotation, Ledger will figure out that the price of the shares you’re selling, and the cost you’re selling them at, don’t balance:
2012-04-10 My Broker Assets:Brokerage:Cash $750.00 Assets:Brokerage -10 AAPL {$50.00} @ $75.00
This transaction will fail because the $250.00 price difference between the price you bought those shares at, and the cost you’re selling them for, does not match. The lot price also identifies which shares you purchased on that prior date.
| • Total commodity prices: |
Previous: Commodity prices, Up: Commodity prices [Contents][Index]
As a shorthand, you can specify the total price instead of the per-share price in doubled braces. This goes well with total costs, but is not required to be used with them:
2012-04-10 My Broker Assets:Brokerage:Cash $750.00 Assets:Brokerage -10 AAPL {{$500.00}} @@ $750.00 Income:Capital Gains $-250.00
It should be noted that this is a convenience only for cases where you buy and sell whole lots. The {{$500.00}} is not an attribute of the commodity, whereas {$50.00} is. In fact, when you write {{$500.00}}, Ledger just divides that value by 10 and sees {$50.00}. So if you use the print command to look at this transaction, you’ll see the single braces form in the output. The double braces price form is a shorthand only.
Plus, it comes with dangers. This works fine:
2012-04-10 My Broker Assets:Brokerage 10 AAPL @ $50.00 Assets:Brokerage:Cash $-500.00 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 Assets:Brokerage -5 AAPL {$50.00} @@ $375.00 Income:Capital Gains $-125.00 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 Assets:Brokerage -5 AAPL {$50.00} @@ $375.00 Income:Capital Gains $-125.00
But this does not do what you might expect:
2012-04-10 My Broker Assets:Brokerage 10 AAPL @ $50.00 Assets:Brokerage:Cash $-500.00 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 Assets:Brokerage -5 AAPL {{$500.00}} @@ $375.00 Income:Capital Gains $-125.00 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 Assets:Brokerage -5 AAPL {{$500.00}} @@ $375.00 Income:Capital Gains $-125.00
And in cases where the amounts do not divide into whole figures and must be rounded, the capital gains figure could be off by a cent. Use with caution.
Next: Fixated prices and costs, Previous: Commodity prices, Up: Transactions [Contents][Index]
Because lot pricing provides enough information to infer the cost, the following two transactions are equivalent:
2012-04-10 My Broker Assets:Brokerage 10 AAPL @ $50.00 Assets:Brokerage:Cash $-500.00 2012-04-10 My Broker Assets:Brokerage 10 AAPL {$50.00} Assets:Brokerage:Cash $-500.00
However, note that what you see in some reports may differ, for example in the print report. Functionally, however, there is no difference, and neither the register nor the balance report are sensitive to this difference.
Next: Lot dates, Previous: Prices versus costs, Up: Transactions [Contents][Index]
If you bought a stock last year, and ask for its value today, Ledger will consult its price database to see what the most recent price for that stock is. You can short-circuit this lookup by “fixing” the price at the time of a transaction. This is done using ‘{=AMOUNT}’:
2012-04-10 My Broker Assets:Brokerage 10 AAPL {=$50.00} Assets:Brokerage:Cash $-500.00
These 10 AAPL will now always be reported as being worth $50, no matter what else happens to the stock in the meantime.
Fixated prices are a special case of using lot valuation expressions (see below) to fix the value of a commodity lot.
Since price annotations and costs are largely interchangeable and a matter of preference, there is an equivalent syntax for specified fixated prices by way of the cost:
2012-04-10 My Broker Assets:Brokerage 10 AAPL @ =$50.00 Assets:Brokerage:Cash $-500.00
This is the same as the previous transaction, with the same caveats found in Prices versus costs.
Next: Lot notes, Previous: Fixated prices and costs, Up: Transactions [Contents][Index]
In addition to lot prices, you can specify lot dates and reveal them with --lot-dates. Other than that, however, they have no special meaning to Ledger. They are specified after the amount in square brackets (the same way that dates are parsed in value expressions):
2012-04-10 My Broker Assets:Brokerage:Cash $375.00 Assets:Brokerage -5 AAPL {$50.00} [2012-04-10] @@ $375.00 Income:Capital Gains $-125.00
Next: Lot value expressions, Previous: Lot dates, Up: Transactions [Contents][Index]
You can also associate arbitrary notes for your own record keeping in parentheses, and reveal them with --lot-notes. One caveat is that the note cannot begin with an ‘@’ character, as that would indicate a virtual cost:
2012-04-10 My Broker Assets:Brokerage:Cash $375.00 Assets:Brokerage -5 AAPL {$50.00} [2012-04-10] (Oh my!) @@ $375.00 Income:Capital Gains $-125.00
You can specify any combination of lot prices, dates or notes, in any order. They are all optional.
To show all lot information in a report, use --lots.
Next: Automated Transactions, Previous: Lot notes, Up: Transactions [Contents][Index]
Normally when you ask Ledger to display the values of commodities held, it uses a value expression called “market” to determine the most recent value from its price database—even downloading prices from the Internet, if --download (-Q) was specified and a suitable getquote script is found on your system.
However, you can override this valuation logic by providing a commodity valuation expression in doubled parentheses. This expression must result in one of two values: either an amount to always be used as the per-share price for that commodity; or a function taking three arguments, which is called to determine that price.
If you use the functional form, you can either specify a function name, or a lambda expression. Here’s a function that yields the price as $10 in whatever commodity is being requested:
define ten_dollars(s, date, t) = market($10, date, t)
I can now use that in a lot value expression as follows:
2012-04-10 My Broker Assets:Brokerage:Cash $375.00 Assets:Brokerage -5 AAPL {$50.00} ((ten_dollars)) @@ $375.00 Income:Capital Gains $-125.00
Alternatively, I could do the same thing without pre-defining a function by using a lambda expression taking three arguments:
2012-04-10 My Broker A:B:Cash $375.00 A:B -5 AAPL {$50.00} ((s, d, t -> market($10, date, t))) @@ $375.00 Income:Capital Gains $-125.00
The arguments passed to these functions have the following meaning:
In most cases, it is simplest to either use explicit amounts in your valuation expressions, or just pass the arguments down to ‘market’ after modifying them to suit your needs.
Previous: Lot value expressions, Up: Transactions [Contents][Index]
An automated transaction is a special kind of transaction which adds its postings to other transactions any time one of that other transactions’ postings matches its predicate. The predicate uses the same query syntax as the Ledger command-line.
Consider this posting:
2012-03-10 KFC Expenses:Food $20.00 Assets:Cash
If I write this automated transaction before it in the file:
= expr true Foo $50.00 Bar $-50.00
Then the first transaction will be modified during parsing as if I’d written this:
2012-03-10 KFC Expenses:Food $20.00 Foo $50.00 Bar $-50.00 Assets:Cash $-20.00 Foo $50.00 Bar $-50.00
Despite this fancy logic, automated transactions themselves follow most of the same rules as regular transactions: their postings must balance (unless you use a virtual posting), you can have metadata, etc.
One thing you cannot do, however, is elide amounts in an automated transaction.
Next: Accessing the matching posting's amount, Previous: Automated Transactions, Up: Automated Transactions [Contents][Index]
As a special case, if an automated transaction’s posting’s amount (phew) has no commodity, it is taken as a multiplier upon the matching posting’s cost. For example:
= expr true Foo 50.00 Bar -50.00 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash
Then the latter transaction turns into this during parsing:
2012-03-10 KFC Expenses:Food $20.00 Foo $1000.00 Bar $-1000.00 Assets:Cash $-20.00 Foo $1000.00 Bar $-1000.00
Next: Referring to the matching posting's account, Previous: Amount multipliers, Up: Automated Transactions [Contents][Index]
If you use an amount expression for an automated transaction’s posting, that expression has access to all the details of the matched posting. For example, you can refer to that posting’s amount using the “amount” value expression variable:
= expr true (Foo) (amount * 2) ; same as just "2" in this case 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash
This becomes:
2012-03-10 KFC Expenses:Food $20.00 (Foo) $40.00 Assets:Cash $-20.00 (Foo) $-40.00
Next: Applying metadata to every matched posting, Previous: Accessing the matching posting's amount, Up: Automated Transactions [Contents][Index]
Sometimes you want to refer to the account that was matched in some way within the automated transaction itself. This is done by using the string ‘$account’, anywhere within the account part of the automated posting:
= food (Budget:$account) 10 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash
Becomes:
2012-03-10 KFC Expenses:Food $20.00 (Budget:Expenses:Food) $200.00 Assets:Cash $-20.00
Keep in mind that if you are using --strict or --pedantic you will have to explicitly define an account ‘$account’ to avoid errors.
account $account
Next: Applying metadata to the generated posting, Previous: Referring to the matching posting's account, Up: Automated Transactions [Contents][Index]
If the automated transaction has a transaction note, that note is copied (along with any metadata) to every posting that matches the predicate:
= food ; Foo: Bar (Budget:$account) 10 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash
Becomes:
2012-03-10 KFC Expenses:Food $20.00 ; Foo: Bar (Budget:Expenses:Food) $200.00 Assets:Cash $-20.00
Next: State flags, Previous: Applying metadata to every matched posting, Up: Automated Transactions [Contents][Index]
If the automated transaction’s posting has a note, that note is carried to the generated posting within the matched transaction:
= food (Budget:$account) 10 ; Foo: Bar 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash
Becomes:
2012-03-10 KFC Expenses:Food $20.00 (Budget:Expenses:Food) $200.00 ; Foo: Bar Assets:Cash $-20.00
This is slightly different from the rules for regular transaction notes, in that an automated transaction’s note does not apply to every posting within the automated transaction itself, but rather to every posting it matches.
Next: Effective Dates, Previous: Applying metadata to the generated posting, Up: Automated Transactions [Contents][Index]
Although you cannot mark an automated transaction as a whole as cleared or pending, you can mark its postings with a ‘*’ or ‘!’ before the account name, and that state flag gets carried to the generated posting.
Next: Periodic Transactions, Previous: State flags, Up: Automated Transactions [Contents][Index]
In the real world, transactions do not take place instantaneously. Purchases can take several days to post to a bank account. And you may pay ahead for something for which you want to distribute costs. With Ledger you can control every aspect of the timing of a transaction.
Say you’re in business. If you bill a customer, you can enter something like
2008/01/01=2008/01/14 Client invoice ; estimated date you'll be paid Assets:Accounts Receivable $100.00 Income: Client name
Then, when you receive the payment, you change it to
2008/01/01=2008/01/15 Client invoice ; actual date money received Assets:Accounts Receivable $100.00 Income: Client name
and add something like
2008/01/15 Client payment Assets:Checking $100.00 Assets:Accounts Receivable
Now
$ ledger --begin 2008/01/01 --end 2008/01/14 bal Income
gives you your accrued income in the first two weeks of the year, and
$ ledger --effective --begin 2008/01/01 --end 2008/01/14 bal Income
gives you your cash basis income in the same two weeks.
Another use is distributing costs out in time. As an example, suppose you just prepaid into a local vegetable co-op that sustains you through the winter. It costs $225 to join the program, so you write a check. You don’t want your October grocery budget to be blown because you bought food ahead, however. What you really want is for the money to be evenly distributed over the next six months so that your monthly budgets gradually take a hit for the vegetables you’ll pick up from the co-op, even though you’ve already paid for them.
2008/10/16 * (2090) Bountiful Blessings Farm Expenses:Food:Groceries $ 37.50 ; [=2008/10/01] Expenses:Food:Groceries $ 37.50 ; [=2008/11/01] Expenses:Food:Groceries $ 37.50 ; [=2008/12/01] Expenses:Food:Groceries $ 37.50 ; [=2009/01/01] Expenses:Food:Groceries $ 37.50 ; [=2009/02/01] Expenses:Food:Groceries $ 37.50 ; [=2009/03/01] Assets:Checking
This entry accomplishes this. Every month you’ll see an automatic $37.50 deficit like you should, while your checking account really knows that it debited $225 this month.
And using the --effective option, the initial date will be overridden by the effective dates.
$ ledger --effective register Groceries
08-Oct-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 37.50 08-Nov-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 75.00 08-Dec-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 112.50 09-Jan-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 150.00 09-Feb-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 187.50 09-Mar-01 Bountiful Blessings.. Expense:Food:Groceries $ 37.50 $ 225.00
Next: Concrete Example of Automated Transactions, Previous: Effective Dates, Up: Automated Transactions [Contents][Index]
A periodic transaction starts with a tilde ‘~’ followed by a period expression (see Period Expressions). Periodic transactions are used for budgeting and forecasting only, they have no effect without the --budget option specified. For examples and details, see Budgeting and Forecasting.
Previous: Periodic Transactions, Up: Automated Transactions [Contents][Index]
As a Bahá’í, I need to compute Huqúqu’lláh whenever I acquire assets. It is similar to tithing for Jews and Christians, or to Zakát for Muslims. The exact details of computing Huqúqu’lláh are somewhat complex, but if you have further interest, please consult the Web.
Ledger makes this otherwise difficult law very easy. Just set up an automated posting at the top of your ledger file:
; This automated transaction will compute Huqúqu'lláh based on this ; journal's postings. Any accounts that match will affect the ; Liabilities:Huququ'llah account by 19% of the value of that posting. = /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/ (Liabilities:Huququ'llah) 0.19
This automated posting works by looking at each posting in the ledger file. If any match the given value expression, 19% of the posting’s value is applied to the ‘Liabilities:Huququ'llah’ account. So, if $1000 is earned from ‘Income:Salary’, $190 is added to ‘Liabilities:Huqúqu'lláh’; if $1000 is spent on Rent, $190 is subtracted.
2003/01/01 (99) Salary Income:Salary -$1000 Assets:Checking 2003/01/01 (100) Rent Expenses:Rent $500 Assets:Checking
The ultimate balance of Huqúqu’lláh reflects how much is owed in order to fulfill one’s obligation to Huqúqu’lláh. When ready to pay, just write a check to cover the amount shown in ‘Liabilities:Huququ'llah’. That transaction would look like:
2003/01/01 (101) Baha'i Huqúqu'lláh Trust Liabilities:Huququ'llah $1,000.00 Assets:Checking
That’s it. To see how much Huqúq is currently owed based on your ledger transactions, use:
$ ledger balance Liabilities:Huquq
$-95 Liabilities:Huququ'llah
This works fine, but omits one aspect of the law: that Huqúq is only due once the liability exceeds the value of 19 mithqáls of gold (which is roughly 2.22 ounces). So what we want is for the liability to appear in the balance report only when it exceeds the present day value of 2.22 ounces of gold. This can be accomplished using the command:
$ ledger -Q -t "/Liab.*Huquq/?(a/P{2.22 AU}<={-1.0}&a):a" bal liab
With this command, the current price for gold is downloaded, and the Huqúqu’lláh is reported only if its value exceeds that of 2.22 ounces of gold. If you wish the liability to be reflected in the parent subtotal either way, use this instead:
$ ledger -Q -T "/Liab.*Huquq/?(O/P{2.22 AU}<={-1.0}&O):O" bal liab
In some cases, you may wish to refer to the account of whichever posting matched your automated transaction’s value expression. To do this, use the special account name ‘$account’:
= /^Some:Long:Account:Name/ [$account] -0.10 [Savings] 0.10
This example causes 10% of the matching account’s total to be deferred to the ‘Savings’ account—as a balanced virtual posting, which may be excluded from reports by using --real.
Next: Reporting Commands, Previous: Transactions, Up: Top [Contents][Index]
| • Introduction: | ||
| • Balance Reports: | ||
| • Typical queries: | ||
| • Advanced Reports: |
Next: Balance Reports, Previous: Building Reports, Up: Building Reports [Contents][Index]
The power of Ledger comes from the incredible flexibility in its reporting commands, combined with formatting commands. Some options control what is included in the calculations, and formatting controls how it is displayed. The combinations are infinite. This chapter will show you the basics of combining various options and commands. In the next chapters you will find details about the specific commands and options.
Next: Typical queries, Previous: Introduction, Up: Building Reports [Contents][Index]
| • Controlling the Accounts and Payees: | ||
| • Controlling Formatting: |
Next: Controlling Formatting, Previous: Balance Reports, Up: Balance Reports [Contents][Index]
The balance report is the most commonly used report. The simplest invocation is:
$ ledger balance -f drewr3.dat
which will print the balances of every account in your journal.
$ -3,804.00 Assets $ 1,396.00 Checking $ 30.00 Business $ -5,200.00 Savings $ -1,000.00 Equity:Opening Balances $ 6,654.00 Expenses $ 5,500.00 Auto $ 20.00 Books $ 300.00 Escrow $ 334.00 Food:Groceries $ 500.00 Interest:Mortgage $ -2,030.00 Income $ -2,000.00 Salary $ -30.00 Sales $ -63.60 Liabilities $ -20.00 MasterCard $ 200.00 Mortgage:Principal $ -243.60 Tithe -------------------- $ -243.60
Most times, this is more than you want. Limiting the results to specific accounts is as easy as entering the names of the accounts after the command:
$ ledger balance -f drewr3.dat Auto MasterCard
$ 5,500.00 Expenses:Auto $ -20.00 Liabilities:MasterCard -------------------- $ 5,480.00
Note the implicit logical or between ‘Auto’ and ‘Mastercard’.
If you want the entire contents of a branch of your account tree, use the highest common name in the branch:
$ ledger balance -f drewr3.dat Income
$ -2,030.00 Income $ -2,000.00 Salary $ -30.00 Sales -------------------- $ -2,030.00
You can use general regular expressions in nearly any place Ledger needs a string:
$ ledger balance -f drewr3.dat ^Bo
This first example looks for any account starting with ‘Bo’, of which there are none.
$ ledger balance -f drewr3.dat Bo
$ 20.00 Expenses:Books
This second example looks for any account containing ‘Bo’, which is ‘Expenses:Books’.
If you want to know exactly how much you have spent in a particular account on a particular payee, the following are equivalent:
$ ledger balance Auto:Fuel and Chevron
$ ledger balance --limit 'account=~/Fuel/' and 'payee=~/Chev/'
will show you the amount expended on gasoline at Chevron. The second example is the first example of the very powerful expression language available to shape reports. The first example may be easier to remember, but learning to use the second will open up far more possibilities.
If you want to exclude specific accounts from the report, you can exclude multiple accounts with parentheses:
$ ledger bal Expenses and not (Expenses:Drinks or Expenses:Candy or Expenses:Gifts)
Previous: Controlling the Accounts and Payees, Up: Balance Reports [Contents][Index]
These examples all use the default formatting for the balance report. Customizing the formatting allows you to see only what you want, or interface Ledger with other programs. For examples and details, see Format Strings and Asset Allocation.
Next: Advanced Reports, Previous: Balance Reports, Up: Building Reports [Contents][Index]
A query such as the following shows all expenses since last October, sorted by total:
$ ledger -b "last oct" -S T bal ^expenses
From left to right the options mean: Show transactions since last October; sort by the absolute value of the total; and report the balance for all accounts that begin with ‘expenses’.
| • Reporting monthly expenses: |
Previous: Typical queries, Up: Typical queries [Contents][Index]
The following query makes it easy to see monthly expenses, with each month’s expenses sorted by the amount:
$ ledger -M --period-sort "(amount)" reg ^expenses
Now, you might wonder where the money came from to pay for these things. To see that report, add --related (-r), which shows the “related account” postings:
$ ledger -M --period-sort "(amount)" -r reg ^expenses
But maybe this prints too much information. You might just want to see how much you’re spending with your MasterCard. That kind of query requires the use of a display predicate, since the postings calculated must match ‘^expenses’, while the postings displayed must match ‘mastercard’. The command would be:
$ ledger -M -r --display 'account=~/mastercard/' reg ^expenses
This query says: Report monthly subtotals; report the “related account” postings; display only related postings whose account matches ‘mastercard’, and base the calculation on postings matching ‘^expenses’.
This works just as well for reporting the overall total, too:
$ ledger -s -r --display "account=~/mastercard/" reg ^expenses
The --subtotal (-s) option subtotals all postings, just as --monthly (-M) subtotaled by the month. The running total in both cases is off, however, since a display expression is being used.
Previous: Typical queries, Up: Building Reports [Contents][Index]
| • Asset Allocation: | ||
| • Visualizing with Gnuplot: |
Next: Visualizing with Gnuplot, Previous: Advanced Reports, Up: Advanced Reports [Contents][Index]
A very popular method of managing portfolios is to control the percent allocation of assets by certain categories. The mix of categories and the weights applied to them vary by investing philosophy, but most follow a similar pattern. Tracking asset allocation in ledger is not difficult but does require some additional effort to describe how the various assets you own contribute to the asset classes you want to track.
In our simple example we assume you want to apportion your assets into the general categories of domestic and international equities (stocks) and a combined category of bonds and cash. For illustrative purposes, we will use several publicly available mutual funds from Vanguard. The three funds we will track are the Vanguard 500 IDX FD Signal (VIFSX), the Vanguard Target Retirement 2030 (VTHRX), and the Vanguard Short Term Federal Fund (VSGBX). Each of these funds allocates assets to different categories of the investment universe and in different proportions. When you buy a share of VTHRX, that share is partially invested in equities, and partially invested in bonds and cash. Below is the asset allocation for each of the instruments listed above:
| Domestic | Global | ||
| Symbol | Equity | Equity | bonds/cash |
| VIFSX | 100% | ||
| VTHRX | 24.0% | 56.3% | 19.7% |
| VSGBX | 100% |
These numbers are available from the prospectus of any publicly available mutual fund. Of course a single stock issue is 100% equity and a single bond issue is 100% bonds.
We track purchases of specific investments using the symbol of that investment as its commodity. How do we tell Ledger that a share of VTHRX is 24% Domestic equity? Enter automatic transactions and virtual accounts.
At the top of our ledger we enter automatic transactions that describe these proportions to Ledger. In the same entries we set up virtual accounts that let us separate these abstract calculations from our actual balances.
For the three instruments listed above, those automatic transactions would look like:
= expr ( commodity == 'VIFSX' ) (Allocation:Equities:Domestic) 1.000 = expr ( commodity == 'VTHRX' ) (Allocation:Equities:Global) 0.240 (Allocation:Equities:Domestic) 0.563 (Allocation:Bonds/Cash) 0.197 = expr ( commodity == 'VBMFX') (Allocation:Bonds/Cash) 1.000 2015-01-01 Buy VIFSX Assets:Broker 100 VIFSX Assets:Cash $-10000 2015-01-01 Buy VTHRX Assets:Broker 10 VTHRX Assets:Cash $-10000 2015-01-01 Buy VBMFX Assets:Broker 1 VBMFX Assets:Cash $-10000
How do these work? First the ‘=’ sign at the beginning of the line tells ledger this is an automatic transaction to be applied when the condition following the ‘=’ is true. After the ‘=’ sign is a value expression (see Value Expressions) that returns true any time a posting contains the commodity of interest.
The following line gives the proportions (not percentages) of each unit of commodity that belongs to each asset class. Whenever Ledger sees a buy or sell of a particular commodity it will credit or debit these virtual accounts with that proportion of the number of shares moved.
Now that Ledger understands how to distribute the commodities amongst the various asset classes how do we get a report that tells us our current allocation? Using the balance command and some tricky formatting!
ledger bal Allocation --current --format "\ %-17((depth_spacer)+(partial_account))\ %10(percent(market(display_total), market(parent.total)))\ %16(market(display_total))\n%/"
Which yields:
Allocation 100.00% $30000 Bonds/Cash 39.90% $11970 Equities 60.10% $18030 Domestic 86.69% $15630 Global 13.31% $2400
Let’s look at the Ledger invocation a bit closer. The command above is split into lines for clarity. The first line is very vanilla Ledger asking for the current balances of the account in the “Allocation” tree, using a special formatter.
The magic is in the formatter. The second line simply tells Ledger to
print the partial account name indented by its depth in the tree. The
third line is where we calculate and display the percentages. The
display_total
command gives the values of the total calculated
for the account in this line. The parent.total
command gives
the total for the next level up in the tree. percent
formats
their ratio as a percentage. The fourth line tells ledger to display
the current market value of the line. The last two characters
‘%/’ tell Ledger what to do for the last line, in this case,
nothing.
Previous: Asset Allocation, Up: Advanced Reports [Contents][Index]
If you have the “Gnuplot” program installed, you can graph any of the
above register reports. The script to do this is included in the ledger
distribution, and is named contrib/report. Install report
anywhere along your PATH
, and then use report instead of
ledger when doing a register report. The only thing to keep in
mind is that you must specify --amount-data (-j) or
--total-data (-J) to indicate whether “Gnuplot” should plot
the amount, or the running total. For example, this command plots total
monthly expenses made on your MasterCard.
$ report -j -M -r --display "account =~ /mastercard/" reg ^expenses
The report script is a very simple Bourne shell script, that passes a set of scripted commands to “Gnuplot”. Feel free to modify the script to your liking, since you may prefer histograms to line plots, for example.
Here are some useful plots:
report -j -M reg ^expenses # monthly expenses report -J reg checking # checking account balance report -J reg ^income ^expenses # cash flow report # net worth report, ignoring non-$ postings report -J -l "Ua>={\$0.01}" reg ^assets ^liab # net worth report starting last February. the use of a display # predicate (-d) is needed, otherwise the balance will start at # zero, and thus the y-axis will not reflect the true balance report -J -l "Ua>={\$0.01}" -d "d>=[last feb]" reg ^assets ^liab
The last report uses both a calculation predicate --limit EXPR (-l) and a display predicate --display EXPR (-d). The calculation predicate limits the report to postings whose amount is greater than or equal to $1 (which can only happen if the posting amount is in dollars). The display predicate limits the transactions displayed to just those since last February, even though those transactions from before will be computed as part of the balance.
Next: Command-Line Syntax, Previous: Building Reports, Up: Top [Contents][Index]
| • Primary Financial Reports: | Reports in other formats:: Reports about | |
| • Reports in other Formats: | ||
| • Reports about your Journals: |
Next: Reports in other Formats, Previous: Reporting Commands, Up: Reporting Commands [Contents][Index]
• The balance command: | ||
• The equity command: | ||
• The register command: | ||
• The print command: |
Next: The equity
command, Previous: Primary Financial Reports, Up: Primary Financial Reports [Contents][Index]
balance
commandThe balance
command reports the current balance of all
accounts. It accepts a list of optional regexes, which confine the
balance report to the matching accounts. If an account contains
multiple types of commodities, each commodity’s total is reported
separately.
Next: The register
command, Previous: The balance
command, Up: Primary Financial Reports [Contents][Index]
equity
commandThe equity
command prints out account balances as if they
were transactions. This makes it easy to establish the starting
balances for an account, such as when Archiving Previous Years.
Next: The print
command, Previous: The equity
command, Up: Primary Financial Reports [Contents][Index]
register
commandThe register
command displays all the postings occurring in
a single account, line by line. The account regex must be specified as
the only argument to this command. If any regexes occur after the
required account name, the register will contain only those postings
that match, which makes it very useful for hunting down a particular
posting.
The output from register
is very close to what a typical
checkbook, or single-account ledger, would look like. It also shows a
running balance. The final running balance of any register should
always be the same as the current balance of that account.
If you have “Gnuplot” installed, you may plot the amount or running
total of any register by using the script report, which is
included in the Ledger distribution. The only requirement is that you
add either --amount-data (-j) or --total-data (-J) to
your register
command, in order to plot either the amount or
total column, respectively.
Previous: The register
command, Up: Primary Financial Reports [Contents][Index]
print
commandThe print
command prints out ledger transactions in a textual
format that can be parsed by Ledger. They will be properly formatted,
and output in the most economic form possible. The print
command also takes a list of optional regexes, which will cause only
those postings which match in some way to be printed.
The print
command can be a handy way to clean up a ledger
file whose formatting has gotten out of hand.
Next: Reports about your Journals, Previous: Primary Financial Reports, Up: Reporting Commands [Contents][Index]
| • Comma Separated Values files: | ||
• The lisp command: | ||
• Emacs org Mode: | ||
| • Org mode with Babel: | ||
• The pricemap command: | ||
• The xml command: | ||
• prices and pricedb commands: |
Next: The lisp
command, Previous: Reports in other Formats, Up: Reports in other Formats [Contents][Index]
• The csv command: | ||
• The convert command: |
Next: The convert
command, Previous: Comma Separated Values files, Up: Comma Separated Values files [Contents][Index]
csv
commandThe csv
command prints the desired ledger
transactions in a csv format suitable for importing into other programs.
You can specify the transactions to print using all the normal
limiting and searching functions.
Previous: The csv
command, Up: Comma Separated Values files [Contents][Index]
convert
commandThe convert
command parses a comma separated value (csv) file
and prints Ledger transactions. Many banks offer csv file downloads.
Unfortunately, the file formats, aside from the commas, are all
different. The ledger convert
command tries to help as much
as it can.
Your bank’s csv files will have fields in different orders from other banks, so there must be a way to tell Ledger what to expect. Insert a line at the beginning of the csv file that describes the fields to Ledger.
For example, this is a portion of a csv file downloaded from a credit union in the United States:
Account Name: VALUFIRST CHECKING Account Number: 71 Date Range: 11/13/2011 - 12/13/2011 Transaction Number,Date,Description,Memo,Amount Debit,Amount Credit,Balance,Check Number,Fees 767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,, 767406,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-1.03,,00001648.84,, 683342,12/13/2011,"Visa Checking","NetFlix Date 12/12/11<PHONE_NUMBER>96 5968",-21.85,,00001649.87,, 639668,12/13/2011,"Withdrawal","ID:<PHONE_NUMBER> CO: XXAA.COM PAYMNT",-236.65,,00001671.72,, 1113648,12/12/2011,"Withdrawal","Tuscan IT #00037657",-29.73,,00001908.37,,
Unfortunately, as it stands Ledger cannot read it, but you can. Ledger
expects the first line to contain a description of the fields on each
line of the file. The fields ledger can recognize contain these
case-insensitive strings date
, posted
, code
,
payee
or desc
or description
, amount
,
cost
, total
, and note
.
Delete the account description lines at the top, and replace the first line in the data above with:
,date,payee,note,amount,,,code,
Then execute ledger like this:
$ ledger convert download.csv --input-date-format "%m/%d/%Y"
Where the --input-date-format DATE_FORMAT option tells ledger how to interpret the dates.
Importing csv files is a lot of work, but is very amenable to scripting.
If there are columns in the bank data you would like to keep in your ledger data, besides the primary fields described above, you can name them in the field descriptor list and Ledger will include them in the transaction as meta data if it doesn’t recognize the field name. For example, if you want to capture the bank transaction number and it occurs in the first column of the data use:
transid,date,payee,note,amount,,,code,
Ledger will include ‘; transid: 767718’ in the first transaction from the file above.
The convert
command accepts four options. They are
--invert which inverts the amount field, --auto-match
which automatically matches an account from the Ledger journal for every
CSV line, --account STR which you can use to specify the
account to balance against, and --rich-data which stores
additional tag/value pairs.
Using the two first lines of the above csv file,
,date,payee,note,amount,,,code, 767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,, 767406,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-1.03,,00001648.84,,
and launching the below command,
$ ledger convert download.csv --input-date-format "%m/%d/%Y" \ --invert --account Assets:MyBank --rich-data \ --file sample.dat --now=2012/01/13
you will get the result:
2011/12/13 * Withdrawal ;ACE HARDWARE 16335 S HOUGHTON RD ; CSV: 767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,, ; Imported: 2012/01/13 ; UUID: dfdc3c3d5c54c6967dd39d5b4e4fd1ea76e87233 Expenses:Unknown 8.8 Assets:MyBank 2011/12/13 * Withdrawal ;ACE HARDWARE 16335 S HOUGHTON RD ; CSV: 767406,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-1.03,,00001648.84,, ; Imported: 2012/01/13 ; UUID: 63086448b1f29f7fd6efb11ea40660185a213f9d Expenses:Unknown 1.03 Assets:MyBank
The three added metadata are: ‘CSV’ as the original line from csv file, ‘Imported’ as the date when the csv file was imported into Ledger, and ‘UUID’ as a checksum of original csv line.
If an entry with the same ‘UUID’ tag is already included in the
normal ledger file (specified via --file FILE (-f) or via
the environment variable LEDGER_FILE
) this entry will not be
printed again.
In the output above, the account is ‘Expenses:Unknown’ for CSV lines. You can use the --auto-match option to automatically match an account from your Ledger journal.
You can also use convert
with payee
and account
directives. First, you can use the payee
and alias
directive to rewrite the payee
field based on some rules. Then
you can use the account and its payee
directive to specify the
account. I use it like this, for example:
payee Aldi alias ^ALDI SUED SAGT DANKE account Aufwand:Einkauf:Lebensmittel payee ^(Aldi|Alnatura|Kaufland|REWE)$
Note that it may be necessary for the output of ‘ledger convert’
to be passed through ledger print
a second time if you want to
match on the new payee field. During the ledger convert
run,
only the original payee name as specified in the csv data seems to be
used.
Next: Emacs org
Mode, Previous: Comma Separated Values files, Up: Reports in other Formats [Contents][Index]
lisp
commandThe lisp
command prints results in a form that can be read
directly by Emacs Lisp. The format of the sexp
is:
((BEG-POS CLEARED DATE CODE PAYEE (ACCOUNT AMOUNT)...) ; list of postings ...) ; list of transactions
emacs
can also be used as a synonym for lisp
.
Next: Org mode with Babel, Previous: The lisp
command, Up: Reports in other Formats [Contents][Index]
org
ModeOrg mode has a sub-system known as Babel which allows for literate programming. This allows you to mix text and code within the same document and automatically execute code which may generate results which will then appear in the text.