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

docs: move convert docs into general file reading

Browse Source
This commit is contained in:
Simon Michael 2012-03-24 19:20:59 +00:00
parent 09d39ed622
commit cca3434ea3
1 changed files with 95 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

194
MANUAL.md
View File

@ -113,8 +113,14 @@ enter some transactions. Or, save this
## The journal file ## The journal file
hledger reads data from a plain text file, called a *journal* because it hledger normally reads data from a plain text file in hledger journal
represents a standard accounting format. hledger can read some [other file formats](#other-file-formats)
as well, but first we'll discuss hledger's journal format. Note this is
compatible subset of
[c++ ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format),
so hledger can work with many c++ ledger journal files as well.
The journal file is so called because it represents a standard accounting
[general journal](http://en.wikipedia.org/wiki/General_journal). It [general journal](http://en.wikipedia.org/wiki/General_journal). It
contains a number of transaction entries, each describing a transfer of contains a number of transaction entries, each describing a transfer of
money (or any commodity) between two or more named accounts, in a simple money (or any commodity) between two or more named accounts, in a simple
@ -126,6 +132,8 @@ journal file directly with a text editor, perhaps assisted by the helper
modes for emacs or vi. Note the file uses unix line endings on all modes for emacs or vi. Note the file uses unix line endings on all
platforms. platforms.
hledger's file format aims to be [compatible](#file-format-compatibility) hledger's file format aims to be [compatible](#file-format-compatibility)
with c++ ledger, so you can use both tools on your journal. with c++ ledger, so you can use both tools on your journal.
@ -438,111 +446,57 @@ Command-line alias options are applied after any alias directives in the
journal. At most one alias directive and one alias option will be applied journal. At most one alias directive and one alias option will be applied
to each account name. to each account name.
## Commands ## Other file formats
hledger provides a number of subcommands, in the style of git or darcs. In addition to the usual [journal files](#the-journal-file), hledger can
Run `hledger` with no arguments to see a list. Most are built in to the read [timelog files](#timelog-reporting). hledger 0.18 can also read
core hledger package, while [add-on commands](#add-on-commands) will [CSV](http://en.wikipedia.org/wiki/Comma-separated_values) files natively
appear if you install additional hledger-* packages. You can also install (the old `convert` command is no longer needed.)
your own subcommands by putting programs or scripts named `hledger-NAME`
in your PATH.
### Misc commands An arbitrary CSV file does not provide enough information to be parsed as
a journal. So when reading CSV, hledger first reads an additional file
called the [rules file](#the-rules-file), which identifies the CSV fields
and assigns accounts. For reading `FILE.csv`, hledger uses a rules file in
the same directory called `FILE.rules`, auto-creating it if needed. You
should configure the rules to best match your CSV file. You can specify a
different rules file with `--rules-file` (useful when reading from
standard input).
Here are some miscellaneous commands you might use to get started: An example - sample.csv:
#### add sample.csv:
"2012/3/22","TRANSFER TO SAVINGS","-10.00"
"2012/3/23","SOMETHING ELSE","5.50"
The add command prompts interactively for new transactions, and appends sample.rules:
them to the journal file. Each transaction is appended when you complete
it by entering `.` (period) at the account prompt. Enter control-D or
control-C when you are done.
The add command tries to be helpful, providing:
- Sensible defaults
- History awareness: if there are existing transactions approximately
matching the description you enter, they will be displayed and the best
match will provide defaults for the other fields. If you specify
[filter pattern(s)](#filter-patterns) on the command line, only matching
transactions will be considered as history.
- Readline-style input: during data entry, the usual editing keys should
work.
- Auto-completion for account names: while entering account names, the tab
key will auto-complete as far as possible, or list the available
options.
- Default commodity awareness: if the journal has a
[default commodity directive](#default-commodity), that will be applied
to any bare numbers entered.
Examples:
$ hledger add
$ hledger -f home.journal add equity:bob
#### convert
The convert command reads a
[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) file - perhaps
downloaded from your bank - and prints out the transactions in date-sorted
hledger journal format. You can copy these into your journal (taking care
to ignore old transactions that you added previously, if any). A temporary
file may be helpful if the output is large. Eg:
$ hledger convert FILE.csv [>temp.journal]
hledger convert looks for conversion hints in a rules file, named
`FILE.rules` by default (or specify it with `--rules-file`). This file
will be auto-created if it does not exist. An empty rules file is valid,
but you'll probably need to add at least a few
[directives](#rules-file-directives) for a useful conversion.
You can also convert standard input by specifying no CSV file, or `-`, in
which case `--rules-file` is required.
An example: here's a trimmed `wf.csv` file, downloaded from a Wells Fargo
checking account:
"07/11/2011","-0.99","*","","CHECK CRD PURCHASE 07/09 APL*ITUNES"
Here's a `wf.rules` file which identifes some fields by their zero-based
position, sets a default account and currency symbol, and declares a
couple of account-assigning rules:
date-field 0 date-field 0
amount-field 1 description-field 1
description-field 4 amount-field 2
currency $
base-account assets:bank:checking base-account assets:bank:checking
base-currency $
; the rest of the file is account-assigning rules SAVINGS
; if description contains ITUNES, use transfer account expenses:entertainment
ITUNES
expenses:entertainment
; if description contains TO SAVINGS or FROM SAVINGS, use transfer account assets:bank:savings
(TO|FROM) SAVINGS
assets:bank:savings assets:bank:savings
And here's the result: the resulting journal:
$ hledger convert wf.csv $ hledger -f sample.csv print
using conversion rules file wf.rules using conversion rules file sample.rules
2011/07/11 CHECK CRD PURCHASE 07/09 APL*ITUNES 2012/03/22 TRANSFER TO SAVINGS
expenses:entertainment $0.99 assets:bank:savings $10.00
assets:bank:checking $-0.99 assets:bank:checking $-10.00
2012/03/23 SOMETHING ELSE
income:unknown $-5.50
assets:bank:checking $5.50
##### rules file directives ### The rules file
Directives should appear at the beginning of the rules file, before any A rules file consists of the following optional directives, followed by
account-assigning rules. (Note directive parse errors may not be reported account-assigning rules. (Tip: rules file parse errors are not the
clearly, so check them for typos if you're getting unexpected results.) greatest, so check your rules file format if you're getting unexpected
results.)
`account-field` `account-field`
@ -626,11 +580,9 @@ clearly, so check them for typos if you're getting unexpected results.)
> Which field contains the transaction cleared status (`*`). > Which field contains the transaction cleared status (`*`).
##### account-assigning rules Account-assigning rules select an account to transfer to based on the
description field (unless `account2-field` is used.) Each
The rest of the file is account-assigning rules, which select a transfer account-assigning rule is a paragraph consisting of one or more
account based on the transaction's description (unless `account2-field` is
used.) Each of these is a paragraph consisting of one or more
case-insensitive regular expressions), one per line, followed by the case-insensitive regular expressions), one per line, followed by the
account name to use when the transaction's description matches any of account name to use when the transaction's description matches any of
these patterns. Eg: these patterns. Eg:
@ -647,12 +599,56 @@ groups in the usual way with `\0` etc. Eg:
BLKBSTR=BLOCKBUSTER BLKBSTR=BLOCKBUSTER
expenses:entertainment expenses:entertainment
##### comment lines
Lines beginning with `;` or `#` are ignored - just don't use them in the Lines beginning with `;` or `#` are ignored - just don't use them in the
middle of an account-assigning rule. middle of an account-assigning rule.
## Commands
hledger provides a number of subcommands, in the style of git or darcs.
Run `hledger` with no arguments to see a list. Most are built in to the
core hledger package, while [add-on commands](#add-on-commands) will
appear if you install additional hledger-* packages. You can also install
your own subcommands by putting programs or scripts named `hledger-NAME`
in your PATH.
### Misc commands
Here are some miscellaneous commands you might use to get started:
#### add
The add command prompts interactively for new transactions, and appends
them to the journal file. Each transaction is appended when you complete
it by entering `.` (period) at the account prompt. Enter control-D or
control-C when you are done.
The add command tries to be helpful, providing:
- Sensible defaults
- History awareness: if there are existing transactions approximately
matching the description you enter, they will be displayed and the best
match will provide defaults for the other fields. If you specify
[filter pattern(s)](#filter-patterns) on the command line, only matching
transactions will be considered as history.
- Readline-style input: during data entry, the usual editing keys should
work.
- Auto-completion for account names: while entering account names, the tab
key will auto-complete as far as possible, or list the available
options.
- Default commodity awareness: if the journal has a
[default commodity directive](#default-commodity), that will be applied
to any bare numbers entered.
Examples:
$ hledger add
$ hledger -f home.journal add equity:bob
#### test #### test
This command runs hledger's internal self-tests and displays a quick This command runs hledger's internal self-tests and displays a quick