slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: update/style tutorial

Browse Source
This commit is contained in:
Simon Michael 2015-05-25 17:43:50 -07:00
parent 7a8f813d2f
commit 5e7fd191f2
2 changed files with 153 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/site/css/style.css
View File

@ -48,7 +48,12 @@ pre {
.shell::first-line { .shell::first-line {
font-weight:bold; font-weight:bold;
} }
.nobold::first-line { .shell.continued {
background-color:white;
border-top:none;
border-top-left-radius:0;
}
.shell.continued::first-line, .nobold::first-line {
font-weight:normal; font-weight:normal;
} }
.bold { .bold {

273
doc/site/step-by-step.md
View File

@ -15,7 +15,7 @@ You'll need:
1. A basic understanding of the command line, text file editing, and regular expressions. Or, the ability to ask for help on the IRC channel. 1. A basic understanding of the command line, text file editing, and regular expressions. Or, the ability to ask for help on the IRC channel.
2. hledger (see [Download](download.html)). These exercises were last tested with: hledger 0.23dev-20140212. 2. hledger (see [Download](download.html)). These exercises were last tested with: hledger 0.25.1.
@ -25,7 +25,7 @@ You'll need:
Get a command prompt, and run hledger to check the version. It should be reasonably [up to date](release-notes.html): Get a command prompt, and run hledger to check the version. It should be reasonably [up to date](release-notes.html):
``` ```shell
$ hledger --version $ hledger --version
hledger 0.23 hledger 0.23
``` ```
@ -37,7 +37,7 @@ hledger 0.23
hledger reads financial transactions from a "journal file" (so named because it represents a [General Journal](http://en.wikipedia.org/wiki/General_Journal)). hledger reads financial transactions from a "journal file" (so named because it represents a [General Journal](http://en.wikipedia.org/wiki/General_Journal)).
The default journal file is in your home directory; check its path using the [stats](manual.html#stats) command. The default journal file is in your home directory; check its path using the [stats](manual.html#stats) command.
You should see something like: You should see something like:
``` ```shell
$ hledger stats $ hledger stats
The hledger journal file "/home/YOU/.hledger.journal" was not found. The hledger journal file "/home/YOU/.hledger.journal" was not found.
Please create it first, eg with "hledger add" or a text editor. Please create it first, eg with "hledger add" or a text editor.
@ -54,34 +54,33 @@ Follow the help and use the [add](manual.html#add) command to record your first
an imaginary purchase at the supermarket. an imaginary purchase at the supermarket.
We'll go through this in detail. Later you'll learn other ways to enter data. We'll go through this in detail. Later you'll learn other ways to enter data.
``` ```shell
$ hledger add $ hledger add
Creating hledger journal file "/home/YOU/.hledger.journal".
Adding transactions to journal file /home/YOU/.hledger.journal Adding transactions to journal file /home/YOU/.hledger.journal
Provide field values at the prompts, or press enter to accept defaults. Any command line arguments will be used as defaults.
Use readline keys to edit, use tab key to complete account names. Use tab key to complete, readline keys to edit, enter to accept defaults.
A code (in parentheses) may be entered following transaction dates. An optional (CODE) may follow transaction dates.
A comment may be entered following descriptions or amounts. An optional ; COMMENT may follow descriptions or amounts.
If you make a mistake, enter < at any prompt to restart the transaction. If you make a mistake, enter < at any prompt to restart the transaction.
To complete a transaction, enter . when prompted. To end a transaction, enter . when prompted.
To quit, press control-d or control-c. To quit, enter . at a date prompt or press control-d or control-c.
Date [2015/05/25]:
Starting a new transaction.
date ? [2014/02/12]:
``` ```
`add` prompts for each transaction field. The first is the date. `add` prompts for each transaction field. The first is the date.
The value in square brackets is the suggested default (today's date). Press enter to accept it. The value in square brackets is the suggested default (today's date). Press enter to accept it.
``` ```{.shell .continued}
description ? : trip to the supermarket Description: trip to the supermarket
``` ```
Transactions have an optional description (a single line of text) to help you understand them. Transactions have an optional description (a single line of text) to help you understand them.
You can describe the transaction here, or put a payee name, or leave it blank. You can describe the transaction here, or put a payee name, or leave it blank.
Type `trip to the supermarket` and press enter. Type `trip to the supermarket` and press enter.
``` ```{.shell .continued}
account 1 ? : expenses Account 1: expenses
``` ```
Transactions have two or more accounts. Keep it simple; just enter `expenses` for the first one. Transactions have two or more accounts. Keep it simple; just enter `expenses` for the first one.
@ -91,20 +90,20 @@ A purchase is a transfer of money from an asset account to an expense account.
An asset is something you own, like some money in a bank account or in your pocket. An asset is something you own, like some money in a bank account or in your pocket.
Once the money has been "moved" to an expense, you no longer own it, but the increasing balance in the expense account reminds you where it went. Once the money has been "moved" to an expense, you no longer own it, but the increasing balance in the expense account reminds you where it went.
``` ```{.shell .continued}
amount 1 ? : $10 Amount 1: $10
``` ```
The amount being "moved" to `expenses`. In this case 10 US dollars. The amount being "moved" to `expenses`. In this case 10 US dollars.
``` ```{.shell .continued}
account 2 ? : assets Account 2: assets
``` ```
Next, specify which account the money comes from. Just say `assets`. Next, specify which account the money comes from. Just say `assets`.
``` ```{.shell .continued}
amount 2 ? [$-10.0]: Amount 2 ? [$-10.0]:
``` ```
Now you're asked for the amount to "move" to or from the `assets` account. Now you're asked for the amount to "move" to or from the `assets` account.
@ -115,19 +114,18 @@ In a balanced transaction, the sum of posted amounts is zero, in other words no
hledger does not allow unbalanced transactions. hledger does not allow unbalanced transactions.
Press enter to accept the default. It has an extra decimal place, but never mind. Press enter to accept the default. It has an extra decimal place, but never mind.
``` ```{.shell .continued}
account 3 (or . to complete this transaction) ? : . Account 3 (or . to finish this transaction): .
``` ```
Type `.` (period) and press enter. Type `.` (period) and press enter.
``` ```{.shell .continued}
Transaction entered: 2015/05/25 trip to the supermarket
2014/02/12 trip to the supermarket
expenses $10 expenses $10
assets $-10.0 assets $-10.0
Accept this transaction ? [y]: Save this transaction to the journal ? [y]:
``` ```
You are given a chance to review the transaction just entered. You are given a chance to review the transaction just entered.
@ -138,12 +136,10 @@ two or more spaces, and an amount.
(Account names can contain spaces, so at least two spaces are needed to separate them from the amount.) (Account names can contain spaces, so at least two spaces are needed to separate them from the amount.)
Press enter. Press enter.
``` ```{.shell .continued}
Added to the journal. Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Starting a new transaction. Date [2015/05/25]: <CTRL-D>
date ? [2014/02/12]: <CTRL-D>
$
``` ```
hledger has saved it to the journal file and is ready for the next hledger has saved it to the journal file and is ready for the next
@ -151,12 +147,12 @@ entry. Press control-d (on Windows, control-c) once to exit.
`stats` should now report that your journal exists and contains one transaction: `stats` should now report that your journal exists and contains one transaction:
``` ```shell
$ hledger stats $ hledger stats
Main journal file : /home/YOU/.hledger.journal Main journal file : /home/YOU/.hledger.journal
Included journal files : Included journal files :
Transactions span : 2014-02-12 to 2014-02-13 (1 days) Transactions span : 2015-05-25 to 2015-05-26 (1 days)
Last transaction : 2014-02-12 (0 days ago) Last transaction : 2015-05-25 (0 days ago)
Transactions : 1 (1.0 per day) Transactions : 1 (1.0 per day)
Transactions last 30 days: 1 (0.0 per day) Transactions last 30 days: 1 (0.0 per day)
Transactions last 7 days : 1 (0.1 per day) Transactions last 7 days : 1 (0.1 per day)
@ -170,23 +166,25 @@ Commodities : 1 ($)
The [print](manual.html#print) command shows a tidied-up view of the transaction entries in your journal. The [print](manual.html#print) command shows a tidied-up view of the transaction entries in your journal.
Since there's just one so far, you should see: Since there's just one so far, you should see:
``` ```shell
$ hledger print $ hledger print
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses $10 expenses $10
assets $-10 assets $-10
``` ```
### Examine your journal file ### Examine your journal file
List and print the journal file (on Windows, use `dir` and `type` and the file path from `hledger stats`): List and print the journal file (on Windows, use `dir` and `type` and the file path from `hledger stats`):
``` ```shell
$ ls -l ~/.hledger.journal $ ls -l ~/.hledger.journal
-rw-rw-r-- 1 YOU YOU 74 Feb 12 08:10 /home/YOU/.hledger.journal -rw-r--r-- 1 YOU YOU 114 May 25 16:55 /home/YOU/.hledger.journal
$ cat ~/.hledger.journal $ cat ~/.hledger.journal
; journal created 2015-05-25 by hledger
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses $10 expenses $10
assets assets
``` ```
@ -205,13 +203,13 @@ Only one missing amount is allowed in each transaction.
Since the journal file is plain text, you can edit it directly with any text editor. Since the journal file is plain text, you can edit it directly with any text editor.
Edit the file and change it to test whether two missing amounts is reported as an error. Eg: Edit the file and change it to test whether two missing amounts is reported as an error. Eg:
``` ```shell
$ emacs ~/.hledger.journal $ emacs ~/.hledger.journal
``` ```
Remove the expenses amount and save the file. It now looks like this: Remove the expenses amount and save the file. It now looks like this:
``` ```journal
2014/02/12 trip to the supermarket 2014/02/12 trip to the supermarket
expenses expenses
assets assets
@ -219,13 +217,13 @@ Remove the expenses amount and save the file. It now looks like this:
Running `print` again, you should see: Running `print` again, you should see:
``` ```shell
$ hledger print
hledger: could not balance this transaction (can't have more than one missing amount; remember to put 2 or more spaces before amounts) hledger: could not balance this transaction (can't have more than one missing amount; remember to put 2 or more spaces before amounts)
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses expenses
assets assets
``` ```
All hledger commands expect the journal to be well-formed, and will report an error and exit otherwise. All hledger commands expect the journal to be well-formed, and will report an error and exit otherwise.
@ -236,9 +234,9 @@ Notice the last part of that error message: "`... remember to put 2 or more spac
Another cause of this error is forgetting to put two spaces before the Another cause of this error is forgetting to put two spaces before the
amount, like this: amount, like this:
``` ```journal
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses $10 ; <- only one space between expenses and $10 - need at least two expenses $10 ; <- problem: only one space between expenses and $10
assets assets
``` ```
@ -250,27 +248,36 @@ amount. So remember: two or more spaces.
Edit the file to look like this: Edit the file to look like this:
``` ```journal
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses $10 expenses $10
assets $10 assets $10 ; <- deliberate problem: both amounts are positive
``` ```
Here, we wrote both posting amounts but got the sign wrong on one of them, so they don't add up to zero. Here, we wrote both posting amounts but got the sign wrong on one of them, so they don't add up to zero.
hledger should detect this mistake. Verify it by running some command, eg `print`. You should see: hledger should detect this mistake. Verify it by running some command, eg `print`. You should see:
``` ```shell
$ hledger print $ hledger print
hledger: could not balance this transaction (real postings are off by $20) hledger: could not balance this transaction (real postings are off by $20)
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses $10 expenses $10
assets $10 assets $10
``` ```
That makes sense. (It calls them "real" postings because there are some other kinds of posting you haven't learned about yet; they aren't important.) That makes sense. (It calls them "real" postings because there are some other kinds of posting you haven't learned about yet; they aren't important.)
Correct the mistake by adding the minus sign, or just removing the assets amount entirely, and verify Correct the mistake by adding the minus sign, or just removing the assets amount entirely, and verify
that `print` works again. that `print` works again:
```shell
$ hledger print
2015/05/25 trip to the supermarket
expenses $10
assets $-10
```
### Record a transaction by editing ### Record a transaction by editing
@ -278,26 +285,26 @@ Edit the file again and manually add a second purchase transaction.
It's often quickest to copy & paste a similar entry, then change it. It's often quickest to copy & paste a similar entry, then change it.
Make the file look like this: Make the file look like this:
``` ```journal
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses $10 expenses $10
assets assets $-10
2014/02/13 forgot the bread 2015/05/26 forgot the bread
expenses $5 expenses $5
assets assets
``` ```
The blank line between transactions is customary, though not required. The blank line between transactions is customary, though not required.
Test your work with `print`. You should see: Test your work with `print`. You should see:
``` ```shell
$ hledger print $ hledger print
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses $10 expenses $10
assets $-10 assets $-10
2014/02/13 forgot the bread 2015/05/26 forgot the bread
expenses $5 expenses $5
assets $-5 assets $-5
@ -309,12 +316,12 @@ The [register](manual.html#register) command shows transactions in a different f
Remember, a posting is an increase or decrease of some account by some amount, and a transaction contains two or more of them. Remember, a posting is an increase or decrease of some account by some amount, and a transaction contains two or more of them.
Run `register` and compare with the output of `print` above. You should see: Run `register` and compare with the output of `print` above. You should see:
``` ```shell
$ hledger register $ hledger register
2014/02/12 trip to the super.. expenses $10 $10 2015/05/25 trip to the supermarket expenses $10 $10
assets $-10 0 assets $-10 0
2014/02/13 forgot the bread expenses $5 $5 2015/05/26 forgot the bread expenses $5 $5
assets $-5 0 assets $-5 0
``` ```
Postings are displayed one per line. Postings are displayed one per line.
@ -330,22 +337,24 @@ The register report is more useful when we restrict it to a subset of postings -
say, only the postings within a single account. say, only the postings within a single account.
You can do this by specifying the account name as a command line argument. You can do this by specifying the account name as a command line argument.
Run a register report for the `expenses` account. You should see: Run a register report for the `expenses` account. You should see something like the below.
(On POSIX platforms, this command uses the terminal width so the output may look slightly different.
You can force it to look like the below by running `export COLUMNS=80` first:
``` ```shell
$ hledger register expenses $ hledger register expenses
2014/02/12 trip to the super.. expenses $10 $10 2015/05/25 trip to the super.. expenses $10 $10
2014/02/13 forgot the bread expenses $5 $15 2015/05/26 forgot the bread expenses $5 $15
``` ```
Now it's clear that your `expenses` balance - ie, the total amount spent - has increased to $15. Now it's clear that your `expenses` balance - ie, the total amount spent - has increased to $15.
Your `assets` balance should have dropped accordingly. Check it: Your `assets` balance should have dropped accordingly. Check it:
``` ```shell
$ hledger register assets $ hledger register assets
2014/02/12 trip to the super.. assets $-10 $-10 2015/05/25 trip to the super.. assets $-10 $-10
2014/02/13 forgot the bread assets $-5 $-15 2015/05/26 forgot the bread assets $-5 $-15
``` ```
### Query expressions ### Query expressions
@ -359,31 +368,31 @@ So "`e`" would match both `expenses` and `assets`.
And if you had an account named `other assets`, "`assets`" would also match that, so to match only the `assets` And if you had an account named `other assets`, "`assets`" would also match that, so to match only the `assets`
account you'd need a more precise pattern like "`^assets$`". account you'd need a more precise pattern like "`^assets$`".
If this doesn't make sense, read a little about regular expressions. (In a regular expression `^` means "match at the beginning" and `$` means "match at the end".)
In a regular expression `^` means "match at the beginning" and `$` means "match at the end". If this doesn't make sense, read a little about [regular expressions](manual.html#regular-expressions).
Multiple query arguments are ANDed and ORed together in a fixed way - follow the link for details. Multiple query arguments are ANDed and ORed together in a fixed way - follow the link for details.
Basically queries on the same field are ORed, and queries on different fields are ANDed. Basically queries on the same field are ORed, and queries on different fields are ANDed.
Run the following examples and make sure they make sense, consulting the manual as needed. Run the following examples and make sure they make sense, consulting the manual as needed.
Show only transactions whose description contains the regular expression "`bread`": Show only transactions whose description ends with "bread":
```shell
``` $ hledger print desc:bread$
$ hledger print desc:bread 2015/05/26 forgot the bread
2014/02/13 forgot the bread
expenses $5 expenses $5
assets $-5 assets $-5
``` ```
Show only postings on or after a certain date to an account whose name ends with "es": <!-- Note how the account-matching pattern `es$` needs to be quoted here, -->
``` <!-- because it contains the regular expression metacharacter `$` which would otherwise be interpreted by the unix shell. -->
$ hledger register date:2014/2/13- 'es$'
2014/02/13 forgot the bread expenses $5 $5
```
Note how the account-matching pattern `es$` needs to be quoted here, Show only postings on or after a certain date to an account whose name contains "exp":
because it contains the regular expression metacharacter `$` which would otherwise be interpreted by the unix shell. ```shell
$ hledger register date:2015/5/26- exp
2015/05/26 forgot the bread expenses $5 $5
```
### Show accounts and their balances with "hledger balance" ### Show accounts and their balances with "hledger balance"
@ -391,7 +400,8 @@ The third of hledger's three core reporting commands is [balance](manual.html#ba
Use it to list all the accounts posted to, and their ending balance. Use it to list all the accounts posted to, and their ending balance.
You should see account balances agreeing with the final running total in the register reports above: You should see account balances agreeing with the final running total in the register reports above:
``` ```{.shell .nobold}
$ hledger balance
$-15 assets $-15 assets
$15 expenses $15 expenses
-------------------- --------------------
@ -401,7 +411,7 @@ You should see account balances agreeing with the final running total in the reg
The overall total of these balances is also shown. As with other reports, you can use a query expression to select a subset of the data to report on. The overall total of these balances is also shown. As with other reports, you can use a query expression to select a subset of the data to report on.
Eg: Eg:
``` ```shell
$ hledger balance assets $ hledger balance assets
$-15 assets $-15 assets
-------------------- --------------------
@ -411,8 +421,8 @@ $ hledger balance assets
### balance shows the sum of matched posting amounts ### balance shows the sum of matched posting amounts
Here's a balance report based only on the postings dated 2013/2/13: Here's a balance report based only on the postings dated 2013/2/13:
``` ```shell
$ hledger balance date:2014/2/13 $ hledger balance date:2015/5/26
$-5 assets $-5 assets
$5 expenses $5 expenses
-------------------- --------------------
@ -424,9 +434,9 @@ real-world account balance, rather it shows the sum of the postings
you have selected. you have selected.
If you're not sure what those are, run a `register` report with the same arguments to see them: If you're not sure what those are, run a `register` report with the same arguments to see them:
``` ```shell
$ hledger register date:2014/2/13 $ hledger register date:2015/5/26
2014/02/13 forgot the bread expenses $5 $5 2015/05/26 forgot the bread expenses $5 $5
assets $-5 0 assets $-5 0
``` ```
@ -520,9 +530,9 @@ Five numbers does not give a lot of detail. If you want to know what
portion of expenses went to buy food, you could add up just the portion of expenses went to buy food, you could add up just the
transactions with (say) "supermarket" in their description. You know how to do this with hledger: transactions with (say) "supermarket" in their description. You know how to do this with hledger:
``` ```shell
$ hledger register desc:supermarket expenses $ hledger register desc:supermarket expenses
2014/02/12 trip to the super.. expenses $10 $10 2015/05/25 trip to the super.. expenses $10 $10
``` ```
But descriptions are irregular, and as you can see we missed the $5 purchase on the following day. But descriptions are irregular, and as you can see we missed the $5 purchase on the following day.
@ -586,21 +596,40 @@ In others, the tree structure is encoded as decimal account numbers, something l
With hledger, tree structure is implied by writing account names like `ACCOUNT:SUBACCOUNT`. With hledger, tree structure is implied by writing account names like `ACCOUNT:SUBACCOUNT`.
Try it: edit your journal file and change the account names like so: Try it: edit your journal file and change the account names like so:
``` ```shell
$ cat ~/.hledger.journal $ cat ~/.hledger.journal
2014/02/12 trip to the supermarket 2015/05/25 trip to the supermarket
expenses:supplies $10 expenses:supplies $10
assets:checking assets:checking $-10
2014/02/13 forgot the bread 2015/05/26 forgot the bread
expenses:food $5 expenses:food $5
assets:cash assets:cash
``` ```
hledger will infer the chart of accounts from these names, and `balance` will indent subaccounts to show the tree structure: hledger will infer the chart of accounts from these names.
The `accounts` command will list all accounts posted to:
```shell
$ hledger accounts
assets:cash
assets:checking
expenses:food
expenses:supplies
``` ```
and `accounts --tree` will show the tree structure, indenting subaccounts below their parents (and eliding the common part of their names):
```shell
assets
cash
checking
expenses
food
supplies
```
Conversely, the `balance` command shows the tree structure by default:
```shell
$ hledger balance $ hledger balance
$-15 assets $-15 assets
$-5 cash $-5 cash
@ -612,35 +641,27 @@ $ hledger balance
0 0
``` ```
For clarity, the common part of the subaccount names is not displayed. As you can see, the balance reported for parent accounts includes the
You can see the full account names used internally like this: balances of any subaccounts (it would also include any postings to the
parent account itself.)
``` To see full account names in a flat list, use `--flat`:
$ hledger balance --flat --empty
$-15 assets ```shell
$ hledger balance --flat
$-5 assets:cash $-5 assets:cash
$-10 assets:checking $-10 assets:checking
$15 expenses
$5 expenses:food $5 expenses:food
$10 expenses:supplies $10 expenses:supplies
-------------------- --------------------
0 0
``` ```
With `--flat`, the balance command shows full account names without indentation.
The `--empty` flag here requests that the accounts with no direct postings of their own be displayed.
Normally the balance report omits or elides such "uninteresting" accounts when they don't add much information.
(In the default indented view, they are included to clarify the structure.)
As you can see, the balance reported for parent accounts includes the
balances of any subaccounts (it would also include any postings to the
parent account itself.)
hledger accepts whatever account names you choose, so you can use as much or as little account hierarchy as you need. hledger accepts whatever account names you choose, so you can use as much or as little account hierarchy as you need.
Most users have at least two levels of accounts. Most users have at least two levels of accounts.
You can always limit the amount of detail in a balance report with `--depth`: You can limit the amount of detail in a balance report by hiding accounts below a certain depth:
``` ```shell
$ hledger balance --depth 1 $ hledger balance --depth 1
$-15 assets $-15 assets
$15 expenses $15 expenses