mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-20 02:37:12 +03:00
doc: remove wrong "(dev)" suffix in 1.9 html manuals
This commit is contained in:
parent
7f1b34ea1d
commit
1e27675c7d
@ -1,6 +1,6 @@
|
|||||||
# csv format
|
# csv format
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
# hledger-api
|
# hledger-api
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
# hledger-ui
|
# hledger-ui
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
# hledger-web
|
# hledger-web
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
# hledger
|
# hledger
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
@ -705,7 +705,7 @@ in a number of places:
|
|||||||
- [query terms](#queries), on the command line and in the hledger-web
|
- [query terms](#queries), on the command line and in the hledger-web
|
||||||
search form: `REGEX`, `desc:REGEX`, `cur:REGEX`, `tag:...=REGEX`
|
search form: `REGEX`, `desc:REGEX`, `cur:REGEX`, `tag:...=REGEX`
|
||||||
- [CSV rules](#csv-rules) conditional blocks: `if REGEX ...`
|
- [CSV rules](#csv-rules) conditional blocks: `if REGEX ...`
|
||||||
- [account alias](#account-aliases) directives and options:
|
- [account alias](#rewriting-accounts) directives and options:
|
||||||
`alias /REGEX/ = REPLACEMENT`, `--alias /REGEX/=REPLACEMENT`
|
`alias /REGEX/ = REPLACEMENT`, `--alias /REGEX/=REPLACEMENT`
|
||||||
|
|
||||||
hledger's regular expressions come from the
|
hledger's regular expressions come from the
|
||||||
@ -770,11 +770,9 @@ which:
|
|||||||
The following kinds of search terms can be used. Remember these can also
|
The following kinds of search terms can be used. Remember these can also
|
||||||
be prefixed with **`not:`**, eg to exclude a particular subaccount.
|
be prefixed with **`not:`**, eg to exclude a particular subaccount.
|
||||||
|
|
||||||
**`REGEX`**
|
**`REGEX`, `acct:REGEX`**
|
||||||
: match account names by this regular expression. (No prefix is
|
: match account names by this regular expression. (With no prefix,
|
||||||
equivalent to `acct:`).
|
`acct:` is assumed.)
|
||||||
|
|
||||||
**`acct:REGEX`**
|
|
||||||
: same as above
|
: same as above
|
||||||
|
|
||||||
**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**
|
**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**
|
||||||
@ -1117,8 +1115,33 @@ Show accounts and their balances. Aliases: b, bal.
|
|||||||
`--show-unbudgeted`
|
`--show-unbudgeted`
|
||||||
: with --budget, show unbudgeted accounts also
|
: with --budget, show unbudgeted accounts also
|
||||||
|
|
||||||
The balance command displays accounts and balances. It is hledger's most
|
The balance command is hledger's most versatile command. Note, despite
|
||||||
featureful and versatile command.
|
the name, it is not always used for showing real-world account balances;
|
||||||
|
the more accounting-aware [balancesheet](#balancesheet) and
|
||||||
|
[incomestatement](#incomestatement) may be more convenient for that.
|
||||||
|
|
||||||
|
By default, it displays all accounts, and each account's change in
|
||||||
|
balance during the entire period of the journal. Balance changes are
|
||||||
|
calculated by adding up the postings in each account. You can limit the
|
||||||
|
postings matched, by a [query](#queries), to see fewer accounts, changes
|
||||||
|
over a different time period, changes from only cleared transactions,
|
||||||
|
etc.
|
||||||
|
|
||||||
|
If you include an account's complete history of postings in the report,
|
||||||
|
the balance change is equivalent to the account's current ending
|
||||||
|
balance. For a real-world account, typically you won't have all
|
||||||
|
transactions in the journal; instead you'll have all transactions after
|
||||||
|
a certain date, and an "opening balances" transaction setting the
|
||||||
|
correct starting balance on that date. Then the balance command will
|
||||||
|
show real-world account balances. In some cases the -H/--historical flag
|
||||||
|
is used to ensure this (more below).
|
||||||
|
|
||||||
|
The balance command can produce several styles of report:
|
||||||
|
|
||||||
|
#### Classic balance report
|
||||||
|
|
||||||
|
This is the original balance report, as found in Ledger. It usually
|
||||||
|
looks like this:
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance
|
$ hledger balance
|
||||||
@ -1136,19 +1159,14 @@ $ hledger balance
|
|||||||
0
|
0
|
||||||
```
|
```
|
||||||
|
|
||||||
More precisely, the balance command shows the *change* to each account's
|
|
||||||
balance caused by all (matched) postings. In the common case where you
|
|
||||||
do not filter by date and your journal sets the correct opening
|
|
||||||
balances, this is the same as the account's ending balance.
|
|
||||||
|
|
||||||
By default, accounts are displayed hierarchically, with subaccounts
|
By default, accounts are displayed hierarchically, with subaccounts
|
||||||
indented below their parent. At each level of the tree, accounts are
|
indented below their parent. At each level of the tree, accounts are
|
||||||
sorted by [account code](/manual.html#account-directive) if any, then by
|
sorted by [account code](/manual.html#declaring-accounts) if any, then
|
||||||
account name. Or with `-S/--sort-amount`, by their balance amount.
|
by account name. Or with `-S/--sort-amount`, by their balance amount.
|
||||||
|
|
||||||
"Boring" accounts, which contain a single interesting subaccount and no
|
"Boring" accounts, which contain a single interesting subaccount and no
|
||||||
balance of their own, are elided into the following line for more
|
balance of their own, are elided into the following line for more
|
||||||
compact output. (Not yet supported in tabular reports.) Use `--no-elide`
|
compact output. (Eg above, the "liabilities" account.) Use `--no-elide`
|
||||||
to prevent this.
|
to prevent this.
|
||||||
|
|
||||||
Account balances are "inclusive" - they include the balances of any
|
Account balances are "inclusive" - they include the balances of any
|
||||||
@ -1158,7 +1176,7 @@ Accounts which have zero balance (and no non-zero subaccounts) are
|
|||||||
omitted. Use `-E/--empty` to show them.
|
omitted. Use `-E/--empty` to show them.
|
||||||
|
|
||||||
A final total is displayed by default; use `-N/--no-total` to suppress
|
A final total is displayed by default; use `-N/--no-total` to suppress
|
||||||
it:
|
it, eg:
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance -p 2008/6 expenses --no-total
|
$ hledger balance -p 2008/6 expenses --no-total
|
||||||
@ -1167,13 +1185,80 @@ $ hledger balance -p 2008/6 expenses --no-total
|
|||||||
$1 supplies
|
$1 supplies
|
||||||
```
|
```
|
||||||
|
|
||||||
|
#### Customising the classic balance report
|
||||||
|
|
||||||
|
You can customise the layout of classic balance reports with
|
||||||
|
`--format FMT`:
|
||||||
|
|
||||||
|
``` {.shell}
|
||||||
|
$ hledger balance --format "%20(account) %12(total)"
|
||||||
|
assets $-1
|
||||||
|
bank:saving $1
|
||||||
|
cash $-2
|
||||||
|
expenses $2
|
||||||
|
food $1
|
||||||
|
supplies $1
|
||||||
|
income $-2
|
||||||
|
gifts $-1
|
||||||
|
salary $-1
|
||||||
|
liabilities:debts $1
|
||||||
|
---------------------------------
|
||||||
|
0
|
||||||
|
```
|
||||||
|
|
||||||
|
The FMT format string (plus a newline) specifies the formatting applied
|
||||||
|
to each account/balance pair. It may contain any suitable text, with
|
||||||
|
data fields interpolated like so:
|
||||||
|
|
||||||
|
`%[MIN][.MAX](FIELDNAME)`
|
||||||
|
|
||||||
|
- MIN pads with spaces to at least this width (optional)
|
||||||
|
- MAX truncates at this width (optional)
|
||||||
|
- FIELDNAME must be enclosed in parentheses, and can be one of:
|
||||||
|
|
||||||
|
- `depth_spacer` - a number of spaces equal to the account's
|
||||||
|
depth, or if MIN is specified, MIN \* depth spaces.
|
||||||
|
- `account` - the account's name
|
||||||
|
- `total` - the account's balance/posted total, right justified
|
||||||
|
|
||||||
|
Also, FMT can begin with an optional prefix to control how
|
||||||
|
multi-commodity amounts are rendered:
|
||||||
|
|
||||||
|
- `%_` - render on multiple lines, bottom-aligned (the default)
|
||||||
|
- `%^` - render on multiple lines, top-aligned
|
||||||
|
- `%,` - render on one line, comma-separated
|
||||||
|
|
||||||
|
There are some quirks. Eg in one-line mode, `%(depth_spacer)` has no
|
||||||
|
effect, instead `%(account)` has indentation built in. <!-- XXX retest:
|
||||||
|
Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
|
||||||
|
Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
|
||||||
|
--> Experimentation may be needed to get pleasing results.
|
||||||
|
|
||||||
|
Some example formats:
|
||||||
|
|
||||||
|
- `%(total)` - the account's total
|
||||||
|
- `%-20.20(account)` - the account's name, left justified, padded to
|
||||||
|
20 characters and clipped at 20 characters
|
||||||
|
- `%,%-50(account) %25(total)` - account name padded to 50
|
||||||
|
characters, total padded to 20 characters, with multiple commodities
|
||||||
|
rendered on one line
|
||||||
|
- `%20(total) %2(depth_spacer)%-(account)` - the default format for
|
||||||
|
the single-column balance report
|
||||||
|
|
||||||
|
#### Colour support
|
||||||
|
|
||||||
|
The balance command shows negative amounts in red, if:
|
||||||
|
|
||||||
|
- the `TERM` environment variable is not set to `dumb`
|
||||||
|
- the output is not being redirected or piped anywhere
|
||||||
|
|
||||||
#### Flat mode
|
#### Flat mode
|
||||||
|
|
||||||
To see a flat list of full account names instead of the default
|
To see a flat list instead of the default hierarchical display, use
|
||||||
hierarchical display, use `--flat`. In this mode, accounts (unless
|
`--flat`. In this mode, accounts (unless depth-clipped) show their full
|
||||||
depth-clipped) show their "exclusive" balance, excluding any subaccount
|
names and "exclusive" balance, excluding any subaccount balances. In
|
||||||
balances. In this mode, you can also use `--drop N` to omit the first
|
this mode, you can also use `--drop N` to omit the first few account
|
||||||
few account name components.
|
name components.
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
|
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
|
||||||
@ -1183,30 +1268,37 @@ $ hledger balance -p 2008/6 expenses -N --flat --drop 1
|
|||||||
|
|
||||||
#### Depth limited balance reports
|
#### Depth limited balance reports
|
||||||
|
|
||||||
With `--depth N`, balance shows accounts only to the specified depth.
|
With `--depth N` or `depth:N` or just `-N`, balance reports show
|
||||||
This is very useful to show a complex charts of accounts in less detail.
|
accounts only to the specified numeric depth. This is very useful to
|
||||||
In flat mode, balances from accounts below the depth limit will be shown
|
summarise a complex set of accounts and get an overview.
|
||||||
as part of a parent account at the depth limit.
|
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance -N --depth 1
|
$ hledger balance -N -1
|
||||||
$-1 assets
|
$-1 assets
|
||||||
$2 expenses
|
$2 expenses
|
||||||
$-2 income
|
$-2 income
|
||||||
$1 liabilities
|
$1 liabilities
|
||||||
```
|
```
|
||||||
|
|
||||||
<!-- $ for y in 2006 2007 2008 2009 2010; do echo; echo $y; hledger -f $y.journal balance ^expenses --depth 2; done -->
|
Flat-mode balance reports, which normally show exclusive balances, show
|
||||||
#### Multicolumn balance reports
|
inclusive balances at the depth limit.
|
||||||
|
|
||||||
With a [reporting interval](#reporting-interval), multiple balance
|
<!-- $ for y in 2006 2007 2008 2009 2010; do echo; echo $y; hledger -f $y.journal balance ^expenses --depth 2; done -->
|
||||||
columns will be shown, one for each report period. There are three types
|
#### Multicolumn balance report
|
||||||
of multi-column balance report, showing different information:
|
|
||||||
|
Multicolumn or tabular balance reports are a very useful hledger
|
||||||
|
feature, and usually the preferred style. They share many of the above
|
||||||
|
features, but they show the report as a table, with columns representing
|
||||||
|
time periods. This mode is activated by providing a [reporting
|
||||||
|
interval](#reporting-interval).
|
||||||
|
|
||||||
|
There are three types of multicolumn balance report, showing different
|
||||||
|
information:
|
||||||
|
|
||||||
1. By default: each column shows the sum of postings in that period, ie
|
1. By default: each column shows the sum of postings in that period, ie
|
||||||
the account's change of balance in that period. This is useful eg
|
the account's change of balance in that period. This is useful eg
|
||||||
for a monthly income statement: <!--
|
for a monthly income statement: <!--
|
||||||
multi-column income statement:
|
multicolumn income statement:
|
||||||
|
|
||||||
$ hledger balance ^income ^expense -p 'monthly this year' --depth 3
|
$ hledger balance ^income ^expense -p 'monthly this year' --depth 3
|
||||||
|
|
||||||
@ -1267,8 +1359,8 @@ of multi-column balance report, showing different information:
|
|||||||
|| 0 0 0
|
|| 0 0 0
|
||||||
```
|
```
|
||||||
|
|
||||||
Multi-column balance reports display accounts in flat mode by default;
|
Multicolumn balance reports display accounts in flat mode by default; to
|
||||||
to see the hierarchy, use `--tree`.
|
see the hierarchy, use `--tree`.
|
||||||
|
|
||||||
With a reporting interval (like `--quarterly` above), the report
|
With a reporting interval (like `--quarterly` above), the report
|
||||||
start/end dates will be adjusted if necessary so that they encompass the
|
start/end dates will be adjusted if necessary so that they encompass the
|
||||||
@ -1309,14 +1401,23 @@ Balance changes in 2008:
|
|||||||
# Average is rounded to the dollar here since all journal amounts are
|
# Average is rounded to the dollar here since all journal amounts are
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Budgets
|
Limitations:
|
||||||
|
|
||||||
With `--budget` and a [report interval](manual.html#report-intervals),
|
In multicolumn reports the [`-V/--value` flag](#market-value) uses the
|
||||||
all [periodic transactions](journal.html#periodic-transactions) in your
|
market price on the report end date, for all columns (not the price on
|
||||||
journal with that interval, active during the requested report period,
|
each column's end date).
|
||||||
are interpreted as recurring budget goals for the specified accounts
|
|
||||||
(and subaccounts), and the report will show the difference between
|
Eliding of boring parent accounts in tree mode, as in the classic
|
||||||
actual and budgeted balances.
|
balance report, is not yet supported in multicolumn reports.
|
||||||
|
|
||||||
|
#### Budget report
|
||||||
|
|
||||||
|
With `--budget`, extra columns are displayed showing budget goals for
|
||||||
|
each account and period, if any. Budget goals are defined by [periodic
|
||||||
|
transactions](journal.html#periodic-transactions). This is very useful
|
||||||
|
for comparing planned and actual income, expenses, time usage, etc.
|
||||||
|
--budget is most often combined with a [report
|
||||||
|
interval](manual.html#report-intervals).
|
||||||
|
|
||||||
For example, you can take average monthly expenses in the common expense
|
For example, you can take average monthly expenses in the common expense
|
||||||
categories to construct a minimal monthly budget:
|
categories to construct a minimal monthly budget:
|
||||||
@ -1347,141 +1448,59 @@ categories to construct a minimal monthly budget:
|
|||||||
assets:bank:checking
|
assets:bank:checking
|
||||||
```
|
```
|
||||||
|
|
||||||
You can now see a monthly budget performance report:
|
You can now see a monthly budget report:
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance -M --budget
|
$ hledger balance -M --budget
|
||||||
Balance changes in 2017/11/01-2017/12/31:
|
Budget performance in 2017/11/01-2017/12/31:
|
||||||
|
|
||||||
|| 2017/11 2017/12
|
|
||||||
=======================++=================================================
|
|
||||||
<unbudgeted>:expenses || $20 $100
|
|
||||||
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
|
|
||||||
expenses:bus || $49 [98% of $50] $53 [106% of $50]
|
|
||||||
expenses:food || $396 [99% of $400] $412 [103% of $400]
|
|
||||||
expenses:movies || $30 [100% of $30] 0 [0% of $30]
|
|
||||||
income || $1950 [98% of $2000] $2100 [105% of $2000]
|
|
||||||
-----------------------++-------------------------------------------------
|
|
||||||
|| 0 0
|
|
||||||
```
|
|
||||||
|
|
||||||
You can roll over unspent budgets to next period with `--cumulative`:
|
|
||||||
|
|
||||||
``` {.shell}
|
|
||||||
$ hledger balance -M --budget --cumulative
|
|
||||||
Ending balances (cumulative) in 2017/11/01-2017/12/31:
|
|
||||||
|
|
||||||
|| 2017/11/30 2017/12/31
|
|
||||||
=======================++=================================================
|
|
||||||
<unbudgeted>:expenses || $20 $120
|
|
||||||
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
|
|
||||||
expenses:bus || $49 [98% of $50] $102 [102% of $100]
|
|
||||||
expenses:food || $396 [99% of $400] $808 [101% of $800]
|
|
||||||
expenses:movies || $30 [100% of $30] $30 [50% of $60]
|
|
||||||
income || $1950 [98% of $2000] $4050 [101% of $4000]
|
|
||||||
-----------------------++-------------------------------------------------
|
|
||||||
|| 0 0
|
|
||||||
```
|
|
||||||
|
|
||||||
Accounts with no budget goals (not mentioned in the periodic
|
|
||||||
transactions) will be aggregated under `<unbudgeted>`, unless you add
|
|
||||||
the `--show-unbudgeted` flag to display them normally:
|
|
||||||
|
|
||||||
``` {.shell}
|
|
||||||
$ hledger balance --budget --show-unbudgeted
|
|
||||||
Balance changes in 2017/11/01-2017/12/31:
|
|
||||||
|
|
||||||
|| 2017/11 2017/12
|
|| 2017/11 2017/12
|
||||||
======================++=================================================
|
======================++=================================================
|
||||||
|
<unbudgeted> || $20 $100
|
||||||
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
|
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
|
||||||
expenses:bus || $49 [98% of $50] $53 [106% of $50]
|
expenses:bus || $49 [98% of $50] $53 [106% of $50]
|
||||||
expenses:food || $396 [99% of $400] $412 [103% of $400]
|
expenses:food || $396 [99% of $400] $412 [103% of $400]
|
||||||
expenses:gifts || 0 $100
|
|
||||||
expenses:movies || $30 [100% of $30] 0 [0% of $30]
|
expenses:movies || $30 [100% of $30] 0 [0% of $30]
|
||||||
expenses:supplies || $20 0
|
|
||||||
income || $1950 [98% of $2000] $2100 [105% of $2000]
|
income || $1950 [98% of $2000] $2100 [105% of $2000]
|
||||||
----------------------++-------------------------------------------------
|
----------------------++-------------------------------------------------
|
||||||
|| 0 0
|
|| 0 0
|
||||||
```
|
```
|
||||||
|
|
||||||
Note --budget first arrived in hledger in 1.5 and is still pretty young;
|
By default, only accounts with budget goals during the report period are
|
||||||
join the discussions on mail list and issue tracker to help us refine
|
shown. `--show-unbudgeted` shows unbudgeted accounts as well. Top-level
|
||||||
it.
|
accounts with no budget goals anywhere below them are grouped under
|
||||||
|
`<unbudgeted>`.
|
||||||
|
|
||||||
|
You can roll over unspent budgets to next period with `--cumulative`:
|
||||||
|
|
||||||
|
``` {.shell}
|
||||||
|
$ hledger balance -M --budget --cumulative
|
||||||
|
Budget performance in 2017/11/01-2017/12/31:
|
||||||
|
|
||||||
|
|| 2017/11/30 2017/12/31
|
||||||
|
======================++=================================================
|
||||||
|
<unbudgeted> || $20 $120
|
||||||
|
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
|
||||||
|
expenses:bus || $49 [98% of $50] $102 [102% of $100]
|
||||||
|
expenses:food || $396 [99% of $400] $808 [101% of $800]
|
||||||
|
expenses:movies || $30 [100% of $30] $30 [50% of $60]
|
||||||
|
income || $1950 [98% of $2000] $4050 [101% of $4000]
|
||||||
|
----------------------++-------------------------------------------------
|
||||||
|
|| 0 0
|
||||||
|
```
|
||||||
|
|
||||||
|
Note, the `-S/--sort-amount` flag is not yet fully supported with
|
||||||
|
`--budget`.
|
||||||
|
|
||||||
For more examples, see [Budgeting and
|
For more examples, see [Budgeting and
|
||||||
Forecasting](https://github.com/simonmichael/hledger/wiki/Budgeting%20and%20forecasting).
|
Forecasting](https://github.com/simonmichael/hledger/wiki/Budgeting%20and%20forecasting).
|
||||||
|
|
||||||
#### Custom balance output
|
#### Output format
|
||||||
|
|
||||||
You can customise the layout of simple (non-tabular) balance reports
|
The balance command supports [output
|
||||||
with `--format FMT`:
|
|
||||||
|
|
||||||
``` {.shell}
|
|
||||||
$ hledger balance --format "%20(account) %12(total)"
|
|
||||||
assets $-1
|
|
||||||
bank:saving $1
|
|
||||||
cash $-2
|
|
||||||
expenses $2
|
|
||||||
food $1
|
|
||||||
supplies $1
|
|
||||||
income $-2
|
|
||||||
gifts $-1
|
|
||||||
salary $-1
|
|
||||||
liabilities:debts $1
|
|
||||||
---------------------------------
|
|
||||||
0
|
|
||||||
```
|
|
||||||
|
|
||||||
The FMT format string (plus a newline) specifies the formatting applied
|
|
||||||
to each account/balance pair. It may contain any suitable text, with
|
|
||||||
data fields interpolated like so:
|
|
||||||
|
|
||||||
`%[MIN][.MAX](FIELDNAME)`
|
|
||||||
|
|
||||||
- MIN pads with spaces to at least this width (optional)
|
|
||||||
- MAX truncates at this width (optional)
|
|
||||||
- FIELDNAME must be enclosed in parentheses, and can be one of:
|
|
||||||
|
|
||||||
- `depth_spacer` - a number of spaces equal to the account's
|
|
||||||
depth, or if MIN is specified, MIN \* depth spaces.
|
|
||||||
- `account` - the account's name
|
|
||||||
- `total` - the account's balance/posted total, right justified
|
|
||||||
|
|
||||||
Also, FMT can begin with an optional prefix to control how
|
|
||||||
multi-commodity amounts are rendered:
|
|
||||||
|
|
||||||
- `%_` - render on multiple lines, bottom-aligned (the default)
|
|
||||||
- `%^` - render on multiple lines, top-aligned
|
|
||||||
- `%,` - render on one line, comma-separated
|
|
||||||
|
|
||||||
There are some quirks. Eg in one-line mode, `%(depth_spacer)` has no
|
|
||||||
effect, instead `%(account)` has indentation built in. <!-- XXX retest:
|
|
||||||
Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
|
|
||||||
Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
|
|
||||||
--> Experimentation may be needed to get pleasing results.
|
|
||||||
|
|
||||||
Some example formats:
|
|
||||||
|
|
||||||
- `%(total)` - the account's total
|
|
||||||
- `%-20.20(account)` - the account's name, left justified, padded to
|
|
||||||
20 characters and clipped at 20 characters
|
|
||||||
- `%,%-50(account) %25(total)` - account name padded to 50
|
|
||||||
characters, total padded to 20 characters, with multiple commodities
|
|
||||||
rendered on one line
|
|
||||||
- `%20(total) %2(depth_spacer)%-(account)` - the default format for
|
|
||||||
the single-column balance report
|
|
||||||
|
|
||||||
This command also supports [output
|
|
||||||
destination](/manual.html#output-destination) and [output
|
destination](/manual.html#output-destination) and [output
|
||||||
format](/manual.html#output-format) selection.
|
format](/manual.html#output-format) selection.
|
||||||
|
|
||||||
#### Colour support
|
|
||||||
|
|
||||||
The balance command shows negative amounts in red, if:
|
|
||||||
|
|
||||||
- the `TERM` environment variable is not set to `dumb`
|
|
||||||
- the output is not being redirected or piped anywhere
|
|
||||||
|
|
||||||
### balancesheet
|
### balancesheet
|
||||||
|
|
||||||
This command displays a simple balance sheet, showing historical ending
|
This command displays a simple balance sheet, showing historical ending
|
||||||
@ -2301,7 +2320,7 @@ In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
|
|||||||
add.
|
add.
|
||||||
|
|
||||||
Not all of Ledger's journal file syntax is supported. See [file format
|
Not all of Ledger's journal file syntax is supported. See [file format
|
||||||
differences](faq#file-format-differences).
|
differences](https://github.com/simonmichael/hledger/wiki/FAQ#file-formats).
|
||||||
|
|
||||||
On large data files, hledger is slower and uses more memory than Ledger.
|
On large data files, hledger is slower and uses more memory than Ledger.
|
||||||
|
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
# journal format
|
# journal format
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
@ -19,10 +19,11 @@ a number of transaction entries, each describing a transfer of money (or
|
|||||||
any commodity) between two or more named accounts, in a simple format
|
any commodity) between two or more named accounts, in a simple format
|
||||||
readable by both hledger and humans.
|
readable by both hledger and humans.
|
||||||
|
|
||||||
hledger's journal format is a compatible subset,
|
hledger's journal format is a compatible subset, mostly, of [ledger's
|
||||||
[mostly](faq.html#file-format-differences), of [ledger's journal
|
journal
|
||||||
format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), so
|
format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), so
|
||||||
hledger can work with [compatible](faq.html#file-format-differences)
|
hledger can work with
|
||||||
|
[compatible](https://github.com/simonmichael/hledger/wiki/FAQ#file-formats)
|
||||||
ledger journal files as well. It's safe, and encouraged, to run both
|
ledger journal files as well. It's safe, and encouraged, to run both
|
||||||
hledger and ledger on the same journal file, eg to validate the results
|
hledger and ledger on the same journal file, eg to validate the results
|
||||||
you're getting.
|
you're getting.
|
||||||
@ -277,7 +278,7 @@ Account names may contain single spaces, eg:
|
|||||||
`assets:accounts receivable`. Because of this, they must always be
|
`assets:accounts receivable`. Because of this, they must always be
|
||||||
followed by **two or more spaces** (or newline).
|
followed by **two or more spaces** (or newline).
|
||||||
|
|
||||||
Account names can be [aliased](#account-aliases).
|
Account names can be [aliased](#rewriting-accounts).
|
||||||
|
|
||||||
### Amounts
|
### Amounts
|
||||||
|
|
||||||
@ -339,8 +340,8 @@ hledger displays amounts, it will choose a consistent format for each
|
|||||||
commodity. (Except for [price amounts](#prices), which are always
|
commodity. (Except for [price amounts](#prices), which are always
|
||||||
formatted as written). The display format is chosen as follows:
|
formatted as written). The display format is chosen as follows:
|
||||||
|
|
||||||
- if there is a [commodity directive](#commodity-directive) specifying
|
- if there is a [commodity directive](#declaring-commodities)
|
||||||
the format, that is used
|
specifying the format, that is used
|
||||||
- otherwise the format is inferred from the first posting amount in
|
- otherwise the format is inferred from the first posting amount in
|
||||||
that commodity in the journal, and the precision (number of decimal
|
that commodity in the journal, and the precision (number of decimal
|
||||||
places) will be the maximum from all posting amounts in that
|
places) will be the maximum from all posting amounts in that
|
||||||
@ -636,10 +637,6 @@ star (`*`) are comments, and will be ignored. (Star comments cause
|
|||||||
org-mode nodes to be ignored, allowing emacs users to fold and navigate
|
org-mode nodes to be ignored, allowing emacs users to fold and navigate
|
||||||
their journals with org-mode or orgstruct-mode.)
|
their journals with org-mode or orgstruct-mode.)
|
||||||
|
|
||||||
Also, anything between [`comment` and `end comment`
|
|
||||||
directives](#multi-line-comments) is a (multi-line) comment. If there is
|
|
||||||
no `end comment`, the comment extends to the end of the file.
|
|
||||||
|
|
||||||
You can attach comments to a transaction by writing them after the
|
You can attach comments to a transaction by writing them after the
|
||||||
description and/or indented on the following lines (before the
|
description and/or indented on the following lines (before the
|
||||||
postings). Similarly, you can attach comments to an individual posting
|
postings). Similarly, you can attach comments to an individual posting
|
||||||
@ -669,6 +666,9 @@ end comment
|
|||||||
; a file comment (because not indented)
|
; a file comment (because not indented)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
You can also comment larger regions of a file using [`comment` and
|
||||||
|
`end comment` directives](#comment-blocks).
|
||||||
|
|
||||||
### Tags
|
### Tags
|
||||||
|
|
||||||
Tags are a way to add extra labels or labelled data to postings and
|
Tags are a way to add extra labels or labelled data to postings and
|
||||||
@ -721,7 +721,156 @@ except hledger's tag values are simple strings.
|
|||||||
|
|
||||||
### Directives
|
### Directives
|
||||||
|
|
||||||
#### Account aliases
|
#### Comment blocks
|
||||||
|
|
||||||
|
A line containing just `comment` starts a commented region of the file,
|
||||||
|
and a line containing just `end comment` (or the end of the current
|
||||||
|
file) ends it. See also [comments](#comments).
|
||||||
|
|
||||||
|
#### Including other files
|
||||||
|
|
||||||
|
You can pull in the content of additional files by writing an include
|
||||||
|
directive, like this:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
include path/to/file.journal
|
||||||
|
```
|
||||||
|
|
||||||
|
If the path does not begin with a slash, it is relative to the current
|
||||||
|
file. Glob patterns (`*`) are not currently supported.
|
||||||
|
|
||||||
|
The `include` directive can only be used in journal files. It can
|
||||||
|
include journal, timeclock or timedot files, but not CSV files.
|
||||||
|
|
||||||
|
#### Default year
|
||||||
|
|
||||||
|
You can set a default year to be used for subsequent dates which don't
|
||||||
|
specify a year. This is a line beginning with `Y` followed by the year.
|
||||||
|
Eg:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Declaring commodities
|
||||||
|
|
||||||
|
The `commodity` directive declares commodities which may be used in the
|
||||||
|
journal (though currently we do not enforce this). It may be written on
|
||||||
|
a single line, like this:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
; commodity EXAMPLEAMOUNT
|
||||||
|
|
||||||
|
; display AAAA amounts with the symbol on the right, space-separated,
|
||||||
|
; using period as decimal point, with four decimal places, and
|
||||||
|
; separating thousands with comma.
|
||||||
|
commodity 1,000.0000 AAAA
|
||||||
|
```
|
||||||
|
|
||||||
|
or on multiple lines, using the "format" subdirective. In this case the
|
||||||
|
commodity symbol appears twice and should be the same in both places:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
; commodity SYMBOL
|
||||||
|
; format EXAMPLEAMOUNT
|
||||||
|
|
||||||
|
; display indian rupees with currency name on the left,
|
||||||
|
; thousands, lakhs and crores comma-separated,
|
||||||
|
; period as decimal point, and two decimal places.
|
||||||
|
commodity INR
|
||||||
|
format INR 9,99,99,999.00
|
||||||
|
```
|
||||||
|
|
||||||
|
Commodity directives have a second purpose: they define the standard
|
||||||
|
display format for amounts in the commodity. Normally the display format
|
||||||
|
is inferred from journal entries, but this can be unpredictable;
|
||||||
|
declaring it with a commodity directive overrides this and removes
|
||||||
|
ambiguity. Towards this end, amounts in commodity directives must always
|
||||||
|
be written with a decimal point (a period or comma, followed by 0 or
|
||||||
|
more decimal digits).
|
||||||
|
|
||||||
|
#### Default commodity
|
||||||
|
|
||||||
|
The D directive sets a default commodity (and display format), to be
|
||||||
|
used for amounts without a commodity symbol (ie, plain numbers). (Note
|
||||||
|
this differs from Ledger's default commodity directive.) The commodity
|
||||||
|
and display format will be applied to all subsequent commodity-less
|
||||||
|
amounts, or until the next D directive.
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
# commodity-less amounts should be treated as dollars
|
||||||
|
# (and displayed with symbol on the left, thousands separators and two decimal places)
|
||||||
|
D $1,000.00
|
||||||
|
|
||||||
|
1/1
|
||||||
|
a 5 ; <- commodity-less amount, becomes $1
|
||||||
|
b
|
||||||
|
```
|
||||||
|
|
||||||
|
As with the `commodity` directive, the amount must always be written
|
||||||
|
with a decimal point.
|
||||||
|
|
||||||
|
#### Declaring accounts
|
||||||
|
|
||||||
|
The `account` directive predeclares account names. The simplest form is
|
||||||
|
`account ACCTNAME`, eg:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
account assets:bank:checking
|
||||||
|
```
|
||||||
|
|
||||||
|
Currently this mainly helps with account name autocompletion in eg
|
||||||
|
hledger add, hledger-iadd, hledger-web, and ledger-mode.\
|
||||||
|
In future it will also help detect misspelled accounts.
|
||||||
|
|
||||||
|
Account names can be followed by a numeric account code:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
account assets 1000
|
||||||
|
account assets:bank:checking 1110
|
||||||
|
account liabilities 2000
|
||||||
|
account revenues 4000
|
||||||
|
account expenses 6000
|
||||||
|
```
|
||||||
|
|
||||||
|
This affects account display order in reports: accounts with codes are
|
||||||
|
listed before accounts without codes, in increasing code order.
|
||||||
|
(Otherwise, accounts are listed alphabetically.) Account codes should be
|
||||||
|
all numeric digits, unique, and separated from the account name by at
|
||||||
|
least two spaces (since account names may contain single spaces). By
|
||||||
|
convention, often the first digit indicates the type of account, as in
|
||||||
|
[this numbering
|
||||||
|
scheme](http://www.dwmbeancounter.com/BCTutorSite/Courses/ChartAccounts/lesson02-6.html)
|
||||||
|
and the example above. In future, we might use this to recognize account
|
||||||
|
types.
|
||||||
|
|
||||||
|
An account directive can also have indented subdirectives following it,
|
||||||
|
which are currently ignored. Here is the full syntax:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
; account ACCTNAME [OPTIONALCODE]
|
||||||
|
; [OPTIONALSUBDIRECTIVES]
|
||||||
|
|
||||||
|
account assets:bank:checking 1110
|
||||||
|
a comment
|
||||||
|
some-tag:12345
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Rewriting accounts
|
||||||
|
|
||||||
You can define aliases which rewrite your account names (after reading
|
You can define aliases which rewrite your account names (after reading
|
||||||
the journal, before generating reports). hledger's account aliases can
|
the journal, before generating reports). hledger's account aliases can
|
||||||
@ -734,7 +883,8 @@ be useful for:
|
|||||||
or combining two accounts into one
|
or combining two accounts into one
|
||||||
- customising reports
|
- customising reports
|
||||||
|
|
||||||
See also [Cookbook: rewrite account names](account-aliases.html).
|
See also [Cookbook: Rewrite account
|
||||||
|
names](https://github.com/simonmichael/hledger/wiki/Rewrite-account-names).
|
||||||
|
|
||||||
##### Basic aliases
|
##### Basic aliases
|
||||||
|
|
||||||
@ -796,7 +946,7 @@ order:
|
|||||||
precedence over earlier ones; directives not yet seen are ignored)
|
precedence over earlier ones; directives not yet seen are ignored)
|
||||||
2. alias options, in the order they appear on the command line
|
2. alias options, in the order they appear on the command line
|
||||||
|
|
||||||
##### end aliases
|
##### `end aliases`
|
||||||
|
|
||||||
You can clear (forget) all currently defined aliases with the
|
You can clear (forget) all currently defined aliases with the
|
||||||
`end aliases` directive:
|
`end aliases` directive:
|
||||||
@ -805,53 +955,7 @@ You can clear (forget) all currently defined aliases with the
|
|||||||
end aliases
|
end aliases
|
||||||
```
|
```
|
||||||
|
|
||||||
#### account directive
|
#### Default parent account
|
||||||
|
|
||||||
The `account` directive predeclares account names. The simplest form is
|
|
||||||
`account ACCTNAME`, eg:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
account assets:bank:checking
|
|
||||||
```
|
|
||||||
|
|
||||||
Currently this mainly helps with account name autocompletion in eg
|
|
||||||
hledger add, hledger-iadd, hledger-web, and ledger-mode.\
|
|
||||||
In future it will also help detect misspelled accounts.
|
|
||||||
|
|
||||||
Account names can be followed by a numeric account code:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
account assets 1000
|
|
||||||
account assets:bank:checking 1110
|
|
||||||
account liabilities 2000
|
|
||||||
account revenues 4000
|
|
||||||
account expenses 6000
|
|
||||||
```
|
|
||||||
|
|
||||||
This affects account display order in reports: accounts with codes are
|
|
||||||
listed before accounts without codes, in increasing code order.
|
|
||||||
(Otherwise, accounts are listed alphabetically.) Account codes should be
|
|
||||||
all numeric digits, unique, and separated from the account name by at
|
|
||||||
least two spaces (since account names may contain single spaces). By
|
|
||||||
convention, often the first digit indicates the type of account, as in
|
|
||||||
[this numbering
|
|
||||||
scheme](http://www.dwmbeancounter.com/BCTutorSite/Courses/ChartAccounts/lesson02-6.html)
|
|
||||||
and the example above. In future, we might use this to recognize account
|
|
||||||
types.
|
|
||||||
|
|
||||||
An account directive can also have indented subdirectives following it,
|
|
||||||
which are currently ignored. Here is the full syntax:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
; account ACCTNAME [OPTIONALCODE]
|
|
||||||
; [OPTIONALSUBDIRECTIVES]
|
|
||||||
|
|
||||||
account assets:bank:checking 1110
|
|
||||||
a comment
|
|
||||||
some-tag:12345
|
|
||||||
```
|
|
||||||
|
|
||||||
#### apply account directive
|
|
||||||
|
|
||||||
You can specify a parent account which will be prepended to all accounts
|
You can specify a parent account which will be prepended to all accounts
|
||||||
within a section of the journal. Use the `apply account` and
|
within a section of the journal. Use the `apply account` and
|
||||||
@ -889,106 +993,13 @@ include personal.journal
|
|||||||
Prior to hledger 1.0, legacy `account` and `end` spellings were also
|
Prior to hledger 1.0, legacy `account` and `end` spellings were also
|
||||||
supported.
|
supported.
|
||||||
|
|
||||||
#### Multi-line comments
|
### Periodic transactions
|
||||||
|
|
||||||
A line containing just `comment` starts a multi-line comment, and a line
|
Periodic transaction rules (enabled by `--forecast` or `--budget`)
|
||||||
containing just `end comment` ends it. See [comments](#comments).
|
describe recurring transactions. They look like a transaction where the
|
||||||
|
|
||||||
#### commodity directive
|
|
||||||
|
|
||||||
The `commodity` directive predefines commodities (currently this is just
|
|
||||||
informational), and also it may define the display format for amounts in
|
|
||||||
this commodity (overriding the automatically inferred format).
|
|
||||||
|
|
||||||
It may be written on a single line, like this:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
; commodity EXAMPLEAMOUNT
|
|
||||||
|
|
||||||
; display AAAA amounts with the symbol on the right, space-separated,
|
|
||||||
; using period as decimal point, with four decimal places, and
|
|
||||||
; separating thousands with comma.
|
|
||||||
commodity 1,000.0000 AAAA
|
|
||||||
```
|
|
||||||
|
|
||||||
or on multiple lines, using the "format" subdirective. In this case the
|
|
||||||
commodity symbol appears twice and should be the same in both places:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
; commodity SYMBOL
|
|
||||||
; format EXAMPLEAMOUNT
|
|
||||||
|
|
||||||
; display indian rupees with currency name on the left,
|
|
||||||
; thousands, lakhs and crores comma-separated,
|
|
||||||
; period as decimal point, and two decimal places.
|
|
||||||
commodity INR
|
|
||||||
format INR 9,99,99,999.00
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Default commodity
|
|
||||||
|
|
||||||
The D directive sets a default commodity (and display format), to be
|
|
||||||
used for amounts without a commodity symbol (ie, plain numbers). (Note
|
|
||||||
this differs from Ledger's default commodity directive.) The commodity
|
|
||||||
and display format will be applied to all subsequent commodity-less
|
|
||||||
amounts, or until the next D directive.
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
# commodity-less amounts should be treated as dollars
|
|
||||||
# (and displayed with symbol on the left, thousands separators and two decimal places)
|
|
||||||
D $1,000.00
|
|
||||||
|
|
||||||
1/1
|
|
||||||
a 5 ; <- commodity-less amount, becomes $1
|
|
||||||
b
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Default year
|
|
||||||
|
|
||||||
You can set a default year to be used for subsequent dates which don't
|
|
||||||
specify a year. This is a line beginning with `Y` followed by the year.
|
|
||||||
Eg:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
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 an
|
|
||||||
include directive, like this:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
include path/to/file.journal
|
|
||||||
```
|
|
||||||
|
|
||||||
If the path does not begin with a slash, it is relative to the current
|
|
||||||
file. Glob patterns (`*`) are not currently supported.
|
|
||||||
|
|
||||||
The `include` directive can only be used in journal files. It can
|
|
||||||
include journal, timeclock or timedot files, but not CSV files.
|
|
||||||
|
|
||||||
## Periodic transactions
|
|
||||||
|
|
||||||
Periodic transactions are a kind of rule with a dual purpose: they can
|
|
||||||
specify recurring future transactions (with `--forecast`), or budget
|
|
||||||
goals (with `--budget`). They look a bit like a transaction, except the
|
|
||||||
first line is a tilde (`~`) followed by a [period
|
first line is a tilde (`~`) followed by a [period
|
||||||
expression](manual.html#period-expressions):
|
expression](manual.html#period-expressions) (mnemonic: `~` is like a
|
||||||
|
recurring sine wave):
|
||||||
|
|
||||||
``` {.journal}
|
``` {.journal}
|
||||||
~ weekly
|
~ weekly
|
||||||
@ -996,26 +1007,36 @@ expression](manual.html#period-expressions):
|
|||||||
income:acme inc
|
income:acme inc
|
||||||
```
|
```
|
||||||
|
|
||||||
With `--forecast`, each periodic transaction rule generates recurring
|
Periodic transactions have a dual purpose:
|
||||||
"forecast" transactions at the specified interval, beginning the day
|
|
||||||
after the latest recorded journal transaction (or today, if there are no
|
|
||||||
transactions) and ending 6 months from today (or at the report end date,
|
|
||||||
if specified).
|
|
||||||
|
|
||||||
With `balance --budget`, each periodic transaction declares recurring
|
- With `--forecast`, each periodic transaction rule generates future
|
||||||
budget goals for the specified accounts. Eg the example above declares
|
transactions, recurring at the specified interval, which can be seen
|
||||||
the goal of receiving \$400 from `income:acme inc` (and also, depositing
|
in reports. Forecast transactions begin the day after the latest
|
||||||
\$400 into `assets:bank:checking`) every week.
|
recorded journal transaction (or today, if there are no
|
||||||
|
transactions) and end 6 months from today (or at the report end
|
||||||
|
date, if specified).
|
||||||
|
|
||||||
For more details, see: [balance: Budgeting](manual.html#budgeting) and
|
- With `--budget` (supported by the balance command), each periodic
|
||||||
[Budgeting and Forecasting](budgeting-and-forecasting.html).
|
transaction rule declares recurring budget goals for the specified
|
||||||
|
accounts, which can be seen in [budget
|
||||||
|
reports](/manual.html#budget-report). Eg the example above declares
|
||||||
|
the goal of receiving \$400 from `income:acme inc` (and also,
|
||||||
|
depositing \$400 into `assets:bank:checking`) every week.
|
||||||
|
|
||||||
## Automated postings
|
(Actually, you can generate one-off transactions too, by writing a
|
||||||
|
period expression with no report interval.)
|
||||||
|
|
||||||
Automated postings are postings added automatically by rule to certain
|
For more details, see: [balance: Budget
|
||||||
transactions (with `--auto`). An automated posting rule looks like a
|
report](manual.html#budget-report) and [Cookbook: Budgeting and
|
||||||
transaction where the first line is an equal sign (`=`) followed by a
|
Forecasting](https://github.com/simonmichael/hledger/wiki/Budgeting-and-forecasting).
|
||||||
[query](manual.html#queries):
|
|
||||||
|
### Automated postings
|
||||||
|
|
||||||
|
Automated postings (enabled by `--auto`) are postings added
|
||||||
|
automatically by rule to certain transactions. An automated posting rule
|
||||||
|
looks like a transaction where the first line is an equal sign (`=`)
|
||||||
|
followed by a [query](manual.html#queries) (mnemonic: `=` tests for
|
||||||
|
matching transactions, and also looks like posting lines):
|
||||||
|
|
||||||
``` {.journal}
|
``` {.journal}
|
||||||
= expenses:gifts
|
= expenses:gifts
|
||||||
@ -1028,8 +1049,9 @@ the matched transaction's first posting, multiplied by N". They can also
|
|||||||
be ordinary fixed amounts. Fixed amounts with no commodity symbol will
|
be ordinary fixed amounts. Fixed amounts with no commodity symbol will
|
||||||
be given the same commodity as the matched transaction's first posting.
|
be given the same commodity as the matched transaction's first posting.
|
||||||
|
|
||||||
This example adds a corresponding (unbalanced) budget posting to every
|
This example adds a corresponding ([unbalanced](#virtual-postings))
|
||||||
transaction involving the `expenses:gifts` account:
|
budget posting to every transaction involving the `expenses:gifts`
|
||||||
|
account:
|
||||||
|
|
||||||
``` {.journal}
|
``` {.journal}
|
||||||
= expenses:gifts
|
= expenses:gifts
|
||||||
@ -1044,10 +1066,14 @@ transaction involving the `expenses:gifts` account:
|
|||||||
$ hledger print --auto
|
$ hledger print --auto
|
||||||
2017/12/14
|
2017/12/14
|
||||||
expenses:gifts $20
|
expenses:gifts $20
|
||||||
assets
|
|
||||||
(budget:gifts) $-20
|
(budget:gifts) $-20
|
||||||
|
assets
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Like postings recorded by hand, automated postings participate in
|
||||||
|
[transaction balancing, missing amount inference](#postings) and
|
||||||
|
[balance assertions](#balance-assertions).
|
||||||
|
|
||||||
## EDITOR SUPPORT
|
## EDITOR SUPPORT
|
||||||
|
|
||||||
Add-on modes exist for various text editors, to make working with
|
Add-on modes exist for various text editors, to make working with
|
||||||
|
@ -1,10 +1,8 @@
|
|||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## hledger
|
## hledger
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
### NAME
|
### NAME
|
||||||
|
|
||||||
@ -708,7 +706,7 @@ in a number of places:
|
|||||||
- [query terms](#queries), on the command line and in the hledger-web
|
- [query terms](#queries), on the command line and in the hledger-web
|
||||||
search form: `REGEX`, `desc:REGEX`, `cur:REGEX`, `tag:...=REGEX`
|
search form: `REGEX`, `desc:REGEX`, `cur:REGEX`, `tag:...=REGEX`
|
||||||
- [CSV rules](#csv-rules) conditional blocks: `if REGEX ...`
|
- [CSV rules](#csv-rules) conditional blocks: `if REGEX ...`
|
||||||
- [account alias](#account-aliases) directives and options:
|
- [account alias](#rewriting-accounts) directives and options:
|
||||||
`alias /REGEX/ = REPLACEMENT`, `--alias /REGEX/=REPLACEMENT`
|
`alias /REGEX/ = REPLACEMENT`, `--alias /REGEX/=REPLACEMENT`
|
||||||
|
|
||||||
hledger's regular expressions come from the
|
hledger's regular expressions come from the
|
||||||
@ -773,11 +771,9 @@ which:
|
|||||||
The following kinds of search terms can be used. Remember these can also
|
The following kinds of search terms can be used. Remember these can also
|
||||||
be prefixed with **`not:`**, eg to exclude a particular subaccount.
|
be prefixed with **`not:`**, eg to exclude a particular subaccount.
|
||||||
|
|
||||||
**`REGEX`**
|
**`REGEX`, `acct:REGEX`**
|
||||||
: match account names by this regular expression. (No prefix is
|
: match account names by this regular expression. (With no prefix,
|
||||||
equivalent to `acct:`).
|
`acct:` is assumed.)
|
||||||
|
|
||||||
**`acct:REGEX`**
|
|
||||||
: same as above
|
: same as above
|
||||||
|
|
||||||
**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**
|
**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**
|
||||||
@ -1120,8 +1116,33 @@ Show accounts and their balances. Aliases: b, bal.
|
|||||||
`--show-unbudgeted`
|
`--show-unbudgeted`
|
||||||
: with --budget, show unbudgeted accounts also
|
: with --budget, show unbudgeted accounts also
|
||||||
|
|
||||||
The balance command displays accounts and balances. It is hledger's most
|
The balance command is hledger's most versatile command. Note, despite
|
||||||
featureful and versatile command.
|
the name, it is not always used for showing real-world account balances;
|
||||||
|
the more accounting-aware [balancesheet](#balancesheet) and
|
||||||
|
[incomestatement](#incomestatement) may be more convenient for that.
|
||||||
|
|
||||||
|
By default, it displays all accounts, and each account's change in
|
||||||
|
balance during the entire period of the journal. Balance changes are
|
||||||
|
calculated by adding up the postings in each account. You can limit the
|
||||||
|
postings matched, by a [query](#queries), to see fewer accounts, changes
|
||||||
|
over a different time period, changes from only cleared transactions,
|
||||||
|
etc.
|
||||||
|
|
||||||
|
If you include an account's complete history of postings in the report,
|
||||||
|
the balance change is equivalent to the account's current ending
|
||||||
|
balance. For a real-world account, typically you won't have all
|
||||||
|
transactions in the journal; instead you'll have all transactions after
|
||||||
|
a certain date, and an "opening balances" transaction setting the
|
||||||
|
correct starting balance on that date. Then the balance command will
|
||||||
|
show real-world account balances. In some cases the -H/--historical flag
|
||||||
|
is used to ensure this (more below).
|
||||||
|
|
||||||
|
The balance command can produce several styles of report:
|
||||||
|
|
||||||
|
##### Classic balance report
|
||||||
|
|
||||||
|
This is the original balance report, as found in Ledger. It usually
|
||||||
|
looks like this:
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance
|
$ hledger balance
|
||||||
@ -1139,19 +1160,14 @@ $ hledger balance
|
|||||||
0
|
0
|
||||||
```
|
```
|
||||||
|
|
||||||
More precisely, the balance command shows the *change* to each account's
|
|
||||||
balance caused by all (matched) postings. In the common case where you
|
|
||||||
do not filter by date and your journal sets the correct opening
|
|
||||||
balances, this is the same as the account's ending balance.
|
|
||||||
|
|
||||||
By default, accounts are displayed hierarchically, with subaccounts
|
By default, accounts are displayed hierarchically, with subaccounts
|
||||||
indented below their parent. At each level of the tree, accounts are
|
indented below their parent. At each level of the tree, accounts are
|
||||||
sorted by [account code](/manual.html#account-directive) if any, then by
|
sorted by [account code](/manual.html#declaring-accounts) if any, then
|
||||||
account name. Or with `-S/--sort-amount`, by their balance amount.
|
by account name. Or with `-S/--sort-amount`, by their balance amount.
|
||||||
|
|
||||||
"Boring" accounts, which contain a single interesting subaccount and no
|
"Boring" accounts, which contain a single interesting subaccount and no
|
||||||
balance of their own, are elided into the following line for more
|
balance of their own, are elided into the following line for more
|
||||||
compact output. (Not yet supported in tabular reports.) Use `--no-elide`
|
compact output. (Eg above, the "liabilities" account.) Use `--no-elide`
|
||||||
to prevent this.
|
to prevent this.
|
||||||
|
|
||||||
Account balances are "inclusive" - they include the balances of any
|
Account balances are "inclusive" - they include the balances of any
|
||||||
@ -1161,7 +1177,7 @@ Accounts which have zero balance (and no non-zero subaccounts) are
|
|||||||
omitted. Use `-E/--empty` to show them.
|
omitted. Use `-E/--empty` to show them.
|
||||||
|
|
||||||
A final total is displayed by default; use `-N/--no-total` to suppress
|
A final total is displayed by default; use `-N/--no-total` to suppress
|
||||||
it:
|
it, eg:
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance -p 2008/6 expenses --no-total
|
$ hledger balance -p 2008/6 expenses --no-total
|
||||||
@ -1170,13 +1186,80 @@ $ hledger balance -p 2008/6 expenses --no-total
|
|||||||
$1 supplies
|
$1 supplies
|
||||||
```
|
```
|
||||||
|
|
||||||
|
##### Customising the classic balance report
|
||||||
|
|
||||||
|
You can customise the layout of classic balance reports with
|
||||||
|
`--format FMT`:
|
||||||
|
|
||||||
|
``` {.shell}
|
||||||
|
$ hledger balance --format "%20(account) %12(total)"
|
||||||
|
assets $-1
|
||||||
|
bank:saving $1
|
||||||
|
cash $-2
|
||||||
|
expenses $2
|
||||||
|
food $1
|
||||||
|
supplies $1
|
||||||
|
income $-2
|
||||||
|
gifts $-1
|
||||||
|
salary $-1
|
||||||
|
liabilities:debts $1
|
||||||
|
---------------------------------
|
||||||
|
0
|
||||||
|
```
|
||||||
|
|
||||||
|
The FMT format string (plus a newline) specifies the formatting applied
|
||||||
|
to each account/balance pair. It may contain any suitable text, with
|
||||||
|
data fields interpolated like so:
|
||||||
|
|
||||||
|
`%[MIN][.MAX](FIELDNAME)`
|
||||||
|
|
||||||
|
- MIN pads with spaces to at least this width (optional)
|
||||||
|
- MAX truncates at this width (optional)
|
||||||
|
- FIELDNAME must be enclosed in parentheses, and can be one of:
|
||||||
|
|
||||||
|
- `depth_spacer` - a number of spaces equal to the account's
|
||||||
|
depth, or if MIN is specified, MIN \* depth spaces.
|
||||||
|
- `account` - the account's name
|
||||||
|
- `total` - the account's balance/posted total, right justified
|
||||||
|
|
||||||
|
Also, FMT can begin with an optional prefix to control how
|
||||||
|
multi-commodity amounts are rendered:
|
||||||
|
|
||||||
|
- `%_` - render on multiple lines, bottom-aligned (the default)
|
||||||
|
- `%^` - render on multiple lines, top-aligned
|
||||||
|
- `%,` - render on one line, comma-separated
|
||||||
|
|
||||||
|
There are some quirks. Eg in one-line mode, `%(depth_spacer)` has no
|
||||||
|
effect, instead `%(account)` has indentation built in. <!-- XXX retest:
|
||||||
|
Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
|
||||||
|
Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
|
||||||
|
--> Experimentation may be needed to get pleasing results.
|
||||||
|
|
||||||
|
Some example formats:
|
||||||
|
|
||||||
|
- `%(total)` - the account's total
|
||||||
|
- `%-20.20(account)` - the account's name, left justified, padded to
|
||||||
|
20 characters and clipped at 20 characters
|
||||||
|
- `%,%-50(account) %25(total)` - account name padded to 50
|
||||||
|
characters, total padded to 20 characters, with multiple commodities
|
||||||
|
rendered on one line
|
||||||
|
- `%20(total) %2(depth_spacer)%-(account)` - the default format for
|
||||||
|
the single-column balance report
|
||||||
|
|
||||||
|
##### Colour support
|
||||||
|
|
||||||
|
The balance command shows negative amounts in red, if:
|
||||||
|
|
||||||
|
- the `TERM` environment variable is not set to `dumb`
|
||||||
|
- the output is not being redirected or piped anywhere
|
||||||
|
|
||||||
##### Flat mode
|
##### Flat mode
|
||||||
|
|
||||||
To see a flat list of full account names instead of the default
|
To see a flat list instead of the default hierarchical display, use
|
||||||
hierarchical display, use `--flat`. In this mode, accounts (unless
|
`--flat`. In this mode, accounts (unless depth-clipped) show their full
|
||||||
depth-clipped) show their "exclusive" balance, excluding any subaccount
|
names and "exclusive" balance, excluding any subaccount balances. In
|
||||||
balances. In this mode, you can also use `--drop N` to omit the first
|
this mode, you can also use `--drop N` to omit the first few account
|
||||||
few account name components.
|
name components.
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
|
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
|
||||||
@ -1186,30 +1269,37 @@ $ hledger balance -p 2008/6 expenses -N --flat --drop 1
|
|||||||
|
|
||||||
##### Depth limited balance reports
|
##### Depth limited balance reports
|
||||||
|
|
||||||
With `--depth N`, balance shows accounts only to the specified depth.
|
With `--depth N` or `depth:N` or just `-N`, balance reports show
|
||||||
This is very useful to show a complex charts of accounts in less detail.
|
accounts only to the specified numeric depth. This is very useful to
|
||||||
In flat mode, balances from accounts below the depth limit will be shown
|
summarise a complex set of accounts and get an overview.
|
||||||
as part of a parent account at the depth limit.
|
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance -N --depth 1
|
$ hledger balance -N -1
|
||||||
$-1 assets
|
$-1 assets
|
||||||
$2 expenses
|
$2 expenses
|
||||||
$-2 income
|
$-2 income
|
||||||
$1 liabilities
|
$1 liabilities
|
||||||
```
|
```
|
||||||
|
|
||||||
<!-- $ for y in 2006 2007 2008 2009 2010; do echo; echo $y; hledger -f $y.journal balance ^expenses --depth 2; done -->
|
Flat-mode balance reports, which normally show exclusive balances, show
|
||||||
##### Multicolumn balance reports
|
inclusive balances at the depth limit.
|
||||||
|
|
||||||
With a [reporting interval](#reporting-interval), multiple balance
|
<!-- $ for y in 2006 2007 2008 2009 2010; do echo; echo $y; hledger -f $y.journal balance ^expenses --depth 2; done -->
|
||||||
columns will be shown, one for each report period. There are three types
|
##### Multicolumn balance report
|
||||||
of multi-column balance report, showing different information:
|
|
||||||
|
Multicolumn or tabular balance reports are a very useful hledger
|
||||||
|
feature, and usually the preferred style. They share many of the above
|
||||||
|
features, but they show the report as a table, with columns representing
|
||||||
|
time periods. This mode is activated by providing a [reporting
|
||||||
|
interval](#reporting-interval).
|
||||||
|
|
||||||
|
There are three types of multicolumn balance report, showing different
|
||||||
|
information:
|
||||||
|
|
||||||
1. By default: each column shows the sum of postings in that period, ie
|
1. By default: each column shows the sum of postings in that period, ie
|
||||||
the account's change of balance in that period. This is useful eg
|
the account's change of balance in that period. This is useful eg
|
||||||
for a monthly income statement: <!--
|
for a monthly income statement: <!--
|
||||||
multi-column income statement:
|
multicolumn income statement:
|
||||||
|
|
||||||
$ hledger balance ^income ^expense -p 'monthly this year' --depth 3
|
$ hledger balance ^income ^expense -p 'monthly this year' --depth 3
|
||||||
|
|
||||||
@ -1270,8 +1360,8 @@ of multi-column balance report, showing different information:
|
|||||||
|| 0 0 0
|
|| 0 0 0
|
||||||
```
|
```
|
||||||
|
|
||||||
Multi-column balance reports display accounts in flat mode by default;
|
Multicolumn balance reports display accounts in flat mode by default; to
|
||||||
to see the hierarchy, use `--tree`.
|
see the hierarchy, use `--tree`.
|
||||||
|
|
||||||
With a reporting interval (like `--quarterly` above), the report
|
With a reporting interval (like `--quarterly` above), the report
|
||||||
start/end dates will be adjusted if necessary so that they encompass the
|
start/end dates will be adjusted if necessary so that they encompass the
|
||||||
@ -1312,14 +1402,23 @@ Balance changes in 2008:
|
|||||||
# Average is rounded to the dollar here since all journal amounts are
|
# Average is rounded to the dollar here since all journal amounts are
|
||||||
```
|
```
|
||||||
|
|
||||||
##### Budgets
|
Limitations:
|
||||||
|
|
||||||
With `--budget` and a [report interval](manual.html#report-intervals),
|
In multicolumn reports the [`-V/--value` flag](#market-value) uses the
|
||||||
all [periodic transactions](journal.html#periodic-transactions) in your
|
market price on the report end date, for all columns (not the price on
|
||||||
journal with that interval, active during the requested report period,
|
each column's end date).
|
||||||
are interpreted as recurring budget goals for the specified accounts
|
|
||||||
(and subaccounts), and the report will show the difference between
|
Eliding of boring parent accounts in tree mode, as in the classic
|
||||||
actual and budgeted balances.
|
balance report, is not yet supported in multicolumn reports.
|
||||||
|
|
||||||
|
##### Budget report
|
||||||
|
|
||||||
|
With `--budget`, extra columns are displayed showing budget goals for
|
||||||
|
each account and period, if any. Budget goals are defined by [periodic
|
||||||
|
transactions](journal.html#periodic-transactions). This is very useful
|
||||||
|
for comparing planned and actual income, expenses, time usage, etc.
|
||||||
|
--budget is most often combined with a [report
|
||||||
|
interval](manual.html#report-intervals).
|
||||||
|
|
||||||
For example, you can take average monthly expenses in the common expense
|
For example, you can take average monthly expenses in the common expense
|
||||||
categories to construct a minimal monthly budget:
|
categories to construct a minimal monthly budget:
|
||||||
@ -1350,141 +1449,59 @@ categories to construct a minimal monthly budget:
|
|||||||
assets:bank:checking
|
assets:bank:checking
|
||||||
```
|
```
|
||||||
|
|
||||||
You can now see a monthly budget performance report:
|
You can now see a monthly budget report:
|
||||||
|
|
||||||
``` {.shell}
|
``` {.shell}
|
||||||
$ hledger balance -M --budget
|
$ hledger balance -M --budget
|
||||||
Balance changes in 2017/11/01-2017/12/31:
|
Budget performance in 2017/11/01-2017/12/31:
|
||||||
|
|
||||||
|| 2017/11 2017/12
|
|
||||||
=======================++=================================================
|
|
||||||
<unbudgeted>:expenses || $20 $100
|
|
||||||
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
|
|
||||||
expenses:bus || $49 [98% of $50] $53 [106% of $50]
|
|
||||||
expenses:food || $396 [99% of $400] $412 [103% of $400]
|
|
||||||
expenses:movies || $30 [100% of $30] 0 [0% of $30]
|
|
||||||
income || $1950 [98% of $2000] $2100 [105% of $2000]
|
|
||||||
-----------------------++-------------------------------------------------
|
|
||||||
|| 0 0
|
|
||||||
```
|
|
||||||
|
|
||||||
You can roll over unspent budgets to next period with `--cumulative`:
|
|
||||||
|
|
||||||
``` {.shell}
|
|
||||||
$ hledger balance -M --budget --cumulative
|
|
||||||
Ending balances (cumulative) in 2017/11/01-2017/12/31:
|
|
||||||
|
|
||||||
|| 2017/11/30 2017/12/31
|
|
||||||
=======================++=================================================
|
|
||||||
<unbudgeted>:expenses || $20 $120
|
|
||||||
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
|
|
||||||
expenses:bus || $49 [98% of $50] $102 [102% of $100]
|
|
||||||
expenses:food || $396 [99% of $400] $808 [101% of $800]
|
|
||||||
expenses:movies || $30 [100% of $30] $30 [50% of $60]
|
|
||||||
income || $1950 [98% of $2000] $4050 [101% of $4000]
|
|
||||||
-----------------------++-------------------------------------------------
|
|
||||||
|| 0 0
|
|
||||||
```
|
|
||||||
|
|
||||||
Accounts with no budget goals (not mentioned in the periodic
|
|
||||||
transactions) will be aggregated under `<unbudgeted>`, unless you add
|
|
||||||
the `--show-unbudgeted` flag to display them normally:
|
|
||||||
|
|
||||||
``` {.shell}
|
|
||||||
$ hledger balance --budget --show-unbudgeted
|
|
||||||
Balance changes in 2017/11/01-2017/12/31:
|
|
||||||
|
|
||||||
|| 2017/11 2017/12
|
|| 2017/11 2017/12
|
||||||
======================++=================================================
|
======================++=================================================
|
||||||
|
<unbudgeted> || $20 $100
|
||||||
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
|
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
|
||||||
expenses:bus || $49 [98% of $50] $53 [106% of $50]
|
expenses:bus || $49 [98% of $50] $53 [106% of $50]
|
||||||
expenses:food || $396 [99% of $400] $412 [103% of $400]
|
expenses:food || $396 [99% of $400] $412 [103% of $400]
|
||||||
expenses:gifts || 0 $100
|
|
||||||
expenses:movies || $30 [100% of $30] 0 [0% of $30]
|
expenses:movies || $30 [100% of $30] 0 [0% of $30]
|
||||||
expenses:supplies || $20 0
|
|
||||||
income || $1950 [98% of $2000] $2100 [105% of $2000]
|
income || $1950 [98% of $2000] $2100 [105% of $2000]
|
||||||
----------------------++-------------------------------------------------
|
----------------------++-------------------------------------------------
|
||||||
|| 0 0
|
|| 0 0
|
||||||
```
|
```
|
||||||
|
|
||||||
Note --budget first arrived in hledger in 1.5 and is still pretty young;
|
By default, only accounts with budget goals during the report period are
|
||||||
join the discussions on mail list and issue tracker to help us refine
|
shown. `--show-unbudgeted` shows unbudgeted accounts as well. Top-level
|
||||||
it.
|
accounts with no budget goals anywhere below them are grouped under
|
||||||
|
`<unbudgeted>`.
|
||||||
|
|
||||||
|
You can roll over unspent budgets to next period with `--cumulative`:
|
||||||
|
|
||||||
|
``` {.shell}
|
||||||
|
$ hledger balance -M --budget --cumulative
|
||||||
|
Budget performance in 2017/11/01-2017/12/31:
|
||||||
|
|
||||||
|
|| 2017/11/30 2017/12/31
|
||||||
|
======================++=================================================
|
||||||
|
<unbudgeted> || $20 $120
|
||||||
|
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
|
||||||
|
expenses:bus || $49 [98% of $50] $102 [102% of $100]
|
||||||
|
expenses:food || $396 [99% of $400] $808 [101% of $800]
|
||||||
|
expenses:movies || $30 [100% of $30] $30 [50% of $60]
|
||||||
|
income || $1950 [98% of $2000] $4050 [101% of $4000]
|
||||||
|
----------------------++-------------------------------------------------
|
||||||
|
|| 0 0
|
||||||
|
```
|
||||||
|
|
||||||
|
Note, the `-S/--sort-amount` flag is not yet fully supported with
|
||||||
|
`--budget`.
|
||||||
|
|
||||||
For more examples, see [Budgeting and
|
For more examples, see [Budgeting and
|
||||||
Forecasting](https://github.com/simonmichael/hledger/wiki/Budgeting%20and%20forecasting).
|
Forecasting](https://github.com/simonmichael/hledger/wiki/Budgeting%20and%20forecasting).
|
||||||
|
|
||||||
##### Custom balance output
|
##### Output format
|
||||||
|
|
||||||
You can customise the layout of simple (non-tabular) balance reports
|
The balance command supports [output
|
||||||
with `--format FMT`:
|
|
||||||
|
|
||||||
``` {.shell}
|
|
||||||
$ hledger balance --format "%20(account) %12(total)"
|
|
||||||
assets $-1
|
|
||||||
bank:saving $1
|
|
||||||
cash $-2
|
|
||||||
expenses $2
|
|
||||||
food $1
|
|
||||||
supplies $1
|
|
||||||
income $-2
|
|
||||||
gifts $-1
|
|
||||||
salary $-1
|
|
||||||
liabilities:debts $1
|
|
||||||
---------------------------------
|
|
||||||
0
|
|
||||||
```
|
|
||||||
|
|
||||||
The FMT format string (plus a newline) specifies the formatting applied
|
|
||||||
to each account/balance pair. It may contain any suitable text, with
|
|
||||||
data fields interpolated like so:
|
|
||||||
|
|
||||||
`%[MIN][.MAX](FIELDNAME)`
|
|
||||||
|
|
||||||
- MIN pads with spaces to at least this width (optional)
|
|
||||||
- MAX truncates at this width (optional)
|
|
||||||
- FIELDNAME must be enclosed in parentheses, and can be one of:
|
|
||||||
|
|
||||||
- `depth_spacer` - a number of spaces equal to the account's
|
|
||||||
depth, or if MIN is specified, MIN \* depth spaces.
|
|
||||||
- `account` - the account's name
|
|
||||||
- `total` - the account's balance/posted total, right justified
|
|
||||||
|
|
||||||
Also, FMT can begin with an optional prefix to control how
|
|
||||||
multi-commodity amounts are rendered:
|
|
||||||
|
|
||||||
- `%_` - render on multiple lines, bottom-aligned (the default)
|
|
||||||
- `%^` - render on multiple lines, top-aligned
|
|
||||||
- `%,` - render on one line, comma-separated
|
|
||||||
|
|
||||||
There are some quirks. Eg in one-line mode, `%(depth_spacer)` has no
|
|
||||||
effect, instead `%(account)` has indentation built in. <!-- XXX retest:
|
|
||||||
Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
|
|
||||||
Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
|
|
||||||
--> Experimentation may be needed to get pleasing results.
|
|
||||||
|
|
||||||
Some example formats:
|
|
||||||
|
|
||||||
- `%(total)` - the account's total
|
|
||||||
- `%-20.20(account)` - the account's name, left justified, padded to
|
|
||||||
20 characters and clipped at 20 characters
|
|
||||||
- `%,%-50(account) %25(total)` - account name padded to 50
|
|
||||||
characters, total padded to 20 characters, with multiple commodities
|
|
||||||
rendered on one line
|
|
||||||
- `%20(total) %2(depth_spacer)%-(account)` - the default format for
|
|
||||||
the single-column balance report
|
|
||||||
|
|
||||||
This command also supports [output
|
|
||||||
destination](/manual.html#output-destination) and [output
|
destination](/manual.html#output-destination) and [output
|
||||||
format](/manual.html#output-format) selection.
|
format](/manual.html#output-format) selection.
|
||||||
|
|
||||||
##### Colour support
|
|
||||||
|
|
||||||
The balance command shows negative amounts in red, if:
|
|
||||||
|
|
||||||
- the `TERM` environment variable is not set to `dumb`
|
|
||||||
- the output is not being redirected or piped anywhere
|
|
||||||
|
|
||||||
#### balancesheet
|
#### balancesheet
|
||||||
|
|
||||||
This command displays a simple balance sheet, showing historical ending
|
This command displays a simple balance sheet, showing historical ending
|
||||||
@ -2304,7 +2321,7 @@ In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
|
|||||||
add.
|
add.
|
||||||
|
|
||||||
Not all of Ledger's journal file syntax is supported. See [file format
|
Not all of Ledger's journal file syntax is supported. See [file format
|
||||||
differences](faq#file-format-differences).
|
differences](https://github.com/simonmichael/hledger/wiki/FAQ#file-formats).
|
||||||
|
|
||||||
On large data files, hledger is slower and uses more memory than Ledger.
|
On large data files, hledger is slower and uses more memory than Ledger.
|
||||||
|
|
||||||
@ -2378,7 +2395,7 @@ accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`).
|
|||||||
|
|
||||||
## hledger-ui
|
## hledger-ui
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
### NAME
|
### NAME
|
||||||
|
|
||||||
@ -2787,7 +2804,7 @@ program is restarted.
|
|||||||
|
|
||||||
## hledger-web
|
## hledger-web
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
### NAME
|
### NAME
|
||||||
|
|
||||||
@ -3037,7 +3054,7 @@ Does not work well on small screens.
|
|||||||
|
|
||||||
## hledger-api
|
## hledger-api
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
### NAME
|
### NAME
|
||||||
|
|
||||||
@ -3139,7 +3156,7 @@ awkward.
|
|||||||
|
|
||||||
## journal format
|
## journal format
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
### NAME
|
### NAME
|
||||||
|
|
||||||
@ -3156,10 +3173,11 @@ a number of transaction entries, each describing a transfer of money (or
|
|||||||
any commodity) between two or more named accounts, in a simple format
|
any commodity) between two or more named accounts, in a simple format
|
||||||
readable by both hledger and humans.
|
readable by both hledger and humans.
|
||||||
|
|
||||||
hledger's journal format is a compatible subset,
|
hledger's journal format is a compatible subset, mostly, of [ledger's
|
||||||
[mostly](faq.html#file-format-differences), of [ledger's journal
|
journal
|
||||||
format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), so
|
format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), so
|
||||||
hledger can work with [compatible](faq.html#file-format-differences)
|
hledger can work with
|
||||||
|
[compatible](https://github.com/simonmichael/hledger/wiki/FAQ#file-formats)
|
||||||
ledger journal files as well. It's safe, and encouraged, to run both
|
ledger journal files as well. It's safe, and encouraged, to run both
|
||||||
hledger and ledger on the same journal file, eg to validate the results
|
hledger and ledger on the same journal file, eg to validate the results
|
||||||
you're getting.
|
you're getting.
|
||||||
@ -3414,7 +3432,7 @@ Account names may contain single spaces, eg:
|
|||||||
`assets:accounts receivable`. Because of this, they must always be
|
`assets:accounts receivable`. Because of this, they must always be
|
||||||
followed by **two or more spaces** (or newline).
|
followed by **two or more spaces** (or newline).
|
||||||
|
|
||||||
Account names can be [aliased](#account-aliases).
|
Account names can be [aliased](#rewriting-accounts).
|
||||||
|
|
||||||
#### Amounts
|
#### Amounts
|
||||||
|
|
||||||
@ -3476,8 +3494,8 @@ hledger displays amounts, it will choose a consistent format for each
|
|||||||
commodity. (Except for [price amounts](#prices), which are always
|
commodity. (Except for [price amounts](#prices), which are always
|
||||||
formatted as written). The display format is chosen as follows:
|
formatted as written). The display format is chosen as follows:
|
||||||
|
|
||||||
- if there is a [commodity directive](#commodity-directive) specifying
|
- if there is a [commodity directive](#declaring-commodities)
|
||||||
the format, that is used
|
specifying the format, that is used
|
||||||
- otherwise the format is inferred from the first posting amount in
|
- otherwise the format is inferred from the first posting amount in
|
||||||
that commodity in the journal, and the precision (number of decimal
|
that commodity in the journal, and the precision (number of decimal
|
||||||
places) will be the maximum from all posting amounts in that
|
places) will be the maximum from all posting amounts in that
|
||||||
@ -3773,10 +3791,6 @@ star (`*`) are comments, and will be ignored. (Star comments cause
|
|||||||
org-mode nodes to be ignored, allowing emacs users to fold and navigate
|
org-mode nodes to be ignored, allowing emacs users to fold and navigate
|
||||||
their journals with org-mode or orgstruct-mode.)
|
their journals with org-mode or orgstruct-mode.)
|
||||||
|
|
||||||
Also, anything between [`comment` and `end comment`
|
|
||||||
directives](#multi-line-comments) is a (multi-line) comment. If there is
|
|
||||||
no `end comment`, the comment extends to the end of the file.
|
|
||||||
|
|
||||||
You can attach comments to a transaction by writing them after the
|
You can attach comments to a transaction by writing them after the
|
||||||
description and/or indented on the following lines (before the
|
description and/or indented on the following lines (before the
|
||||||
postings). Similarly, you can attach comments to an individual posting
|
postings). Similarly, you can attach comments to an individual posting
|
||||||
@ -3806,6 +3820,9 @@ end comment
|
|||||||
; a file comment (because not indented)
|
; a file comment (because not indented)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
You can also comment larger regions of a file using [`comment` and
|
||||||
|
`end comment` directives](#comment-blocks).
|
||||||
|
|
||||||
#### Tags
|
#### Tags
|
||||||
|
|
||||||
Tags are a way to add extra labels or labelled data to postings and
|
Tags are a way to add extra labels or labelled data to postings and
|
||||||
@ -3858,7 +3875,156 @@ except hledger's tag values are simple strings.
|
|||||||
|
|
||||||
#### Directives
|
#### Directives
|
||||||
|
|
||||||
##### Account aliases
|
##### Comment blocks
|
||||||
|
|
||||||
|
A line containing just `comment` starts a commented region of the file,
|
||||||
|
and a line containing just `end comment` (or the end of the current
|
||||||
|
file) ends it. See also [comments](#comments).
|
||||||
|
|
||||||
|
##### Including other files
|
||||||
|
|
||||||
|
You can pull in the content of additional files by writing an include
|
||||||
|
directive, like this:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
include path/to/file.journal
|
||||||
|
```
|
||||||
|
|
||||||
|
If the path does not begin with a slash, it is relative to the current
|
||||||
|
file. Glob patterns (`*`) are not currently supported.
|
||||||
|
|
||||||
|
The `include` directive can only be used in journal files. It can
|
||||||
|
include journal, timeclock or timedot files, but not CSV files.
|
||||||
|
|
||||||
|
##### Default year
|
||||||
|
|
||||||
|
You can set a default year to be used for subsequent dates which don't
|
||||||
|
specify a year. This is a line beginning with `Y` followed by the year.
|
||||||
|
Eg:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
##### Declaring commodities
|
||||||
|
|
||||||
|
The `commodity` directive declares commodities which may be used in the
|
||||||
|
journal (though currently we do not enforce this). It may be written on
|
||||||
|
a single line, like this:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
; commodity EXAMPLEAMOUNT
|
||||||
|
|
||||||
|
; display AAAA amounts with the symbol on the right, space-separated,
|
||||||
|
; using period as decimal point, with four decimal places, and
|
||||||
|
; separating thousands with comma.
|
||||||
|
commodity 1,000.0000 AAAA
|
||||||
|
```
|
||||||
|
|
||||||
|
or on multiple lines, using the "format" subdirective. In this case the
|
||||||
|
commodity symbol appears twice and should be the same in both places:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
; commodity SYMBOL
|
||||||
|
; format EXAMPLEAMOUNT
|
||||||
|
|
||||||
|
; display indian rupees with currency name on the left,
|
||||||
|
; thousands, lakhs and crores comma-separated,
|
||||||
|
; period as decimal point, and two decimal places.
|
||||||
|
commodity INR
|
||||||
|
format INR 9,99,99,999.00
|
||||||
|
```
|
||||||
|
|
||||||
|
Commodity directives have a second purpose: they define the standard
|
||||||
|
display format for amounts in the commodity. Normally the display format
|
||||||
|
is inferred from journal entries, but this can be unpredictable;
|
||||||
|
declaring it with a commodity directive overrides this and removes
|
||||||
|
ambiguity. Towards this end, amounts in commodity directives must always
|
||||||
|
be written with a decimal point (a period or comma, followed by 0 or
|
||||||
|
more decimal digits).
|
||||||
|
|
||||||
|
##### Default commodity
|
||||||
|
|
||||||
|
The D directive sets a default commodity (and display format), to be
|
||||||
|
used for amounts without a commodity symbol (ie, plain numbers). (Note
|
||||||
|
this differs from Ledger's default commodity directive.) The commodity
|
||||||
|
and display format will be applied to all subsequent commodity-less
|
||||||
|
amounts, or until the next D directive.
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
# commodity-less amounts should be treated as dollars
|
||||||
|
# (and displayed with symbol on the left, thousands separators and two decimal places)
|
||||||
|
D $1,000.00
|
||||||
|
|
||||||
|
1/1
|
||||||
|
a 5 ; <- commodity-less amount, becomes $1
|
||||||
|
b
|
||||||
|
```
|
||||||
|
|
||||||
|
As with the `commodity` directive, the amount must always be written
|
||||||
|
with a decimal point.
|
||||||
|
|
||||||
|
##### Declaring accounts
|
||||||
|
|
||||||
|
The `account` directive predeclares account names. The simplest form is
|
||||||
|
`account ACCTNAME`, eg:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
account assets:bank:checking
|
||||||
|
```
|
||||||
|
|
||||||
|
Currently this mainly helps with account name autocompletion in eg
|
||||||
|
hledger add, hledger-iadd, hledger-web, and ledger-mode.\
|
||||||
|
In future it will also help detect misspelled accounts.
|
||||||
|
|
||||||
|
Account names can be followed by a numeric account code:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
account assets 1000
|
||||||
|
account assets:bank:checking 1110
|
||||||
|
account liabilities 2000
|
||||||
|
account revenues 4000
|
||||||
|
account expenses 6000
|
||||||
|
```
|
||||||
|
|
||||||
|
This affects account display order in reports: accounts with codes are
|
||||||
|
listed before accounts without codes, in increasing code order.
|
||||||
|
(Otherwise, accounts are listed alphabetically.) Account codes should be
|
||||||
|
all numeric digits, unique, and separated from the account name by at
|
||||||
|
least two spaces (since account names may contain single spaces). By
|
||||||
|
convention, often the first digit indicates the type of account, as in
|
||||||
|
[this numbering
|
||||||
|
scheme](http://www.dwmbeancounter.com/BCTutorSite/Courses/ChartAccounts/lesson02-6.html)
|
||||||
|
and the example above. In future, we might use this to recognize account
|
||||||
|
types.
|
||||||
|
|
||||||
|
An account directive can also have indented subdirectives following it,
|
||||||
|
which are currently ignored. Here is the full syntax:
|
||||||
|
|
||||||
|
``` {.journal}
|
||||||
|
; account ACCTNAME [OPTIONALCODE]
|
||||||
|
; [OPTIONALSUBDIRECTIVES]
|
||||||
|
|
||||||
|
account assets:bank:checking 1110
|
||||||
|
a comment
|
||||||
|
some-tag:12345
|
||||||
|
```
|
||||||
|
|
||||||
|
##### Rewriting accounts
|
||||||
|
|
||||||
You can define aliases which rewrite your account names (after reading
|
You can define aliases which rewrite your account names (after reading
|
||||||
the journal, before generating reports). hledger's account aliases can
|
the journal, before generating reports). hledger's account aliases can
|
||||||
@ -3871,7 +4037,8 @@ be useful for:
|
|||||||
or combining two accounts into one
|
or combining two accounts into one
|
||||||
- customising reports
|
- customising reports
|
||||||
|
|
||||||
See also [Cookbook: rewrite account names](account-aliases.html).
|
See also [Cookbook: Rewrite account
|
||||||
|
names](https://github.com/simonmichael/hledger/wiki/Rewrite-account-names).
|
||||||
|
|
||||||
###### Basic aliases
|
###### Basic aliases
|
||||||
|
|
||||||
@ -3933,7 +4100,7 @@ order:
|
|||||||
precedence over earlier ones; directives not yet seen are ignored)
|
precedence over earlier ones; directives not yet seen are ignored)
|
||||||
2. alias options, in the order they appear on the command line
|
2. alias options, in the order they appear on the command line
|
||||||
|
|
||||||
###### end aliases
|
###### `end aliases`
|
||||||
|
|
||||||
You can clear (forget) all currently defined aliases with the
|
You can clear (forget) all currently defined aliases with the
|
||||||
`end aliases` directive:
|
`end aliases` directive:
|
||||||
@ -3942,53 +4109,7 @@ You can clear (forget) all currently defined aliases with the
|
|||||||
end aliases
|
end aliases
|
||||||
```
|
```
|
||||||
|
|
||||||
##### account directive
|
##### Default parent account
|
||||||
|
|
||||||
The `account` directive predeclares account names. The simplest form is
|
|
||||||
`account ACCTNAME`, eg:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
account assets:bank:checking
|
|
||||||
```
|
|
||||||
|
|
||||||
Currently this mainly helps with account name autocompletion in eg
|
|
||||||
hledger add, hledger-iadd, hledger-web, and ledger-mode.\
|
|
||||||
In future it will also help detect misspelled accounts.
|
|
||||||
|
|
||||||
Account names can be followed by a numeric account code:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
account assets 1000
|
|
||||||
account assets:bank:checking 1110
|
|
||||||
account liabilities 2000
|
|
||||||
account revenues 4000
|
|
||||||
account expenses 6000
|
|
||||||
```
|
|
||||||
|
|
||||||
This affects account display order in reports: accounts with codes are
|
|
||||||
listed before accounts without codes, in increasing code order.
|
|
||||||
(Otherwise, accounts are listed alphabetically.) Account codes should be
|
|
||||||
all numeric digits, unique, and separated from the account name by at
|
|
||||||
least two spaces (since account names may contain single spaces). By
|
|
||||||
convention, often the first digit indicates the type of account, as in
|
|
||||||
[this numbering
|
|
||||||
scheme](http://www.dwmbeancounter.com/BCTutorSite/Courses/ChartAccounts/lesson02-6.html)
|
|
||||||
and the example above. In future, we might use this to recognize account
|
|
||||||
types.
|
|
||||||
|
|
||||||
An account directive can also have indented subdirectives following it,
|
|
||||||
which are currently ignored. Here is the full syntax:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
; account ACCTNAME [OPTIONALCODE]
|
|
||||||
; [OPTIONALSUBDIRECTIVES]
|
|
||||||
|
|
||||||
account assets:bank:checking 1110
|
|
||||||
a comment
|
|
||||||
some-tag:12345
|
|
||||||
```
|
|
||||||
|
|
||||||
##### apply account directive
|
|
||||||
|
|
||||||
You can specify a parent account which will be prepended to all accounts
|
You can specify a parent account which will be prepended to all accounts
|
||||||
within a section of the journal. Use the `apply account` and
|
within a section of the journal. Use the `apply account` and
|
||||||
@ -4026,106 +4147,13 @@ include personal.journal
|
|||||||
Prior to hledger 1.0, legacy `account` and `end` spellings were also
|
Prior to hledger 1.0, legacy `account` and `end` spellings were also
|
||||||
supported.
|
supported.
|
||||||
|
|
||||||
##### Multi-line comments
|
#### Periodic transactions
|
||||||
|
|
||||||
A line containing just `comment` starts a multi-line comment, and a line
|
Periodic transaction rules (enabled by `--forecast` or `--budget`)
|
||||||
containing just `end comment` ends it. See [comments](#comments).
|
describe recurring transactions. They look like a transaction where the
|
||||||
|
|
||||||
##### commodity directive
|
|
||||||
|
|
||||||
The `commodity` directive predefines commodities (currently this is just
|
|
||||||
informational), and also it may define the display format for amounts in
|
|
||||||
this commodity (overriding the automatically inferred format).
|
|
||||||
|
|
||||||
It may be written on a single line, like this:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
; commodity EXAMPLEAMOUNT
|
|
||||||
|
|
||||||
; display AAAA amounts with the symbol on the right, space-separated,
|
|
||||||
; using period as decimal point, with four decimal places, and
|
|
||||||
; separating thousands with comma.
|
|
||||||
commodity 1,000.0000 AAAA
|
|
||||||
```
|
|
||||||
|
|
||||||
or on multiple lines, using the "format" subdirective. In this case the
|
|
||||||
commodity symbol appears twice and should be the same in both places:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
; commodity SYMBOL
|
|
||||||
; format EXAMPLEAMOUNT
|
|
||||||
|
|
||||||
; display indian rupees with currency name on the left,
|
|
||||||
; thousands, lakhs and crores comma-separated,
|
|
||||||
; period as decimal point, and two decimal places.
|
|
||||||
commodity INR
|
|
||||||
format INR 9,99,99,999.00
|
|
||||||
```
|
|
||||||
|
|
||||||
##### Default commodity
|
|
||||||
|
|
||||||
The D directive sets a default commodity (and display format), to be
|
|
||||||
used for amounts without a commodity symbol (ie, plain numbers). (Note
|
|
||||||
this differs from Ledger's default commodity directive.) The commodity
|
|
||||||
and display format will be applied to all subsequent commodity-less
|
|
||||||
amounts, or until the next D directive.
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
# commodity-less amounts should be treated as dollars
|
|
||||||
# (and displayed with symbol on the left, thousands separators and two decimal places)
|
|
||||||
D $1,000.00
|
|
||||||
|
|
||||||
1/1
|
|
||||||
a 5 ; <- commodity-less amount, becomes $1
|
|
||||||
b
|
|
||||||
```
|
|
||||||
|
|
||||||
##### Default year
|
|
||||||
|
|
||||||
You can set a default year to be used for subsequent dates which don't
|
|
||||||
specify a year. This is a line beginning with `Y` followed by the year.
|
|
||||||
Eg:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
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 an
|
|
||||||
include directive, like this:
|
|
||||||
|
|
||||||
``` {.journal}
|
|
||||||
include path/to/file.journal
|
|
||||||
```
|
|
||||||
|
|
||||||
If the path does not begin with a slash, it is relative to the current
|
|
||||||
file. Glob patterns (`*`) are not currently supported.
|
|
||||||
|
|
||||||
The `include` directive can only be used in journal files. It can
|
|
||||||
include journal, timeclock or timedot files, but not CSV files.
|
|
||||||
|
|
||||||
### Periodic transactions
|
|
||||||
|
|
||||||
Periodic transactions are a kind of rule with a dual purpose: they can
|
|
||||||
specify recurring future transactions (with `--forecast`), or budget
|
|
||||||
goals (with `--budget`). They look a bit like a transaction, except the
|
|
||||||
first line is a tilde (`~`) followed by a [period
|
first line is a tilde (`~`) followed by a [period
|
||||||
expression](manual.html#period-expressions):
|
expression](manual.html#period-expressions) (mnemonic: `~` is like a
|
||||||
|
recurring sine wave):
|
||||||
|
|
||||||
``` {.journal}
|
``` {.journal}
|
||||||
~ weekly
|
~ weekly
|
||||||
@ -4133,26 +4161,36 @@ expression](manual.html#period-expressions):
|
|||||||
income:acme inc
|
income:acme inc
|
||||||
```
|
```
|
||||||
|
|
||||||
With `--forecast`, each periodic transaction rule generates recurring
|
Periodic transactions have a dual purpose:
|
||||||
"forecast" transactions at the specified interval, beginning the day
|
|
||||||
after the latest recorded journal transaction (or today, if there are no
|
|
||||||
transactions) and ending 6 months from today (or at the report end date,
|
|
||||||
if specified).
|
|
||||||
|
|
||||||
With `balance --budget`, each periodic transaction declares recurring
|
- With `--forecast`, each periodic transaction rule generates future
|
||||||
budget goals for the specified accounts. Eg the example above declares
|
transactions, recurring at the specified interval, which can be seen
|
||||||
the goal of receiving \$400 from `income:acme inc` (and also, depositing
|
in reports. Forecast transactions begin the day after the latest
|
||||||
\$400 into `assets:bank:checking`) every week.
|
recorded journal transaction (or today, if there are no
|
||||||
|
transactions) and end 6 months from today (or at the report end
|
||||||
|
date, if specified).
|
||||||
|
|
||||||
For more details, see: [balance: Budgeting](manual.html#budgeting) and
|
- With `--budget` (supported by the balance command), each periodic
|
||||||
[Budgeting and Forecasting](budgeting-and-forecasting.html).
|
transaction rule declares recurring budget goals for the specified
|
||||||
|
accounts, which can be seen in [budget
|
||||||
|
reports](/manual.html#budget-report). Eg the example above declares
|
||||||
|
the goal of receiving \$400 from `income:acme inc` (and also,
|
||||||
|
depositing \$400 into `assets:bank:checking`) every week.
|
||||||
|
|
||||||
### Automated postings
|
(Actually, you can generate one-off transactions too, by writing a
|
||||||
|
period expression with no report interval.)
|
||||||
|
|
||||||
Automated postings are postings added automatically by rule to certain
|
For more details, see: [balance: Budget
|
||||||
transactions (with `--auto`). An automated posting rule looks like a
|
report](manual.html#budget-report) and [Cookbook: Budgeting and
|
||||||
transaction where the first line is an equal sign (`=`) followed by a
|
Forecasting](https://github.com/simonmichael/hledger/wiki/Budgeting-and-forecasting).
|
||||||
[query](manual.html#queries):
|
|
||||||
|
#### Automated postings
|
||||||
|
|
||||||
|
Automated postings (enabled by `--auto`) are postings added
|
||||||
|
automatically by rule to certain transactions. An automated posting rule
|
||||||
|
looks like a transaction where the first line is an equal sign (`=`)
|
||||||
|
followed by a [query](manual.html#queries) (mnemonic: `=` tests for
|
||||||
|
matching transactions, and also looks like posting lines):
|
||||||
|
|
||||||
``` {.journal}
|
``` {.journal}
|
||||||
= expenses:gifts
|
= expenses:gifts
|
||||||
@ -4165,8 +4203,9 @@ the matched transaction's first posting, multiplied by N". They can also
|
|||||||
be ordinary fixed amounts. Fixed amounts with no commodity symbol will
|
be ordinary fixed amounts. Fixed amounts with no commodity symbol will
|
||||||
be given the same commodity as the matched transaction's first posting.
|
be given the same commodity as the matched transaction's first posting.
|
||||||
|
|
||||||
This example adds a corresponding (unbalanced) budget posting to every
|
This example adds a corresponding ([unbalanced](#virtual-postings))
|
||||||
transaction involving the `expenses:gifts` account:
|
budget posting to every transaction involving the `expenses:gifts`
|
||||||
|
account:
|
||||||
|
|
||||||
``` {.journal}
|
``` {.journal}
|
||||||
= expenses:gifts
|
= expenses:gifts
|
||||||
@ -4181,10 +4220,14 @@ transaction involving the `expenses:gifts` account:
|
|||||||
$ hledger print --auto
|
$ hledger print --auto
|
||||||
2017/12/14
|
2017/12/14
|
||||||
expenses:gifts $20
|
expenses:gifts $20
|
||||||
assets
|
|
||||||
(budget:gifts) $-20
|
(budget:gifts) $-20
|
||||||
|
assets
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Like postings recorded by hand, automated postings participate in
|
||||||
|
[transaction balancing, missing amount inference](#postings) and
|
||||||
|
[balance assertions](#balance-assertions).
|
||||||
|
|
||||||
### EDITOR SUPPORT
|
### EDITOR SUPPORT
|
||||||
|
|
||||||
Add-on modes exist for various text editors, to make working with
|
Add-on modes exist for various text editors, to make working with
|
||||||
@ -4225,7 +4268,7 @@ https://twitter.com/LedgerTips/status/501767602067472384
|
|||||||
|
|
||||||
## csv format
|
## csv format
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
### NAME
|
### NAME
|
||||||
|
|
||||||
@ -4498,7 +4541,7 @@ rules file will be used for all the CSV files being read.
|
|||||||
|
|
||||||
## timeclock format
|
## timeclock format
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
### NAME
|
### NAME
|
||||||
|
|
||||||
@ -4567,7 +4610,7 @@ To generate time logs, ie to clock in and clock out, you could:
|
|||||||
|
|
||||||
## timedot format
|
## timedot format
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
### NAME
|
### NAME
|
||||||
|
|
||||||
@ -4661,7 +4704,7 @@ Balance changes in 2016/02/01-2016/02/03:
|
|||||||
```
|
```
|
||||||
|
|
||||||
I prefer to use period for separating account components. We can make
|
I prefer to use period for separating account components. We can make
|
||||||
this work with an [account alias](/journal.html#account-aliases):
|
this work with an [account alias](/journal.html#rewriting-accounts):
|
||||||
|
|
||||||
``` {.timedot}
|
``` {.timedot}
|
||||||
2016/2/4
|
2016/2/4
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
# timeclock format
|
# timeclock format
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
# timedot format
|
# timedot format
|
||||||
|
|
||||||
This doc is for version **1.9 (dev)**. []{.docversions}
|
This doc is for version **1.9.1**. []{.docversions}
|
||||||
|
|
||||||
\$toc\$
|
\$toc\$
|
||||||
|
|
||||||
@ -96,7 +96,7 @@ Balance changes in 2016/02/01-2016/02/03:
|
|||||||
```
|
```
|
||||||
|
|
||||||
I prefer to use period for separating account components. We can make
|
I prefer to use period for separating account components. We can make
|
||||||
this work with an [account alias](/journal.html#account-aliases):
|
this work with an [account alias](/journal.html#rewriting-accounts):
|
||||||
|
|
||||||
``` {.timedot}
|
``` {.timedot}
|
||||||
2016/2/4
|
2016/2/4
|
||||||
|
Loading…
Reference in New Issue
Block a user