simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-12-26 11:52:43 +03:00
Code Issues Projects Releases Wiki Activity

regen manuals

Browse Source
This commit is contained in:
Simon Michael 2018-04-29 18:04:59 -07:00
parent 59c804dac4
commit 290ea1891a
6 changed files with 1039 additions and 1018 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

398
hledger-lib/hledger_journal.5
View File

@ -758,11 +758,6 @@ Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash
(Star comments cause org\-mode nodes to be ignored, allowing emacs users
to fold and navigate their journals with org\-mode or orgstruct\-mode.)
.PP
Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[]
directives is a (multi\-line) comment.
If there is no \f[C]end\ comment\f[], the comment extends to the end of
the file.
.PP
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the
postings).
@ -795,6 +790,9 @@ end\ comment
;\ a\ file\ comment\ (because\ not\ indented)
\f[]
.fi
.PP
You can also comment larger regions of a file using \f[C]comment\f[] and
\f[C]end\ comment\f[] directives.
.SS Tags
.PP
Tags are a way to add extra labels or labelled data to postings and
@ -855,7 +853,173 @@ For example, the following transaction has three tags (\f[C]A\f[],
Tags are like Ledger's metadata feature, except hledger's tag values are
simple strings.
.SS Directives
.SS Account aliases
.SS Comment blocks
.PP
A line containing just \f[C]comment\f[] starts a commented region of the
file, and a line containing just \f[C]end\ comment\f[] (or the end of
the current file) ends it.
See also comments.
.SS Including other files
.PP
You can pull in the content of additional files by writing an include
directive, like this:
.IP
.nf
\f[C]
include\ path/to/file.journal
\f[]
.fi
.PP
If the path does not begin with a slash, it is relative to the current
file.
Glob patterns (\f[C]*\f[]) are not currently supported.
.PP
The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files.
.SS Default year
.PP
You can set a default year to be used for subsequent dates which don't
specify a year.
This is a line beginning with \f[C]Y\f[] followed by the year.
Eg:
.IP
.nf
\f[C]
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
\f[]
.fi
.SS Declaring commodities
.PP
The \f[C]commodity\f[] 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:
.IP
.nf
\f[C]
;\ 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
\f[]
.fi
.PP
or on multiple lines, using the \[lq]format\[rq] subdirective.
In this case the commodity symbol appears twice and should be the same
in both places:
.IP
.nf
\f[C]
;\ 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
\f[]
.fi
.PP
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).
.SS Default commodity
.PP
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.
.IP
.nf
\f[C]
#\ 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
\f[]
.fi
.PP
As with the \f[C]commodity\f[] directive, the amount must always be
written with a decimal point.
.SS Declaring accounts
.PP
The \f[C]account\f[] directive predeclares account names.
The simplest form is \f[C]account\ ACCTNAME\f[], eg:
.IP
.nf
\f[C]
account\ assets:bank:checking
\f[]
.fi
.PP
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger\-iadd, hledger\-web, and ledger\-mode.
.PD 0
.P
.PD
In future it will also help detect misspelled accounts.
.PP
Account names can be followed by a numeric account code:
.IP
.nf
\f[C]
account\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1000
account\ assets:bank:checking\ \ \ \ 1110
account\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ 2000
account\ revenues\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4000
account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000
\f[]
.fi
.PP
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 and the example above.
In future, we might use this to recognize account types.
.PP
An account directive can also have indented subdirectives following it,
which are currently ignored.
Here is the full syntax:
.IP
.nf
\f[C]
;\ account\ ACCTNAME\ \ [OPTIONALCODE]
;\ \ \ [OPTIONALSUBDIRECTIVES]
account\ assets:bank:checking\ \ \ 1110
\ \ a\ comment
\ \ some\-tag:12345
\f[]
.fi
.SS Rewriting accounts
.PP
You can define aliases which rewrite your account names (after reading
the journal, before generating reports).
@ -871,7 +1035,7 @@ combining two accounts into one
.IP \[bu] 2
customising reports
.PP
See also Cookbook: rewrite account names.
See also Cookbook: Rewrite account names.
.SS Basic aliases
.PP
To set an account alias, use the \f[C]alias\f[] directive in your
@ -946,7 +1110,7 @@ alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
.IP "2." 3
alias options, in the order they appear on the command line
.SS end aliases
.SS \f[C]end\ aliases\f[]
.PP
You can clear (forget) all currently defined aliases with the
\f[C]end\ aliases\f[] directive:
@ -956,60 +1120,7 @@ You can clear (forget) all currently defined aliases with the
end\ aliases
\f[]
.fi
.SS account directive
.PP
The \f[C]account\f[] directive predeclares account names.
The simplest form is \f[C]account\ ACCTNAME\f[], eg:
.IP
.nf
\f[C]
account\ assets:bank:checking
\f[]
.fi
.PP
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger\-iadd, hledger\-web, and ledger\-mode.
.PD 0
.P
.PD
In future it will also help detect misspelled accounts.
.PP
Account names can be followed by a numeric account code:
.IP
.nf
\f[C]
account\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1000
account\ assets:bank:checking\ \ \ \ 1110
account\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ 2000
account\ revenues\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4000
account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000
\f[]
.fi
.PP
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 and the example above.
In future, we might use this to recognize account types.
.PP
An account directive can also have indented subdirectives following it,
which are currently ignored.
Here is the full syntax:
.IP
.nf
\f[C]
;\ account\ ACCTNAME\ \ [OPTIONALCODE]
;\ \ \ [OPTIONALSUBDIRECTIVES]
account\ assets:bank:checking\ \ \ 1110
\ \ a\ comment
\ \ some\-tag:12345
\f[]
.fi
.SS apply account directive
.SS Default parent account
.PP
You can specify a parent account which will be prepended to all accounts
within a section of the journal.
@ -1054,125 +1165,13 @@ include\ personal.journal
.PP
Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings
were also supported.
.SS Multi\-line comments
.SS Periodic transactions
.PP
A line containing just \f[C]comment\f[] starts a multi\-line comment,
and a line containing just \f[C]end\ comment\f[] ends it.
See comments.
.SS commodity directive
.PP
The \f[C]commodity\f[] 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:
.IP
.nf
\f[C]
;\ 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
\f[]
.fi
.PP
or on multiple lines, using the \[lq]format\[rq] subdirective.
In this case the commodity symbol appears twice and should be the same
in both places:
.IP
.nf
\f[C]
;\ 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
\f[]
.fi
.PP
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).
.SS Default commodity
.PP
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.
.IP
.nf
\f[C]
#\ 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
\f[]
.fi
.PP
As with the \f[C]commodity\f[] directive, the amount must always be
written with a decimal point.
.SS Default year
.PP
You can set a default year to be used for subsequent dates which don't
specify a year.
This is a line beginning with \f[C]Y\f[] followed by the year.
Eg:
.IP
.nf
\f[C]
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
\f[]
.fi
.SS Including other files
.PP
You can pull in the content of additional journal files by writing an
include directive, like this:
.IP
.nf
\f[C]
include\ path/to/file.journal
\f[]
.fi
.PP
If the path does not begin with a slash, it is relative to the current
file.
Glob patterns (\f[C]*\f[]) are not currently supported.
.PP
The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files.
.SH Periodic transactions
.PP
Periodic transactions are a kind of rule with a dual purpose: they can
specify recurring future transactions (with \f[C]\-\-forecast\f[]), or
budget goals (with \f[C]\-\-budget\f[]).
They look a bit like a transaction, except the first line is a tilde
(\f[C]~\f[]) followed by a period expression:
Periodic transaction rules (enabled by \f[C]\-\-forecast\f[] or
\f[C]\-\-budget\f[]) describe recurring transactions.
They look like a transaction where the first line is a tilde
(\f[C]~\f[]) followed by a period expression (mnemonic: \f[C]~\f[] is
like a recurring sine wave):
.IP
.nf
\f[C]
@ -1182,25 +1181,34 @@ They look a bit like a transaction, except the first line is a tilde
\f[]
.fi
.PP
Periodic transactions have a dual purpose:
.IP \[bu] 2
With \f[C]\-\-forecast\f[], each periodic transaction rule generates
recurring \[lq]forecast\[rq] 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).
.PP
With \f[C]balance\ \-\-budget\f[], each periodic transaction declares
recurring budget goals for the specified accounts.
future transactions, recurring at the specified interval, which can be
seen in reports.
Forecast transactions begin the day after the latest recorded journal
transaction (or today, if there are no transactions) and end 6 months
from today (or at the report end date, if specified).
.IP \[bu] 2
With \f[C]\-\-budget\f[] (supported by the balance command), each
periodic transaction rule declares recurring budget goals for the
specified accounts, which can be seen in budget reports.
Eg the example above declares the goal of receiving $400 from
\f[C]income:acme\ inc\f[] (and also, depositing $400 into
\f[C]assets:bank:checking\f[]) every week.
.PP
For more details, see: balance: Budgeting and Budgeting and Forecasting.
.SH Automated postings
(Actually, you can generate one\-off transactions too, by writing a
period expression with no report interval.)
.PP
Automated postings are postings added automatically by rule to certain
transactions (with \f[C]\-\-auto\f[]).
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
.SS Automated postings
.PP
Automated postings (enabled by \f[C]\-\-auto\f[]) 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 (\f[C]=\f[]) followed by a query:
is an equal sign (\f[C]=\f[]) followed by a query (mnemonic: \f[C]=\f[]
tests for matching transactions, and also looks like posting lines):
.IP
.nf
\f[C]
@ -1240,10 +1248,8 @@ $\ hledger\ print\ \-\-auto
\f[]
.fi
.PP
Automated postings would not be distinguishable from equivalent postings
written by hand.
In particular, they would affect [amount inference|#postings] and
[balance assertion|#balance\-assertions] checks in the usual way.
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.
.SH EDITOR SUPPORT
.PP
Add\-on modes exist for various text editors, to make working with

652
hledger-lib/hledger_journal.info
View File

@ -57,12 +57,10 @@ assisted by the helper modes for emacs or vim.
* Menu:
* FILE FORMAT::
* Periodic transactions::
* Automated postings::
* EDITOR SUPPORT::

File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, Prev: Top, Up: Top
File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: Top, Up: Top
1 FILE FORMAT
*************
@ -83,6 +81,8 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, P
* Comments::
* Tags::
* Directives::
* Periodic transactions::
* Automated postings::

File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT
@ -713,10 +713,6 @@ star ('*') are comments, and will be ignored. (Star comments cause
org-mode nodes to be ignored, allowing emacs users to fold and navigate
their journals with org-mode or orgstruct-mode.)
Also, anything between 'comment' and 'end comment' directives 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
description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual posting
@ -744,6 +740,9 @@ end comment
; another comment line for posting 2
; a file comment (because not indented)
You can also comment larger regions of a file using 'comment' and
'end comment' directives.

File: hledger_journal.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT
@ -788,128 +787,142 @@ example, the following transaction has three tags ('A', 'TAG2',
are simple strings.

File: hledger_journal.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Tags, Up: FILE FORMAT
1.14 Directives
===============
* Menu:
* Account aliases::
* account directive::
* apply account directive::
* Multi-line comments::
* commodity directive::
* Default commodity::
* Default year::
* Comment blocks::
* Including other files::
* Default year::
* Declaring commodities::
* Default commodity::
* Declaring accounts::
* Rewriting accounts::
* Default parent account::

File: hledger_journal.info, Node: Account aliases, Next: account directive, Up: Directives
File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives
1.14.1 Account aliases
----------------------
1.14.1 Comment blocks
---------------------
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
* expanding shorthand account names to their full form, allowing
easier data entry and a less verbose journal
* adapting old journals to your current chart of accounts
* experimenting with new account organisations, like a new hierarchy
or combining two accounts into one
* customising reports
See also Cookbook: rewrite account names.
* Menu:
* Basic aliases::
* Regex aliases::
* Multiple aliases::
* end aliases::
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.

File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases
File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives
1.14.1.1 Basic aliases
......................
1.14.2 Including other files
----------------------------
To set an account alias, use the 'alias' directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
You can pull in the content of additional files by writing an include
directive, like this:
alias OLD = NEW
include path/to/file.journal
Or, you can use the '--alias 'OLD=NEW'' option on the command line.
This affects all entries. It's useful for trying out aliases
interactively.
If the path does not begin with a slash, it is relative to the
current file. Glob patterns ('*') are not currently supported.
OLD and NEW are full account names. hledger will replace any
occurrence of the old account name with the new one. Subaccounts are
also affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
The 'include' directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.

File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases
File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives
1.14.1.2 Regex aliases
......................
1.14.3 Default year
-------------------
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
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:
alias /REGEX/ = REPLACEMENT
Y2009 ; set default year to 2009
or '--alias '/REGEX/=REPLACEMENT''.
12/15 ; equivalent to 2009/12/15
expenses 1
assets
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by
REPLACEMENT. If REGEX contains parenthesised match groups, these can be
referenced by the usual numeric backreferences in REPLACEMENT. Eg:
Y2010 ; change default year to 2010
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
2009/1/30 ; specifies the year, not affected
expenses 1
assets
Also note that REPLACEMENT continues to the end of line (or on
command line, to end of option argument), so it can contain trailing
whitespace.
1/31 ; equivalent to 2010/1/31
expenses 1
assets

File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases
File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives
1.14.1.3 Multiple aliases
.........................
1.14.4 Declaring commodities
----------------------------
You can define as many aliases as you like using directives or
command-line options. Aliases are recursive - each alias sees the
result of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the
following order:
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:
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
; 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:
; 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).

File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases
File: hledger_journal.info, Node: Default commodity, Next: Declaring accounts, Prev: Declaring commodities, Up: Directives
1.14.1.4 end aliases
....................
You can clear (forget) all currently defined aliases with the 'end
aliases' directive:
end aliases

File: hledger_journal.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives
1.14.2 account directive
1.14.5 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.
# 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.

File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Default commodity, Up: Directives
1.14.6 Declaring accounts
-------------------------
The 'account' directive predeclares account names. The simplest form is
'account ACCTNAME', eg:
@ -947,10 +960,110 @@ account assets:bank:checking 1110
some-tag:12345

File: hledger_journal.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives
File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives
1.14.3 apply account directive
------------------------------
1.14.7 Rewriting accounts
-------------------------
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
* expanding shorthand account names to their full form, allowing
easier data entry and a less verbose journal
* adapting old journals to your current chart of accounts
* experimenting with new account organisations, like a new hierarchy
or combining two accounts into one
* customising reports
See also Cookbook: Rewrite account names.
* Menu:
* Basic aliases::
* Regex aliases::
* Multiple aliases::
* end aliases::

File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts
1.14.7.1 Basic aliases
......................
To set an account alias, use the 'alias' directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
Or, you can use the '--alias 'OLD=NEW'' option on the command line.
This affects all entries. It's useful for trying out aliases
interactively.
OLD and NEW are full account names. hledger will replace any
occurrence of the old account name with the new one. Subaccounts are
also affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"

File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts
1.14.7.2 Regex aliases
......................
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or '--alias '/REGEX/=REPLACEMENT''.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by
REPLACEMENT. If REGEX contains parenthesised match groups, these can be
referenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on
command line, to end of option argument), so it can contain trailing
whitespace.

File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
1.14.7.3 Multiple aliases
.........................
You can define as many aliases as you like using directives or
command-line options. Aliases are recursive - each alias sees the
result of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the
following order:
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line

File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts
1.14.7.4 'end aliases'
......................
You can clear (forget) all currently defined aliases with the 'end
aliases' directive:
end aliases

File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives
1.14.8 Default parent account
-----------------------------
You can specify a parent account which will be prepended to all accounts
within a section of the journal. Use the 'apply account' and 'end apply
@ -983,157 +1096,52 @@ include personal.journal
supported.

File: hledger_journal.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: Directives, Up: FILE FORMAT
1.14.4 Multi-line comments
--------------------------
1.15 Periodic transactions
==========================
A line containing just 'comment' starts a multi-line comment, and a line
containing just 'end comment' ends it. See comments.

File: hledger_journal.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
1.14.5 commodity directive
--------------------------
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:
; 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:
; 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).

File: hledger_journal.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
1.14.6 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.
# 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.

File: hledger_journal.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
1.14.7 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:
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

File: hledger_journal.info, Node: Including other files, Prev: Default year, Up: Directives
1.14.8 Including other files
----------------------------
You can pull in the content of additional journal files by writing an
include directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the
current file. 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.

File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: FILE FORMAT, Up: Top
2 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 expression:
Periodic transaction rules (enabled by '--forecast' or '--budget')
describe recurring transactions. They look like a transaction where the
first line is a tilde ('~') followed by a period expression (mnemonic:
'~' is like a recurring sine wave):
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
With '--forecast', each periodic transaction rule generates recurring
"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).
Periodic transactions have a dual purpose:
With 'balance --budget', each periodic transaction declares recurring
budget goals for the specified accounts. Eg the example above declares
the goal of receiving $400 from 'income:acme inc' (and also, depositing
$400 into 'assets:bank:checking') every week.
* With '--forecast', each periodic transaction rule generates future
transactions, recurring at the specified interval, which can be
seen in reports. Forecast transactions begin the day after the
latest 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 and Budgeting and
Forecasting.
* With '--budget' (supported by the balance command), each periodic
transaction rule declares recurring budget goals for the specified
accounts, which can be seen in budget reports. Eg the example
above declares the goal of receiving $400 from 'income:acme inc'
(and also, depositing $400 into 'assets:bank:checking') every week.
(Actually, you can generate one-off transactions too, by writing a
period expression with no report interval.)
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.

File: hledger_journal.info, Node: Automated postings, Next: EDITOR SUPPORT, Prev: Periodic transactions, Up: Top
File: hledger_journal.info, Node: Automated postings, Prev: Periodic transactions, Up: FILE FORMAT
3 Automated postings
********************
1.16 Automated postings
=======================
Automated postings are postings added automatically by rule to certain
transactions (with '--auto'). An automated posting rule looks like a
transaction where the first line is an equal sign ('=') followed by a
query:
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 (mnemonic: '=' tests for matching
transactions, and also looks like posting lines):
= expenses:gifts
budget:gifts *-1
@ -1161,15 +1169,13 @@ $ hledger print --auto
(budget:gifts) $-20
assets
Automated postings would not be distinguishable from equivalent
postings written by hand. In particular, they would affect [amount
inference|#postings] and [balance assertion|#balance-assertions] checks
in the usual way.
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.

File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: Automated postings, Up: Top
File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
4 EDITOR SUPPORT
2 EDITOR SUPPORT
****************
Add-on modes exist for various text editors, to make working with
@ -1196,89 +1202,89 @@ Code

Tag Table:
Node: Top76
Node: FILE FORMAT2425
Ref: #file-format2556
Node: Transactions2779
Ref: #transactions2900
Node: Postings3584
Ref: #postings3711
Node: Dates4706
Ref: #dates4821
Node: Simple dates4886
Ref: #simple-dates5012
Node: Secondary dates5378
Ref: #secondary-dates5532
Node: Posting dates7095
Ref: #posting-dates7224
Node: Status8598
Ref: #status8718
Node: Description10426
Ref: #description10564
Node: Payee and note10883
Ref: #payee-and-note10997
Node: Account names11239
Ref: #account-names11382
Node: Amounts11869
Ref: #amounts12005
Node: Virtual Postings15020
Ref: #virtual-postings15179
Node: Balance Assertions16399
Ref: #balance-assertions16574
Node: Assertions and ordering17470
Ref: #assertions-and-ordering17656
Node: Assertions and included files18356
Ref: #assertions-and-included-files18597
Node: Assertions and multiple -f options18930
Ref: #assertions-and-multiple--f-options19184
Node: Assertions and commodities19316
Ref: #assertions-and-commodities19551
Node: Assertions and subaccounts20247
Ref: #assertions-and-subaccounts20479
Node: Assertions and virtual postings21000
Ref: #assertions-and-virtual-postings21207
Node: Balance Assignments21349
Ref: #balance-assignments21518
Node: Prices22638
Ref: #prices22771
Node: Transaction prices22822
Ref: #transaction-prices22967
Node: Market prices25123
Ref: #market-prices25258
Node: Comments26218
Ref: #comments26340
Node: Tags27582
Ref: #tags27700
Node: Directives29102
Ref: #directives29215
Node: Account aliases29408
Ref: #account-aliases29552
Node: Basic aliases30156
Ref: #basic-aliases30299
Node: Regex aliases30989
Ref: #regex-aliases31157
Node: Multiple aliases31875
Ref: #multiple-aliases32047
Node: end aliases32545
Ref: #end-aliases32685
Node: account directive32786
Ref: #account-directive32966
Node: apply account directive34313
Ref: #apply-account-directive34509
Node: Multi-line comments35168
Ref: #multi-line-comments35358
Node: commodity directive35486
Ref: #commodity-directive35670
Node: Default commodity36897
Ref: #default-commodity37070
Node: Default year37702
Ref: #default-year37867
Node: Including other files38290
Ref: #including-other-files38447
Node: Periodic transactions38844
Ref: #periodic-transactions39010
Node: Automated postings39999
Ref: #automated-postings40162
Node: EDITOR SUPPORT41290
Ref: #editor-support41415
Node: FILE FORMAT2376
Ref: #file-format2500
Node: Transactions2772
Ref: #transactions2893
Node: Postings3577
Ref: #postings3704
Node: Dates4699
Ref: #dates4814
Node: Simple dates4879
Ref: #simple-dates5005
Node: Secondary dates5371
Ref: #secondary-dates5525
Node: Posting dates7088
Ref: #posting-dates7217
Node: Status8591
Ref: #status8711
Node: Description10419
Ref: #description10557
Node: Payee and note10876
Ref: #payee-and-note10990
Node: Account names11232
Ref: #account-names11375
Node: Amounts11862
Ref: #amounts11998
Node: Virtual Postings15013
Ref: #virtual-postings15172
Node: Balance Assertions16392
Ref: #balance-assertions16567
Node: Assertions and ordering17463
Ref: #assertions-and-ordering17649
Node: Assertions and included files18349
Ref: #assertions-and-included-files18590
Node: Assertions and multiple -f options18923
Ref: #assertions-and-multiple--f-options19177
Node: Assertions and commodities19309
Ref: #assertions-and-commodities19544
Node: Assertions and subaccounts20240
Ref: #assertions-and-subaccounts20472
Node: Assertions and virtual postings20993
Ref: #assertions-and-virtual-postings21200
Node: Balance Assignments21342
Ref: #balance-assignments21511
Node: Prices22631
Ref: #prices22764
Node: Transaction prices22815
Ref: #transaction-prices22960
Node: Market prices25116
Ref: #market-prices25251
Node: Comments26211
Ref: #comments26333
Node: Tags27503
Ref: #tags27621
Node: Directives29023
Ref: #directives29166
Node: Comment blocks29359
Ref: #comment-blocks29504
Node: Including other files29680
Ref: #including-other-files29860
Node: Default year30249
Ref: #default-year30418
Node: Declaring commodities30841
Ref: #declaring-commodities31024
Node: Default commodity32251
Ref: #default-commodity32432
Node: Declaring accounts33064
Ref: #declaring-accounts33244
Node: Rewriting accounts34591
Ref: #rewriting-accounts34776
Node: Basic aliases35380
Ref: #basic-aliases35526
Node: Regex aliases36216
Ref: #regex-aliases36387
Node: Multiple aliases37105
Ref: #multiple-aliases37280
Node: end aliases37778
Ref: #end-aliases37925
Node: Default parent account38026
Ref: #default-parent-account38192
Node: Periodic transactions38851
Ref: #periodic-transactions39030
Node: Automated postings40329
Ref: #automated-postings40483
Node: EDITOR SUPPORT41616
Ref: #editor-support41734

End Tag Table

486
hledger-lib/hledger_journal.txt
View File

@ -553,10 +553,6 @@ FILE FORMAT
nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
Also, anything between comment and end comment directives 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
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
@ -584,21 +580,24 @@ FILE FORMAT
; another comment line for posting 2
; a file comment (because not indented)
You can also comment larger regions of a file using comment and
end comment directives.
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
transactions, which you can then search or pivot on.
A simple tag is a word (which may contain hyphens) followed by a full
A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
Tags can have a value, which is the text after the colon, up to the
Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or new-
Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
@ -612,213 +611,35 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Directives
Account aliases
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
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.
o expanding shorthand account names to their full form, allowing easier
data entry and a less verbose journal
Including other files
You can pull in the content of additional files by writing an include
directive, like this:
o adapting old journals to your current chart of accounts
include path/to/file.journal
o experimenting with new account organisations, like a new hierarchy or
combining two accounts into one
If the path does not begin with a slash, it is relative to the current
file. Glob patterns (*) are not currently supported.
o customising reports
See also Cookbook: rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are full account names. hledger will replace any occur-
rence of the old account name with the new one. Subaccounts are also
affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
space.
Multiple aliases
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol-
lowing order:
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
end aliases
You can clear (forget) all currently defined aliases with the
end aliases directive:
end aliases
account directive
The account directive predeclares account names. The simplest form is
account ACCTNAME, eg:
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:
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. (Oth-
erwise, 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 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:
; 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 within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
2010/1/1
food $10
cash
end apply account
which is equivalent to:
2010/01/01
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
include biz.journal
end apply account
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
Multi-line comments
A line containing just comment starts a multi-line comment, and a line
containing just end comment ends it. See comments.
commodity directive
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:
; 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:
; 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 for-
mat 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.
# 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.
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
@ -841,47 +662,234 @@ FILE FORMAT
expenses 1
assets
Including other files
You can pull in the content of additional journal files by writing an
include directive, like this:
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:
include path/to/file.journal
; commodity EXAMPLEAMOUNT
If the path does not begin with a slash, it is relative to the current
file. Glob patterns (*) are not currently supported.
; 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
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
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 expression:
; 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 for-
mat 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.
# 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:
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:
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. (Oth-
erwise, 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 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:
; 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
the journal, before generating reports). hledger's account aliases can
be useful for:
o expanding shorthand account names to their full form, allowing easier
data entry and a less verbose journal
o adapting old journals to your current chart of accounts
o experimenting with new account organisations, like a new hierarchy or
combining two accounts into one
o customising reports
See also Cookbook: Rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are full account names. hledger will replace any occur-
rence of the old account name with the new one. Subaccounts are also
affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
space.
Multiple aliases
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol-
lowing order:
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
end aliases
You can clear (forget) all currently defined aliases with the
end aliases directive:
end aliases
Default parent account
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
2010/1/1
food $10
cash
end apply account
which is equivalent to:
2010/01/01
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
include biz.journal
end apply account
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
Periodic transactions
Periodic transaction rules (enabled by --forecast or --budget) describe
recurring transactions. They look like a transaction where the first
line is a tilde (~) followed by a period expression (mnemonic: ~ is
like a recurring sine wave):
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
With --forecast, each periodic transaction rule generates recurring
"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).
Periodic transactions have a dual purpose:
With balance --budget, each periodic transaction declares recurring
budget goals for the specified accounts. Eg the example above declares
the goal of receiving $400 from income:acme inc (and also, depositing
$400 into assets:bank:checking) every week.
o With --forecast, each periodic transaction rule generates future
transactions, recurring at the specified interval, which can be seen
in reports. Forecast transactions begin the day after the latest
recorded journal transaction (or today, if there are no transactions)
and end 6 months from today (or at the report end date, if speci-
fied).
For more details, see: balance: Budgeting and Budgeting and Forecast-
ing.
o With --budget (supported by the balance command), each periodic
transaction rule declares recurring budget goals for the specified
accounts, which can be seen in budget reports. 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
Automated postings are postings added automatically by rule to certain
transactions (with --auto). An automated posting rule looks like a
transaction where the first line is an equal sign (=) followed by a
query:
(Actually, you can generate one-off transactions too, by writing a
period expression with no report interval.)
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
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 (mnemonic: = tests for matching transactions, and also looks like
posting lines):
= expenses:gifts
budget:gifts *-1
@ -909,18 +917,16 @@ Automated postings
(budget:gifts) $-20
assets
Automated postings would not be distinguishable from equivalent post-
ings written by hand. In particular, they would affect [amount infer-
ence|#postings] and [balance assertion|#balance-assertions] checks in
the usual way.
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger
These were written with Ledger in mind, but also work with hledger
files:
@ -939,7 +945,7 @@ EDITOR SUPPORT
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -953,7 +959,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

3
hledger/hledger.1
View File

@ -1607,7 +1607,8 @@ Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount.
\[lq]Boring\[rq] accounts, which contain a single interesting subaccount
and no balance of their own, are elided into the following line for more
compact output.
Use \f[C]\-\-no\-elide\f[] to prevent this.
(Eg above, the \[lq]liabilities\[rq] account.) Use
\f[C]\-\-no\-elide\f[] to prevent this.
.PP
Account balances are \[lq]inclusive\[rq] \- they include the balances of
any subaccounts.

161
hledger/hledger.info
View File

@ -1212,7 +1212,8 @@ sorted by account code if any, then by account name. Or with
"Boring" accounts, which contain a single interesting subaccount and
no balance of their own, are elided into the following line for more
compact output. Use '--no-elide' to prevent this.
compact output. (Eg above, the "liabilities" account.) Use
'--no-elide' to prevent this.
Account balances are "inclusive" - they include the balances of any
subaccounts.
@ -2485,84 +2486,84 @@ Node: balance35737
Ref: #balance35848
Node: Classic balance report38931
Ref: #classic-balance-report39104
Node: Customising the classic balance report40433
Ref: #customising-the-classic-balance-report40661
Node: Colour support42735
Ref: #colour-support42902
Node: Flat mode43075
Ref: #flat-mode43223
Node: Depth limited balance reports43636
Ref: #depth-limited-balance-reports43836
Node: Multicolumn balance report44292
Ref: #multicolumn-balance-report44490
Node: Budget report49670
Ref: #budget-report49813
Ref: #output-format-152847
Node: balancesheet52925
Ref: #balancesheet53061
Node: balancesheetequity55372
Ref: #balancesheetequity55521
Node: cashflow56058
Ref: #cashflow56186
Node: check-dates58309
Ref: #check-dates58436
Node: check-dupes58553
Ref: #check-dupes58677
Node: close58814
Ref: #close58921
Node: help59251
Ref: #help59351
Node: import60425
Ref: #import60539
Node: incomestatement61269
Ref: #incomestatement61403
Node: prices63807
Ref: #prices63922
Node: print63965
Ref: #print64075
Node: print-unique68969
Ref: #print-unique69095
Node: register69163
Ref: #register69290
Node: Custom register output73791
Ref: #custom-register-output73920
Node: register-match75150
Ref: #register-match75284
Node: rewrite75467
Ref: #rewrite75584
Node: stats75653
Ref: #stats75756
Node: tags76626
Ref: #tags76724
Node: test76960
Ref: #test77044
Node: ADD-ON COMMANDS77412
Ref: #add-on-commands77522
Node: Official add-ons78809
Ref: #official-add-ons78949
Node: api79036
Ref: #api79125
Node: ui79177
Ref: #ui79276
Node: web79334
Ref: #web79423
Node: Third party add-ons79469
Ref: #third-party-add-ons79644
Node: diff79779
Ref: #diff79876
Node: iadd79975
Ref: #iadd80089
Node: interest80172
Ref: #interest80293
Node: irr80388
Ref: #irr80486
Node: Experimental add-ons80564
Ref: #experimental-add-ons80716
Node: autosync80996
Ref: #autosync81107
Node: chart81346
Ref: #chart81465
Node: check81536
Ref: #check81638
Node: Customising the classic balance report40473
Ref: #customising-the-classic-balance-report40701
Node: Colour support42775
Ref: #colour-support42942
Node: Flat mode43115
Ref: #flat-mode43263
Node: Depth limited balance reports43676
Ref: #depth-limited-balance-reports43876
Node: Multicolumn balance report44332
Ref: #multicolumn-balance-report44530
Node: Budget report49710
Ref: #budget-report49853
Ref: #output-format-152887
Node: balancesheet52965
Ref: #balancesheet53101
Node: balancesheetequity55412
Ref: #balancesheetequity55561
Node: cashflow56098
Ref: #cashflow56226
Node: check-dates58349
Ref: #check-dates58476
Node: check-dupes58593
Ref: #check-dupes58717
Node: close58854
Ref: #close58961
Node: help59291
Ref: #help59391
Node: import60465
Ref: #import60579
Node: incomestatement61309
Ref: #incomestatement61443
Node: prices63847
Ref: #prices63962
Node: print64005
Ref: #print64115
Node: print-unique69009
Ref: #print-unique69135
Node: register69203
Ref: #register69330
Node: Custom register output73831
Ref: #custom-register-output73960
Node: register-match75190
Ref: #register-match75324
Node: rewrite75507
Ref: #rewrite75624
Node: stats75693
Ref: #stats75796
Node: tags76666
Ref: #tags76764
Node: test77000
Ref: #test77084
Node: ADD-ON COMMANDS77452
Ref: #add-on-commands77562
Node: Official add-ons78849
Ref: #official-add-ons78989
Node: api79076
Ref: #api79165
Node: ui79217
Ref: #ui79316
Node: web79374
Ref: #web79463
Node: Third party add-ons79509
Ref: #third-party-add-ons79684
Node: diff79819
Ref: #diff79916
Node: iadd80015
Ref: #iadd80129
Node: interest80212
Ref: #interest80333
Node: irr80428
Ref: #irr80526
Node: Experimental add-ons80604
Ref: #experimental-add-ons80756
Node: autosync81036
Ref: #autosync81147
Node: chart81386
Ref: #chart81505
Node: check81576
Ref: #check81678

End Tag Table

357
hledger/hledger.txt
View File

@ -1099,15 +1099,16 @@ COMMANDS
"Boring" accounts, which contain a single interesting subaccount and no
balance of their own, are elided into the following line for more com-
pact output. Use --no-elide to prevent this.
pact output. (Eg above, the "liabilities" account.) Use --no-elide to
prevent this.
Account balances are "inclusive" - they include the balances of any
Account balances are "inclusive" - they include the balances of any
subaccounts.
Accounts which have zero balance (and no non-zero subaccounts) are
Accounts which have zero balance (and no non-zero subaccounts) are
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, eg:
$ hledger balance -p 2008/6 expenses --no-total
@ -1116,7 +1117,7 @@ COMMANDS
$1 supplies
Customising the classic balance report
You can customise the layout of classic balance reports with --for-
You can customise the layout of classic balance reports with --for-
mat FMT:
$ hledger balance --format "%20(account) %12(total)"
@ -1134,7 +1135,7 @@ COMMANDS
0
The FMT format string (plus a newline) specifies the formatting applied
to each account/balance pair. It may contain any suitable text, with
to each account/balance pair. It may contain any suitable text, with
data fields interpolated like so:
%[MIN][.MAX](FIELDNAME)
@ -1145,14 +1146,14 @@ COMMANDS
o FIELDNAME must be enclosed in parentheses, and can be one of:
o depth_spacer - a number of spaces equal to the account's depth, or
o depth_spacer - a number of spaces equal to the account's depth, or
if MIN is specified, MIN * depth spaces.
o account - the account's name
o total - the account's balance/posted total, right justified
Also, FMT can begin with an optional prefix to control how multi-com-
Also, FMT can begin with an optional prefix to control how multi-com-
modity amounts are rendered:
o %_ - render on multiple lines, bottom-aligned (the default)
@ -1161,7 +1162,7 @@ COMMANDS
o %, - render on one line, comma-separated
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
effect, instead %(account) has indentation built in.
Experimentation may be needed to get pleasing results.
@ -1169,14 +1170,14 @@ COMMANDS
o %(total) - the account's total
o %-20.20(account) - the account's name, left justified, padded to 20
o %-20.20(account) - the account's name, left justified, padded to 20
characters and clipped at 20 characters
o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
one line
o %20(total) %2(depth_spacer)%-(account) - the default format for the
o %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report
Colour support
@ -1187,9 +1188,9 @@ COMMANDS
o the output is not being redirected or piped anywhere
Flat mode
To see a flat list instead of the default hierarchical display, use
--flat. In this mode, accounts (unless depth-clipped) show their full
names and "exclusive" balance, excluding any subaccount balances. In
To see a flat list instead of the default hierarchical display, use
--flat. In this mode, accounts (unless depth-clipped) show their full
names and "exclusive" balance, excluding any subaccount balances. In
this mode, you can also use --drop N to omit the first few account name
components.
@ -1198,8 +1199,8 @@ COMMANDS
$1 supplies
Depth limited balance reports
With --depth N or depth:N or just -N, balance reports show accounts
only to the specified numeric depth. This is very useful to summarise
With --depth N or depth:N or just -N, balance reports show accounts
only to the specified numeric depth. This is very useful to summarise
a complex set of accounts and get an overview.
$ hledger balance -N -1
@ -1212,17 +1213,17 @@ COMMANDS
inclusive balances at the depth limit.
Multicolumn balance report
Multicolumn or tabular balance reports are a very useful hledger fea-
ture, and usually the preferred style. They share many of the above
features, but they show the report as a table, with columns represent-
ing time periods. This mode is activated by providing a reporting
Multicolumn or tabular balance reports are a very useful hledger fea-
ture, and usually the preferred style. They share many of the above
features, but they show the report as a table, with columns represent-
ing time periods. This mode is activated by providing a reporting
interval.
There are three types of multicolumn balance report, showing different
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
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:
$ hledger balance --quarterly income expenses -E
@ -1237,8 +1238,8 @@ COMMANDS
-------------------++---------------------------------
|| $-1 $1 0 0
2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
the report start date:
$ hledger balance --quarterly income expenses -E --cumulative
@ -1254,8 +1255,8 @@ COMMANDS
|| $-1 0 0 0
3. With --historical/-H: each column shows the actual historical ending
balance for that period, accumulating the changes across periods,
starting from the actual balance at the report start date. This is
balance for that period, accumulating the changes across periods,
starting from the actual balance at the report start date. This is
useful eg for a multi-period balance sheet, and when you are showing
only the data after a certain start date:
@ -1271,26 +1272,26 @@ COMMANDS
----------------------++-------------------------------------
|| 0 0 0
Multicolumn balance reports display accounts in flat mode by default;
Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass
With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass
the displayed report periods. This is so that the first and last peri-
ods will be "full" and comparable to the others.
The -E/--empty flag does two things in multicolumn balance reports:
first, the report will show all columns within the specified report
period (without -E, leading and trailing columns with all zeroes are
not shown). Second, all accounts which existed at the report start
date will be considered, not just the ones with activity during the
The -E/--empty flag does two things in multicolumn balance reports:
first, the report will show all columns within the specified report
period (without -E, leading and trailing columns with all zeroes are
not shown). Second, all accounts which existed at the report start
date will be considered, not just the ones with activity during the
report period (use -E to include low-activity accounts which would oth-
erwise would be omitted).
The -T/--row-total flag adds an additional column showing the total for
each row.
The -A/--average flag adds a column showing the average value in each
The -A/--average flag adds a column showing the average value in each
row.
Here's an example of all three:
@ -1314,20 +1315,20 @@ COMMANDS
Limitations:
In multicolumn reports the -V/--value flag uses the market price on the
report end date, for all columns (not the price on each column's end
report end date, for all columns (not the price on each column's end
date).
Eliding of boring parent accounts in tree mode, as in the classic bal-
Eliding of boring parent accounts in tree mode, as in the classic bal-
ance 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. This is very useful for comparing planned and actual
With --budget, extra columns are displayed showing budget goals for
each account and period, if any. Budget goals are defined by 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.
For example, you can take average monthly expenses in the common
For example, you can take average monthly expenses in the common
expense categories to construct a minimal monthly budget:
;; Budget
@ -1370,7 +1371,7 @@ COMMANDS
----------------------++-------------------------------------------------
|| 0 0
By default, only accounts with budget goals during the report period
By default, only accounts with budget goals during the report period
are shown. --show-unbudgeted shows unbudgeted accounts as well.
Top-level accounts with no budget goals anywhere below them are grouped
under <unbudgeted>.
@ -1391,22 +1392,22 @@ COMMANDS
----------------------++-------------------------------------------------
|| 0 0
Note, the -S/--sort-amount flag is not yet fully supported with --bud-
Note, the -S/--sort-amount flag is not yet fully supported with --bud-
get.
For more examples, see Budgeting and Forecasting.
Output format
The balance command supports output destination and output format
The balance command supports output destination and output format
selection.
balancesheet
This command displays a simple balance sheet, showing historical ending
balances of asset and liability accounts (ignoring any report begin
date). It assumes that these accounts are under a top-level asset or
liability account (case insensitive, plural forms also allowed). Note
this report shows all account balances with normal positive sign (like
conventional financial statements, unlike balance/print/register)
balances of asset and liability accounts (ignoring any report begin
date). It assumes that these accounts are under a top-level asset or
liability account (case insensitive, plural forms also allowed). Note
this report shows all account balances with normal positive sign (like
conventional financial statements, unlike balance/print/register)
(experimental). (bs)
--change
@ -1414,7 +1415,7 @@ COMMANDS
balances
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of historical ending balances
-H --historical
@ -1470,16 +1471,16 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for
report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
balancesheetequity
Just like balancesheet, but also reports Equity (which it assumes is
Just like balancesheet, but also reports Equity (which it assumes is
under a top-level equity account).
Example:
@ -1509,10 +1510,10 @@ COMMANDS
0
cashflow
This command displays a simple cashflow statement, showing changes in
"cash" accounts. It assumes that these accounts are under a top-level
asset account (case insensitive, plural forms also allowed) and do not
contain receivable or A/R in their name. Note this report shows all
This command displays a simple cashflow statement, showing changes in
"cash" accounts. It assumes that these accounts are under a top-level
asset account (case insensitive, plural forms also allowed) and do not
contain receivable or A/R in their name. Note this report shows all
account balances with normal positive sign (like conventional financial
statements, unlike balance/print/register) (experimental). (cf)
@ -1520,7 +1521,7 @@ COMMANDS
show balance change in each period (default)
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@ -1571,38 +1572,38 @@ COMMANDS
$-1
With a reporting interval, multiple columns will be shown, one for each
report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report
report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report
mode with --change/--cumulative/--historical.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
check-dates
Check that transactions are sorted by increasing date. With a query,
Check that transactions are sorted by increasing date. With a query,
only matched transactions' dates are checked.
check-dupes
Report account names having the same leaf but different prefixes. An
Report account names having the same leaf but different prefixes. An
example: http://stefanorodighiero.net/software/hledger-dupes.html
close
Print closing/opening transactions that bring some or all account bal-
ances to zero and back. Can be useful for bringing asset/liability
Print closing/opening transactions that bring some or all account bal-
ances to zero and back. Can be useful for bringing asset/liability
balances across file boundaries, or for closing out income/expenses for
a period. This was formerly called "equity", as in Ledger, and that
a period. This was formerly called "equity", as in Ledger, and that
alias is also accepted. See close -help for more.
help
Show any of the hledger manuals.
The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide
The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide
a full or partial manual name to select one.
hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can
hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can
force a particular viewer with the --info, --man, --pager, --cat flags.
$ hledger help
@ -1626,7 +1627,7 @@ COMMANDS
...
import
Read new transactions added to each FILE since last run, and add them
Read new transactions added to each FILE since last run, and add them
to the main journal file.
--dry-run
@ -1636,28 +1637,28 @@ COMMANDS
each one. So eg to add new transactions from all CSV files to the main
journal, it's just: hledger import *.csv
New transactions are detected in the same way as print -new: by assum-
New transactions are detected in the same way as print -new: by assum-
ing transactions are always added to the input files in increasing date
order, and by saving .latest.FILE state files.
The -dry-run output is in journal format, so you can filter it, eg to
The -dry-run output is in journal format, so you can filter it, eg to
see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
incomestatement
This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements,
This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements,
unlike balance/print/register) (experimental). (is)
--change
show balance change in each period (default)
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@ -1691,8 +1692,8 @@ COMMANDS
--sort-amount
sort by amount instead of account code/name
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.)
$ hledger incomestatement
@ -1717,11 +1718,11 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
prices
@ -1731,7 +1732,7 @@ COMMANDS
Show transactions from the journal. Aliases: p, txns.
-m STR --match=STR
show the transaction whose description is most similar to STR,
show the transaction whose description is most similar to STR,
and is most recent
--new show only newer-dated transactions added in each file since last
@ -1744,7 +1745,7 @@ COMMANDS
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger print
@ -1775,39 +1776,39 @@ COMMANDS
it does not preserve directives or inter-transaction comments
Normally, the journal entry's explicit or implicit amount style is pre-
served. Ie when an amount is omitted in the journal, it will be omit-
ted in the output. You can use the -x/--explicit flag to make all
served. Ie when an amount is omitted in the journal, it will be omit-
ted in the output. You can use the -x/--explicit flag to make all
amounts explicit, which can be useful for troubleshooting or for making
your journal more readable and robust against data entry errors. Note,
-x will cause postings with a multi-commodity amount (these can arise
when a multi-commodity transaction has an implicit amount) will be
split into multiple single-commodity postings, for valid journal out-
-x will cause postings with a multi-commodity amount (these can arise
when a multi-commodity transaction has an implicit amount) will be
split into multiple single-commodity postings, for valid journal out-
put.
With -B/--cost, amounts with transaction prices are converted to cost
With -B/--cost, amounts with transaction prices are converted to cost
using that price. This can be used for troubleshooting.
With -m/--match and a STR argument, print will show at most one trans-
action: the one one whose description is most similar to STR, and is
most recent. STR should contain at least two characters. If there is
With -m/--match and a STR argument, print will show at most one trans-
action: the one one whose description is most similar to STR, and is
most recent. STR should contain at least two characters. If there is
no similar-enough match, no transaction will be shown.
With --new, for each FILE being read, hledger reads (and writes) a spe-
cial state file (.latest.FILE in the same directory), containing the
latest transaction date(s) that were seen last time FILE was read.
When this file is found, only transactions with newer dates (and new
transactions on the latest date) are printed. This is useful for
ignoring already-seen entries in import data, such as downloaded CSV
cial state file (.latest.FILE in the same directory), containing the
latest transaction date(s) that were seen last time FILE was read.
When this file is found, only transactions with newer dates (and new
transactions on the latest date) are printed. This is useful for
ignoring already-seen entries in import data, such as downloaded CSV
files. Eg:
$ hledger -f bank1.csv print --new
# shows transactions added since last print --new on this file
This assumes that transactions added to FILE always have same or
increasing dates, and that transactions on the same day do not get
This assumes that transactions added to FILE always have same or
increasing dates, and that transactions on the same day do not get
reordered. See also the import command.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion. Here's an example of print's CSV output:
$ hledger print -Ocsv
@ -1824,20 +1825,20 @@ COMMANDS
"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
o There is one CSV record per posting, with the parent transaction's
o There is one CSV record per posting, with the parent transaction's
fields repeated.
o The "txnidx" (transaction index) field shows which postings belong to
the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different
the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different
order, etc.)
o The amount is separated into "commodity" (the symbol) and "amount"
o The amount is separated into "commodity" (the symbol) and "amount"
(numeric quantity) fields.
o The numeric amount is repeated in either the "credit" or "debit" col-
umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or
umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or
greater amounts under debit.)
print-unique
@ -1850,7 +1851,7 @@ COMMANDS
show running total from report start date (default)
-H --historical
show historical running total/balance (includes postings before
show historical running total/balance (includes postings before
report start date)
-A --average
@ -1861,18 +1862,18 @@ COMMANDS
show postings' siblings instead
-w N --width=N
set output width (default: terminal width or COLUMNS. -wN,M
set output width (default: terminal width or COLUMNS. -wN,M
sets description width as well)
-O FMT --output-format=FMT
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
The register command displays postings, one per line, and their running
total. This is typically used with a query selecting a particular
total. This is typically used with a query selecting a particular
account, to see that account's activity:
$ hledger register checking
@ -1881,8 +1882,8 @@ COMMANDS
2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
only recent activity, with a historically accurate running balance:
$ hledger register checking -b 2008/6 --historical
@ -1892,23 +1893,23 @@ COMMANDS
The --depth option limits the amount of sub-account detail displayed.
The --average/-A flag shows the running average posting amount instead
The --average/-A flag shows the running average posting amount instead
of the running total (so, the final number displayed is the average for
the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one
the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one
account and one commodity.
The --related/-r flag shows the other postings in the transactions of
The --related/-r flag shows the other postings in the transactions of
the postings which would normally be shown.
With a reporting interval, register shows summary postings, one per
With a reporting interval, register shows summary postings, one per
interval, aggregating the postings to each account:
$ hledger register --monthly income
2008/01 income:salary $-1 $-1
2008/06 income:gifts $-1 $-2
Periods with no activity, and summary postings with a zero amount, are
Periods with no activity, and summary postings with a zero amount, are
not shown by default; use the --empty/-E flag to see them:
$ hledger register --monthly income -E
@ -1925,7 +1926,7 @@ COMMANDS
2008/11 0 $-2
2008/12 0 $-2
Often, you'll want to see just one line per interval. The --depth
Often, you'll want to see just one line per interval. The --depth
option helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h
@ -1933,18 +1934,18 @@ COMMANDS
2008/06 assets $-1 0
2008/12 assets $-1 $-1
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
length and comparable to the others in the report.
Custom register output
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option.
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
description width as part of -width's argument, comma-separated:
--width W,D . Here's a diagram:
@ -1961,12 +1962,12 @@ COMMANDS
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
register-match
Print the one posting whose transaction description is closest to DESC,
in the style of the register command. Helps ledger-autosync detect
in the style of the register command. Helps ledger-autosync detect
already-seen transactions when importing.
rewrite
@ -1976,7 +1977,7 @@ COMMANDS
Show some journal statistics.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger stats
@ -1991,16 +1992,16 @@ COMMANDS
Accounts : 8 (depth 3)
Commodities : 1 ($)
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
for each report period.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
tags
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are
shown. With additional QUERY arguments, only transactions matching the
query are considered.
@ -2010,34 +2011,34 @@ COMMANDS
$ hledger test
Cases: 74 Tried: 74 Errors: 0 Failures: 0
This command runs hledger's built-in unit tests and displays a quick
This command runs hledger's built-in unit tests and displays a quick
report. With a regular expression argument, it selects only tests with
matching names. It's mainly used in development, but it's also nice to
be able to check your hledger executable for smoke at any time.
ADD-ON COMMANDS
hledger also searches for external add-on commands, and will include
hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH
whose name starts with hledger- and ends with a recognised file exten-
whose name starts with hledger- and ends with a recognised file exten-
sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
Add-ons can be invoked like any hledger command, but there are a few
Add-ons can be invoked like any hledger command, but there are a few
things to be aware of. Eg if the hledger-web add-on is installed,
o hledger -h web shows hledger's help, while hledger web -h shows
hledger-web's help.
o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected;
o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000.
o You can always run add-ons directly if preferred:
o You can always run add-ons directly if preferred:
hledger-web --serve --port 9000.
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Here are some hledger add-ons available:
@ -2055,7 +2056,7 @@ ADD-ON COMMANDS
hledger-web provides a simple web interface.
Third party add-ons
These are maintained separately, and usually updated shortly after a
These are maintained separately, and usually updated shortly after a
hledger release.
diff
@ -2063,7 +2064,7 @@ ADD-ON COMMANDS
journal file and another.
iadd
hledger-iadd is a curses-style, more interactive replacement for the
hledger-iadd is a curses-style, more interactive replacement for the
add command.
interest
@ -2071,19 +2072,19 @@ ADD-ON COMMANDS
ing to various schemes.
irr
hledger-irr calculates the internal rate of return of an investment
hledger-irr calculates the internal rate of return of an investment
account.
Experimental add-ons
These are available in source form in the hledger repo's bin/ direc-
These are available in source form in the hledger repo's bin/ direc-
tory; installing them is pretty easy. They may be less mature and doc-
umented than built-in commands. Reading and tweaking these is a good
umented than built-in commands. Reading and tweaking these is a good
way to start making your own!
autosync
hledger-autosync is a symbolic link for easily running ledger-autosync,
if installed. ledger-autosync does deduplicating conversion of OFX
data and some CSV formats, and can also download the data if your bank
if installed. ledger-autosync does deduplicating conversion of OFX
data and some CSV formats, and can also download the data if your bank
offers OFX Direct Connect.
chart
@ -2093,21 +2094,21 @@ ADD-ON COMMANDS
hledger-check.hs checks more powerful account balance assertions.
ENVIRONMENT
COLUMNS The screen width used by the register command. Default: the
COLUMNS The screen width used by the register command. Default: the
full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede addon command options with -- when invoked from
The need to precede addon command options with -- when invoked from
hledger is awkward.
When input data contains non-ascii characters, a suitable system locale
@ -2120,33 +2121,33 @@ BUGS
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
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.
On large data files, hledger is slower and uses more memory than
On large data files, hledger is slower and uses more memory than
Ledger.
TROUBLESHOOTING
Here are some issues you might encounter when you run hledger (and
remember you can also seek help from the IRC channel, mail list or bug
Here are some issues you might encounter when you run hledger (and
remember you can also seek help from the IRC channel, mail list or bug
tracker):
Successfully installed, but "No command `hledger' found"
stack and cabal install binaries into a special directory, which should
be added to your PATH environment variable. Eg on unix-like systems,
be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively.
I set a custom LEDGER_FILE, but hledger is still using the default file
LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may
LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation.
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors
In order to handle non-ascii letters and symbols (like ), hledger needs
an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that sup-
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet).
Here's an example of setting the locale temporarily, on ubuntu
@ -2165,7 +2166,7 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login
If we preferred to use eg fr_FR.utf8, we might have to install that
If we preferred to use eg fr_FR.utf8, we might have to install that
first:
$ apt-get install language-pack-fr
@ -2186,7 +2187,7 @@ TROUBLESHOOTING
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -2200,7 +2201,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)