simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-10-06 10:57:30 +03:00
Code Issues Projects Releases Wiki Activity

doc: manual: rewrites & cleanups

Browse Source
This commit is contained in:
Simon Michael 2015-05-21 15:37:17 -07:00
parent 1499e0b001
commit 669f3d498d
1 changed files with 92 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
doc/manual.md
View File

@ -103,28 +103,18 @@ in a certain account.
To create an initial journal, run `hledger add` and follow the prompts to
enter some transactions. Or, save this
[sample file](https://raw.github.com/simonmichael/hledger/master/data/sample.journal) as
`.hledger.journal` in your home directory. Now try commands like these:
`.hledger.journal` in your home directory. Now try some commands, eg like these:
$ hledger
# show available commands
$ hledger add
# add more transactions to the journal file
$ hledger balance
# all accounts with aggregated balances
$ hledger balance --help
# show help for balance command
$ hledger balance --depth 1
# only top-level accounts
$ hledger register
# show account postings, with running total
$ hledger reg income
# show postings to/from income accounts
$ hledger reg 'assets:some bank:checking'
# show postings to/from this checking account
$ hledger print desc:shop
# show transactions with shop in the description
$ hledger activity -W
# show transaction counts per week as a bar chart
$ hledger # show available commands
$ hledger add # add more transactions to the journal file
$ hledger balance # all accounts with aggregated balances
$ hledger balance --help # show help for balance command
$ hledger balance --depth 1 # only top-level accounts
$ hledger register # show account postings, with running total
$ hledger reg income # show postings to/from income accounts
$ hledger reg 'assets:some bank:checking' # show postings to/from this checking account
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
## Data formats
@ -193,23 +183,12 @@ The posting amounts within a transaction must always balance, ie add up to
##### Simple dates
Within a journal file, transaction dates always follow a year/month/day
format, although several different separator characters are accepted. Some
examples: `2010/01/31`, `2010/1/31`, `2010-1-31`, `2010.1.31`.
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
format. Eg: `2010/01/31`, `2010/1/31`, `2010-1-31`, `2010.1.31`.
Writing the year is optional if you set a default year with a Y directive.
This is a line containing `Y` and the year; it affects subsequent
transactions, like so:
Y2009
12/15 ; equivalent to 2009/12/15
...
Y2010
1/31 ; equivalent to 2010/1/31
...
Writing the year is optional. If missing, it is assumed to be the
current year, or (better) the year you have set with a
[default year directive](#default-year).
##### Secondary dates
@ -442,18 +421,19 @@ P 2010/1/1 € $1.40
#### Comments
- A semicolon (`;`) or hash (`#`) or asterisk (`*`) in column 0 starts
a journal comment line, which hledger will ignore. (Asterisk allows you
to embed emacs org/outline-mode nodes and treat your journal like an outline.)
Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or
asterisk (`*`) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.)
- A semicolon after a transaction's description and/or indented on the following lines
starts a transaction comment.
Also, anything between
[`comment` and `end comment` directives](#multi-line-comments) is a
(multi-line) comment.
- A semicolon after a posting's amount and/or indented on the following lines starts a posting comment.
- With the `comment` and `end comment` keywords it is possible to have multiline comments.
Transaction and posting comments are displayed by [print](#print), can contain [tags](#tags) and can be [queried](#queries).
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual
posting by writing them after the amount and/or indented on the
following lines.
Some examples:
@ -479,32 +459,31 @@ Some examples:
#### Tags
You can include *tags* (labels), optionally with values,
in transaction and posting comments, and then [query by tag](manual#queries).
This is like Ledger's [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
feature, except hledger's tag values are simple strings.
A *tag* is a word followed by a full colon inside a transaction or
posting [comment](#comments). You can write multiple tags, comma
separated. Eg: `; a comment containing sometag:, anothertag:`. You can search for tags
with the [`tag:` query](manual#queries).
A tag is any unspaced word immediately followed by a full colon, eg: `sometag:` .
A tag's *value* is the characters following the colon, if any, until the next comma or newline,
with any leading and trailing whitespace removed.
Comma may be used to write multiple tags on one line.
A tag can also have a value, which is any text between the colon and
the next comma or newline, excluding leading/trailing whitespace.
(So hledger tag values can not contain commas or newlines).
For example, here is a transaction with three tags, the posting has
one, and all tags have values except TAG1:
Tags in a transaction comment affect the transaction and all of its postings,
while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third-tag)
and the posting has four (A, TAG2, third-tag, posting-tag):
1/1 a transaction ; TAG1:, TAG2: tag2's value
; TAG3: a third transaction tag
a $1 ; TAG4: a posting tag
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, this time with a value
(a) $1 ; posting-tag:
**Things to note:**
Tags are like Ledger's
[metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
feature, except hledger's tag values are always simple strings.
In the journal file, a hledger tag value can contain: text, internal whitespace, or punctuation, but not: commas, newlines, or leading/trailing whitespace (putting quotes around it doesn't work, but probably should).
The position of the comment containing the tag determines what is
tagged - the whole transaction and all of its postings, or just a
single posting (cf [transaction comment or posting comment](manual#comments)).
In [tag queries](manual#queries), remember the tag name must match exactly, while the value part is the usual case-insensitive infix regular expression match.
Note: when searching with a `tag:` query, currently tag names must
match exactly (and case sensitively!). (Tag values are matched in the more
usual way, as case-insensitive infix [regular expressions](#regular-expressions)).
#### Directives
@ -559,6 +538,23 @@ Account aliases changed significantly in hledger 0.24 and are
currently somewhat incompatible with Ledger's aliases, which do not
use regular expressions. They can also hurt performance.
##### Multi-line comments
A line containing just `comment` starts a multi-line [comment](#comments),
and a line containing just `end comment` ends it. Eg:
1/1
a 1
comment
this is ignored
and so is this
end comment
1/2
a 1
##### Default commodity
You can set a default commodity, to be used for amounts without one.
@ -604,7 +600,7 @@ within a section of the journal. Use the `account` directive like so:
end
If `!end` is omitted, the effect lasts to the end of the file.
If `end` is omitted, the effect lasts to the end of the file.
The above is equivalent to:
2010/01/01
@ -620,12 +616,37 @@ Included files are also affected, eg:
include personal.journal
end
##### Default year
You can set a default year to be used for subsequent dates which do
not specify a year. The directive is an old-fashioned kind: a line
containing `Y` and the year. Eg:
Y2009 ; set default year to 2009
12/15 ; equivalent to 2009/12/15
expenses 1
assets
Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected
expenses 1
assets
1/31 ; equivalent to 2010/1/31
expenses 1
assets
##### Including other files
You can pull in the content of additional journal files, by writing lines like this:
You can pull in the content of additional journal files by writing an
include directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current file.
The `include` directive may only be used in journal files, and currently
it may only include other journal files (eg, not CSV or timelog files.)
@ -970,7 +991,7 @@ A query term can be any of the following:
- `desc:REGEX` - match transaction descriptions
- `date:PERIODEXPR` - match dates within the specified [period](#period-expressions). *Actually, full period syntax is [not yet supported](https://github.com/simonmichael/hledger/issues/141).*
- `date2:PERIODEXPR` - as above, but match secondary dates
- `tag:NAME[=REGEX]` - match by (exact, case sensitive) [tag](#tags) name, and optionally match the tag value by regular expression. Note `tag:` will match a transaction if it or any its postings have the tag, and will match posting if it or its parent transaction has the tag.
- `tag:NAME[=REGEX]` - match by (exact, case sensitive) [tag](#tags) name, and optionally match the tag value by regular expression. Note `tag:` will match a transaction if it or any its postings have the tag, and will match a posting if it or its parent transaction has the tag.
- `depth:N` - match (or display, depending on command) accounts at or above this [depth](#depth-limiting)
- `status:1` or `status:0` - match pending/cleared or uncleared transactions respectively
- `real:1` or `real:0` - match real/virtual-ness