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

update generated manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-01-22 13:36:11 -08:00
parent cc7c3928fb
commit a29b70c93f
6 changed files with 697 additions and 372 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
hledger-lib/hledger_journal.5
View File

@ -1189,8 +1189,7 @@ The \f[C]\-V/\-\-value\f[] flag can be used to convert reported amounts
to another commodity using these prices. to another commodity using these prices.
.SS Declaring accounts .SS Declaring accounts
.PP .PP
\f[C]account\f[] directives can be used to pre\-declare some or all \f[C]account\f[] directives can be used to pre\-declare accounts.
accounts.
Though not required, they can provide several benefits: Though not required, they can provide several benefits:
.IP \[bu] 2 .IP \[bu] 2
They can document your intended chart of accounts, providing a They can document your intended chart of accounts, providing a
@ -1209,38 +1208,86 @@ sorting (eg Revenues to appear above Expenses).
They help with account name completion in the add command, They help with account name completion in the add command,
hledger\-iadd, hledger\-web, ledger\-mode etc. hledger\-iadd, hledger\-web, ledger\-mode etc.
.PP .PP
Here is the full syntax: The simplest form is just the word \f[C]account\f[] followed by a
.IP hledger\-style account name, eg:
.nf
\f[C]
account\ ACCTNAME\ \ [ACCTTYPE]
\ \ [COMMENTS]
\f[]
.fi
.PP
The simplest form just declares a hledger\-style account name, eg:
.IP .IP
.nf .nf
\f[C] \f[C]
account\ assets:bank:checking account\ assets:bank:checking
\f[] \f[]
.fi .fi
.SS Account comments
.PP
Comments, beginning with a semicolon, optionally including tags, can be
written after the account name, and/or on following lines.
Eg:
.IP
.nf
\f[C]
account\ assets:bank:checking\ \ ;\ a\ comment
\ \ ;\ another\ comment
\ \ ;\ acctno:12345,\ a\ tag
\f[]
.fi
.PP
Tip: comments on the same line require hledger 1.12+.
If you need your journal to be compatible with older hledger versions,
write comments on the next line instead.
.SS Account subdirectives
.PP
We also allow (and ignore) Ledger\-style indented subdirectives, just
for compatibility.:
.IP
.nf
\f[C]
account\ assets:bank:checking
\ \ format\ blah\ blah\ \ ;\ <\-\ subdirective,\ ignored
\f[]
.fi
.PP
Here is the full syntax of account directives:
.IP
.nf
\f[C]
account\ ACCTNAME\ \ [ACCTTYPE]\ [;COMMENT]
\ \ [;COMMENTS]
\ \ [LEDGER\-STYLE\ SUBDIRECTIVES,\ IGNORED]
\f[]
.fi
.SS Account types .SS Account types
.PP .PP
hledger recognises five types of account: asset, liability, equity, hledger recognises five types (or classes) of account: Asset, Liability,
revenue, expense. Equity, Revenue, Expense.
This is useful for certain accounting\-aware reports, in particular This is used by a few accounting\-aware reports such as balancesheet,
balancesheet, incomestatement and cashflow. incomestatement and cashflow.
.SS Auto\-detected account types
.PP .PP
If you name your top\-level accounts with some variation of If you name your top\-level accounts with some variation of
\f[C]assets\f[], \f[C]liabilities\f[]/\f[C]debts\f[], \f[C]equity\f[], \f[C]assets\f[], \f[C]liabilities\f[]/\f[C]debts\f[], \f[C]equity\f[],
\f[C]revenues\f[]/\f[C]income\f[], or \f[C]expenses\f[], their types are \f[C]revenues\f[]/\f[C]income\f[], or \f[C]expenses\f[], their types are
detected automatically. detected automatically.
.SS Account types declared with tags
.PP .PP
More generally, you can declare an account's type by adding one of the More generally, you can declare an account's type with an account
letters \f[C]ALERX\f[] to its account directive, separated from the directive, by writing a \f[C]type:\f[] tag in a comment, followed by one
account name by two or more spaces. of the words \f[C]Asset\f[], \f[C]Liability\f[], \f[C]Equity\f[],
Eg: \f[C]Revenue\f[], \f[C]Expense\f[], or one of the letters \f[C]ALERX\f[]
(case insensitive):
.IP
.nf
\f[C]
account\ assets\ \ \ \ \ \ \ ;\ type:Asset
account\ liabilities\ \ ;\ type:Liability
account\ equity\ \ \ \ \ \ \ ;\ type:Equity
account\ revenues\ \ \ \ \ ;\ type:Revenue
account\ expenses\ \ \ \ \ ;\ type:Expenses
\f[]
.fi
.SS Account types declared with account type codes
.PP
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered deprecated
as of hledger 1.13:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1251,46 +1298,29 @@ account\ revenues\ \ \ \ \ R
account\ expenses\ \ \ \ \ X account\ expenses\ \ \ \ \ X
\f[] \f[]
.fi .fi
.SS Overriding auto\-detected types
.PP .PP
Note: if you ever override the types of those auto\-detected english If you ever override the types of those auto\-detected english account
account names mentioned above, you might need to help the reports a bit: names mentioned above, you might need to help the reports a bit.
Eg:
.IP .IP
.nf .nf
\f[C] \f[C]
;\ make\ "liabilities"\ not\ have\ the\ liability\ type,\ who\ knows\ why ;\ make\ "liabilities"\ not\ have\ the\ liability\ type\ \-\ who\ knows\ why
account\ liabilities\ \ \ E account\ liabilities\ \ \ ;\ type:E
;\ better\ ensure\ some\ other\ account\ has\ the\ liability\ type,\ ;\ we\ need\ to\ ensure\ some\ other\ account\ has\ the\ liability\ type,\
;\ otherwise\ balancesheet\ would\ still\ show\ "liabilities"\ under\ Liabilities\ ;\ otherwise\ balancesheet\ would\ still\ show\ "liabilities"\ under\ Liabilities\
account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ L account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ ;\ type:L
\f[] \f[]
.fi .fi
.PP
)
.SS Account comments
.PP
An account directive can also have indented comments on following lines,
eg:
.IP
.nf
\f[C]
account\ assets:bank:checking
\ \ ;\ acctno:12345
\ \ ;\ a\ comment
\f[]
.fi
.PP
We also allow (and ignore) Ledger\-style subdirectives, with no leading
semicolon, for compatibility.
.PP
Tags in account comments, like \f[C]acctno\f[] above, currently have no
effect.
.SS Account display order .SS Account display order
.PP .PP
Account directives also set the order in which accounts are displayed in Account directives also set the order in which accounts are displayed,
reports, the hledger\-ui accounts screen, the hledger\-web sidebar, etc. eg in reports, the hledger\-ui accounts screen, and the hledger\-web
Normally accounts are listed in alphabetical order, but if you have eg sidebar.
these account directives in the journal: By default accounts are listed in alphabetical order.
But if you have these account directives in the journal:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1302,7 +1332,7 @@ account\ expenses
\f[] \f[]
.fi .fi
.PP .PP
you'll see those accounts listed in declaration order, not you'll see those accounts displayed in declaration order, not
alphabetically: alphabetically:
.IP .IP
.nf .nf

192
hledger-lib/hledger_journal.info
View File

@ -1055,8 +1055,8 @@ File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts
1.14.7 Declaring accounts 1.14.7 Declaring accounts
------------------------- -------------------------
'account' directives can be used to pre-declare some or all accounts. 'account' directives can be used to pre-declare accounts. Though not
Though not required, they can provide several benefits: required, they can provide several benefits:
* They can document your intended chart of accounts, providing a * They can document your intended chart of accounts, providing a
reference. reference.
@ -1070,38 +1070,80 @@ Though not required, they can provide several benefits:
* They help with account name completion in the add command, * They help with account name completion in the add command,
hledger-iadd, hledger-web, ledger-mode etc. hledger-iadd, hledger-web, ledger-mode etc.
Here is the full syntax: The simplest form is just the word 'account' followed by a
hledger-style account name, eg:
account ACCTNAME [ACCTTYPE]
[COMMENTS]
The simplest form just declares a hledger-style account name, eg:
account assets:bank:checking account assets:bank:checking
* Menu: * Menu:
* Account types::
* Account comments:: * Account comments::
* Account subdirectives::
* Account types::
* Account display order:: * Account display order::
 
File: hledger_journal.info, Node: Account types, Next: Account comments, Up: Declaring accounts File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Up: Declaring accounts
1.14.7.1 Account types 1.14.7.1 Account comments
.........................
Comments, beginning with a semicolon, optionally including tags, can be
written after the account name, and/or on following lines. Eg:
account assets:bank:checking ; a comment
; another comment
; acctno:12345, a tag
Tip: comments on the same line require hledger 1.12+. If you need
your journal to be compatible with older hledger versions, write
comments on the next line instead.

File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts
1.14.7.2 Account subdirectives
..............................
We also allow (and ignore) Ledger-style indented subdirectives, just for
compatibility.:
account assets:bank:checking
format blah blah ; <- subdirective, ignored
Here is the full syntax of account directives:
account ACCTNAME [ACCTTYPE] [;COMMENT]
[;COMMENTS]
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]

File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts
1.14.7.3 Account types
...................... ......................
hledger recognises five types of account: asset, liability, equity, hledger recognises five types (or classes) of account: Asset, Liability,
revenue, expense. This is useful for certain accounting-aware reports, Equity, Revenue, Expense. This is used by a few accounting-aware
in particular balancesheet, incomestatement and cashflow. reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types If you name your top-level accounts with
some variation of 'assets', 'liabilities'/'debts', 'equity',
'revenues'/'income', or 'expenses', their types are detected
automatically. Account types declared with tags More generally, you can
declare an account's type with an account directive, by writing a
'type:' tag in a comment, followed by one of the words 'Asset',
'Liability', 'Equity', 'Revenue', 'Expense', or one of the letters
'ALERX' (case insensitive):
If you name your top-level accounts with some variation of 'assets', account assets ; type:Asset
'liabilities'/'debts', 'equity', 'revenues'/'income', or 'expenses', account liabilities ; type:Liability
their types are detected automatically. account equity ; type:Equity
account revenues ; type:Revenue
account expenses ; type:Expenses
More generally, you can declare an account's type by adding one of Account types declared with account type codes Or, you can write one
the letters 'ALERX' to its account directive, separated from the account of those letters separated from the account name by two or more spaces,
name by two or more spaces. Eg: but this should probably be considered deprecated as of hledger 1.13:
account assets A account assets A
account liabilities L account liabilities L
@ -1109,47 +1151,27 @@ account equity E
account revenues R account revenues R
account expenses X account expenses X
Note: if you ever override the types of those auto-detected english Overriding auto-detected types If you ever override the types of
account names mentioned above, you might need to help the reports a bit: those auto-detected english account names mentioned above, you might
need to help the reports a bit. Eg:
; make "liabilities" not have the liability type, who knows why ; make "liabilities" not have the liability type - who knows why
account liabilities E account liabilities ; type:E
; better ensure some other account has the liability type, ; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities ; otherwise balancesheet would still show "liabilities" under Liabilities
account - L account - ; type:L
)
 
File: hledger_journal.info, Node: Account comments, Next: Account display order, Prev: Account types, Up: Declaring accounts File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts
1.14.7.2 Account comments 1.14.7.4 Account display order
.........................
An account directive can also have indented comments on following lines,
eg:
account assets:bank:checking
; acctno:12345
; a comment
We also allow (and ignore) Ledger-style subdirectives, with no
leading semicolon, for compatibility.
Tags in account comments, like 'acctno' above, currently have no
effect.

File: hledger_journal.info, Node: Account display order, Prev: Account comments, Up: Declaring accounts
1.14.7.3 Account display order
.............................. ..............................
Account directives also set the order in which accounts are displayed in Account directives also set the order in which accounts are displayed,
reports, the hledger-ui accounts screen, the hledger-web sidebar, etc. eg in reports, the hledger-ui accounts screen, and the hledger-web
Normally accounts are listed in alphabetical order, but if you have eg sidebar. By default accounts are listed in alphabetical order. But if
these account directives in the journal: you have these account directives in the journal:
account assets account assets
account liabilities account liabilities
@ -1157,7 +1179,7 @@ account equity
account revenues account revenues
account expenses account expenses
you'll see those accounts listed in declaration order, not you'll see those accounts displayed in declaration order, not
alphabetically: alphabetically:
$ hledger accounts -1 $ hledger accounts -1
@ -1605,35 +1627,37 @@ Node: Market prices38745
Ref: #market-prices38910 Ref: #market-prices38910
Node: Declaring accounts39751 Node: Declaring accounts39751
Ref: #declaring-accounts39927 Ref: #declaring-accounts39927
Node: Account types40884 Node: Account comments40852
Ref: #account-types41033 Ref: #account-comments41015
Node: Account comments42107 Node: Account subdirectives41410
Ref: #account-comments42292 Ref: #account-subdirectives41605
Node: Account display order42613 Node: Account types41918
Ref: #account-display-order42786 Ref: #account-types42102
Node: Rewriting accounts43908 Node: Account display order43746
Ref: #rewriting-accounts44093 Ref: #account-display-order43916
Node: Basic aliases44827 Node: Rewriting accounts45045
Ref: #basic-aliases44973 Ref: #rewriting-accounts45230
Node: Regex aliases45677 Node: Basic aliases45964
Ref: #regex-aliases45848 Ref: #basic-aliases46110
Node: Multiple aliases46566 Node: Regex aliases46814
Ref: #multiple-aliases46741 Ref: #regex-aliases46985
Node: end aliases47239 Node: Multiple aliases47703
Ref: #end-aliases47386 Ref: #multiple-aliases47878
Node: Default parent account47487 Node: end aliases48376
Ref: #default-parent-account47653 Ref: #end-aliases48523
Node: Periodic transactions48537 Node: Default parent account48624
Ref: #periodic-transactions48719 Ref: #default-parent-account48790
Node: Two spaces after the period expression49844 Node: Periodic transactions49674
Ref: #two-spaces-after-the-period-expression50089 Ref: #periodic-transactions49856
Node: Forecasting with periodic transactions50574 Node: Two spaces after the period expression50981
Ref: #forecasting-with-periodic-transactions50864 Ref: #two-spaces-after-the-period-expression51226
Node: Budgeting with periodic transactions52551 Node: Forecasting with periodic transactions51711
Ref: #budgeting-with-periodic-transactions52790 Ref: #forecasting-with-periodic-transactions52001
Node: Transaction Modifiers53249 Node: Budgeting with periodic transactions53688
Ref: #transaction-modifiers53412 Ref: #budgeting-with-periodic-transactions53927
Node: EDITOR SUPPORT55393 Node: Transaction Modifiers54386
Ref: #editor-support55511 Ref: #transaction-modifiers54549
Node: EDITOR SUPPORT56530
Ref: #editor-support56648
 
End Tag Table End Tag Table

108
hledger-lib/hledger_journal.txt
View File

@ -846,8 +846,8 @@ FILE FORMAT
commodity using these prices. commodity using these prices.
Declaring accounts Declaring accounts
account directives can be used to pre-declare some or all accounts. account directives can be used to pre-declare accounts. Though not
Though not required, they can provide several benefits: required, they can provide several benefits:
o They can document your intended chart of accounts, providing a refer- o They can document your intended chart of accounts, providing a refer-
ence. ence.
@ -865,27 +865,62 @@ FILE FORMAT
o They help with account name completion in the add command, o They help with account name completion in the add command,
hledger-iadd, hledger-web, ledger-mode etc. hledger-iadd, hledger-web, ledger-mode etc.
Here is the full syntax: The simplest form is just the word account followed by a hledger-style
account name, eg:
account ACCTNAME [ACCTTYPE]
[COMMENTS]
The simplest form just declares a hledger-style account name, eg:
account assets:bank:checking account assets:bank:checking
Account types Account comments
hledger recognises five types of account: asset, liability, equity, Comments, beginning with a semicolon, optionally including tags, can be
revenue, expense. This is useful for certain accounting-aware reports, written after the account name, and/or on following lines. Eg:
in particular balancesheet, incomestatement and cashflow.
account assets:bank:checking ; a comment
; another comment
; acctno:12345, a tag
Tip: comments on the same line require hledger 1.12+. If you need your
journal to be compatible with older hledger versions, write comments on
the next line instead.
Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.:
account assets:bank:checking
format blah blah ; <- subdirective, ignored
Here is the full syntax of account directives:
account ACCTNAME [ACCTTYPE] [;COMMENT]
[;COMMENTS]
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types
If you name your top-level accounts with some variation of assets, lia- If you name your top-level accounts with some variation of assets, lia-
bilities/debts, equity, revenues/income, or expenses, their types are bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically. detected automatically.
More generally, you can declare an account's type by adding one of the Account types declared with tags
letters ALERX to its account directive, separated from the account name More generally, you can declare an account's type with an account
by two or more spaces. Eg: directive, by writing a type: tag in a comment, followed by one of the
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive):
account assets ; type:Asset
account liabilities ; type:Liability
account equity ; type:Equity
account revenues ; type:Revenue
account expenses ; type:Expenses
Account types declared with account type codes
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13:
account assets A account assets A
account liabilities L account liabilities L
@ -893,37 +928,22 @@ FILE FORMAT
account revenues R account revenues R
account expenses X account expenses X
Note: if you ever override the types of those auto-detected english Overriding auto-detected types
account names mentioned above, you might need to help the reports a If you ever override the types of those auto-detected english account
bit: names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type, who knows why ; make "liabilities" not have the liability type - who knows why
account liabilities E account liabilities ; type:E
; better ensure some other account has the liability type, ; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities ; otherwise balancesheet would still show "liabilities" under Liabilities
account - L account - ; type:L
)
Account comments
An account directive can also have indented comments on following
lines, eg:
account assets:bank:checking
; acctno:12345
; a comment
We also allow (and ignore) Ledger-style subdirectives, with no leading
semicolon, for compatibility.
Tags in account comments, like acctno above, currently have no effect.
Account display order Account display order
Account directives also set the order in which accounts are displayed Account directives also set the order in which accounts are displayed,
in reports, the hledger-ui accounts screen, the hledger-web sidebar, eg in reports, the hledger-ui accounts screen, and the hledger-web
etc. Normally accounts are listed in alphabetical order, but if you sidebar. By default accounts are listed in alphabetical order. But if
have eg these account directives in the journal: you have these account directives in the journal:
account assets account assets
account liabilities account liabilities
@ -931,8 +951,8 @@ FILE FORMAT
account revenues account revenues
account expenses account expenses
you'll see those accounts listed in declaration order, not alphabeti- you'll see those accounts displayed in declaration order, not alphabet-
cally: ically:
$ hledger accounts -1 $ hledger accounts -1
assets assets

113
hledger/hledger.1
View File

@ -2318,13 +2318,112 @@ Report account names having the same leaf but different prefixes.
An example: http://stefanorodighiero.net/software/hledger\-dupes.html An example: http://stefanorodighiero.net/software/hledger\-dupes.html
.SS close .SS close
.PP .PP
Print closing/opening transactions that bring some or all account close, equity
balances to zero and back. .PP
Can be useful for bringing asset/liability balances across file Prints a \[lq]closing balances\[rq] transaction and an \[lq]opening
boundaries, or for closing out income/expenses for a period. balances\[rq] transaction, that bring account balances to and from zero,
This was formerly called \[lq]equity\[rq], as in Ledger, and that alias respectively.
is also accepted. Useful for, eg:
See close \[en]help for more. .IP \[bu] 2
bringing asset/liability balances forward into a new journal file
.IP \[bu] 2
closing out revenues/expenses to retained earnings at the end of a
period
.PP
The closing transaction transfers balances to \[lq]equity:closing
balances\[rq].
The opening transaction transfers balances from \[lq]equity:opening
balances\[rq].
You can chose to print just one of the transactions by using the
\f[C]\-\-opening\f[] or \f[C]\-\-closing\f[] flag.
.PP
If you split your journal files by time (eg yearly), you will typically
run this command at the end of the year, and save the closing
transaction as last entry of the old file, and the opening transaction
as the first entry of the new file.
This makes the files self contained, so that correct balances are
reported no matter which of them are loaded.
Ie, if you load just one file, the balances are initialised correctly;
or if you load several files, the redundant closing/opening transactions
cancel each other out.
(They will show up in print or register reports; you can exclude them
with a query like
\f[C]not:desc:\[aq](opening|closing)\ balances\[aq]\f[].)
.PP
If you're running a business, you might also use this command to
\[lq]close the books\[rq] at the end of an accounting period,
transferring income statement account balances to retained earnings.
(You may want to change the equity account name to something like
\[lq]equity:retained earnings\[rq] for clarity.)
.PP
By default, the closing transaction is dated yesterday, the balances are
calculated as of end of yesterday, and the opening transaction is dated
today.
To close on some other date, use:
\f[C]hledger\ close\ \-e\ OPENINGDATE\f[].
Eg, to close/open on the 2018/2019 boundary, use \f[C]\-e\ 2019\f[].
You can also use \-p or \f[C]date:PERIOD\f[] (any starting date is
ignored).
.PP
Both transactions will include balance assertions for the
closed/reopened accounts.
You probably shouldn't use status or realness filters (like \-C or \-R
or \f[C]status:\f[]) with this command, or the generated balance
assertions will depend on these flags.
Likewise, if you run this command with \[en]auto, the balance assertions
will probably always require \[en]auto.
.PP
Examples:
.PP
Carrying asset/liability balances into a new file for 2019, all from
command line.
.PP
\f[I]Warning: we use \f[CI]>>\f[I] here to append; be careful not to
type a single \f[CI]>\f[I] which would wipe your journal!\f[]
.IP
.nf
\f[C]
$\ hledger\ close\ \-f\ 2018.journal\ \-e\ 2019\ assets\ liabilities\ \-\-opening\ >>2019.journal
$\ hledger\ close\ \-f\ 2018.journal\ \-e\ 2019\ assets\ liabilities\ \-\-closing\ >>2018.journal
\f[]
.fi
.PP
Now:
.IP
.nf
\f[C]
$\ hledger\ bs\ \-f\ 2019.journal\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ one\ file\ \-\ balances\ are\ correct
$\ hledger\ bs\ \-f\ 2018.journal\ \-f\ 2019.journal\ \ \ #\ two\ files\ \-\ balances\ still\ correct
$\ hledger\ bs\ \-f\ 2018.journal\ not:desc:closing\ \ #\ to\ see\ year\-end\ balances,\ must\ exclude\ closing\ txn
\f[]
.fi
.PP
Transactions spanning the closing date can complicate matters, breaking
balance assertions:
.IP
.nf
\f[C]
2018/12/30\ a\ purchase\ made\ in\ 2018,\ clearing\ the\ following\ year
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ 5
\ \ \ \ assets:bank:checking\ \ \-5\ \ ;\ [2019/1/2]
\f[]
.fi
.PP
Here's one way to resolve that:
.IP
.nf
\f[C]
;\ in\ 2018.journal:
2018/12/30\ a\ purchase\ made\ in\ 2018,\ clearing\ the\ following\ year
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ 5
\ \ \ \ liabilities:pending
;\ in\ 2019.journal:
2019/1/2\ clearance\ of\ last\ year\[aq]s\ pending\ transactions
\ \ \ \ liabilities:pending\ \ \ \ 5\ =\ 0
\ \ \ \ assets:checking
\f[]
.fi
.SS files .SS files
.PP .PP
List all files included in the journal. List all files included in the journal.

202
hledger/hledger.info
View File

@ -1851,11 +1851,87 @@ File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMAND
4.10 close 4.10 close
========== ==========
Print closing/opening transactions that bring some or all account close, equity
balances to zero and back. Can be useful for bringing asset/liability
balances across file boundaries, or for closing out income/expenses for Prints a "closing balances" transaction and an "opening balances"
a period. This was formerly called "equity", as in Ledger, and that transaction, that bring account balances to and from zero, respectively.
alias is also accepted. See close -help for more. Useful for, eg:
* bringing asset/liability balances forward into a new journal file
* closing out revenues/expenses to retained earnings at the end of a
period
The closing transaction transfers balances to "equity:closing
balances". The opening transaction transfers balances from
"equity:opening balances". You can chose to print just one of the
transactions by using the '--opening' or '--closing' flag.
If you split your journal files by time (eg yearly), you will
typically run this command at the end of the year, and save the closing
transaction as last entry of the old file, and the opening transaction
as the first entry of the new file. This makes the files self
contained, so that correct balances are reported no matter which of them
are loaded. Ie, if you load just one file, the balances are initialised
correctly; or if you load several files, the redundant closing/opening
transactions cancel each other out. (They will show up in print or
register reports; you can exclude them with a query like
'not:desc:'(opening|closing) balances''.)
If you're running a business, you might also use this command to
"close the books" at the end of an accounting period, transferring
income statement account balances to retained earnings. (You may want
to change the equity account name to something like "equity:retained
earnings" for clarity.)
By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is
dated today. To close on some other date, use: 'hledger close -e
OPENINGDATE'. Eg, to close/open on the 2018/2019 boundary, use '-e
2019'. You can also use -p or 'date:PERIOD' (any starting date is
ignored).
Both transactions will include balance assertions for the
closed/reopened accounts. You probably shouldn't use status or realness
filters (like -C or -R or 'status:') with this command, or the generated
balance assertions will depend on these flags. Likewise, if you run
this command with -auto, the balance assertions will probably always
require -auto.
Examples:
Carrying asset/liability balances into a new file for 2019, all from
command line.
_Warning: we use '>>' here to append; be careful not to type a single
'>' which would wipe your journal!_
$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal
$ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal
Now:
$ hledger bs -f 2019.journal # one file - balances are correct
$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct
$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn
Transactions spanning the closing date can complicate matters,
breaking balance assertions:
2018/12/30 a purchase made in 2018, clearing the following year
expenses:food 5
assets:bank:checking -5 ; [2019/1/2]
Here's one way to resolve that:
; in 2018.journal:
2018/12/30 a purchase made in 2018, clearing the following year
expenses:food 5
liabilities:pending
; in 2019.journal:
2019/1/2 clearance of last year's pending transactions
liabilities:pending 5 = 0
assets:checking
 
File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS
@ -2643,63 +2719,63 @@ Node: check-dupes61080
Ref: #check-dupes61204 Ref: #check-dupes61204
Node: close61341 Node: close61341
Ref: #close61449 Ref: #close61449
Node: files61779 Node: files64891
Ref: #files61880 Ref: #files64992
Node: help62021 Node: help65133
Ref: #help62121 Ref: #help65233
Node: import63195 Node: import66307
Ref: #import63309 Ref: #import66421
Node: incomestatement64039 Node: incomestatement67151
Ref: #incomestatement64173 Ref: #incomestatement67285
Node: prices66577 Node: prices69689
Ref: #prices66692 Ref: #prices69804
Node: print66964 Node: print70076
Ref: #print67074 Ref: #print70186
Node: print-unique71968 Node: print-unique75080
Ref: #print-unique72094 Ref: #print-unique75206
Node: register72162 Node: register75274
Ref: #register72289 Ref: #register75401
Node: Custom register output76790 Node: Custom register output79902
Ref: #custom-register-output76919 Ref: #custom-register-output80031
Node: register-match78149 Node: register-match81261
Ref: #register-match78283 Ref: #register-match81395
Node: rewrite78466 Node: rewrite81578
Ref: #rewrite78581 Ref: #rewrite81693
Node: roi78650 Node: roi81762
Ref: #roi78748 Ref: #roi81860
Node: stats78864 Node: stats81976
Ref: #stats78963 Ref: #stats82075
Node: tags79833 Node: tags82945
Ref: #tags79931 Ref: #tags83043
Node: test80167 Node: test83279
Ref: #test80251 Ref: #test83363
Node: ADD-ON COMMANDS80959 Node: ADD-ON COMMANDS84071
Ref: #add-on-commands81069 Ref: #add-on-commands84181
Node: Official add-ons82356 Node: Official add-ons85468
Ref: #official-add-ons82496 Ref: #official-add-ons85608
Node: api82583 Node: api85695
Ref: #api82672 Ref: #api85784
Node: ui82724 Node: ui85836
Ref: #ui82823 Ref: #ui85935
Node: web82881 Node: web85993
Ref: #web82970 Ref: #web86082
Node: Third party add-ons83016 Node: Third party add-ons86128
Ref: #third-party-add-ons83191 Ref: #third-party-add-ons86303
Node: diff83326 Node: diff86438
Ref: #diff83423 Ref: #diff86535
Node: iadd83522 Node: iadd86634
Ref: #iadd83636 Ref: #iadd86748
Node: interest83719 Node: interest86831
Ref: #interest83840 Ref: #interest86952
Node: irr83935 Node: irr87047
Ref: #irr84033 Ref: #irr87145
Node: Experimental add-ons84164 Node: Experimental add-ons87276
Ref: #experimental-add-ons84316 Ref: #experimental-add-ons87428
Node: autosync84596 Node: autosync87708
Ref: #autosync84707 Ref: #autosync87819
Node: chart84946 Node: chart88058
Ref: #chart85065 Ref: #chart88177
Node: check85136 Node: check88248
Ref: #check85238 Ref: #check88350
 
End Tag Table End Tag Table

322
hledger/hledger.txt
View File

@ -1646,26 +1646,102 @@ COMMANDS
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- close, equity
ances to zero and back. Can be useful for bringing asset/liability
balances across file boundaries, or for closing out income/expenses for Prints a "closing balances" transaction and an "opening balances"
a period. This was formerly called "equity", as in Ledger, and that transaction, that bring account balances to and from zero, respec-
alias is also accepted. See close -help for more. tively. Useful for, eg:
o bringing asset/liability balances forward into a new journal file
o closing out revenues/expenses to retained earnings at the end of a
period
The closing transaction transfers balances to "equity:closing bal-
ances". The opening transaction transfers balances from "equity:open-
ing balances". You can chose to print just one of the transactions by
using the --opening or --closing flag.
If you split your journal files by time (eg yearly), you will typically
run this command at the end of the year, and save the closing transac-
tion as last entry of the old file, and the opening transaction as the
first entry of the new file. This makes the files self contained, so
that correct balances are reported no matter which of them are loaded.
Ie, if you load just one file, the balances are initialised correctly;
or if you load several files, the redundant closing/opening transac-
tions cancel each other out. (They will show up in print or register
reports; you can exclude them with a query like not:desc:'(open-
ing|closing) balances'.)
If you're running a business, you might also use this command to "close
the books" at the end of an accounting period, transferring income
statement account balances to retained earnings. (You may want to
change the equity account name to something like "equity:retained earn-
ings" for clarity.)
By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is
dated today. To close on some other date, use: hledger close -e OPEN-
INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
You can also use -p or date:PERIOD (any starting date is ignored).
Both transactions will include balance assertions for the
closed/reopened accounts. You probably shouldn't use status or real-
ness filters (like -C or -R or status:) with this command, or the gen-
erated balance assertions will depend on these flags. Likewise, if you
run this command with -auto, the balance assertions will probably
always require -auto.
Examples:
Carrying asset/liability balances into a new file for 2019, all from
command line.
Warning: we use >> here to append; be careful not to type a single >
which would wipe your journal!
$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal
$ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal
Now:
$ hledger bs -f 2019.journal # one file - balances are correct
$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct
$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn
Transactions spanning the closing date can complicate matters, breaking
balance assertions:
2018/12/30 a purchase made in 2018, clearing the following year
expenses:food 5
assets:bank:checking -5 ; [2019/1/2]
Here's one way to resolve that:
; in 2018.journal:
2018/12/30 a purchase made in 2018, clearing the following year
expenses:food 5
liabilities:pending
; in 2019.journal:
2019/1/2 clearance of last year's pending transactions
liabilities:pending 5 = 0
assets:checking
files files
List all files included in the journal. With a REGEX argument, only List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown. file names matching the regular expression (case sensitive) are shown.
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
@ -1689,7 +1765,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
@ -1699,28 +1775,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
@ -1754,8 +1830,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
@ -1780,16 +1856,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. 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
Print market price directives from the journal. With -costs, also Print market price directives from the journal. With -costs, also
print synthetic market prices based on transaction prices. With print synthetic market prices based on transaction prices. With
-inverted-costs, also print inverse prices based on transaction prices. -inverted-costs, also print inverse prices based on transaction prices.
Prices (and postings providing prices) can be filtered by a query. Prices (and postings providing prices) can be filtered by a query.
@ -1797,7 +1873,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
@ -1810,7 +1886,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
@ -1841,39 +1917,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
@ -1890,20 +1966,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
@ -1916,7 +1992,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
@ -1927,18 +2003,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
@ -1947,8 +2023,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
@ -1958,23 +2034,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
@ -1991,7 +2067,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
@ -1999,18 +2075,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:
@ -2027,26 +2103,26 @@ 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
Print all transactions, adding custom postings to the matched ones. Print all transactions, adding custom postings to the matched ones.
roi roi
Shows time-weighted (TWR) and money-weighted (IRR) rate of return on Shows time-weighted (TWR) and money-weighted (IRR) rate of return on
your investments. See roi --help for more. your investments. See roi --help for more.
stats stats
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
@ -2061,61 +2137,61 @@ 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.
test test
Run built-in unit tests. Run built-in unit tests.
Prints test names and their results on stdout. If any test fails or Prints test names and their results on stdout. If any test fails or
gives an error, the exit code will be non-zero. gives an error, the exit code will be non-zero.
Test names include a group prefix. If a (exact, case sensitive) group Test names include a group prefix. If a (exact, case sensitive) group
prefix, or a full test name is provided as the first argument, only prefix, or a full test name is provided as the first argument, only
that group or test is run. that group or test is run.
If a numeric second argument is provided, it will set the randomness If a numeric second argument is provided, it will set the randomness
seed, for repeatable results from tests using randomness (currently seed, for repeatable results from tests using randomness (currently
none of them). none of them).
This is mainly used by developers, but it's nice to be able to san- This is mainly used by developers, but it's nice to be able to san-
ity-check your installed hledger executable at any time. All tests are ity-check your installed hledger executable at any time. All tests are
expected to pass - if you ever see otherwise, something has gone wrong, expected to pass - if you ever see otherwise, something has gone wrong,
please report a bug! please report a bug!
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:
@ -2133,7 +2209,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
@ -2141,7 +2217,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
@ -2149,19 +2225,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, but it's superseded now by the built-in roi command. account, but it's superseded now by the built-in roi command.
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
@ -2171,21 +2247,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
@ -2198,33 +2274,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
@ -2243,7 +2319,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
@ -2264,7 +2340,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)
@ -2278,7 +2354,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)