2621 lines
76 KiB
Groff
2621 lines
76 KiB
Groff
.\"t
|
|
|
|
.TH "hledger" "1" "January 2017" "hledger dev" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
hledger \- a command\-line accounting tool
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[C]hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [CMDARGS]\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [CMDARGS]\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[].
|
|
See COMMANDS and EXAMPLES below.
|
|
.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
|
|
.PP
|
|
To see general usage and the command list: \f[C]hledger\ \-h\f[] or just
|
|
\f[C]hledger\f[].
|
|
To see usage for a specific command: \f[C]hledger\ COMMAND\ \-h\f[].
|
|
.PP
|
|
hledger has several kinds of options:
|
|
.IP \[bu] 2
|
|
General options are always available and can appear anywhere on the
|
|
command line.
|
|
\f[C]hledger\ \-h\f[] shows these.
|
|
Eg: \f[C]hledger\ \-\-version\f[].
|
|
.IP \[bu] 2
|
|
Common reporting options are available with most commands.
|
|
These and all other non\-general options must be written after COMMAND.
|
|
\f[C]hledger\ COMMAND\ \-h\f[] shows these.
|
|
Eg: \f[C]hledger\ register\ \-\-cleared\f[].
|
|
.IP \[bu] 2
|
|
Command\-specific options are also provided by some commands.
|
|
\f[C]hledger\ COMMAND\ \-h\f[] shows these too.
|
|
Eg: \f[C]hledger\ register\ \-\-average\f[].
|
|
.IP \[bu] 2
|
|
Some hledger commands come from separate add\-on executables, which have
|
|
their own options.
|
|
\f[C]hledger\ COMMAND\ \-h\f[] shows these, as usual.
|
|
Such options, if not also supported by hledger, should be written
|
|
following a double hyphen argument (\f[C]\-\-\f[]) so that hledger\[aq]s
|
|
option parser does not complain.
|
|
Eg: \f[C]hledger\ ui\ \-\-\ \-\-register=checking\f[].
|
|
Or, you can just run the add\-on directly:
|
|
\f[C]hledger\-ui\ \-\-register=checking\f[].
|
|
.PP
|
|
Command arguments may also follow the command name.
|
|
In most cases these specify a query which filters the data.
|
|
Command options and arguments can be intermixed.
|
|
.PP
|
|
Option and argument values containing problematic characters should be
|
|
escaped with double quotes, backslashes, or (best) single quotes.
|
|
This means spaces, but 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 to the shell and also in regular
|
|
expressions, like parentheses, the pipe symbol and the dollar sign, must
|
|
sometimes be double\-escaped.
|
|
Eg, to match the dollar symbol:
|
|
\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] or
|
|
\f[C]hledger\ balance\ cur:\\\\$\f[].
|
|
.PP
|
|
There\[aq]s more..
|
|
options and arguments being passed by hledger to an add\-on executable
|
|
get de\-escaped once in the process.
|
|
In this case you might need triple\-escaping.
|
|
Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or
|
|
\f[C]hledger\ ui\ cur:\\\\\\\\$\f[].
|
|
.PP
|
|
If in doubt, keep things simple:
|
|
.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
|
|
.IP \[bu] 2
|
|
run add\-on executables directly
|
|
.PP
|
|
If you\[aq]re really curious, add \f[C]\-\-debug=2\f[] for
|
|
troubleshooting.
|
|
.SS General options
|
|
.PP
|
|
Always available, can be written before or after COMMAND.
|
|
.TP
|
|
.B \f[C]\-h\f[]
|
|
show general usage (or after COMMAND, the command\[aq]s usage)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-help\f[]
|
|
show the current program\[aq]s manual as plain text (or after an add\-on
|
|
COMMAND, the add\-on\[aq]s manual)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-man\f[]
|
|
show the current program\[aq]s manual with man
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-info\f[]
|
|
show the current program\[aq]s manual with info
|
|
.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
|
|
.TP
|
|
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[]
|
|
use a different input file.
|
|
For stdin, use \-
|
|
.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[]
|
|
display accounts named OLD as NEW
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-I\ \-\-ignore\-assertions\f[]
|
|
ignore any failing balance assertions in the journal
|
|
.RS
|
|
.RE
|
|
.SS Reporting options
|
|
.PP
|
|
Common reporting options, must be written after COMMAND.
|
|
.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
|
|
(overrides the flags above)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-date2\f[]
|
|
show, and match with \-b/\-e/\-p/date:, secondary dates instead
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-C\ \-\-cleared\f[]
|
|
include only cleared postings/txns
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-pending\f[]
|
|
include only pending postings/txns
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-U\ \-\-uncleared\f[]
|
|
include only uncleared (and pending) postings/txns
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-R\ \-\-real\f[]
|
|
include only non\-virtual postings
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-depth=N\f[]
|
|
hide accounts/postings deeper than N
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-E\ \-\-empty\f[]
|
|
show items with zero amount, normally hidden
|
|
.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]\-\-pivot\ TAGNAME\f[]
|
|
organize reports by some tag\[aq]s value instead of by account
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-anon\f[]
|
|
show anonymized accounts and payees
|
|
.RS
|
|
.RE
|
|
.PP
|
|
If a reporting option occurs more than once on the command line, the
|
|
last one takes precedence.
|
|
Eg \-p jan \-p feb is equivalent to \-p feb.
|
|
.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\[aq]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 "reader" in turn:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(10.7n) lw(33.2n) lw(26.1n).
|
|
T{
|
|
Reader:
|
|
T}@T{
|
|
Reads:
|
|
T}@T{
|
|
Used for file extensions:
|
|
T}
|
|
_
|
|
T{
|
|
\f[C]journal\f[]
|
|
T}@T{
|
|
hledger\[aq]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
|
|
"wrong" 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\[aq]s user interfaces accept a flexible "smart date" syntax
|
|
(unlike dates in the journal file).
|
|
Smart dates allow some english words, can be relative to today\[aq]s
|
|
date, and can have less\-significant date parts omitted (defaulting to
|
|
1).
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
\f[C]2009/1/1\f[], \f[C]2009/01/01\f[], \f[C]2009\-1\-1\f[],
|
|
\f[C]2009.1.1\f[]
|
|
T}@T{
|
|
simple dates, several separators allowed
|
|
T}
|
|
T{
|
|
\f[C]2009/1\f[], \f[C]2009\f[]
|
|
T}@T{
|
|
same as above \- a missing day or month defaults to 1
|
|
T}
|
|
T{
|
|
\f[C]1/1\f[], \f[C]january\f[], \f[C]jan\f[], \f[C]this\ year\f[]
|
|
T}@T{
|
|
relative dates, meaning january 1 of the current year
|
|
T}
|
|
T{
|
|
\f[C]next\ year\f[]
|
|
T}@T{
|
|
january 1 of next year
|
|
T}
|
|
T{
|
|
\f[C]this\ month\f[]
|
|
T}@T{
|
|
the 1st of the current month
|
|
T}
|
|
T{
|
|
\f[C]this\ week\f[]
|
|
T}@T{
|
|
the most recent monday
|
|
T}
|
|
T{
|
|
\f[C]last\ week\f[]
|
|
T}@T{
|
|
the monday of the week before this one
|
|
T}
|
|
T{
|
|
\f[C]lastweek\f[]
|
|
T}@T{
|
|
spaces are optional
|
|
T}
|
|
T{
|
|
\f[C]today\f[], \f[C]yesterday\f[], \f[C]tomorrow\f[]
|
|
T}@T{
|
|
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\[aq]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\[aq]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 "from" and "to" are optional, and so are the spaces, as
|
|
long as you don\[aq]t run two dates together.
|
|
"to" can also be written as "\-".
|
|
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 "from" or "to" 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 "2009/1/1 to 2010/1/1"
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "2009/1"\f[]
|
|
T}@T{
|
|
the month of jan; equivalent to "2009/1/1 to 2009/2/1"
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "2009/1/1"\f[]
|
|
T}@T{
|
|
just that day; equivalent to "2009/1/1 to 2009/1/2"
|
|
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
|
|
The following more complex report intervals are also supported:
|
|
\f[C]biweekly\f[], \f[C]bimonthly\f[],
|
|
\f[C]every\ N\ days|weeks|months|quarters|years\f[],
|
|
\f[C]every\ Nth\ day\ [of\ month]\f[],
|
|
\f[C]every\ Nth\ day\ of\ week\f[].
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[C]\-p\ "bimonthly\ from\ 2008"\f[]
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ 2\ weeks"\f[]
|
|
T}
|
|
T{
|
|
\f[C]\-p\ "every\ 5\ days\ from\ 1/3"\f[]
|
|
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, 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.
|
|
.SS Pivoting
|
|
.PP
|
|
Normally hledger sums amounts, and organizes them in a hierarchy, based
|
|
on account name.
|
|
The \f[C]\-\-pivot\ TAGNAME\f[] option causes it to sum and organize
|
|
hierarchy based on some other field instead.
|
|
.PP
|
|
TAGNAME is the full, case\-insensitive name of a tag you have defined,
|
|
or one of the built\-in implicit tags (like \f[C]code\f[] or
|
|
\f[C]payee\f[]).
|
|
As with account names, when tag values have
|
|
\f[C]multiple:colon\-separated:parts\f[] hledger will build hierarchy,
|
|
displayed in tree\-mode reports, summarisable with a depth limit, and so
|
|
on.
|
|
.PP
|
|
\f[C]\-\-pivot\f[] affects all reports, and is one of those options you
|
|
can write before the command name if you wish.
|
|
You can think of hledger transforming the journal before any other
|
|
processing, replacing every posting\[aq]s account name with the value of
|
|
the specified tag on that posting, inheriting it from the transaction or
|
|
using a blank value if it\[aq]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 "account
|
|
name"):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-\-pivot\ member\ acct:.
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
|
|
\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\[aq]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
|
|
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 a second time, with single
|
|
or double quotes or another backslash.
|
|
Eg, to match amounts with the dollar sign from the command line, write
|
|
\f[C]cur:\[aq]\\$\[aq]\f[] or \f[C]cur:\\\\$\f[].
|
|
.SH QUERIES
|
|
.PP
|
|
One of hledger\[aq]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, optional prefixes to match
|
|
specific fields.
|
|
Multiple search terms are combined as follows:
|
|
.PP
|
|
All commands except print: 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
|
|
all the other terms.
|
|
.PP
|
|
The print command: show 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:
|
|
.TP
|
|
.B \f[B]\f[C]REGEX\f[]\f[]
|
|
match account names by this regular expression
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]acct:REGEX\f[]\f[]
|
|
same as above
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]amt:N,\ amt:<N,\ amt:<=N,\ amt:>N,\ amt:>=N\f[]\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[C]code:REGEX\f[]\f[]
|
|
match by transaction code (eg check number)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]cur:REGEX\f[]\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[C]desc:REGEX\f[]\f[]
|
|
match transaction descriptions
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]date:PERIODEXPR\f[]\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[C]date2:PERIODEXPR\f[]\f[]
|
|
match secondary dates within the specified period.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]depth:N\f[]\f[]
|
|
match (or display, depending on command) accounts at or above this depth
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]real:,\ real:0\f[]\f[]
|
|
match real or virtual postings respectively
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]status:*,\ status:!,\ status:\f[]\f[]
|
|
match cleared, pending, or uncleared/pending transactions respectively
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]tag:REGEX[=REGEX]\f[]\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
|
|
.TP
|
|
.B \f[B]\f[C]not:\f[]\f[]
|
|
before any of the above negates the match.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[B]\f[C]inacct:ACCTNAME\f[]\f[]
|
|
a special term used automatically when you click an account name in
|
|
hledger\-web, specifying the account register we are currently in
|
|
(selects the transactions of that account and how to show them, can be
|
|
filtered further with \f[C]acct\f[] etc).
|
|
Not supported elsewhere in hledger.
|
|
.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 any unambiguous prefix of a command name
|
|
(\f[C]hledger\ inc\f[]), or one of the standard short aliases displayed
|
|
in the command list (\f[C]hledger\ is\f[]).
|
|
.SS accounts
|
|
.PP
|
|
Show account names.
|
|
.TP
|
|
.B \f[C]\-\-tree\f[]
|
|
show short account names, 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 all account names that are in use (ie, all the
|
|
accounts which have at least one transaction posting to them).
|
|
With query arguments, only matched account names are shown.
|
|
.PP
|
|
It shows a flat list by default.
|
|
With \f[C]\-\-tree\f[], it uses indentation to show the account
|
|
hierarchy.
|
|
.PP
|
|
In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few
|
|
account name components.
|
|
.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\[aq]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.
|
|
Alias: 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\[aq]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\[aq]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.
|
|
.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 balance command displays accounts and balances.
|
|
It is hledger\[aq]s most featureful and most useful command.
|
|
.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
|
|
More precisely, the balance command shows the \f[I]change\f[] to each
|
|
account\[aq]s balance caused by all (matched) postings.
|
|
In the common case where you do not filter by date and your journal sets
|
|
the correct opening balances, this is the same as the account\[aq]s
|
|
ending balance.
|
|
.PP
|
|
By default, accounts are displayed hierarchically, with subaccounts
|
|
indented below their parent.
|
|
"Boring" accounts, which contain a single interesting subaccount and no
|
|
balance of their own, are elided into the following line for more
|
|
compact output.
|
|
(Use \f[C]\-\-no\-elide\f[] to prevent this.)
|
|
.PP
|
|
Each account\[aq]s balance is the "inclusive" balance \- it includes 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:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies
|
|
\f[]
|
|
.fi
|
|
.SS Flat mode
|
|
.PP
|
|
To see a flat list of full account names instead of the default
|
|
hierarchical display, use \f[C]\-\-flat\f[].
|
|
In this mode, accounts (unless depth\-clipped) show their "exclusive"
|
|
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[], balance shows accounts only to the specified
|
|
depth.
|
|
This is very useful to show a complex charts of accounts in less detail.
|
|
In flat mode, balances from accounts below the depth limit will be shown
|
|
as part of a parent account at the depth limit.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ balance\ \-N\ \-\-depth\ 1
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities
|
|
\f[]
|
|
.fi
|
|
.SS Multicolumn balance reports
|
|
.PP
|
|
With a reporting interval, multiple balance columns will be shown, one
|
|
for each report period.
|
|
There are three types of multi\-column balance report, showing different
|
|
information:
|
|
.IP "1." 3
|
|
By default: each column shows the sum of postings in that period, ie the
|
|
account\[aq]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
|
|
Multi\-column 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 "full" 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\[aq]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
|
|
.SS Market value
|
|
.PP
|
|
The \f[C]\-V/\-\-value\f[] flag converts the reported amounts to their
|
|
market value on the report end date, using the most recent applicable
|
|
market prices, when known.
|
|
Specifically, when there is a market price (P directive) for the
|
|
amount\[aq]s commodity, dated on or before the report end date (see
|
|
hledger \-> Report start & end date), the amount will be converted to
|
|
the price\[aq]s commodity.
|
|
If multiple applicable prices are defined, the latest\-dated one is used
|
|
(and if dates are equal, the one last parsed).
|
|
.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\ euros
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
What are they worth on nov 3 ?
|
|
(no report end date specified, defaults to the last date in the journal)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ t.j\ bal\ euros\ \-V
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
What are they worth on dec 21 ?
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Currently, hledger\[aq]s \-V only uses market prices recorded with P
|
|
directives, not transaction prices (unlike Ledger).
|
|
.PP
|
|
Using \-B and \-V together is allowed.
|
|
.SS Custom balance output
|
|
.PP
|
|
In simple (non\-multi\-column) balance reports, you can customise the
|
|
output 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\[aq]s
|
|
depth, or if MIN is specified, MIN * depth spaces.
|
|
.IP \[bu] 2
|
|
\f[C]account\f[] \- the account\[aq]s name
|
|
.IP \[bu] 2
|
|
\f[C]total\f[] \- the account\[aq]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\[aq]s total
|
|
.IP \[bu] 2
|
|
\f[C]%\-20.20(account)\f[] \- the account\[aq]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 Output destination
|
|
.PP
|
|
The balance, print, register and stats 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 CSV output
|
|
.PP
|
|
The balance, print and register commands can write their output as CSV.
|
|
This is useful for exporting data to other applications, eg to make
|
|
charts in a spreadsheet.
|
|
This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by
|
|
specifying a \f[C]\&.csv\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 balancesheet
|
|
.PP
|
|
Show a balance sheet.
|
|
Alias: 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\[aq]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\[aq]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
|
|
.PP
|
|
This command displays a simple balance sheet.
|
|
It currently assumes that you have top\-level accounts named
|
|
\f[C]asset\f[] and \f[C]liability\f[] (plural forms also allowed.)
|
|
.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
|
|
If given a period flag, renders a multi\-column balance with the same
|
|
format as \f[C]balance\f[], with asset and liability totals as well as
|
|
an overall total if desired.
|
|
.PP
|
|
This command shows normally historical end\-balance reports, but for
|
|
flexibility, also accepts \f[C]\-\-cumulative\f[] and
|
|
\f[C]\-\-change\f[] to display cumulative ending balances and changes in
|
|
reporting periods.
|
|
.SS cashflow
|
|
.PP
|
|
Show a cashflow statement.
|
|
Alias: 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\[aq]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\[aq]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
|
|
.PP
|
|
This command displays a simple cashflow statement It shows the change in
|
|
all "cash" (ie, liquid assets) accounts for the period.
|
|
It currently assumes that cash accounts are under a top\-level account
|
|
named \f[C]asset\f[] and do not contain \f[C]receivable\f[] or
|
|
\f[C]A/R\f[] (plural forms also allowed.)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ cashflow
|
|
Cashflow\ Statement
|
|
|
|
Cash\ flows:
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If given a period flag, renders a multi\-column balance with the same
|
|
format as \f[C]balance\f[].
|
|
.PP
|
|
This command normally shows period change reports, but for flexibility,
|
|
also accepts \f[C]\-\-cumulative\f[] and \f[C]\-\-historical\f[] to
|
|
display cumulative ending balances and historical ending balances, as
|
|
well.
|
|
.SS help
|
|
.PP
|
|
Show any of the hledger manuals.
|
|
.PP
|
|
The \f[C]help\f[] command displays any of the main hledger man pages.
|
|
(Unlike \f[C]hledger\ \-\-help\f[], which displays only the hledger man
|
|
page.) Run it with no arguments to list available topics (their names
|
|
are shortened for easier typing), and run \f[C]hledger\ help\ TOPIC\f[]
|
|
to select one.
|
|
The output is similar to a man page, but fixed width.
|
|
It may be long, so you may wish to pipe it into a pager.
|
|
See also info and man.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ help
|
|
Choose\ a\ topic,\ eg:\ hledger\ help\ cli
|
|
cli,\ ui,\ web,\ api,\ journal,\ csv,\ timeclock,\ timedot
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ hledger\ help\ cli\ |\ less
|
|
|
|
hledger(1)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger\ User\ Manuals\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger(1)
|
|
|
|
|
|
|
|
NAME
|
|
\ \ \ \ \ \ \ hledger\ \-\ a\ command\-line\ accounting\ tool
|
|
|
|
SYNOPSIS
|
|
\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [CMDARGS]
|
|
\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [CMDARGS]
|
|
:
|
|
\f[]
|
|
.fi
|
|
.SS incomestatement
|
|
.PP
|
|
Show an income statement.
|
|
Alias: 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\[aq]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\[aq]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
|
|
.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
|
|
If given a period flag, renders a multi\-column balance with the same
|
|
format as \f[C]balance\f[].
|
|
.PP
|
|
This command normally shows period change reports, but for flexibility,
|
|
also accepts \f[C]\-\-cumulative\f[] and \f[C]\-\-historical\f[] to
|
|
display cumulative ending balances and historical ending balances, as
|
|
well.
|
|
.SS info
|
|
.PP
|
|
Show any of the hledger manuals using info.
|
|
.PP
|
|
The \f[C]info\f[] command displays any of the hledger reference manuals
|
|
using the info hypertextual documentation viewer.
|
|
This can be a very efficient way to browse large manuals.
|
|
It requires the "info" program to be available in your PATH.
|
|
.PP
|
|
As with help, run it with no arguments to list available topics
|
|
(manuals).
|
|
.SS man
|
|
.PP
|
|
Show any of the hledger manuals using man.
|
|
.PP
|
|
The \f[C]man\f[] command displays any of the hledger reference manuals
|
|
using man, the standard documentation viewer on unix systems.
|
|
This will fit the text to your terminal width, and probably invoke a
|
|
pager automatically.
|
|
It requires the "man" program to be available in your PATH.
|
|
.PP
|
|
As with help, run it with no arguments to list available topics
|
|
(manuals).
|
|
.SS print
|
|
.PP
|
|
Show transactions from the journal.
|
|
.TP
|
|
.B \f[C]\-x\ \ \ \ \ \-\-explicit\f[]
|
|
show all amounts explicitly
|
|
.RS
|
|
.RE
|
|
.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]\-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, tidily formatted.
|
|
.PP
|
|
As of hledger 1.2, print\[aq]s output is always a valid hledger journal.
|
|
However it may not preserve all original content, eg it does not print
|
|
directives or inter\-transaction comments.
|
|
.PP
|
|
Normally, transactions\[aq] implicit/explicit amount style is preserved:
|
|
when an amount is omitted in the journal, it will be omitted in the
|
|
output.
|
|
You can use the \f[C]\-x/\-\-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, in this mode postings with a multi\-commodity amount (possible
|
|
with an implicit amount in a multi\-commodity transaction) will be split
|
|
into multiple single\-commodity postings, for valid journal output.
|
|
.PP
|
|
With \-B/\-\-cost, amounts with transaction prices are converted to cost
|
|
(using the transaction price).
|
|
.PP
|
|
The print command also supports output destination and CSV output.
|
|
Here\[aq]s an example of print\[aq]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\[aq]s
|
|
fields repeated.
|
|
.IP \[bu] 2
|
|
The "txnidx" (transaction index) field shows which postings belong to
|
|
the same transaction.
|
|
(This number might change if transactions are reordered within the file,
|
|
files are parsed/included in a different order, etc.)
|
|
.IP \[bu] 2
|
|
The amount is separated into "commodity" (the symbol) and "amount"
|
|
(numeric quantity) fields.
|
|
.IP \[bu] 2
|
|
The numeric amount is repeated in either the "credit" or "debit" 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 register
|
|
.PP
|
|
Show postings and their running total.
|
|
Alias: 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
|
|
\-\-empty)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-r\ \-\-related\f[]
|
|
show postings\[aq] 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\[aq]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\[aq]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
|
|
\-\-width\[aq]s argument, comma\-separated: \f[C]\-\-width\ W,D\f[] .
|
|
Here\[aq]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
|
|
The register command also supports the \f[C]\-o/\-\-output\-file\f[] and
|
|
\f[C]\-O/\-\-output\-format\f[] options for controlling output
|
|
destination and CSV output.
|
|
.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
|
|
The stats command also supports \f[C]\-o/\-\-output\-file\f[] for
|
|
controlling output destination.
|
|
.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\[aq]s built\-in unit tests and displays a
|
|
quick report.
|
|
With a regular expression argument, it selects only tests with matching
|
|
names.
|
|
It\[aq]s mainly used in development, but it\[aq]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\[aq]s help, while
|
|
\f[C]hledger\ web\ \-h\f[] shows hledger\-web\[aq]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\[aq]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\[aq]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 budget
|
|
.PP
|
|
hledger\-budget.hs adds more budget\-tracking features to hledger.
|
|
.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.
|
|
.SS check\-dates
|
|
.PP
|
|
hledger\-check\-dates.hs checks that journal entries are ordered by
|
|
date.
|
|
.SS check\-dupes
|
|
.PP
|
|
hledger\-check\-dupes.hs checks for account names sharing the same leaf
|
|
name.
|
|
.SS equity
|
|
.PP
|
|
hledger\-equity.hs prints balance\-resetting transactions, useful for
|
|
bringing account balances across file boundaries.
|
|
.SS prices
|
|
.PP
|
|
hledger\-prices.hs prints all prices from the journal.
|
|
.SS print\-unique
|
|
.PP
|
|
hledger\-print\-unique.hs prints transactions which do not reuse an
|
|
already\-seen description.
|
|
.SS register\-match
|
|
.PP
|
|
hledger\-register\-match.hs helps ledger\-autosync detect already\-seen
|
|
transactions when importing.
|
|
.SS rewrite
|
|
.PP
|
|
hledger\-rewrite.hs Adds one or more custom postings to matched
|
|
transactions.
|
|
.SH TROUBLESHOOTING
|
|
.SS Run\-time problems
|
|
.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 "No command \[aq]hledger\[aq]
|
|
found"\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\[aq]s an explanation.
|
|
.PP
|
|
\f[B]"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
|
|
character" 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\[aq]m not sure yet).
|
|
.PP
|
|
Here\[aq]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\[aq]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[]).
|
|
.SS Known limitations
|
|
.PP
|
|
\f[B]Command line interface\f[]
|
|
.PP
|
|
Add\-on command options, unless they are also understood by the main
|
|
hledger executable, must be written after \f[C]\-\-\f[], like this:
|
|
\f[C]hledger\ web\ \-\-\ \-\-server\f[]
|
|
.PP
|
|
\f[B]Differences from Ledger\f[]
|
|
.PP
|
|
Not all of Ledger\[aq]s journal file syntax is supported.
|
|
See file format differences.
|
|
.PP
|
|
hledger is slower than Ledger, and uses more memory, on large data
|
|
files.
|
|
.PP
|
|
\f[B]Windows limitations\f[]
|
|
.PP
|
|
In a windows CMD window, non\-ascii characters and colours are not
|
|
supported.
|
|
.PP
|
|
In a windows Cygwin/MSYS/Mintty window, the tab key is not supported in
|
|
hledger add.
|
|
.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 options with \f[C]\-\-\f[] when invoked from hledger
|
|
is awkward.
|
|
.PP
|
|
hledger can\[aq]t render non\-ascii characters when run from a Windows
|
|
command prompt (up to Windows 7 at least).
|
|
.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.
|
|
|
|
|
|
.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
|