slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages 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 (Star comments cause org\-mode nodes to be ignored, allowing emacs users
to fold and navigate their journals with org\-mode or orgstruct\-mode.) to fold and navigate their journals with org\-mode or orgstruct\-mode.)
.PP .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 You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the description and/or indented on the following lines (before the
postings). postings).
@ -795,6 +790,9 @@ end\ comment
;\ a\ file\ comment\ (because\ not\ indented) ;\ a\ file\ comment\ (because\ not\ indented)
\f[] \f[]
.fi .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 .SS Tags
.PP .PP
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
@ -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 Tags are like Ledger's metadata feature, except hledger's tag values are
simple strings. simple strings.
.SS Directives .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 .PP
You can define aliases which rewrite your account names (after reading You can define aliases which rewrite your account names (after reading
the journal, before generating reports). the journal, before generating reports).
@ -871,7 +1035,7 @@ combining two accounts into one
.IP \[bu] 2 .IP \[bu] 2
customising reports customising reports
.PP .PP
See also Cookbook: rewrite account names. See also Cookbook: Rewrite account names.
.SS Basic aliases .SS Basic aliases
.PP .PP
To set an account alias, use the \f[C]alias\f[] directive in your 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) precedence over earlier ones; directives not yet seen are ignored)
.IP "2." 3 .IP "2." 3
alias options, in the order they appear on the command line alias options, in the order they appear on the command line
.SS end aliases .SS \f[C]end\ aliases\f[]
.PP .PP
You can clear (forget) all currently defined aliases with the You can clear (forget) all currently defined aliases with the
\f[C]end\ aliases\f[] directive: \f[C]end\ aliases\f[] directive:
@ -956,60 +1120,7 @@ You can clear (forget) all currently defined aliases with the
end\ aliases end\ aliases
\f[] \f[]
.fi .fi
.SS account directive .SS Default parent account
.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
.PP .PP
You can specify a parent account which will be prepended to all accounts You can specify a parent account which will be prepended to all accounts
within a section of the journal. within a section of the journal.
@ -1054,125 +1165,13 @@ include\ personal.journal
.PP .PP
Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings
were also supported. were also supported.
.SS Multi\-line comments .SS Periodic transactions
.PP .PP
A line containing just \f[C]comment\f[] starts a multi\-line comment, Periodic transaction rules (enabled by \f[C]\-\-forecast\f[] or
and a line containing just \f[C]end\ comment\f[] ends it. \f[C]\-\-budget\f[]) describe recurring transactions.
See comments. They look like a transaction where the first line is a tilde
.SS commodity directive (\f[C]~\f[]) followed by a period expression (mnemonic: \f[C]~\f[] is
.PP like a recurring sine wave):
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:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1182,25 +1181,34 @@ They look a bit like a transaction, except the first line is a tilde
\f[] \f[]
.fi .fi
.PP .PP
Periodic transactions have a dual purpose:
.IP \[bu] 2
With \f[C]\-\-forecast\f[], each periodic transaction rule generates With \f[C]\-\-forecast\f[], each periodic transaction rule generates
recurring \[lq]forecast\[rq] transactions at the specified interval, future transactions, recurring at the specified interval, which can be
beginning the day after the latest recorded journal transaction (or seen in reports.
today, if there are no transactions) and ending 6 months from today (or Forecast transactions begin the day after the latest recorded journal
at the report end date, if specified). transaction (or today, if there are no transactions) and end 6 months
.PP from today (or at the report end date, if specified).
With \f[C]balance\ \-\-budget\f[], each periodic transaction declares .IP \[bu] 2
recurring budget goals for the specified accounts. 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 Eg the example above declares the goal of receiving $400 from
\f[C]income:acme\ inc\f[] (and also, depositing $400 into \f[C]income:acme\ inc\f[] (and also, depositing $400 into
\f[C]assets:bank:checking\f[]) every week. \f[C]assets:bank:checking\f[]) every week.
.PP .PP
For more details, see: balance: Budgeting and Budgeting and Forecasting. (Actually, you can generate one\-off transactions too, by writing a
.SH Automated postings period expression with no report interval.)
.PP .PP
Automated postings are postings added automatically by rule to certain For more details, see: balance: Budget report and Cookbook: Budgeting
transactions (with \f[C]\-\-auto\f[]). 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 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 .IP
.nf .nf
\f[C] \f[C]
@ -1240,10 +1248,8 @@ $\ hledger\ print\ \-\-auto
\f[] \f[]
.fi .fi
.PP .PP
Automated postings would not be distinguishable from equivalent postings Like postings recorded by hand, automated postings participate in
written by hand. transaction balancing, missing amount inference and balance assertions.
In particular, they would affect [amount inference|#postings] and
[balance assertion|#balance\-assertions] checks in the usual way.
.SH EDITOR SUPPORT .SH EDITOR SUPPORT
.PP .PP
Add\-on modes exist for various text editors, to make working with 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: * Menu:
* FILE FORMAT:: * FILE FORMAT::
* Periodic transactions::
* Automated postings::
* EDITOR SUPPORT:: * 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 1 FILE FORMAT
************* *************
@ -83,6 +81,8 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, P
* Comments:: * Comments::
* Tags:: * Tags::
* Directives:: * Directives::
* Periodic transactions::
* Automated postings::
 
File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT 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 org-mode nodes to be ignored, allowing emacs users to fold and navigate
their journals with org-mode or orgstruct-mode.) their journals with org-mode or orgstruct-mode.)
Also, anything between 'comment' and 'end comment' directives is a
(multi-line) comment. If there is no 'end comment', the comment extends
to the end of the file.
You can attach comments to a transaction by writing them after the You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual posting postings). Similarly, you can attach comments to an individual posting
@ -744,6 +740,9 @@ end comment
; another comment line for posting 2 ; another comment line for posting 2
; a file comment (because not indented) ; a file comment (because not indented)
You can also comment larger regions of a file using 'comment' and
'end comment' directives.
 
File: hledger_journal.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT 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. 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 1.14 Directives
=============== ===============
* Menu: * Menu:
* Account aliases:: * Comment blocks::
* account directive::
* apply account directive::
* Multi-line comments::
* commodity directive::
* Default commodity::
* Default year::
* Including other files:: * 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 A line containing just 'comment' starts a commented region of the file,
the journal, before generating reports). hledger's account aliases can and a line containing just 'end comment' (or the end of the current
be useful for: file) ends it. See also comments.
* 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: 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. You can pull in the content of additional files by writing an include
This affects all subsequent journal entries in the current file or its directive, like this:
included files. The spaces around the = are optional:
alias OLD = NEW include path/to/file.journal
Or, you can use the '--alias 'OLD=NEW'' option on the command line. If the path does not begin with a slash, it is relative to the
This affects all entries. It's useful for trying out aliases current file. Glob patterns ('*') are not currently supported.
interactively.
OLD and NEW are full account names. hledger will replace any The 'include' directive can only be used in journal files. It can
occurrence of the old account name with the new one. Subaccounts are include journal, timeclock or timedot files, but not CSV files.
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: 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, You can set a default year to be used for subsequent dates which don't
indicated by the forward slashes: 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 Y2010 ; change default year to 2010
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 2009/1/30 ; specifies the year, not affected
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" expenses 1
assets
Also note that REPLACEMENT continues to the end of line (or on 1/31 ; equivalent to 2010/1/31
command line, to end of option argument), so it can contain trailing expenses 1
whitespace. 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 The 'commodity' directive declares commodities which may be used in the
command-line options. Aliases are recursive - each alias sees the journal (though currently we do not enforce this). It may be written on
result of applying previous ones. (This is different from Ledger, where a single line, like this:
aliases are non-recursive by default). Aliases are applied in the
following order:
1. alias directives, most recently seen first (recent directives take ; commodity EXAMPLEAMOUNT
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line ; 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 1.14.5 Default commodity
....................
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
------------------------ ------------------------
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 The 'account' directive predeclares account names. The simplest form is
'account ACCTNAME', eg: 'account ACCTNAME', eg:
@ -947,10 +960,110 @@ account assets:bank:checking 1110
some-tag:12345 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 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 within a section of the journal. Use the 'apply account' and 'end apply
@ -983,157 +1096,52 @@ include personal.journal
supported. 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 Periodic transaction rules (enabled by '--forecast' or '--budget')
containing just 'end comment' ends it. See comments. 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):
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:
~ weekly ~ weekly
assets:bank:checking $400 ; paycheck assets:bank:checking $400 ; paycheck
income:acme inc income:acme inc
With '--forecast', each periodic transaction rule generates recurring Periodic transactions have a dual purpose:
"forecast" transactions at the specified interval, beginning the day
after the latest recorded journal transaction (or today, if there are no
transactions) and ending 6 months from today (or at the report end date,
if specified).
With 'balance --budget', each periodic transaction declares recurring * With '--forecast', each periodic transaction rule generates future
budget goals for the specified accounts. Eg the example above declares transactions, recurring at the specified interval, which can be
the goal of receiving $400 from 'income:acme inc' (and also, depositing seen in reports. Forecast transactions begin the day after the
$400 into 'assets:bank:checking') every week. 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 * With '--budget' (supported by the balance command), each periodic
Forecasting. 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 Automated postings (enabled by '--auto') are postings added
transactions (with '--auto'). An automated posting rule looks like a automatically by rule to certain transactions. An automated posting
transaction where the first line is an equal sign ('=') followed by a rule looks like a transaction where the first line is an equal sign
query: ('=') followed by a query (mnemonic: '=' tests for matching
transactions, and also looks like posting lines):
= expenses:gifts = expenses:gifts
budget:gifts *-1 budget:gifts *-1
@ -1161,15 +1169,13 @@ $ hledger print --auto
(budget:gifts) $-20 (budget:gifts) $-20
assets assets
Automated postings would not be distinguishable from equivalent Like postings recorded by hand, automated postings participate in
postings written by hand. In particular, they would affect [amount transaction balancing, missing amount inference and balance assertions.
inference|#postings] and [balance assertion|#balance-assertions] checks
in the usual way.
 
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 Add-on modes exist for various text editors, to make working with
@ -1196,89 +1202,89 @@ Code
 
Tag Table: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT2425 Node: FILE FORMAT2376
Ref: #file-format2556 Ref: #file-format2500
Node: Transactions2779 Node: Transactions2772
Ref: #transactions2900 Ref: #transactions2893
Node: Postings3584 Node: Postings3577
Ref: #postings3711 Ref: #postings3704
Node: Dates4706 Node: Dates4699
Ref: #dates4821 Ref: #dates4814
Node: Simple dates4886 Node: Simple dates4879
Ref: #simple-dates5012 Ref: #simple-dates5005
Node: Secondary dates5378 Node: Secondary dates5371
Ref: #secondary-dates5532 Ref: #secondary-dates5525
Node: Posting dates7095 Node: Posting dates7088
Ref: #posting-dates7224 Ref: #posting-dates7217
Node: Status8598 Node: Status8591
Ref: #status8718 Ref: #status8711
Node: Description10426 Node: Description10419
Ref: #description10564 Ref: #description10557
Node: Payee and note10883 Node: Payee and note10876
Ref: #payee-and-note10997 Ref: #payee-and-note10990
Node: Account names11239 Node: Account names11232
Ref: #account-names11382 Ref: #account-names11375
Node: Amounts11869 Node: Amounts11862
Ref: #amounts12005 Ref: #amounts11998
Node: Virtual Postings15020 Node: Virtual Postings15013
Ref: #virtual-postings15179 Ref: #virtual-postings15172
Node: Balance Assertions16399 Node: Balance Assertions16392
Ref: #balance-assertions16574 Ref: #balance-assertions16567
Node: Assertions and ordering17470 Node: Assertions and ordering17463
Ref: #assertions-and-ordering17656 Ref: #assertions-and-ordering17649
Node: Assertions and included files18356 Node: Assertions and included files18349
Ref: #assertions-and-included-files18597 Ref: #assertions-and-included-files18590
Node: Assertions and multiple -f options18930 Node: Assertions and multiple -f options18923
Ref: #assertions-and-multiple--f-options19184 Ref: #assertions-and-multiple--f-options19177
Node: Assertions and commodities19316 Node: Assertions and commodities19309
Ref: #assertions-and-commodities19551 Ref: #assertions-and-commodities19544
Node: Assertions and subaccounts20247 Node: Assertions and subaccounts20240
Ref: #assertions-and-subaccounts20479 Ref: #assertions-and-subaccounts20472
Node: Assertions and virtual postings21000 Node: Assertions and virtual postings20993
Ref: #assertions-and-virtual-postings21207 Ref: #assertions-and-virtual-postings21200
Node: Balance Assignments21349 Node: Balance Assignments21342
Ref: #balance-assignments21518 Ref: #balance-assignments21511
Node: Prices22638 Node: Prices22631
Ref: #prices22771 Ref: #prices22764
Node: Transaction prices22822 Node: Transaction prices22815
Ref: #transaction-prices22967 Ref: #transaction-prices22960
Node: Market prices25123 Node: Market prices25116
Ref: #market-prices25258 Ref: #market-prices25251
Node: Comments26218 Node: Comments26211
Ref: #comments26340 Ref: #comments26333
Node: Tags27582 Node: Tags27503
Ref: #tags27700 Ref: #tags27621
Node: Directives29102 Node: Directives29023
Ref: #directives29215 Ref: #directives29166
Node: Account aliases29408 Node: Comment blocks29359
Ref: #account-aliases29552 Ref: #comment-blocks29504
Node: Basic aliases30156 Node: Including other files29680
Ref: #basic-aliases30299 Ref: #including-other-files29860
Node: Regex aliases30989 Node: Default year30249
Ref: #regex-aliases31157 Ref: #default-year30418
Node: Multiple aliases31875 Node: Declaring commodities30841
Ref: #multiple-aliases32047 Ref: #declaring-commodities31024
Node: end aliases32545 Node: Default commodity32251
Ref: #end-aliases32685 Ref: #default-commodity32432
Node: account directive32786 Node: Declaring accounts33064
Ref: #account-directive32966 Ref: #declaring-accounts33244
Node: apply account directive34313 Node: Rewriting accounts34591
Ref: #apply-account-directive34509 Ref: #rewriting-accounts34776
Node: Multi-line comments35168 Node: Basic aliases35380
Ref: #multi-line-comments35358 Ref: #basic-aliases35526
Node: commodity directive35486 Node: Regex aliases36216
Ref: #commodity-directive35670 Ref: #regex-aliases36387
Node: Default commodity36897 Node: Multiple aliases37105
Ref: #default-commodity37070 Ref: #multiple-aliases37280
Node: Default year37702 Node: end aliases37778
Ref: #default-year37867 Ref: #end-aliases37925
Node: Including other files38290 Node: Default parent account38026
Ref: #including-other-files38447 Ref: #default-parent-account38192
Node: Periodic transactions38844 Node: Periodic transactions38851
Ref: #periodic-transactions39010 Ref: #periodic-transactions39030
Node: Automated postings39999 Node: Automated postings40329
Ref: #automated-postings40162 Ref: #automated-postings40483
Node: EDITOR SUPPORT41290 Node: EDITOR SUPPORT41616
Ref: #editor-support41415 Ref: #editor-support41734
 
End Tag Table 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 nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.) 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 You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post- description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by ings). Similarly, you can attach comments to an individual posting by
@ -584,21 +580,24 @@ FILE FORMAT
; another comment line for posting 2 ; another comment line for posting 2
; a file comment (because not indented) ; a file comment (because not indented)
You can also comment larger regions of a file using comment and
end comment directives.
Tags Tags
Tags are a way to add extra labels or labelled data to postings and Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on. 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: colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag: 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: next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value 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 lines. Ending at commas means you can write multiple short tags on one
line, comma separated: line, comma separated:
@ -612,213 +611,35 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..." o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting. postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag): third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2: 1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value ; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag: (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. are simple strings.
Directives Directives
Account aliases Comment blocks
You can define aliases which rewrite your account names (after reading A line containing just comment starts a commented region of the file,
the journal, before generating reports). hledger's account aliases can and a line containing just end comment (or the end of the current file)
be useful for: ends it. See also comments.
o expanding shorthand account names to their full form, allowing easier Including other files
data entry and a less verbose journal 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 If the path does not begin with a slash, it is relative to the current
combining two accounts into one file. Glob patterns (*) are not currently supported.
o customising reports The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
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.
Default year Default year
You can set a default year to be used for subsequent dates which don't You can set a default year to be used for subsequent dates which don't
@ -841,47 +662,234 @@ FILE FORMAT
expenses 1 expenses 1
assets assets
Including other files Declaring commodities
You can pull in the content of additional journal files by writing an The commodity directive declares commodities which may be used in the
include directive, like this: 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 ; display AAAA amounts with the symbol on the right, space-separated,
file. Glob patterns (*) are not currently supported. ; 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 or on multiple lines, using the "format" subdirective. In this case
include journal, timeclock or timedot files, but not CSV files. the commodity symbol appears twice and should be the same in both
places:
Periodic transactions ; commodity SYMBOL
Periodic transactions are a kind of rule with a dual purpose: they can ; format EXAMPLEAMOUNT
specify recurring future transactions (with --forecast), or budget
goals (with --budget). They look a bit like a transaction, except the ; display indian rupees with currency name on the left,
first line is a tilde (~) followed by a period expression: ; 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 ~ weekly
assets:bank:checking $400 ; paycheck assets:bank:checking $400 ; paycheck
income:acme inc income:acme inc
With --forecast, each periodic transaction rule generates recurring Periodic transactions have a dual purpose:
"forecast" transactions at the specified interval, beginning the day
after the latest recorded journal transaction (or today, if there are
no transactions) and ending 6 months from today (or at the report end
date, if specified).
With balance --budget, each periodic transaction declares recurring o With --forecast, each periodic transaction rule generates future
budget goals for the specified accounts. Eg the example above declares transactions, recurring at the specified interval, which can be seen
the goal of receiving $400 from income:acme inc (and also, depositing in reports. Forecast transactions begin the day after the latest
$400 into assets:bank:checking) every week. recorded journal transaction (or today, if there are no transactions)
and end 6 months from today (or at the report end date, if speci-
fied).
For more details, see: balance: Budgeting and Budgeting and Forecast- o With --budget (supported by the balance command), each periodic
ing. 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 (Actually, you can generate one-off transactions too, by writing a
Automated postings are postings added automatically by rule to certain period expression with no report interval.)
transactions (with --auto). An automated posting rule looks like a
transaction where the first line is an equal sign (=) followed by a For more details, see: balance: Budget report and Cookbook: Budgeting
query: 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 = expenses:gifts
budget:gifts *-1 budget:gifts *-1
@ -909,18 +917,16 @@ Automated postings
(budget:gifts) $-20 (budget:gifts) $-20
assets assets
Automated postings would not be distinguishable from equivalent post- Like postings recorded by hand, automated postings participate in
ings written by hand. In particular, they would affect [amount infer- transaction balancing, missing amount inference and balance assertions.
ence|#postings] and [balance assertion|#balance-assertions] checks in
the usual way.
EDITOR SUPPORT EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com- nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended. 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: files:
@ -939,7 +945,7 @@ EDITOR SUPPORT
REPORTING BUGS 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) or hledger mail list)
@ -953,7 +959,7 @@ COPYRIGHT
SEE ALSO 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- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) 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 \[lq]Boring\[rq] accounts, which contain a single interesting subaccount
and no balance of their own, are elided into the following line for more and no balance of their own, are elided into the following line for more
compact output. 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 .PP
Account balances are \[lq]inclusive\[rq] \- they include the balances of Account balances are \[lq]inclusive\[rq] \- they include the balances of
any subaccounts. 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 "Boring" accounts, which contain a single interesting subaccount and
no balance of their own, are elided into the following line for more 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 Account balances are "inclusive" - they include the balances of any
subaccounts. subaccounts.
@ -2485,84 +2486,84 @@ Node: balance35737
Ref: #balance35848 Ref: #balance35848
Node: Classic balance report38931 Node: Classic balance report38931
Ref: #classic-balance-report39104 Ref: #classic-balance-report39104
Node: Customising the classic balance report40433 Node: Customising the classic balance report40473
Ref: #customising-the-classic-balance-report40661 Ref: #customising-the-classic-balance-report40701
Node: Colour support42735 Node: Colour support42775
Ref: #colour-support42902 Ref: #colour-support42942
Node: Flat mode43075 Node: Flat mode43115
Ref: #flat-mode43223 Ref: #flat-mode43263
Node: Depth limited balance reports43636 Node: Depth limited balance reports43676
Ref: #depth-limited-balance-reports43836 Ref: #depth-limited-balance-reports43876
Node: Multicolumn balance report44292 Node: Multicolumn balance report44332
Ref: #multicolumn-balance-report44490 Ref: #multicolumn-balance-report44530
Node: Budget report49670 Node: Budget report49710
Ref: #budget-report49813 Ref: #budget-report49853
Ref: #output-format-152847 Ref: #output-format-152887
Node: balancesheet52925 Node: balancesheet52965
Ref: #balancesheet53061 Ref: #balancesheet53101
Node: balancesheetequity55372 Node: balancesheetequity55412
Ref: #balancesheetequity55521 Ref: #balancesheetequity55561
Node: cashflow56058 Node: cashflow56098
Ref: #cashflow56186 Ref: #cashflow56226
Node: check-dates58309 Node: check-dates58349
Ref: #check-dates58436 Ref: #check-dates58476
Node: check-dupes58553 Node: check-dupes58593
Ref: #check-dupes58677 Ref: #check-dupes58717
Node: close58814 Node: close58854
Ref: #close58921 Ref: #close58961
Node: help59251 Node: help59291
Ref: #help59351 Ref: #help59391
Node: import60425 Node: import60465
Ref: #import60539 Ref: #import60579
Node: incomestatement61269 Node: incomestatement61309
Ref: #incomestatement61403 Ref: #incomestatement61443
Node: prices63807 Node: prices63847
Ref: #prices63922 Ref: #prices63962
Node: print63965 Node: print64005
Ref: #print64075 Ref: #print64115
Node: print-unique68969 Node: print-unique69009
Ref: #print-unique69095 Ref: #print-unique69135
Node: register69163 Node: register69203
Ref: #register69290 Ref: #register69330
Node: Custom register output73791 Node: Custom register output73831
Ref: #custom-register-output73920 Ref: #custom-register-output73960
Node: register-match75150 Node: register-match75190
Ref: #register-match75284 Ref: #register-match75324
Node: rewrite75467 Node: rewrite75507
Ref: #rewrite75584 Ref: #rewrite75624
Node: stats75653 Node: stats75693
Ref: #stats75756 Ref: #stats75796
Node: tags76626 Node: tags76666
Ref: #tags76724 Ref: #tags76764
Node: test76960 Node: test77000
Ref: #test77044 Ref: #test77084
Node: ADD-ON COMMANDS77412 Node: ADD-ON COMMANDS77452
Ref: #add-on-commands77522 Ref: #add-on-commands77562
Node: Official add-ons78809 Node: Official add-ons78849
Ref: #official-add-ons78949 Ref: #official-add-ons78989
Node: api79036 Node: api79076
Ref: #api79125 Ref: #api79165
Node: ui79177 Node: ui79217
Ref: #ui79276 Ref: #ui79316
Node: web79334 Node: web79374
Ref: #web79423 Ref: #web79463
Node: Third party add-ons79469 Node: Third party add-ons79509
Ref: #third-party-add-ons79644 Ref: #third-party-add-ons79684
Node: diff79779 Node: diff79819
Ref: #diff79876 Ref: #diff79916
Node: iadd79975 Node: iadd80015
Ref: #iadd80089 Ref: #iadd80129
Node: interest80172 Node: interest80212
Ref: #interest80293 Ref: #interest80333
Node: irr80388 Node: irr80428
Ref: #irr80486 Ref: #irr80526
Node: Experimental add-ons80564 Node: Experimental add-ons80604
Ref: #experimental-add-ons80716 Ref: #experimental-add-ons80756
Node: autosync80996 Node: autosync81036
Ref: #autosync81107 Ref: #autosync81147
Node: chart81346 Node: chart81386
Ref: #chart81465 Ref: #chart81505
Node: check81536 Node: check81576
Ref: #check81638 Ref: #check81678
 
End Tag Table End Tag Table

357
hledger/hledger.txt
View File

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