3041 lines
90 KiB
Groff
3041 lines
90 KiB
Groff
.\"t
|
|
|
|
.TH "hledger" "1" "March 2018" "hledger 1.9.99" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
hledger \- a command\-line accounting tool
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[C]hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [ARGS]\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [ARGS]\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]hledger\f[]
|
|
.SH DESCRIPTION
|
|
.PP
|
|
hledger is a cross\-platform program for tracking money, time, or any
|
|
other commodity, using double\-entry accounting and a simple, editable
|
|
file format.
|
|
hledger is inspired by and largely compatible with ledger(1).
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Tested on unix, mac, windows, hledger aims to be a reliable, practical
|
|
tool for daily use.
|
|
.PP
|
|
This is hledger's command\-line interface (there are also curses and web
|
|
interfaces).
|
|
Its basic function is to read a plain text file describing financial
|
|
transactions (in accounting terms, a general journal) and print useful
|
|
reports on standard output, or export them as CSV.
|
|
hledger can also read some other file formats such as CSV files,
|
|
translating them to journal format.
|
|
Additionally, hledger lists other hledger\-* executables found in the
|
|
user's $PATH and can invoke them as subcommands.
|
|
.PP
|
|
hledger reads data from one or more files in hledger journal, timeclock,
|
|
timedot, or CSV format specified with \f[C]\-f\f[], or
|
|
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows,
|
|
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
|
|
If using \f[C]$LEDGER_FILE\f[], note this must be a real environment
|
|
variable, not a shell variable.
|
|
You can specify standard input with \f[C]\-f\-\f[].
|
|
.PP
|
|
Transactions are dated movements of money between two (or more) named
|
|
accounts, and are recorded with journal entries like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2015/10/16\ bought\ food
|
|
\ expenses:food\ \ \ \ \ \ \ \ \ \ $10
|
|
\ assets:cash
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
For more about this format, see hledger_journal(5).
|
|
.PP
|
|
Most users use a text editor to edit the journal, usually with an editor
|
|
mode such as ledger\-mode for added convenience.
|
|
hledger's interactive add command is another way to record new
|
|
transactions.
|
|
hledger never changes existing transactions.
|
|
.PP
|
|
To get started, you can either save some entries like the above in
|
|
\f[C]~/.hledger.journal\f[], or run \f[C]hledger\ add\f[] and follow the
|
|
prompts.
|
|
Then try some commands like \f[C]hledger\ print\f[] or
|
|
\f[C]hledger\ balance\f[].
|
|
Run \f[C]hledger\f[] with no arguments for a list of commands.
|
|
.SH EXAMPLES
|
|
.PP
|
|
Two simple transactions in hledger journal format:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2015/9/30\ gift\ received
|
|
\ \ assets:cash\ \ \ $20
|
|
\ \ income:gifts
|
|
|
|
2015/10/16\ farmers\ market
|
|
\ \ expenses:food\ \ \ \ $10
|
|
\ \ assets:cash
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Some basic reports:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ print
|
|
2015/09/30\ gift\ received
|
|
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ $20
|
|
\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ $\-20
|
|
|
|
2015/10/16\ farmers\ market
|
|
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ $10
|
|
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ $\-10
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ accounts\ \-\-tree
|
|
assets
|
|
\ \ cash
|
|
expenses
|
|
\ \ food
|
|
income
|
|
\ \ gifts
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ assets:cash
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ expenses:food
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-20\ \ income:gifts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ register\ cash
|
|
2015/09/30\ gift\ received\ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ $20
|
|
2015/10/16\ farmers\ market\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ \ $10
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
More commands:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ available\ commands
|
|
$\ hledger\ add\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ add\ more\ transactions\ to\ the\ journal\ file
|
|
$\ hledger\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ all\ accounts\ with\ aggregated\ balances
|
|
$\ hledger\ balance\ \-\-help\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ detailed\ help\ for\ balance\ command
|
|
$\ hledger\ balance\ \-\-depth\ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ only\ top\-level\ accounts
|
|
$\ hledger\ register\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ account\ postings,\ with\ running\ total
|
|
$\ hledger\ reg\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ postings\ to/from\ income\ accounts
|
|
$\ hledger\ reg\ \[aq]assets:some\ bank:checking\[aq]\ #\ show\ postings\ to/from\ this\ checking\ account
|
|
$\ hledger\ print\ desc:shop\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transactions\ with\ shop\ in\ the\ description
|
|
$\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transaction\ counts\ per\ week\ as\ a\ bar\ chart
|
|
\f[]
|
|
.fi
|
|
.SH OPTIONS
|
|
.SS General options
|
|
.PP
|
|
To see general usage help, including general options which are supported
|
|
by most hledger commands, run \f[C]hledger\ \-h\f[].
|
|
.PP
|
|
General help options:
|
|
.TP
|
|
.B \f[C]\-h\ \-\-help\f[]
|
|
show general usage (or after COMMAND, command usage)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-version\f[]
|
|
show version
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-debug[=N]\f[]
|
|
show debug output (levels 1\-9, default: 1)
|
|
.RS
|
|
.RE
|
|
.PP
|
|
General input options:
|
|
.TP
|
|
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[]
|
|
use a different input file.
|
|
For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or
|
|
\f[C]$HOME/.hledger.journal\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-rules\-file=RULESFILE\f[]
|
|
Conversion rules file to use when reading CSV (default: FILE.rules)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-alias=OLD=NEW\f[]
|
|
rename accounts named OLD to NEW
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-anon\f[]
|
|
anonymize accounts and payees
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-pivot\ FIELDNAME\f[]
|
|
use some other field or tag for the account name
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-I\ \-\-ignore\-assertions\f[]
|
|
ignore any failing balance assertions
|
|
.RS
|
|
.RE
|
|
.PP
|
|
General reporting options:
|
|
.TP
|
|
.B \f[C]\-b\ \-\-begin=DATE\f[]
|
|
include postings/txns on or after this date
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-e\ \-\-end=DATE\f[]
|
|
include postings/txns before this date
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-D\ \-\-daily\f[]
|
|
multiperiod/multicolumn report by day
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-W\ \-\-weekly\f[]
|
|
multiperiod/multicolumn report by week
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-M\ \-\-monthly\f[]
|
|
multiperiod/multicolumn report by month
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-Q\ \-\-quarterly\f[]
|
|
multiperiod/multicolumn report by quarter
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-Y\ \-\-yearly\f[]
|
|
multiperiod/multicolumn report by year
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
|
|
set start date, end date, and/or reporting interval all at once using
|
|
period expressions syntax (overrides the flags above)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-date2\f[]
|
|
match the secondary date instead (see command help for other effects)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-U\ \-\-unmarked\f[]
|
|
include only unmarked postings/txns (can combine with \-P or \-C)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-P\ \-\-pending\f[]
|
|
include only pending postings/txns
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-C\ \-\-cleared\f[]
|
|
include only cleared postings/txns
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-R\ \-\-real\f[]
|
|
include only non\-virtual postings
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-NUM\ \-\-depth=NUM\f[]
|
|
hide/aggregate accounts or postings more than NUM levels deep
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-E\ \-\-empty\f[]
|
|
show items with zero amount, normally hidden (and vice\-versa in
|
|
hledger\-ui/hledger\-web)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-B\ \-\-cost\f[]
|
|
convert amounts to their cost at transaction time (using the transaction
|
|
price, if any)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-V\ \-\-value\f[]
|
|
convert amounts to their market value on the report end date (using the
|
|
most recent applicable market price, if any)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-auto\f[]
|
|
apply automated posting rules to modify transactions.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-forecast\f[]
|
|
apply periodic transaction rules to generate future transactions, to 6
|
|
months from now or report end date.
|
|
.RS
|
|
.RE
|
|
.PP
|
|
When a reporting option appears more than once in the command line, the
|
|
last one takes precedence.
|
|
.PP
|
|
Some reporting options can also be written as query arguments.
|
|
.SS Command options
|
|
.PP
|
|
To see options for a particular command, including command\-specific
|
|
options, run: \f[C]hledger\ COMMAND\ \-h\f[].
|
|
.PP
|
|
Command\-specific options must be written after the command name, eg:
|
|
\f[C]hledger\ print\ \-x\f[].
|
|
.PP
|
|
Additionally, if the command is an addon, you may need to put its
|
|
options after a double\-hyphen, eg:
|
|
\f[C]hledger\ ui\ \-\-\ \-\-watch\f[].
|
|
Or, you can run the addon executable directly:
|
|
\f[C]hledger\-ui\ \-\-watch\f[].
|
|
.SS Command arguments
|
|
.PP
|
|
Most hledger commands accept arguments after the command name, which are
|
|
often a query, filtering the data in some way.
|
|
.SS Argument files
|
|
.PP
|
|
You can save a set of command line options/arguments in a file, one per
|
|
line, and then reuse them by writing \f[C]\@FILENAME\f[] in a command
|
|
line.
|
|
To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a
|
|
\f[C]\-\-\f[] argument.
|
|
For more, see Save frequently used options.
|
|
.SS Special characters
|
|
.PP
|
|
Option and argument values which contain problematic characters should
|
|
be escaped with double quotes, backslashes, or (best) single quotes.
|
|
Problematic characters means spaces, and also characters which are
|
|
significant to your command shell, such as less\-than/greater\-than.
|
|
Eg:
|
|
\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[].
|
|
.PP
|
|
Characters which are significant both to the shell and in regular
|
|
expressions sometimes need to be double\-escaped.
|
|
These include parentheses, the pipe symbol and the dollar sign.
|
|
Eg, to match the dollar symbol, bash users should do:
|
|
\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] or
|
|
\f[C]hledger\ balance\ cur:\\\\$\f[].
|
|
.PP
|
|
When hledger is invoking an addon executable (like hledger\-ui), options
|
|
and arguments get de\-escaped once more, so you might need
|
|
\f[I]triple\f[]\-escaping.
|
|
Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or
|
|
\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] in bash.
|
|
(The number of backslashes in fish shell is left as an exercise for the
|
|
reader.)
|
|
.PP
|
|
Inside a file used for argument expansion, one less level of escaping is
|
|
enough.
|
|
(And in this case, backslashes seem to work better than quotes.
|
|
Eg: \f[C]cur:\\$\f[]).
|
|
.PP
|
|
If in doubt, keep things simple:
|
|
.IP \[bu] 2
|
|
run add\-on executables directly
|
|
.IP \[bu] 2
|
|
write options after the command
|
|
.IP \[bu] 2
|
|
enclose problematic args in single quotes
|
|
.IP \[bu] 2
|
|
if needed, also add a backslash to escape regexp metacharacters
|
|
.PP
|
|
If you're really stumped, add \f[C]\-\-debug=2\f[] to troubleshoot.
|
|
.SS Input files
|
|
.PP
|
|
hledger reads transactions from a data file (and the add command writes
|
|
to it).
|
|
By default this file is \f[C]$HOME/.hledger.journal\f[] (or on Windows,
|
|
something like \f[C]C:/Users/USER/.hledger.journal\f[]).
|
|
You can override this with the \f[C]$LEDGER_FILE\f[] environment
|
|
variable:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ setenv\ LEDGER_FILE\ ~/finance/2016.journal
|
|
$\ hledger\ stats
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
or with the \f[C]\-f/\-\-file\f[] option:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ /some/file\ stats
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The file name \f[C]\-\f[] (hyphen) means standard input:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ cat\ some.journal\ |\ hledger\ \-f\-
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Usually the data file is in hledger's journal format, but it can also be
|
|
one of several other formats, listed below.
|
|
hledger detects the format automatically based on the file extension, or
|
|
if that is not recognised, by trying each built\-in \[lq]reader\[rq] in
|
|
turn:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(10.3n) lw(33.5n) lw(26.2n).
|
|
T{
|
|
Reader:
|
|
T}@T{
|
|
Reads:
|
|
T}@T{
|
|
Used for file extensions:
|
|
T}
|
|
_
|
|
T{
|
|
\f[C]journal\f[]
|
|
T}@T{
|
|
hledger's journal format, also some Ledger journals
|
|
T}@T{
|
|
\f[C]\&.journal\f[] \f[C]\&.j\f[] \f[C]\&.hledger\f[] \f[C]\&.ledger\f[]
|
|
T}
|
|
T{
|
|
\f[C]timeclock\f[]
|
|
T}@T{
|
|
timeclock files (precise time logging)
|
|
T}@T{
|
|
\f[C]\&.timeclock\f[]
|
|
T}
|
|
T{
|
|
\f[C]timedot\f[]
|
|
T}@T{
|
|
timedot files (approximate time logging)
|
|
T}@T{
|
|
\f[C]\&.timedot\f[]
|
|
T}
|
|
T{
|
|
\f[C]csv\f[]
|
|
T}@T{
|
|
comma\-separated values (data interchange)
|
|
T}@T{
|
|
\f[C]\&.csv\f[]
|
|
T}
|
|
.TE
|
|
.PP
|
|
If needed (eg to ensure correct error messages when a file has the
|
|
\[lq]wrong\[rq] extension), you can force a specific reader/format by
|
|
prepending it to the file path with a colon.
|
|
Examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ csv:/some/csv\-file.dat\ stats
|
|
$\ echo\ \[aq]i\ 2009/13/1\ 08:00:00\[aq]\ |\ hledger\ print\ \-ftimeclock:\-
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
You can also specify multiple \f[C]\-f\f[] options, to read multiple
|
|
files as one big journal.
|
|
There are some limitations with this:
|
|
.IP \[bu] 2
|
|
directives in one file will not affect the other files
|
|
.IP \[bu] 2
|
|
balance assertions will not see any account balances from previous files
|
|
.PP
|
|
If you need those, either use the include directive, or concatenate the
|
|
files, eg: \f[C]cat\ a.journal\ b.journal\ |\ hledger\ \-f\-\ CMD\f[].
|
|
.SS Smart dates
|
|
.PP
|
|
hledger's user interfaces accept a flexible \[lq]smart date\[rq] syntax
|
|
(unlike dates in the journal file).
|
|
Smart dates allow some english words, can be relative to today's date,
|
|
and can have less\-significant date parts omitted (defaulting to 1).
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
\f[C]2004/10/1\f[], \f[C]2004\-01\-01\f[], \f[C]2004.9.1\f[]
|
|
T}@T{
|
|
exact date, several separators allowed.
|
|
Year is 4+ digits, month is 1\-12, day is 1\-31
|
|
T}
|
|
T{
|
|
\f[C]2004\f[]
|
|
T}@T{
|
|
start of year
|
|
T}
|
|
T{
|
|
\f[C]2004/10\f[]
|
|
T}@T{
|
|
start of month
|
|
T}
|
|
T{
|
|
\f[C]10/1\f[]
|
|
T}@T{
|
|
month and day in current year
|
|
T}
|
|
T{
|
|
\f[C]21\f[]
|
|
T}@T{
|
|
day in current month
|
|
T}
|
|
T{
|
|
\f[C]october,\ oct\f[]
|
|
T}@T{
|
|
start of month in current year
|
|
T}
|
|
T{
|
|
\f[C]yesterday,\ today,\ tomorrow\f[]
|
|
T}@T{
|
|
\-1, 0, 1 days from today
|
|
T}
|
|
T{
|
|
\f[C]last/this/next\ day/week/month/quarter/year\f[]
|
|
T}@T{
|
|
\-1, 0, 1 periods from the current period
|
|
T}
|
|
T{
|
|
\f[C]20181201\f[]
|
|
T}@T{
|
|
8 digit YYYYMMDD with valid year month and day
|
|
T}
|
|
T{
|
|
\f[C]201812\f[]
|
|
T}@T{
|
|
6 digit YYYYMM with valid year and month
|
|
T}
|
|
.TE
|
|
.PP
|
|
Counterexamples \- malformed digit sequences might give surprising
|
|
results:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
\f[C]201813\f[]
|
|
T}@T{
|
|
6 digits with an invalid month is parsed as start of 6\-digit year
|
|
T}
|
|
T{
|
|
\f[C]20181301\f[]
|
|
T}@T{
|
|
8 digits with an invalid month is parsed as start of 8\-digit year
|
|
T}
|
|
T{
|
|
\f[C]20181232\f[]
|
|
T}@T{
|
|
8 digits with an invalid day gives an error
|
|
T}
|
|
T{
|
|
\f[C]201801012\f[]
|
|
T}@T{
|
|
9+ digits beginning with a valid YYYYMMDD gives an error
|
|
T}
|
|
.TE
|
|
.SS Report start & end date
|
|
.PP
|
|
Most hledger reports show the full span of time represented by the
|
|
journal data, by default.
|
|
So, the effective report start and end dates will be the earliest and
|
|
latest transaction or posting dates found in the journal.
|
|
.PP
|
|
Often you will want to see a shorter time span, such as the current
|
|
month.
|
|
You can specify a start and/or end date using \f[C]\-b/\-\-begin\f[],
|
|
\f[C]\-e/\-\-end\f[], \f[C]\-p/\-\-period\f[] or a \f[C]date:\f[] query
|
|
(described below).
|
|
All of these accept the smart date syntax.
|
|
One important thing to be aware of when specifying end dates: as in
|
|
Ledger, end dates are exclusive, so you need to write the date
|
|
\f[I]after\f[] the last day you want to include.
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
\f[C]\-b\ 2016/3/17\f[]
|
|
T}@T{
|
|
begin on St.\ Patrick's day 2016
|
|
T}
|
|
T{
|
|
\f[C]\-e\ 12/1\f[]
|
|
T}@T{
|
|
end at the start of december 1st of the current year (11/30 will be the
|
|
last date included)
|
|
T}
|
|
T{
|
|
\f[C]\-b\ thismonth\f[]
|
|
T}@T{
|
|
all transactions on or after the 1st of the current month
|
|
T}
|
|
T{
|
|
\f[C]\-p\ thismonth\f[]
|
|
T}@T{
|
|
all transactions in the current month
|
|
T}
|
|
T{
|
|
\f[C]date:2016/3/17\-\f[]
|
|
T}@T{
|
|
the above written as queries instead
|
|
T}
|
|
T{
|
|
\f[C]date:\-12/1\f[]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[C]date:thismonth\-\f[]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[C]date:thismonth\f[]
|
|
T}@T{
|
|
T}
|
|
.TE
|
|
.SS Report intervals
|
|
.PP
|
|
A report interval can be specified so that commands like register,
|
|
balance and activity will divide their reports into multiple subperiods.
|
|
The basic intervals can be selected with one of \f[C]\-D/\-\-daily\f[],
|
|
\f[C]\-W/\-\-weekly\f[], \f[C]\-M/\-\-monthly\f[],
|
|
\f[C]\-Q/\-\-quarterly\f[], or \f[C]\-Y/\-\-yearly\f[].
|
|
More complex intervals may be specified with a period expression.
|
|
Report intervals can not be specified with a query, currently.
|
|
.SS Period expressions
|
|
.PP
|
|
The \f[C]\-p/\-\-period\f[] option accepts period expressions, a
|
|
shorthand way of expressing a start date, end date, and/or report
|
|
interval all at once.
|
|
.PP
|
|
Here's a basic period expression specifying the first quarter of 2009.
|
|
Note, hledger always treats start dates as inclusive and end dates as
|
|
exclusive:
|
|
.PP
|
|
\f[C]\-p\ "from\ 2009/1/1\ to\ 2009/4/1"\f[]
|
|
.PP
|
|
Keywords like \[lq]from\[rq] and \[lq]to\[rq] are optional, and so are
|
|
the spaces, as long as you don't run two dates together.
|
|
\[lq]to\[rq] can also be written as \[lq]\-\[rq].
|
|
These are equivalent to the above:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[C]\-p\ "2009/1/1\ 2009/4/1"\f[]
|
|
T}
|
|
T{
|
|
\f[C]\-p2009/1/1to2009/4/1\f[]
|
|
T}
|
|
T{
|
|
\f[C]\-p2009/1/1\-2009/4/1\f[]
|
|
T}
|
|
.TE
|
|
.PP
|
|
Dates are smart dates, so if the current year is 2009, the above can
|
|
also be written as:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[C]\-p\ "1/1\ 4/1"\f[]
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "january\-apr"\f[]
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "this\ year\ to\ 4/1"\f[]
|
|
T}
|
|
.TE
|
|
.PP
|
|
If you specify only one date, the missing start or end date will be the
|
|
earliest or latest transaction in your journal:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
\f[C]\-p\ "from\ 2009/1/1"\f[]
|
|
T}@T{
|
|
everything after january 1, 2009
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "from\ 2009/1"\f[]
|
|
T}@T{
|
|
the same
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "from\ 2009"\f[]
|
|
T}@T{
|
|
the same
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "to\ 2009"\f[]
|
|
T}@T{
|
|
everything before january 1, 2009
|
|
T}
|
|
.TE
|
|
.PP
|
|
A single date with no \[lq]from\[rq] or \[lq]to\[rq] defines both the
|
|
start and end date like so:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
\f[C]\-p\ "2009"\f[]
|
|
T}@T{
|
|
the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq]
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "2009/1"\f[]
|
|
T}@T{
|
|
the month of jan; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq]
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "2009/1/1"\f[]
|
|
T}@T{
|
|
just that day; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq]
|
|
T}
|
|
.TE
|
|
.PP
|
|
The argument of \f[C]\-p\f[] can also begin with, or be, a report
|
|
interval expression.
|
|
The basic report intervals are \f[C]daily\f[], \f[C]weekly\f[],
|
|
\f[C]monthly\f[], \f[C]quarterly\f[], or \f[C]yearly\f[], which have the
|
|
same effect as the \f[C]\-D\f[],\f[C]\-W\f[],\f[C]\-M\f[],\f[C]\-Q\f[],
|
|
or \f[C]\-Y\f[] flags.
|
|
Between report interval and start/end dates (if any), the word
|
|
\f[C]in\f[] is optional.
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[C]\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1"\f[]
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "monthly\ in\ 2008"\f[]
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "quarterly"\f[]
|
|
T}
|
|
.TE
|
|
.PP
|
|
Note that \f[C]weekly\f[], \f[C]monthly\f[], \f[C]quarterly\f[] and
|
|
\f[C]yearly\f[] intervals will always start on the first day on week,
|
|
month, quarter or year accordingly, and will end on the last day of same
|
|
period, even if associated period expression specifies different
|
|
explicit start and end date.
|
|
.PP
|
|
For example:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[C]\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1"\f[] \[en] starts on
|
|
2008/12/29, closest preceeding Monday
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "monthly\ in\ 2008/11/25"\f[] \[en] starts on 2018/11/01
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "quarterly\ from\ 2009\-05\-05\ to\ 2009\-06\-01"\f[] \-
|
|
starts on 2009/04/01, ends on 2009/06/30, which are first and last days
|
|
of Q2 2009
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "yearly\ from\ 2009\-12\-29"\f[] \- starts on 2009/01/01,
|
|
first day of 2009
|
|
T}
|
|
.TE
|
|
.PP
|
|
The following more complex report intervals are also supported:
|
|
\f[C]biweekly\f[], \f[C]bimonthly\f[],
|
|
\f[C]every\ day|week|month|quarter|year\f[],
|
|
\f[C]every\ N\ days|weeks|months|quarters|years\f[].
|
|
.PP
|
|
All of these will start on the first day of the requested period and end
|
|
on the last one, as described above.
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[C]\-p\ "bimonthly\ from\ 2008"\f[] \[en] periods will have boundaries
|
|
on 2008/01/01, 2008/03/01, \&...
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ 2\ weeks"\f[] \[en] starts on closest preceeding
|
|
Monday
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ 5\ month\ from\ 2009/03"\f[] \[en] periods will have
|
|
boundaries on 2009/03/01, 2009/08/01, \&...
|
|
T}
|
|
.TE
|
|
.PP
|
|
If you want intervals that start on arbitrary day of your choosing and
|
|
span a week, month or year, you need to use any of the following:
|
|
.PP
|
|
\f[C]every\ Nth\ day\ of\ week\f[], \f[C]every\ <weekday>\f[],
|
|
\f[C]every\ Nth\ day\ [of\ month]\f[],
|
|
\f[C]every\ Nth\ weekday\ [of\ month]\f[],
|
|
\f[C]every\ MM/DD\ [of\ year]\f[], \f[C]every\ Nth\ MMM\ [of\ year]\f[],
|
|
\f[C]every\ MMM\ Nth\ [of\ year]\f[].
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[C]\-p\ "every\ 2nd\ day\ of\ week"\f[] \[en] periods will go from Tue
|
|
to Tue
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ Tue"\f[] \[en] same
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ 15th\ day"\f[] \[en] period boundaries will be on 15th
|
|
of each month
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ 2nd\ Monday"\f[] \[en] period boundaries will be on
|
|
second Monday of each month
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ 11/05"\f[] \[en] yearly periods with boundaries on 5th
|
|
of Nov
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ 5th\ Nov"\f[] \[en] same
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ Nov\ 5th"\f[] \[en] same
|
|
T}
|
|
.TE
|
|
.PP
|
|
Show historical balances at end of 15th each month (N is exclusive end
|
|
date):
|
|
.PP
|
|
\f[C]hledger\ balance\ \-H\ \-p\ "every\ 16th\ day"\f[]
|
|
.PP
|
|
Group postings from start of wednesday to end of next tuesday (N is
|
|
start date and exclusive end date):
|
|
.PP
|
|
\f[C]hledger\ register\ checking\ \-p\ "every\ 3rd\ day\ of\ week"\f[]
|
|
.SS Depth limiting
|
|
.PP
|
|
With the \f[C]\-\-depth\ N\f[] option (short form: \f[C]\-N\f[]),
|
|
commands like account, balance and register will show only the uppermost
|
|
accounts in the account tree, down to level N.
|
|
Use this when you want a summary with less detail.
|
|
This flag has the same effect as a \f[C]depth:\f[] query argument (so
|
|
\f[C]\-2\f[], \f[C]\-\-depth=2\f[] or \f[C]depth:2\f[] are basically
|
|
equivalent).
|
|
.SS Pivoting
|
|
.PP
|
|
Normally hledger sums amounts, and organizes them in a hierarchy, based
|
|
on account name.
|
|
The \f[C]\-\-pivot\ FIELD\f[] option causes it to sum and organize
|
|
hierarchy based on the value of some other field instead.
|
|
FIELD can be: \f[C]code\f[], \f[C]description\f[], \f[C]payee\f[],
|
|
\f[C]note\f[], or the full name (case insensitive) of any tag.
|
|
As with account names, values containing \f[C]colon:separated:parts\f[]
|
|
will be displayed hierarchically in reports.
|
|
.PP
|
|
\f[C]\-\-pivot\f[] is a general option affecting all reports; you can
|
|
think of hledger transforming the journal before any other processing,
|
|
replacing every posting's account name with the value of the specified
|
|
field on that posting, inheriting it from the transaction or using a
|
|
blank value if it's not present.
|
|
.PP
|
|
An example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2016/02/16\ Member\ Fee\ Payment
|
|
\ \ \ \ assets:bank\ account\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR
|
|
\ \ \ \ income:member\ fees\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ ;\ member:\ John\ Doe
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Normal balance report showing account names:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR\ \ assets:bank\ account
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ income:member\ fees
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Pivoted balance report, using member: tag values instead:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-\-pivot\ member
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
One way to show only amounts with a member: value (using a query,
|
|
described below):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-\-pivot\ member\ tag:member=.
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Another way (the acct: query matches against the pivoted \[lq]account
|
|
name\[rq]):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-\-pivot\ member\ acct:.
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
|
|
\f[]
|
|
.fi
|
|
.SS Cost
|
|
.PP
|
|
The \f[C]\-B/\-\-cost\f[] flag converts amounts to their cost at
|
|
transaction time, if they have a transaction price specified.
|
|
.SS Market value
|
|
.PP
|
|
The \f[C]\-V/\-\-value\f[] flag converts reported amounts to their
|
|
current market value.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Specifically, when there is a market price (P directive) for the
|
|
amount's commodity, dated on or before today's date (or the report end
|
|
date if specified), the amount will be converted to the price's
|
|
commodity.
|
|
.PP
|
|
When there are multiple applicable P directives, \-V chooses the most
|
|
recent one, or in case of equal dates, the last\-parsed one.
|
|
.PP
|
|
For example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ one\ euro\ is\ worth\ this\ many\ dollars\ from\ nov\ 1
|
|
P\ 2016/11/01\ €\ $1.10
|
|
|
|
#\ purchase\ some\ euros\ on\ nov\ 3
|
|
2016/11/3
|
|
\ \ \ \ assets:euros\ \ \ \ \ \ \ \ €100
|
|
\ \ \ \ assets:checking
|
|
|
|
#\ the\ euro\ is\ worth\ fewer\ dollars\ by\ dec\ 21
|
|
P\ 2016/12/21\ €\ $1.03
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
How many euros do I have ?
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ t.j\ bal\ \-N\ euros
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
What are they worth at end of nov 3 ?
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V\ \-e\ 2016/11/4
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
What are they worth after 2016/12/21 ?
|
|
(no report end date specified, defaults to today)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Currently, hledger's \-V only uses market prices recorded with P
|
|
directives, not transaction prices (unlike Ledger).
|
|
.PP
|
|
Currently, \-V has a limitation in multicolumn balance reports: it uses
|
|
the market prices on the report end date for all columns.
|
|
(Instead of the prices on each column's end date.)
|
|
.SS Combining \-B and \-V
|
|
.PP
|
|
Using \-B/\[en]cost and \-V/\[en]value together is currently allowed,
|
|
but the results are probably not meaningful.
|
|
Let us know if you find a use for this.
|
|
.SS Output destination
|
|
.PP
|
|
Some commands (print, register, stats, the balance commands) can write
|
|
their output to a destination other than the console.
|
|
This is controlled by the \f[C]\-o/\-\-output\-file\f[] option.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default)
|
|
$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE
|
|
\f[]
|
|
.fi
|
|
.SS Output format
|
|
.PP
|
|
Some commands can write their output in other formats.
|
|
Eg print and register can output CSV, and the balance commands can
|
|
output CSV or HTML.
|
|
This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by
|
|
specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with
|
|
\f[C]\-o/\-\-output\-file\f[].
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout
|
|
$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv
|
|
\f[]
|
|
.fi
|
|
.SS Regular expressions
|
|
.PP
|
|
hledger uses regular expressions in a number of places:
|
|
.IP \[bu] 2
|
|
query terms, on the command line and in the hledger\-web search form:
|
|
\f[C]REGEX\f[], \f[C]desc:REGEX\f[], \f[C]cur:REGEX\f[],
|
|
\f[C]tag:...=REGEX\f[]
|
|
.IP \[bu] 2
|
|
CSV rules conditional blocks: \f[C]if\ REGEX\ ...\f[]
|
|
.IP \[bu] 2
|
|
account alias directives and options:
|
|
\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[],
|
|
\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[]
|
|
.PP
|
|
hledger's regular expressions come from the regex\-tdfa library.
|
|
In general they:
|
|
.IP \[bu] 2
|
|
are case insensitive
|
|
.IP \[bu] 2
|
|
are infix matching (do not need to match the entire thing being matched)
|
|
.IP \[bu] 2
|
|
are POSIX extended regular expressions
|
|
.IP \[bu] 2
|
|
also support GNU word boundaries (\\<, \\>, \\b, \\B)
|
|
.IP \[bu] 2
|
|
and parenthesised capturing groups and numeric backreferences in
|
|
replacement strings
|
|
.IP \[bu] 2
|
|
do not support mode modifiers like (?s)
|
|
.PP
|
|
Some things to note:
|
|
.IP \[bu] 2
|
|
In the \f[C]alias\f[] directive and \f[C]\-\-alias\f[] option, regular
|
|
expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[]).
|
|
Elsewhere in hledger, these are not required.
|
|
.IP \[bu] 2
|
|
In queries, to match a regular expression metacharacter like \f[C]$\f[]
|
|
as a literal character, prepend a backslash.
|
|
Eg to search for amounts with the dollar sign in hledger\-web, write
|
|
\f[C]cur:\\$\f[].
|
|
.IP \[bu] 2
|
|
On the command line, some metacharacters like \f[C]$\f[] have a special
|
|
meaning to the shell and so must be escaped at least once more.
|
|
See Special characters.
|
|
.SH QUERIES
|
|
.PP
|
|
One of hledger's strengths is being able to quickly report on precise
|
|
subsets of your data.
|
|
Most commands accept an optional query expression, written as arguments
|
|
after the command name, to filter the data by date, account name or
|
|
other criteria.
|
|
The syntax is similar to a web search: one or more space\-separated
|
|
search terms, quotes to enclose whitespace, prefixes to match specific
|
|
fields, a not: prefix to negate the match.
|
|
.PP
|
|
We do not yet support arbitrary boolean combinations of search terms;
|
|
instead most commands show transactions/postings/accounts which match
|
|
(or negatively match):
|
|
.IP \[bu] 2
|
|
any of the description terms AND
|
|
.IP \[bu] 2
|
|
any of the account terms AND
|
|
.IP \[bu] 2
|
|
any of the status terms AND
|
|
.IP \[bu] 2
|
|
all the other terms.
|
|
.PP
|
|
The print command instead shows transactions which:
|
|
.IP \[bu] 2
|
|
match any of the description terms AND
|
|
.IP \[bu] 2
|
|
have any postings matching any of the positive account terms AND
|
|
.IP \[bu] 2
|
|
have no postings matching any of the negative account terms AND
|
|
.IP \[bu] 2
|
|
match all the other terms.
|
|
.PP
|
|
The following kinds of search terms can be used.
|
|
Remember these can also be prefixed with \f[B]\f[BC]not:\f[B]\f[], eg to
|
|
exclude a particular subaccount.
|
|
.TP
|
|
.B \f[B]\f[BC]REGEX\f[B], \f[BC]acct:REGEX\f[B]\f[]
|
|
match account names by this regular expression.
|
|
(With no prefix, \f[C]acct:\f[] is assumed.)
|
|
.RS
|
|
.RE
|
|
same as above
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]amt:N,\ amt:<N,\ amt:<=N,\ amt:>N,\ amt:>=N\f[B]\f[]
|
|
match postings with a single\-commodity amount that is equal to, less
|
|
than, or greater than N.
|
|
(Multi\-commodity amounts are not tested, and will always match.) The
|
|
comparison has two modes: if N is preceded by a + or \- sign (or is 0),
|
|
the two signed numbers are compared.
|
|
Otherwise, the absolute magnitudes are compared, ignoring sign.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]code:REGEX\f[B]\f[]
|
|
match by transaction code (eg check number)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]cur:REGEX\f[B]\f[]
|
|
match postings or transactions including any amounts whose
|
|
currency/commodity symbol is fully matched by REGEX.
|
|
(For a partial match, use \f[C]\&.*REGEX.*\f[]).
|
|
Note, to match characters which are regex\-significant, like the dollar
|
|
sign (\f[C]$\f[]), you need to prepend \f[C]\\\f[].
|
|
And when using the command line you need to add one more level of
|
|
quoting to hide it from the shell, so eg do:
|
|
\f[C]hledger\ print\ cur:\[aq]\\$\[aq]\f[] or
|
|
\f[C]hledger\ print\ cur:\\\\$\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]desc:REGEX\f[B]\f[]
|
|
match transaction descriptions.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]date:PERIODEXPR\f[B]\f[]
|
|
match dates within the specified period.
|
|
PERIODEXPR is a period expression (with no report interval).
|
|
Examples: \f[C]date:2016\f[], \f[C]date:thismonth\f[],
|
|
\f[C]date:2000/2/1\-2/15\f[], \f[C]date:lastweek\-\f[].
|
|
If the \f[C]\-\-date2\f[] command line flag is present, this matches
|
|
secondary dates instead.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]date2:PERIODEXPR\f[B]\f[]
|
|
match secondary dates within the specified period.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]depth:N\f[B]\f[]
|
|
match (or display, depending on command) accounts at or above this depth
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]note:REGEX\f[B]\f[]
|
|
match transaction notes (part of description right of \f[C]|\f[], or
|
|
whole description when there's no \f[C]|\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]payee:REGEX\f[B]\f[]
|
|
match transaction payee/payer names (part of description left of
|
|
\f[C]|\f[], or whole description when there's no \f[C]|\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]real:,\ real:0\f[B]\f[]
|
|
match real or virtual postings respectively
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]status:,\ status:!,\ status:*\f[B]\f[]
|
|
match unmarked, pending, or cleared transactions respectively
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[BC]tag:REGEX[=REGEX]\f[B]\f[]
|
|
match by tag name, and optionally also by tag value.
|
|
Note a tag: query is considered to match a transaction if it matches any
|
|
of the postings.
|
|
Also remember that postings inherit the tags of their parent
|
|
transaction.
|
|
.RS
|
|
.RE
|
|
.PP
|
|
The following special search term is used automatically in hledger\-web,
|
|
only:
|
|
.TP
|
|
.B \f[B]\f[BC]inacct:ACCTNAME\f[B]\f[]
|
|
tells hledger\-web to show the transaction register for this account.
|
|
Can be filtered further with \f[C]acct\f[] etc.
|
|
.RS
|
|
.RE
|
|
.PP
|
|
Some of these can also be expressed as command\-line options (eg
|
|
\f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]).
|
|
Generally you can mix options and query arguments, and the resulting
|
|
query will be their intersection (perhaps excluding the
|
|
\f[C]\-p/\-\-period\f[] option).
|
|
.SH COMMANDS
|
|
.PP
|
|
hledger provides a number of subcommands; \f[C]hledger\f[] with no
|
|
arguments shows a list.
|
|
.PP
|
|
If you install additional \f[C]hledger\-*\f[] packages, or if you put
|
|
programs or scripts named \f[C]hledger\-NAME\f[] in your PATH, these
|
|
will also be listed as subcommands.
|
|
.PP
|
|
Run a subcommand by writing its name as first argument (eg
|
|
\f[C]hledger\ incomestatement\f[]).
|
|
You can also write one of the standard short aliases displayed in
|
|
parentheses in the command list (\f[C]hledger\ b\f[]), or any any
|
|
unambiguous prefix of a command name (\f[C]hledger\ inc\f[]).
|
|
.PP
|
|
Here are all the builtin commands in alphabetical order.
|
|
See also \f[C]hledger\f[] for a more organised command list, and
|
|
\f[C]hledger\ CMD\ \-h\f[] for detailed command help.
|
|
.SS accounts
|
|
.PP
|
|
Show account names.
|
|
Alias: a.
|
|
.TP
|
|
.B \f[C]\-\-declared\f[]
|
|
show account names declared with account directives
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-used\f[]
|
|
show account names posted to by transactions
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-tree\f[]
|
|
show short account names and their parents, as a tree
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-flat\f[]
|
|
show full account names, as a list (default)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-drop=N\f[]
|
|
in flat mode: omit N leading account name parts
|
|
.RS
|
|
.RE
|
|
.PP
|
|
This command lists account names, either declared with account
|
|
directives (\[en]declared), posted to (\[en]used), or both (default).
|
|
With query arguments, only matched account names and account names
|
|
referenced by matched postings are shown.
|
|
It shows a flat list by default.
|
|
With \f[C]\-\-tree\f[], it uses indentation to show the account
|
|
hierarchy.
|
|
In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few
|
|
account name components.
|
|
Account names can be depth\-clipped with \f[C]\-\-depth\ N\f[] or
|
|
depth:N.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ accounts\ \-\-tree
|
|
assets
|
|
\ \ bank
|
|
\ \ \ \ checking
|
|
\ \ \ \ saving
|
|
\ \ cash
|
|
expenses
|
|
\ \ food
|
|
\ \ supplies
|
|
income
|
|
\ \ gifts
|
|
\ \ salary
|
|
liabilities
|
|
\ \ debts
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ accounts\ \-\-drop\ 1
|
|
bank:checking
|
|
bank:saving
|
|
cash
|
|
food
|
|
supplies
|
|
gifts
|
|
salary
|
|
debts
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ accounts
|
|
assets:bank:checking
|
|
assets:bank:saving
|
|
assets:cash
|
|
expenses:food
|
|
expenses:supplies
|
|
income:gifts
|
|
income:salary
|
|
liabilities:debts
|
|
\f[]
|
|
.fi
|
|
.SS activity
|
|
.PP
|
|
Show an ascii barchart of posting counts per interval.
|
|
.PP
|
|
The activity command displays an ascii histogram showing transaction
|
|
counts by day, week, month or other reporting interval (by day is the
|
|
default).
|
|
With query arguments, it counts only matched transactions.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ activity\ \-\-quarterly
|
|
2008\-01\-01\ **
|
|
2008\-04\-01\ *******
|
|
2008\-07\-01\
|
|
2008\-10\-01\ **
|
|
\f[]
|
|
.fi
|
|
.SS add
|
|
.PP
|
|
Prompt for transactions and add them to the journal.
|
|
.TP
|
|
.B \f[C]\-\-no\-new\-accounts\f[]
|
|
don't allow creating new accounts; helps prevent typos when entering
|
|
account names
|
|
.RS
|
|
.RE
|
|
.PP
|
|
Many hledger users edit their journals directly with a text editor, or
|
|
generate them from CSV.
|
|
For more interactive data entry, there is the \f[C]add\f[] command,
|
|
which prompts interactively on the console for new transactions, and
|
|
appends them to the journal file (if there are multiple
|
|
\f[C]\-f\ FILE\f[] options, the first file is used.) Existing
|
|
transactions are not changed.
|
|
This is the only hledger command that writes to the journal file.
|
|
.PP
|
|
To use it, just run \f[C]hledger\ add\f[] and follow the prompts.
|
|
You can add as many transactions as you like; when you are finished,
|
|
enter \f[C]\&.\f[] or press control\-d or control\-c to exit.
|
|
.PP
|
|
Features:
|
|
.IP \[bu] 2
|
|
add tries to provide useful defaults, using the most similar recent
|
|
transaction (by description) as a template.
|
|
.IP \[bu] 2
|
|
You can also set the initial defaults with command line arguments.
|
|
.IP \[bu] 2
|
|
Readline\-style edit keys can be used during data entry.
|
|
.IP \[bu] 2
|
|
The tab key will auto\-complete whenever possible \- accounts,
|
|
descriptions, dates (\f[C]yesterday\f[], \f[C]today\f[],
|
|
\f[C]tomorrow\f[]).
|
|
If the input area is empty, it will insert the default value.
|
|
.IP \[bu] 2
|
|
If the journal defines a default commodity, it will be added to any bare
|
|
numbers entered.
|
|
.IP \[bu] 2
|
|
A parenthesised transaction code may be entered following a date.
|
|
.IP \[bu] 2
|
|
Comments and tags may be entered following a description or amount.
|
|
.IP \[bu] 2
|
|
If you make a mistake, enter \f[C]<\f[] at any prompt to restart the
|
|
transaction.
|
|
.IP \[bu] 2
|
|
Input prompts are displayed in a different colour when the terminal
|
|
supports it.
|
|
.PP
|
|
Example (see the tutorial for a detailed explanation):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ add
|
|
Adding\ transactions\ to\ journal\ file\ /src/hledger/examples/sample.journal
|
|
Any\ command\ line\ arguments\ will\ be\ used\ as\ defaults.
|
|
Use\ tab\ key\ to\ complete,\ readline\ keys\ to\ edit,\ enter\ to\ accept\ defaults.
|
|
An\ optional\ (CODE)\ may\ follow\ transaction\ dates.
|
|
An\ optional\ ;\ COMMENT\ may\ follow\ descriptions\ or\ amounts.
|
|
If\ you\ make\ a\ mistake,\ enter\ <\ at\ any\ prompt\ to\ restart\ the\ transaction.
|
|
To\ end\ a\ transaction,\ enter\ .\ when\ prompted.
|
|
To\ quit,\ enter\ .\ at\ a\ date\ prompt\ or\ press\ control\-d\ or\ control\-c.
|
|
Date\ [2015/05/22]:\
|
|
Description:\ supermarket
|
|
Account\ 1:\ expenses:food
|
|
Amount\ \ 1:\ $10
|
|
Account\ 2:\ assets:checking
|
|
Amount\ \ 2\ [$\-10.0]:\
|
|
Account\ 3\ (or\ .\ or\ enter\ to\ finish\ this\ transaction):\ .
|
|
2015/05/22\ supermarket
|
|
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ $10
|
|
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ $\-10.0
|
|
|
|
Save\ this\ transaction\ to\ the\ journal\ ?\ [y]:\
|
|
Saved.
|
|
Starting\ the\ next\ transaction\ (.\ or\ ctrl\-D/ctrl\-C\ to\ quit)
|
|
Date\ [2015/05/22]:\ <CTRL\-D>\ $
|
|
\f[]
|
|
.fi
|
|
.SS balance
|
|
.PP
|
|
Show accounts and their balances.
|
|
Aliases: b, bal.
|
|
.TP
|
|
.B \f[C]\-\-change\f[]
|
|
show balance change in each period (default)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-cumulative\f[]
|
|
show balance change accumulated across periods (in multicolumn reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-H\ \-\-historical\f[]
|
|
show historical ending balance in each period (includes postings before
|
|
report start date)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-tree\f[]
|
|
show accounts as a tree; amounts include subaccounts (default in simple
|
|
reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-flat\f[]
|
|
show accounts as a list; amounts exclude subaccounts except when account
|
|
is depth\-clipped (default in multicolumn reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-A\ \-\-average\f[]
|
|
show a row average column (in multicolumn mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-T\ \-\-row\-total\f[]
|
|
show a row total column (in multicolumn mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-N\ \-\-no\-total\f[]
|
|
don't show the final total row
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-drop=N\f[]
|
|
omit N leading account name parts (in flat mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-no\-elide\f[]
|
|
don't squash boring parent accounts (in tree mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-format=LINEFORMAT\f[]
|
|
in single\-column balance reports: use this custom line format
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[]
|
|
select the output format.
|
|
Supported formats: txt, csv, html.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[]
|
|
write output to FILE.
|
|
A file extension matching one of the above formats selects that format.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-pretty\-tables\f[]
|
|
use unicode to display prettier tables.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-sort\-amount\f[]
|
|
sort by amount instead of account code/name (in flat mode).
|
|
With multiple columns, sorts by the row total, or by row average if that
|
|
is displayed.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-invert\f[]
|
|
display all amounts with reversed sign
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-budget\f[]
|
|
show performance compared to budget goals defined by periodic
|
|
transactions
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-show\-unbudgeted\f[]
|
|
with \[en]budget, show unbudgeted accounts also
|
|
.RS
|
|
.RE
|
|
.PP
|
|
The balance command is hledger's most versatile command.
|
|
Note, despite the name, it is not always used for showing real\-world
|
|
account balances; the more accounting\-aware balancesheet and
|
|
incomestatement may be more convenient for that.
|
|
.PP
|
|
By default, it displays all accounts, and each account's change in
|
|
balance during the entire period of the journal.
|
|
Balance changes are calculated by adding up the postings in each
|
|
account.
|
|
You can limit the postings matched, by a query, to see fewer accounts,
|
|
changes over a different time period, changes from only cleared
|
|
transactions, etc.
|
|
.PP
|
|
If you include an account's complete history of postings in the report,
|
|
the balance change is equivalent to the account's current ending
|
|
balance.
|
|
For a real\-world account, typically you won't have all transactions in
|
|
the journal; instead you'll have all transactions after a certain date,
|
|
and an \[lq]opening balances\[rq] transaction setting the correct
|
|
starting balance on that date.
|
|
Then the balance command will show real\-world account balances.
|
|
In some cases the \-H/\[en]historical flag is used to ensure this (more
|
|
below).
|
|
.PP
|
|
The balance command can produce several styles of report:
|
|
.SS Classic balance report
|
|
.PP
|
|
This is the original balance report, as found in Ledger.
|
|
It usually looks like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
By default, accounts are displayed hierarchically, with subaccounts
|
|
indented below their parent.
|
|
At each level of the tree, accounts are sorted by account code if any,
|
|
then by account name.
|
|
Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount.
|
|
.PP
|
|
\[lq]Boring\[rq] accounts, which contain a single interesting subaccount
|
|
and no balance of their own, are elided into the following line for more
|
|
compact output.
|
|
(Eg above, the \[lq]liabilities\[rq] account.) Use
|
|
\f[C]\-\-no\-elide\f[] to prevent this.
|
|
.PP
|
|
Account balances are \[lq]inclusive\[rq] \- they include the balances of
|
|
any subaccounts.
|
|
.PP
|
|
Accounts which have zero balance (and no non\-zero subaccounts) are
|
|
omitted.
|
|
Use \f[C]\-E/\-\-empty\f[] to show them.
|
|
.PP
|
|
A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to
|
|
suppress it, eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies
|
|
\f[]
|
|
.fi
|
|
.SS Customising the classic balance report
|
|
.PP
|
|
You can customise the layout of classic balance reports with
|
|
\f[C]\-\-format\ FMT\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-\-format\ "%20(account)\ %12(total)"
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ $\-1
|
|
\ \ \ \ \ \ \ \ \ bank:saving\ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ cash\ \ \ \ \ \ \ \ \ \ $\-2
|
|
\ \ \ \ \ \ \ \ \ \ \ \ expenses\ \ \ \ \ \ \ \ \ \ \ $2
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ food\ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ \ \ \ \ \ \ \ \ supplies\ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ income\ \ \ \ \ \ \ \ \ \ $\-2
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ gifts\ \ \ \ \ \ \ \ \ \ $\-1
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ salary\ \ \ \ \ \ \ \ \ \ $\-1
|
|
\ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ $1
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The FMT format string (plus a newline) specifies the formatting applied
|
|
to each account/balance pair.
|
|
It may contain any suitable text, with data fields interpolated like so:
|
|
.PP
|
|
\f[C]%[MIN][.MAX](FIELDNAME)\f[]
|
|
.IP \[bu] 2
|
|
MIN pads with spaces to at least this width (optional)
|
|
.IP \[bu] 2
|
|
MAX truncates at this width (optional)
|
|
.IP \[bu] 2
|
|
FIELDNAME must be enclosed in parentheses, and can be one of:
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
\f[C]depth_spacer\f[] \- a number of spaces equal to the account's
|
|
depth, or if MIN is specified, MIN * depth spaces.
|
|
.IP \[bu] 2
|
|
\f[C]account\f[] \- the account's name
|
|
.IP \[bu] 2
|
|
\f[C]total\f[] \- the account's balance/posted total, right justified
|
|
.RE
|
|
.PP
|
|
Also, FMT can begin with an optional prefix to control how
|
|
multi\-commodity amounts are rendered:
|
|
.IP \[bu] 2
|
|
\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default)
|
|
.IP \[bu] 2
|
|
\f[C]%^\f[] \- render on multiple lines, top\-aligned
|
|
.IP \[bu] 2
|
|
\f[C]%,\f[] \- render on one line, comma\-separated
|
|
.PP
|
|
There are some quirks.
|
|
Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead
|
|
\f[C]%(account)\f[] has indentation built in.
|
|
Experimentation may be needed to get pleasing results.
|
|
.PP
|
|
Some example formats:
|
|
.IP \[bu] 2
|
|
\f[C]%(total)\f[] \- the account's total
|
|
.IP \[bu] 2
|
|
\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded
|
|
to 20 characters and clipped at 20 characters
|
|
.IP \[bu] 2
|
|
\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50
|
|
characters, total padded to 20 characters, with multiple commodities
|
|
rendered on one line
|
|
.IP \[bu] 2
|
|
\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default
|
|
format for the single\-column balance report
|
|
.SS Colour support
|
|
.PP
|
|
The balance command shows negative amounts in red, if:
|
|
.IP \[bu] 2
|
|
the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[]
|
|
.IP \[bu] 2
|
|
the output is not being redirected or piped anywhere
|
|
.SS Flat mode
|
|
.PP
|
|
To see a flat list instead of the default hierarchical display, use
|
|
\f[C]\-\-flat\f[].
|
|
In this mode, accounts (unless depth\-clipped) show their full names and
|
|
\[lq]exclusive\[rq] balance, excluding any subaccount balances.
|
|
In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first
|
|
few account name components.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-N\ \-\-flat\ \-\-drop\ 1
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ food
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ supplies
|
|
\f[]
|
|
.fi
|
|
.SS Depth limited balance reports
|
|
.PP
|
|
With \f[C]\-\-depth\ N\f[] or \f[C]depth:N\f[] or just \f[C]\-N\f[],
|
|
balance reports show accounts only to the specified numeric depth.
|
|
This is very useful to summarise a complex set of accounts and get an
|
|
overview.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-N\ \-1
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Flat\-mode balance reports, which normally show exclusive balances, show
|
|
inclusive balances at the depth limit.
|
|
.SS Multicolumn balance report
|
|
.PP
|
|
Multicolumn or tabular balance reports are a very useful hledger
|
|
feature, and usually the preferred style.
|
|
They share many of the above features, but they show the report as a
|
|
table, with columns representing time periods.
|
|
This mode is activated by providing a reporting interval.
|
|
.PP
|
|
There are three types of multicolumn balance report, showing different
|
|
information:
|
|
.IP "1." 3
|
|
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 for a monthly income statement:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-\-quarterly\ income\ expenses\ \-E
|
|
Balance\ changes\ in\ 2008:
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2008q1\ \ 2008q2\ \ 2008q3\ \ 2008q4\
|
|
===================++=================================
|
|
\ expenses:food\ \ \ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\
|
|
\ expenses:supplies\ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\
|
|
\ income:gifts\ \ \ \ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\
|
|
\ income:salary\ \ \ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.IP "2." 3
|
|
With \f[C]\-\-cumulative\f[]: each column shows the ending balance for
|
|
that period, accumulating the changes across periods, starting from 0 at
|
|
the report start date:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-\-quarterly\ income\ expenses\ \-E\ \-\-cumulative
|
|
Ending\ balances\ (cumulative)\ in\ 2008:
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2008/03/31\ \ 2008/06/30\ \ 2008/09/30\ \ 2008/12/31\
|
|
===================++=================================================
|
|
\ expenses:food\ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\
|
|
\ expenses:supplies\ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\
|
|
\ income:gifts\ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\
|
|
\ income:salary\ \ \ \ \ ||\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.IP "3." 3
|
|
With \f[C]\-\-historical/\-H\f[]: each column shows the actual
|
|
historical ending balance for that period, accumulating the changes
|
|
across periods, starting from the actual balance at the report start
|
|
date.
|
|
This is useful eg for a multi\-period balance sheet, and when you are
|
|
showing only the data after a certain start date:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ ^assets\ ^liabilities\ \-\-quarterly\ \-\-historical\ \-\-begin\ 2008/4/1
|
|
Ending\ balances\ (historical)\ in\ 2008/04/01\-2008/12/31:
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2008/06/30\ \ 2008/09/30\ \ 2008/12/31\
|
|
======================++=====================================
|
|
\ assets:bank:checking\ ||\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ 0\
|
|
\ assets:bank:saving\ \ \ ||\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\
|
|
\ assets:cash\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ $\-2\ \ \ \ \ \ \ \ \ $\-2\ \ \ \ \ \ \ \ \ $\-2\
|
|
\ liabilities:debts\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ $1\
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Multicolumn balance reports display accounts in flat mode by default; to
|
|
see the hierarchy, use \f[C]\-\-tree\f[].
|
|
.PP
|
|
With a reporting interval (like \f[C]\-\-quarterly\f[] above), the
|
|
report start/end dates will be adjusted if necessary so that they
|
|
encompass the displayed report periods.
|
|
This is so that the first and last periods will be \[lq]full\[rq] and
|
|
comparable to the others.
|
|
.PP
|
|
The \f[C]\-E/\-\-empty\f[] flag does two things in multicolumn balance
|
|
reports: first, the report will show all columns within the specified
|
|
report period (without \-E, leading and trailing columns with all zeroes
|
|
are not shown).
|
|
Second, all accounts which existed at the report start date will be
|
|
considered, not just the ones with activity during the report period
|
|
(use \-E to include low\-activity accounts which would otherwise would
|
|
be omitted).
|
|
.PP
|
|
The \f[C]\-T/\-\-row\-total\f[] flag adds an additional column showing
|
|
the total for each row.
|
|
.PP
|
|
The \f[C]\-A/\-\-average\f[] flag adds a column showing the average
|
|
value in each row.
|
|
.PP
|
|
Here's an example of all three:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-Q\ income\ expenses\ \-\-tree\ \-ETA
|
|
Balance\ changes\ in\ 2008:
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2008q1\ \ 2008q2\ \ 2008q3\ \ 2008q4\ \ \ \ Total\ \ Average\
|
|
============++===================================================
|
|
\ expenses\ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $2\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ $2\ \ \ \ \ \ \ $1\
|
|
\ \ \ food\ \ \ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ 0\
|
|
\ \ \ supplies\ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ 0\
|
|
\ income\ \ \ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ $\-2\ \ \ \ \ \ $\-1\
|
|
\ \ \ gifts\ \ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ 0\
|
|
\ \ \ salary\ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ 0\
|
|
\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ 0\
|
|
|
|
#\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Limitations:
|
|
.PP
|
|
In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market
|
|
price on the report end date, for all columns (not the price on each
|
|
column's end date).
|
|
.PP
|
|
Eliding of boring parent accounts in tree mode, as in the classic
|
|
balance report, is not yet supported in multicolumn reports.
|
|
.SS Budget report
|
|
.PP
|
|
With \f[C]\-\-budget\f[], extra columns are displayed showing budget
|
|
goals for each account and period, if any.
|
|
Budget goals are defined by periodic transactions.
|
|
This is very useful for comparing planned and actual income, expenses,
|
|
time usage, etc.
|
|
\[en]budget is most often combined with a report interval.
|
|
.PP
|
|
For example, you can take average monthly expenses in the common expense
|
|
categories to construct a minimal monthly budget:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
;;\ Budget
|
|
~\ monthly
|
|
\ \ income\ \ $2000
|
|
\ \ expenses:food\ \ \ \ $400
|
|
\ \ expenses:bus\ \ \ \ \ $50
|
|
\ \ expenses:movies\ \ $30
|
|
\ \ assets:bank:checking
|
|
|
|
;;\ Two\ months\ worth\ of\ expenses
|
|
2017\-11\-01
|
|
\ \ income\ \ $1950
|
|
\ \ expenses:food\ \ \ \ $396
|
|
\ \ expenses:bus\ \ \ \ \ $49
|
|
\ \ expenses:movies\ \ $30
|
|
\ \ expenses:supplies\ \ $20
|
|
\ \ assets:bank:checking
|
|
|
|
2017\-12\-01
|
|
\ \ income\ \ $2100
|
|
\ \ expenses:food\ \ \ \ $412
|
|
\ \ expenses:bus\ \ \ \ \ $53
|
|
\ \ expenses:gifts\ \ \ $100
|
|
\ \ assets:bank:checking
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
You can now see a monthly budget report:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-M\ \-\-budget
|
|
Budget\ performance\ in\ 2017/11/01\-2017/12/31:
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
|
|
======================++=================================================
|
|
\ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
|
|
\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
|
|
\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\
|
|
\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\
|
|
\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\
|
|
\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
By default, only accounts with budget goals during the report period are
|
|
shown.
|
|
\f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as well.
|
|
Top\-level accounts with no budget goals anywhere below them are grouped
|
|
under \f[C]<unbudgeted>\f[].
|
|
.PP
|
|
You can roll over unspent budgets to next period with
|
|
\f[C]\-\-cumulative\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
|
|
Budget\ performance\ in\ 2017/11/01\-2017/12/31:
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\
|
|
======================++=================================================
|
|
\ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
|
|
\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
|
|
\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\
|
|
\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\
|
|
\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\
|
|
\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported
|
|
with \f[C]\-\-budget\f[].
|
|
.PP
|
|
For more examples, see Budgeting and Forecasting.
|
|
.SS Output format
|
|
.PP
|
|
The balance command supports output destination and output format
|
|
selection.
|
|
.SS balancesheet
|
|
.PP
|
|
This command displays a simple balance sheet, showing historical ending
|
|
balances of asset and liability accounts (ignoring any report begin
|
|
date).
|
|
It assumes that these accounts are under a top\-level \f[C]asset\f[] or
|
|
\f[C]liability\f[] account (case insensitive, plural forms also
|
|
allowed).
|
|
Note this report shows all account balances with normal positive sign
|
|
(like conventional financial statements, unlike balance/print/register)
|
|
(experimental).
|
|
(bs)
|
|
.TP
|
|
.B \f[C]\-\-change\f[]
|
|
show balance change in each period, instead of historical ending
|
|
balances
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-cumulative\f[]
|
|
show balance change accumulated across periods (in multicolumn reports),
|
|
instead of historical ending balances
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-H\ \-\-historical\f[]
|
|
show historical ending balance in each period (includes postings before
|
|
report start date) (default)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-tree\f[]
|
|
show accounts as a tree; amounts include subaccounts (default in simple
|
|
reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-flat\f[]
|
|
show accounts as a list; amounts exclude subaccounts except when account
|
|
is depth\-clipped (default in multicolumn reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-A\ \-\-average\f[]
|
|
show a row average column (in multicolumn mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-T\ \-\-row\-total\f[]
|
|
show a row total column (in multicolumn mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-N\ \-\-no\-total\f[]
|
|
don't show the final total row
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-drop=N\f[]
|
|
omit N leading account name parts (in flat mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-no\-elide\f[]
|
|
don't squash boring parent accounts (in tree mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-format=LINEFORMAT\f[]
|
|
in single\-column balance reports: use this custom line format
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-sort\-amount\f[]
|
|
sort by amount instead of account code/name
|
|
.RS
|
|
.RE
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balancesheet
|
|
Balance\ Sheet
|
|
|
|
Assets:
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
|
|
Liabilities:
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
With a reporting interval, multiple columns will be shown, one for each
|
|
report period.
|
|
As with multicolumn balance reports, you can alter the report mode with
|
|
\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[].
|
|
Normally balancesheet shows historical ending balances, which is what
|
|
you need for a balance sheet; note this means it ignores report begin
|
|
dates.
|
|
.PP
|
|
This command also supports output destination and output format
|
|
selection.
|
|
.SS balancesheetequity
|
|
.PP
|
|
Just like balancesheet, but also reports Equity (which it assumes is
|
|
under a top\-level \f[C]equity\f[] account).
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balancesheetequity
|
|
Balance\ Sheet\ With\ Equity
|
|
|
|
Assets:
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ assets
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-3\ \ \ \ cash
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
|
|
Liabilities:
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
|
|
Equity:
|
|
\ \ \ \ \ \ \ \ \ \ $1\ \ equity:owner
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ $1
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.SS cashflow
|
|
.PP
|
|
This command displays a simple cashflow statement, showing changes in
|
|
\[lq]cash\[rq] accounts.
|
|
It assumes that these accounts are under a top\-level \f[C]asset\f[]
|
|
account (case insensitive, plural forms also allowed) and do not contain
|
|
\f[C]receivable\f[] or \f[C]A/R\f[] in their name.
|
|
Note this report shows all account balances with normal positive sign
|
|
(like conventional financial statements, unlike balance/print/register)
|
|
(experimental).
|
|
(cf)
|
|
.TP
|
|
.B \f[C]\-\-change\f[]
|
|
show balance change in each period (default)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-cumulative\f[]
|
|
show balance change accumulated across periods (in multicolumn reports),
|
|
instead of changes during periods
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-H\ \-\-historical\f[]
|
|
show historical ending balance in each period (includes postings before
|
|
report start date), instead of changes during each period
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-tree\f[]
|
|
show accounts as a tree; amounts include subaccounts (default in simple
|
|
reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-flat\f[]
|
|
show accounts as a list; amounts exclude subaccounts except when account
|
|
is depth\-clipped (default in multicolumn reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-A\ \-\-average\f[]
|
|
show a row average column (in multicolumn mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-T\ \-\-row\-total\f[]
|
|
show a row total column (in multicolumn mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-N\ \-\-no\-total\f[]
|
|
don't show the final total row (in simple reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-drop=N\f[]
|
|
omit N leading account name parts (in flat mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-no\-elide\f[]
|
|
don't squash boring parent accounts (in tree mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-format=LINEFORMAT\f[]
|
|
in single\-column balance reports: use this custom line format
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-sort\-amount\f[]
|
|
sort by amount instead of account code/name
|
|
.RS
|
|
.RE
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ cashflow
|
|
Cashflow\ Statement
|
|
|
|
Cash\ flows:
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
With a reporting interval, multiple columns will be shown, one for each
|
|
report period.
|
|
Normally cashflow shows changes in assets per period, though as with
|
|
multicolumn balance reports you can alter the report mode with
|
|
\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[].
|
|
.PP
|
|
This command also supports output destination and output format
|
|
selection.
|
|
.SS check\-dates
|
|
.PP
|
|
Check that transactions are sorted by increasing date.
|
|
With a query, only matched transactions' dates are checked.
|
|
.SS check\-dupes
|
|
.PP
|
|
Report account names having the same leaf but different prefixes.
|
|
An example: http://stefanorodighiero.net/software/hledger\-dupes.html
|
|
.SS close
|
|
.PP
|
|
Print closing/opening transactions that bring some or all account
|
|
balances to zero and back.
|
|
Can be useful for bringing asset/liability balances across file
|
|
boundaries, or for closing out income/expenses for a period.
|
|
This was formerly called \[lq]equity\[rq], as in Ledger, and that alias
|
|
is also accepted.
|
|
See close \[en]help for more.
|
|
.SS help
|
|
.PP
|
|
Show any of the hledger manuals.
|
|
.PP
|
|
The \f[C]help\f[] command displays any of the main hledger manuals, in
|
|
one of several ways.
|
|
Run it with no argument to list the manuals, or provide a full or
|
|
partial manual name to select one.
|
|
.PP
|
|
hledger manuals are available in several formats.
|
|
hledger help will use the first of these display methods that it finds:
|
|
info, man, $PAGER, less, stdout (or when non\-interactive, just stdout).
|
|
You can force a particular viewer with the \f[C]\-\-info\f[],
|
|
\f[C]\-\-man\f[], \f[C]\-\-pager\f[], \f[C]\-\-cat\f[] flags.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ help
|
|
Please\ choose\ a\ manual\ by\ typing\ "hledger\ help\ MANUAL"\ (a\ substring\ is\ ok).
|
|
Manuals:\ hledger\ hledger\-ui\ hledger\-web\ hledger\-api\ journal\ csv\ timeclock\ timedot
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ help\ h\ \-\-man
|
|
|
|
hledger(1)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger\ User\ Manuals\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger(1)
|
|
|
|
NAME
|
|
\ \ \ \ \ \ \ hledger\ \-\ a\ command\-line\ accounting\ tool
|
|
|
|
SYNOPSIS
|
|
\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [ARGS]
|
|
\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [ARGS]
|
|
\ \ \ \ \ \ \ hledger
|
|
|
|
DESCRIPTION
|
|
\ \ \ \ \ \ \ hledger\ \ is\ \ a\ \ cross\-platform\ \ program\ \ for\ tracking\ money,\ time,\ or\ any
|
|
\&...
|
|
\f[]
|
|
.fi
|
|
.SS import
|
|
.PP
|
|
Read new transactions added to each FILE since last run, and add them to
|
|
the main journal file.
|
|
.TP
|
|
.B \f[C]\-\-dry\-run\f[]
|
|
just show the transactions to be imported
|
|
.RS
|
|
.RE
|
|
.PP
|
|
The input files are specified as arguments \- no need to write \-f
|
|
before each one.
|
|
So eg to add new transactions from all CSV files to the main journal,
|
|
it's just: \f[C]hledger\ import\ *.csv\f[]
|
|
.PP
|
|
New transactions are detected in the same way as print \[en]new: by
|
|
assuming transactions are always added to the input files in increasing
|
|
date order, and by saving \f[C]\&.latest.FILE\f[] state files.
|
|
.PP
|
|
The \[en]dry\-run output is in journal format, so you can filter it, eg
|
|
to see only uncategorised transactions:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ import\ \-\-dry\ ...\ |\ hledger\ \-f\-\ print\ unknown\ \-\-ignore\-assertions
|
|
\f[]
|
|
.fi
|
|
.SS incomestatement
|
|
.PP
|
|
This command displays a simple income statement, showing revenues and
|
|
expenses during a period.
|
|
It assumes that these accounts are under a top\-level \f[C]revenue\f[]
|
|
or \f[C]income\f[] or \f[C]expense\f[] account (case insensitive, plural
|
|
forms also allowed).
|
|
Note this report shows all account balances with normal positive sign
|
|
(like conventional financial statements, unlike balance/print/register)
|
|
(experimental).
|
|
(is)
|
|
.TP
|
|
.B \f[C]\-\-change\f[]
|
|
show balance change in each period (default)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-cumulative\f[]
|
|
show balance change accumulated across periods (in multicolumn reports),
|
|
instead of changes during periods
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-H\ \-\-historical\f[]
|
|
show historical ending balance in each period (includes postings before
|
|
report start date), instead of changes during each period
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-tree\f[]
|
|
show accounts as a tree; amounts include subaccounts (default in simple
|
|
reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-flat\f[]
|
|
show accounts as a list; amounts exclude subaccounts except when account
|
|
is depth\-clipped (default in multicolumn reports)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-A\ \-\-average\f[]
|
|
show a row average column (in multicolumn mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-T\ \-\-row\-total\f[]
|
|
show a row total column (in multicolumn mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-N\ \-\-no\-total\f[]
|
|
don't show the final total row
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-drop=N\f[]
|
|
omit N leading account name parts (in flat mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-no\-elide\f[]
|
|
don't squash boring parent accounts (in tree mode)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-format=LINEFORMAT\f[]
|
|
in single\-column balance reports: use this custom line format
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-sort\-amount\f[]
|
|
sort by amount instead of account code/name
|
|
.RS
|
|
.RE
|
|
.PP
|
|
This command displays a simple income statement.
|
|
It currently assumes that you have top\-level accounts named
|
|
\f[C]income\f[] (or \f[C]revenue\f[]) and \f[C]expense\f[] (plural forms
|
|
also allowed.)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ incomestatement
|
|
Income\ Statement
|
|
|
|
Revenues:
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
|
|
Expenses:
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
With a reporting interval, multiple columns will be shown, one for each
|
|
report period.
|
|
Normally incomestatement shows revenues/expenses per period, though as
|
|
with multicolumn balance reports you can alter the report mode with
|
|
\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[].
|
|
.PP
|
|
This command also supports output destination and output format
|
|
selection.
|
|
.SS prices
|
|
.PP
|
|
Print all market prices from the journal.
|
|
.SS print
|
|
.PP
|
|
Show transactions from the journal.
|
|
Aliases: p, txns.
|
|
.TP
|
|
.B \f[C]\-m\ STR\ \-\-match=STR\f[]
|
|
show the transaction whose description is most similar to STR, and is
|
|
most recent
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-new\f[]
|
|
show only newer\-dated transactions added in each file since last run
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-x\ \ \ \ \ \-\-explicit\f[]
|
|
show all amounts explicitly
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[]
|
|
select the output format.
|
|
Supported formats: txt, csv.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[]
|
|
write output to FILE.
|
|
A file extension matching one of the above formats selects that format.
|
|
.RS
|
|
.RE
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ print
|
|
2008/01/01\ income
|
|
\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
|
|
2008/06/01\ gift
|
|
\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
|
|
2008/06/02\ save
|
|
\ \ \ \ assets:bank:saving\ \ \ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
|
|
2008/06/03\ *\ eat\ &\ shop
|
|
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ expenses:supplies\ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
|
|
2008/12/31\ *\ pay\ off
|
|
\ \ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The print command displays full journal entries (transactions) from the
|
|
journal file in date order, tidily formatted.
|
|
print's output is always a valid hledger journal.
|
|
It preserves all transaction information, but it does not preserve
|
|
directives or inter\-transaction comments
|
|
.PP
|
|
Normally, the journal entry's explicit or implicit amount style is
|
|
preserved.
|
|
Ie when an amount is omitted in the journal, it will be omitted in the
|
|
output.
|
|
You can use the \f[C]\-x\f[]/\f[C]\-\-explicit\f[] flag to make all
|
|
amounts explicit, which can be useful for troubleshooting or for making
|
|
your journal more readable and robust against data entry errors.
|
|
Note, \f[C]\-x\f[] will cause postings with a multi\-commodity amount
|
|
(these can arise when a multi\-commodity transaction has an implicit
|
|
amount) will be split into multiple single\-commodity postings, for
|
|
valid journal output.
|
|
.PP
|
|
With \f[C]\-B\f[]/\f[C]\-\-cost\f[], amounts with transaction prices are
|
|
converted to cost using that price.
|
|
This can be used for troubleshooting.
|
|
.PP
|
|
With \f[C]\-m\f[]/\f[C]\-\-match\f[] and a STR argument, print will show
|
|
at most one transaction: the one one whose description is most similar
|
|
to STR, and is most recent.
|
|
STR should contain at least two characters.
|
|
If there is no similar\-enough match, no transaction will be shown.
|
|
.PP
|
|
With \f[C]\-\-new\f[], for each FILE being read, hledger reads (and
|
|
writes) a special state file (\f[C]\&.latest.FILE\f[] in the same
|
|
directory), containing the latest transaction date(s) that were seen
|
|
last time FILE was read.
|
|
When this file is found, only transactions with newer dates (and new
|
|
transactions on the latest date) are printed.
|
|
This is useful for ignoring already\-seen entries in import data, such
|
|
as downloaded CSV files.
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ bank1.csv\ print\ \-\-new
|
|
#\ shows\ transactions\ added\ since\ last\ print\ \-\-new\ on\ this\ file
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This assumes that transactions added to FILE always have same or
|
|
increasing dates, and that transactions on the same day do not get
|
|
reordered.
|
|
See also the import command.
|
|
.PP
|
|
This command also supports output destination and output format
|
|
selection.
|
|
Here's an example of print's CSV output:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ print\ \-Ocsv
|
|
"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting\-status","posting\-comment"
|
|
"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
|
|
"1","2008/01/01","","","","income","","income:salary","\-1","$","1","","",""
|
|
"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
|
|
"2","2008/06/01","","","","gift","","income:gifts","\-1","$","1","","",""
|
|
"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
|
|
"3","2008/06/02","","","","save","","assets:bank:checking","\-1","$","1","","",""
|
|
"4","2008/06/03","","*","","eat\ &\ shop","","expenses:food","1","$","","1","",""
|
|
"4","2008/06/03","","*","","eat\ &\ shop","","expenses:supplies","1","$","","1","",""
|
|
"4","2008/06/03","","*","","eat\ &\ shop","","assets:cash","\-2","$","2","","",""
|
|
"5","2008/12/31","","*","","pay\ off","","liabilities:debts","1","$","","1","",""
|
|
"5","2008/12/31","","*","","pay\ off","","assets:bank:checking","\-1","$","1","","",""
|
|
\f[]
|
|
.fi
|
|
.IP \[bu] 2
|
|
There is one CSV record per posting, with the parent transaction's
|
|
fields repeated.
|
|
.IP \[bu] 2
|
|
The \[lq]txnidx\[rq] (transaction index) field shows which postings
|
|
belong to the same transaction.
|
|
(This number might change if transactions are reordered within the file,
|
|
files are parsed/included in a different order, etc.)
|
|
.IP \[bu] 2
|
|
The amount is separated into \[lq]commodity\[rq] (the symbol) and
|
|
\[lq]amount\[rq] (numeric quantity) fields.
|
|
.IP \[bu] 2
|
|
The numeric amount is repeated in either the \[lq]credit\[rq] or
|
|
\[lq]debit\[rq] column, for convenience.
|
|
(Those names are not accurate in the accounting sense; it just puts
|
|
negative amounts under credit and zero or greater amounts under debit.)
|
|
.SS print\-unique
|
|
.PP
|
|
Print transactions which do not reuse an already\-seen description.
|
|
.SS register
|
|
.PP
|
|
Show postings and their running total.
|
|
Aliases: r, reg.
|
|
.TP
|
|
.B \f[C]\-\-cumulative\f[]
|
|
show running total from report start date (default)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-H\ \-\-historical\f[]
|
|
show historical running total/balance (includes postings before report
|
|
start date)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-A\ \-\-average\f[]
|
|
show running average of posting amounts instead of total (implies
|
|
\[en]empty)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-r\ \-\-related\f[]
|
|
show postings' siblings instead
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-w\ N\ \-\-width=N\f[]
|
|
set output width (default: terminal width or COLUMNS.
|
|
\-wN,M sets description width as well)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[]
|
|
select the output format.
|
|
Supported formats: txt, csv.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[]
|
|
write output to FILE.
|
|
A file extension matching one of the above formats selects that format.
|
|
.RS
|
|
.RE
|
|
.PP
|
|
The register command displays postings, one per line, and their running
|
|
total.
|
|
This is typically used with a query selecting a particular account, to
|
|
see that account's activity:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ register\ checking
|
|
2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
2008/06/01\ gift\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $2
|
|
2008/06/02\ save\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
2008/12/31\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The \f[C]\-\-historical\f[]/\f[C]\-H\f[] flag adds the balance from any
|
|
undisplayed prior postings to the running total.
|
|
This is useful when you want to see only recent activity, with a
|
|
historically accurate running balance:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ register\ checking\ \-b\ 2008/6\ \-\-historical
|
|
2008/06/01\ gift\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $2
|
|
2008/06/02\ save\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
2008/12/31\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The \f[C]\-\-depth\f[] option limits the amount of sub\-account detail
|
|
displayed.
|
|
.PP
|
|
The \f[C]\-\-average\f[]/\f[C]\-A\f[] flag shows the running average
|
|
posting amount instead of the running total (so, the final number
|
|
displayed is the average for the whole report period).
|
|
This flag implies \f[C]\-\-empty\f[] (see below).
|
|
It is affected by \f[C]\-\-historical\f[].
|
|
It works best when showing just one account and one commodity.
|
|
.PP
|
|
The \f[C]\-\-related\f[]/\f[C]\-r\f[] flag shows the \f[I]other\f[]
|
|
postings in the transactions of the postings which would normally be
|
|
shown.
|
|
.PP
|
|
With a reporting interval, register shows summary postings, one per
|
|
interval, aggregating the postings to each account:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ register\ \-\-monthly\ income
|
|
2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Periods with no activity, and summary postings with a zero amount, are
|
|
not shown by default; use the \f[C]\-\-empty\f[]/\f[C]\-E\f[] flag to
|
|
see them:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ register\ \-\-monthly\ income\ \-E
|
|
2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
2008/02\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
2008/03\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
2008/04\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
2008/05\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
2008/07\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
2008/08\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
2008/09\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
2008/10\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
2008/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
2008/12\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Often, you'll want to see just one line per interval.
|
|
The \f[C]\-\-depth\f[] option helps with this, causing subaccounts to be
|
|
aggregated:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ register\ \-\-monthly\ assets\ \-\-depth\ 1h
|
|
2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $1
|
|
2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0
|
|
2008/12\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note when using report intervals, if you specify start/end dates these
|
|
will be adjusted outward if necessary to contain a whole number of
|
|
intervals.
|
|
This ensures that the first and last intervals are full length and
|
|
comparable to the others in the report.
|
|
.SS Custom register output
|
|
.PP
|
|
register uses the full terminal width by default, except on windows.
|
|
You can override this by setting the \f[C]COLUMNS\f[] environment
|
|
variable (not a bash shell variable) or by using the
|
|
\f[C]\-\-width\f[]/\f[C]\-w\f[] option.
|
|
.PP
|
|
The description and account columns normally share the space equally
|
|
(about half of (width \- 40) each).
|
|
You can adjust this by adding a description width as part of
|
|
\[en]width's argument, comma\-separated: \f[C]\-\-width\ W,D\f[] .
|
|
Here's a diagram:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ width\ (W)\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
|
|
date\ (10)\ \ description\ (D)\ \ \ \ \ \ \ account\ (W\-41\-D)\ \ \ \ \ amount\ (12)\ \ \ balance\ (12)
|
|
DDDDDDDDDD\ dddddddddddddddddddd\ \ aaaaaaaaaaaaaaaaaaa\ \ AAAAAAAAAAAA\ \ AAAAAAAAAAAA
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
and some examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ reg\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ use\ terminal\ width\ (or\ 80\ on\ windows)
|
|
$\ hledger\ reg\ \-w\ 100\ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ use\ width\ 100
|
|
$\ COLUMNS=100\ hledger\ reg\ \ \ \ \ \ \ \ \ #\ set\ with\ one\-time\ environment\ variable
|
|
$\ export\ COLUMNS=100;\ hledger\ reg\ #\ set\ till\ session\ end\ (or\ window\ resize)
|
|
$\ hledger\ reg\ \-w\ 100,40\ \ \ \ \ \ \ \ \ \ \ #\ set\ overall\ width\ 100,\ description\ width\ 40
|
|
$\ hledger\ reg\ \-w\ $COLUMNS,40\ \ \ \ \ \ #\ use\ terminal\ width,\ and\ set\ description\ width
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This command also supports output destination and output format
|
|
selection.
|
|
.SS register\-match
|
|
.PP
|
|
Print the one posting whose transaction description is closest to DESC,
|
|
in the style of the register command.
|
|
Helps ledger\-autosync detect already\-seen transactions when importing.
|
|
.SS rewrite
|
|
.PP
|
|
Print all transactions, adding custom postings to the matched ones.
|
|
.SS stats
|
|
.PP
|
|
Show some journal statistics.
|
|
.TP
|
|
.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[]
|
|
write output to FILE.
|
|
A file extension matching one of the above formats selects that format.
|
|
.RS
|
|
.RE
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ stats
|
|
Main\ journal\ file\ \ \ \ \ \ \ \ :\ /src/hledger/examples/sample.journal
|
|
Included\ journal\ files\ \ \ :\
|
|
Transactions\ span\ \ \ \ \ \ \ \ :\ 2008\-01\-01\ to\ 2009\-01\-01\ (366\ days)
|
|
Last\ transaction\ \ \ \ \ \ \ \ \ :\ 2008\-12\-31\ (2333\ days\ ago)
|
|
Transactions\ \ \ \ \ \ \ \ \ \ \ \ \ :\ 5\ (0.0\ per\ day)
|
|
Transactions\ last\ 30\ days:\ 0\ (0.0\ per\ day)
|
|
Transactions\ last\ 7\ days\ :\ 0\ (0.0\ per\ day)
|
|
Payees/descriptions\ \ \ \ \ \ :\ 5
|
|
Accounts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 8\ (depth\ 3)
|
|
Commodities\ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 1\ ($)
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The stats command displays summary information for the whole journal, or
|
|
a matched part of it.
|
|
With a reporting interval, it shows a report for each report period.
|
|
.PP
|
|
This command also supports output destination and output format
|
|
selection.
|
|
.SS tags
|
|
.PP
|
|
List all the tag names used in the journal.
|
|
With a TAGREGEX argument, only tag names matching the regular expression
|
|
(case insensitive) are shown.
|
|
With additional QUERY arguments, only transactions matching the query
|
|
are considered.
|
|
.SS test
|
|
.PP
|
|
Run built\-in unit tests.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ test
|
|
Cases:\ 74\ \ Tried:\ 74\ \ Errors:\ 0\ \ Failures:\ 0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This command runs hledger's built\-in unit tests and displays a quick
|
|
report.
|
|
With a regular expression argument, it selects only tests with matching
|
|
names.
|
|
It's mainly used in development, but it's also nice to be able to check
|
|
your hledger executable for smoke at any time.
|
|
.SH ADD\-ON COMMANDS
|
|
.PP
|
|
hledger also searches for external add\-on commands, and will include
|
|
these in the commands list.
|
|
These are programs or scripts in your PATH whose name starts with
|
|
\f[C]hledger\-\f[] and ends with a recognised file extension (currently:
|
|
no extension, \f[C]bat\f[],\f[C]com\f[],\f[C]exe\f[],
|
|
\f[C]hs\f[],\f[C]lhs\f[],\f[C]pl\f[],\f[C]py\f[],\f[C]rb\f[],\f[C]rkt\f[],\f[C]sh\f[]).
|
|
.PP
|
|
Add\-ons can be invoked like any hledger command, but there are a few
|
|
things to be aware of.
|
|
Eg if the \f[C]hledger\-web\f[] add\-on is installed,
|
|
.IP \[bu] 2
|
|
\f[C]hledger\ \-h\ web\f[] shows hledger's help, while
|
|
\f[C]hledger\ web\ \-h\f[] shows hledger\-web's help.
|
|
.IP \[bu] 2
|
|
Flags specific to the add\-on must have a preceding \f[C]\-\-\f[] to
|
|
hide them from hledger.
|
|
So \f[C]hledger\ web\ \-\-serve\ \-\-port\ 9000\f[] will be rejected;
|
|
you must use \f[C]hledger\ web\ \-\-\ \-\-serve\ \-\-port\ 9000\f[].
|
|
.IP \[bu] 2
|
|
You can always run add\-ons directly if preferred:
|
|
\f[C]hledger\-web\ \-\-serve\ \-\-port\ 9000\f[].
|
|
.PP
|
|
Add\-ons are a relatively easy way to add local features or experiment
|
|
with new ideas.
|
|
They can be written in any language, but haskell scripts have a big
|
|
advantage: they can use the same hledger (and haskell) library functions
|
|
that built\-in commands do, for command\-line options, journal parsing,
|
|
reporting, etc.
|
|
.PP
|
|
Here are some hledger add\-ons available:
|
|
.SS Official add\-ons
|
|
.PP
|
|
These are maintained and released along with hledger.
|
|
.SS api
|
|
.PP
|
|
hledger\-api serves hledger data as a JSON web API.
|
|
.SS ui
|
|
.PP
|
|
hledger\-ui provides an efficient curses\-style interface.
|
|
.SS web
|
|
.PP
|
|
hledger\-web provides a simple web interface.
|
|
.SS Third party add\-ons
|
|
.PP
|
|
These are maintained separately, and usually updated shortly after a
|
|
hledger release.
|
|
.SS diff
|
|
.PP
|
|
hledger\-diff shows differences in an account's transactions between one
|
|
journal file and another.
|
|
.SS iadd
|
|
.PP
|
|
hledger\-iadd is a curses\-style, more interactive replacement for the
|
|
add command.
|
|
.SS interest
|
|
.PP
|
|
hledger\-interest generates interest transactions for an account
|
|
according to various schemes.
|
|
.SS irr
|
|
.PP
|
|
hledger\-irr calculates the internal rate of return of an investment
|
|
account.
|
|
.SS Experimental add\-ons
|
|
.PP
|
|
These are available in source form in the hledger repo's bin/ directory;
|
|
installing them is pretty easy.
|
|
They may be less mature and documented than built\-in commands.
|
|
Reading and tweaking these is a good way to start making your own!
|
|
.SS autosync
|
|
.PP
|
|
hledger\-autosync is a symbolic link for easily running
|
|
ledger\-autosync, if installed.
|
|
ledger\-autosync does deduplicating conversion of OFX data and some CSV
|
|
formats, and can also download the data if your bank offers OFX Direct
|
|
Connect.
|
|
.SS chart
|
|
.PP
|
|
hledger\-chart.hs is an old pie chart generator, in need of some love.
|
|
.SS check
|
|
.PP
|
|
hledger\-check.hs checks more powerful account balance assertions.
|
|
.SH ENVIRONMENT
|
|
.PP
|
|
\f[B]COLUMNS\f[] The screen width used by the register command.
|
|
Default: the full terminal width.
|
|
.PP
|
|
\f[B]LEDGER_FILE\f[] The journal file path when not specified with
|
|
\f[C]\-f\f[].
|
|
Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps
|
|
\f[C]C:/Users/USER/.hledger.journal\f[]).
|
|
.SH FILES
|
|
.PP
|
|
Reads data from one or more files in hledger journal, timeclock,
|
|
timedot, or CSV format specified with \f[C]\-f\f[], or
|
|
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows,
|
|
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
|
|
.SH BUGS
|
|
.PP
|
|
The need to precede addon command options with \f[C]\-\-\f[] when
|
|
invoked from hledger is awkward.
|
|
.PP
|
|
When input data contains non\-ascii characters, a suitable system locale
|
|
must be configured (or there will be an unhelpful error).
|
|
Eg on POSIX, set LANG to something other than C.
|
|
.PP
|
|
In a Microsoft Windows CMD window, non\-ascii characters and colours are
|
|
not supported.
|
|
.PP
|
|
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
|
|
add.
|
|
.PP
|
|
Not all of Ledger's journal file syntax is supported.
|
|
See file format differences.
|
|
.PP
|
|
On large data files, hledger is slower and uses more memory than Ledger.
|
|
.SH TROUBLESHOOTING
|
|
.PP
|
|
Here are some issues you might encounter when you run hledger (and
|
|
remember you can also seek help from the IRC channel, mail list or bug
|
|
tracker):
|
|
.PP
|
|
\f[B]Successfully installed, but \[lq]No command `hledger'
|
|
found\[rq]\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
stack and cabal install binaries into a special directory, which should
|
|
be added to your PATH environment variable.
|
|
Eg on unix\-like systems, that is ~/.local/bin and ~/.cabal/bin
|
|
respectively.
|
|
.PP
|
|
\f[B]I set a custom LEDGER_FILE, but hledger is still using the default
|
|
file\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]LEDGER_FILE\f[] should be a real environment variable, not just a
|
|
shell variable.
|
|
The command \f[C]env\ |\ grep\ LEDGER_FILE\f[] should show it.
|
|
You may need to use \f[C]export\f[].
|
|
Here's an explanation.
|
|
.PP
|
|
\f[B]\[lq]Illegal byte sequence\[rq] or \[lq]Invalid or incomplete
|
|
multibyte or wide character\[rq] errors\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
In order to handle non\-ascii letters and symbols (like £), hledger
|
|
needs an appropriate locale.
|
|
This is usually configured system\-wide; you can also configure it
|
|
temporarily.
|
|
The locale may need to be one that supports UTF\-8, if you built hledger
|
|
with GHC < 7.2 (or possibly always, I'm not sure yet).
|
|
.PP
|
|
Here's an example of setting the locale temporarily, on ubuntu
|
|
gnu/linux:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ file\ my.journal
|
|
my.journal:\ UTF\-8\ Unicode\ text\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ the\ file\ is\ UTF8\-encoded
|
|
$\ locale\ \-a
|
|
C
|
|
en_US.utf8\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ a\ UTF8\-aware\ locale\ is\ available
|
|
POSIX
|
|
$\ LANG=en_US.utf8\ hledger\ \-f\ my.journal\ print\ \ \ #\ <\-\ use\ it\ for\ this\ command
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Here's one way to set it permanently, there are probably better ways:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ echo\ "export\ LANG=en_US.UTF\-8"\ >>~/.bash_profile
|
|
$\ bash\ \-\-login
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If we preferred to use eg \f[C]fr_FR.utf8\f[], we might have to install
|
|
that first:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ apt\-get\ install\ language\-pack\-fr
|
|
$\ locale\ \-a
|
|
C
|
|
en_US.utf8
|
|
fr_BE.utf8
|
|
fr_CA.utf8
|
|
fr_CH.utf8
|
|
fr_FR.utf8
|
|
fr_LU.utf8
|
|
POSIX
|
|
$\ LANG=fr_FR.utf8\ hledger\ \-f\ my.journal\ print
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note some platforms allow variant locale spellings, but not all (ubuntu
|
|
accepts \f[C]fr_FR.UTF8\f[], mac osx requires exactly
|
|
\f[C]fr_FR.UTF\-8\f[]).
|
|
|
|
|
|
.SH "REPORTING BUGS"
|
|
Report bugs at http://bugs.hledger.org
|
|
(or on the #hledger IRC channel or hledger mail list)
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Copyright (C) 2007-2016 Simon Michael.
|
|
.br
|
|
Released under GNU GPL v3 or later.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
|
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5),
|
|
ledger(1)
|
|
|
|
http://hledger.org
|