1178 lines
32 KiB
Groff
1178 lines
32 KiB
Groff
.Dd March 23, 2012
|
|
.Dt LEDGER 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ledger
|
|
.Nd Command-line, double-entry account reporting tool
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Ar command
|
|
.Op Ar options
|
|
.Op Ar arguments
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a command-line accounting tool based on the power and completeness
|
|
of double-entry accounting. It is only a reporting tool, which means it never
|
|
modifies your data files, but it does offers a large selection of reports, and
|
|
different ways to customize them to your liking.
|
|
.Sh COMMANDS
|
|
.Nm
|
|
accepts several top-level commands, each of which generates a different
|
|
kind of basic report. Most of them accept a
|
|
.Ar report-query
|
|
argument, in order to determine what should be reported. To understand the
|
|
syntax of a
|
|
.Ar report-query ,
|
|
see the section on
|
|
.Sx QUERIES .
|
|
In its most basic form, simply specifying one or more strings produces a
|
|
report for all accounts containing those strings.
|
|
.Pp
|
|
If no command is given,
|
|
.Nm
|
|
enters a
|
|
.Tn REPL ,
|
|
or command loop, allowing several commands to be executed against the same
|
|
dataset without reparsing.
|
|
.Pp
|
|
The following is a complete list of reporting commands accepted by
|
|
.Nm :
|
|
.Bl -tag -width accounts
|
|
.It Ic accounts Oo Ar report-query Oc
|
|
Lists all accounts for postings matching the
|
|
.Ar report-query .
|
|
.El
|
|
.Bl -tag -width balance
|
|
.It Ic balance Oo Ar report-query Oc
|
|
Produces a balance report showing totals for all matching accounts, and
|
|
aggregate totals for parents of those accounts. Options most commonly used
|
|
with this command are:
|
|
.Bl -tag -compact -width "--collapse (-n)"
|
|
.It Fl \-basis Pq Fl B
|
|
Report in terms of cost basis, not amount or value. This is the only form of
|
|
report which is guaranteed to always balance to zero, when no
|
|
.Ar report-query
|
|
is specified.
|
|
Only show totals for the top-most accounts.
|
|
.It Fl \-empty Pq Fl E
|
|
Also show accounts whose total is zero.
|
|
.It Fl \-flat
|
|
Rather than display a hierarchical tree, flatten the report to show subtotals
|
|
for only accounts matching
|
|
.Ar report-query .
|
|
.It Fl \-no-total
|
|
Suppress the summary total shown at the bottom of the report (when not zero).
|
|
.El
|
|
.Pp
|
|
The synonyms
|
|
.Ic bal
|
|
and
|
|
.Ic b
|
|
are also accepted.
|
|
.It Ic budget Oo Ar report-query Oc
|
|
A special balance report which includes three extra columns: the amount
|
|
budgeted during the reporting period, how spending differed from the budget,
|
|
and the percentage of budget spent (exceeds 100% if you go over budget).
|
|
Note that budgeting requires one or more
|
|
.Do
|
|
periodic transactions
|
|
.Dc
|
|
to be defined in your data file(s). See the manual for more information.
|
|
.It Ic cleared Oo Ar report-query Oc
|
|
A special balance report which adds two extra columns: the cleared balance for
|
|
each account, and the date of the most recent cleared posting in that account.
|
|
For this accounting to be meaningful, the cleared flag must be set on at least
|
|
one posting. See the manual for more information.
|
|
.It Ic commodities Oo Ar report-query Oc
|
|
Lists all commodities for postings matching the
|
|
.Ar report-query .
|
|
.It Ic convert
|
|
Reads data from a CSV (comma-separated values) file and generates
|
|
.Nm
|
|
transactions.
|
|
.It Ic csv Oo Ar report-query Oc
|
|
Report of postings matching the
|
|
.Ar report-query
|
|
in CSV format (comma-separated values). Useful for exporting data to a
|
|
spreadsheet for further analysis or charting.
|
|
.It Ic entry Oo Ar entry-template Oc
|
|
Generate and display a new, properly formatted
|
|
.Nm
|
|
transaction by comparing
|
|
the
|
|
.Ar entry-template
|
|
to the transactions in your data file(s). For more information on draft
|
|
templates and using this command to quickly create new transactions, see the
|
|
section
|
|
.Sx ENTRIES .
|
|
.Pp
|
|
The synonym
|
|
.Ic xact
|
|
is also accepted.
|
|
.It Ic emacs Oo Ar query Oc
|
|
Outputs posting and transaction data in a format readily consumed by the Emacs
|
|
editor, in a series of Lisp forms. This is used by the
|
|
.Pa ledger.el
|
|
Emacs mode to process reporting data from
|
|
.Nm .
|
|
.It Ic equity Oo Ar report-query Oc
|
|
Prints a series of transactions that balance current totals for
|
|
accounts matching the
|
|
.Ar report-query
|
|
in a special account called
|
|
.Li Equity:Opening Balances .
|
|
The purpose of this report is to close the books for a prior year, while using
|
|
these equity transactions to carry forward those balances.
|
|
.It Ic org
|
|
Produces a journal file suitable for use in the Emacs org mode.
|
|
.It Ic payees Oo Ar report-query Oc
|
|
Lists all payees for postings matching the
|
|
.Ar report-query .
|
|
.It Ic pricemap
|
|
Produces a file which can be used to generate a graph with graphviz showing
|
|
the relationship of commodities in the
|
|
.Nm
|
|
file.
|
|
.It Ic prices Oo Ar report-query Oc
|
|
Reports prices for all commodities in postings matching the
|
|
.Ar report-query .
|
|
The prices are reported with the granularity of a single day.
|
|
.It Ic pricedb Oo Ar report-query Oc
|
|
Reports prices for all commodities in postings matching the
|
|
.Ar report-query .
|
|
Prices are reported down to the second, using the same format as the
|
|
.Pa ~/.pricedb
|
|
file.
|
|
.It Ic print Oo Ar report-query Oc
|
|
Prints out the full transactions of any matching postings using the same
|
|
format as they would appear in a data file. This can be used to extract
|
|
subsets from a
|
|
.Nm
|
|
file to transfer to other files.
|
|
.It Ic push Oo Ar options Oc
|
|
In the
|
|
.Tn REPL ,
|
|
this command pushes a set of command-line options, so that they will apply to
|
|
all subsequent reports.
|
|
.It Ic pop
|
|
In the
|
|
.Tn REPL ,
|
|
pops any option settings that have been pushed.
|
|
.It Ic register Oo Ar report-query Oc
|
|
List all postings matching the
|
|
.Ar report-query .
|
|
This is one of the most common commands, and can be used to provide a variety
|
|
of useful reports. Options most commonly used
|
|
with this command are:
|
|
.Pp
|
|
.Bl -tag -compact -width "--collapse (-n)"
|
|
.It Fl \-average Pq Fl A
|
|
Show the running average, rather than a running total.
|
|
.It Fl \-current Pq Fl c
|
|
Don't show postings beyond the present day.
|
|
.It Fl \-exchange Ar commodity Pq Fl X
|
|
Render all values in the given
|
|
.Ar commodity ,
|
|
if a price conversion rate can be determined. Rates are always displayed
|
|
relative to the date of the posting they are calculated for. This means a
|
|
.Ic register
|
|
report is a historical value report. For current values, it may be preferable
|
|
to use the
|
|
.Ic balance
|
|
report.
|
|
.It Fl \-gain Pq Fl G
|
|
Show any gains (or losses) in commodity values over time.
|
|
.It Fl \-head Ar number
|
|
Only show the top
|
|
.Ar number
|
|
postings.
|
|
.\".It Fl \-historical Pq Fl H
|
|
.It Fl \-invert
|
|
Invert the value of amounts shown.
|
|
.It Fl \-market Pq Fl V
|
|
Show current market values for all amounts. This is determined in a somewhat
|
|
magical fashion. It is probably more straightforward to use
|
|
.Fl \-exchange Ar commodity Pq Fl X .
|
|
.It Fl \-period Ar time-period Pq Fl p
|
|
Show postings only for the given
|
|
.Ar time-period .
|
|
.It Fl \-related Pq Fl r
|
|
Show postings that are related to those that would have been shown. It has
|
|
the effect of displaying the
|
|
.Qq other side
|
|
of the values.
|
|
.It Fl \-sort Ar value-expression Pq Fl S
|
|
Sort postings by evaluating the given
|
|
.Ar value-expression .
|
|
Note that a comma-separated list of expressions is allowed, in which case each
|
|
sorting term is used in order to determine the final ordering. For example,
|
|
to search by date and then amount, one would use:
|
|
.Li -S 'date, amount' .
|
|
.It Fl \-tail Ar number
|
|
Only show the last
|
|
.Ar number
|
|
postings.
|
|
.It Fl \-uncleared Pq Fl U
|
|
Only show uncleared (i.e., recent) postings.
|
|
.El
|
|
.Pp
|
|
There are also several grouping options that can be useful:
|
|
.Pp
|
|
.Bl -tag -compact -width "--collapse (-n)"
|
|
.It Fl \-by-payee Pq Fl P
|
|
Group postings by common payee names.
|
|
.It Fl \-daily Pq Fl D
|
|
Group postings by day.
|
|
.It Fl \-weekly Pq Fl W
|
|
Group postings by week (starting on Sundays).
|
|
.It Fl \-start-of-week Ar day
|
|
Set the start of each report grouped by week to the given
|
|
.Ar day .
|
|
.It Fl \-monthly Pq Fl M
|
|
Group postings by month.
|
|
.It Fl \-quarterly
|
|
Group postings by fiscal quarter.
|
|
.It Fl \-yearly Pq Fl Y
|
|
Group postings by year.
|
|
.It Fl \-dow
|
|
Group postings by the day of the week on which they took place.
|
|
.It Fl \-subtotal Pq Fl s
|
|
Group all postings together. This is very similar to the totals shown by the
|
|
.Ic balance
|
|
report.
|
|
.El
|
|
.Pp
|
|
The synonyms
|
|
.Ic reg
|
|
and
|
|
.Ic r
|
|
are also accepted.
|
|
.It Ic server
|
|
This command requires that Python support be active. If so, it starts up an
|
|
.Tn HTTP
|
|
server listening for requests on port 9000. This provides an alternate
|
|
interface to creating and viewing reports. Note that this is very much a
|
|
work-in-progress, and will not be fully functional until a later version.
|
|
.It Ic select Oo Ar sql-query Oc
|
|
List all postings matching the
|
|
.Ar sql-query .
|
|
This command allows to generate SQL-like queries.
|
|
.It Ic source
|
|
Parses a journal file and checks it for errors.
|
|
.Nm
|
|
will return success
|
|
if no errors are found.
|
|
.It Ic stats Oo Ar report-query Oc
|
|
Provides summary information about all the postings matching
|
|
.Ar report-query .
|
|
It provides information such as:
|
|
.Bl -bullet -offset indent -compact
|
|
.It
|
|
Time range of all matching postings
|
|
.It
|
|
Unique payees
|
|
.It
|
|
Unique accounts
|
|
.It
|
|
Postings total
|
|
.It
|
|
Uncleared postings
|
|
.It
|
|
Days since last posting
|
|
.It
|
|
More...
|
|
.El
|
|
.It Ic xml Oo Ar report-query Oc
|
|
Outputs data relating to the current report in
|
|
.Tn XML
|
|
format. It includes all
|
|
accounts and commodities involved in the report, plus the postings and the
|
|
transactions they are contained in. See the manual for more information.
|
|
.El
|
|
.Sh OPTIONS
|
|
.Bl -tag -width -indent
|
|
.It Fl \-abbrev-len Ar INT
|
|
Set the minimum length an account can be abbreviated to if it doesn't
|
|
fit inside the
|
|
.Sy account-width .
|
|
If
|
|
.Ar INT
|
|
is zero, then the
|
|
account name will be truncated on the right. If
|
|
.Ar INT
|
|
is greater
|
|
than
|
|
.Sy account-width
|
|
then the account will be truncated on the
|
|
left, with no shortening of the account names in order to fit into the
|
|
desired width.
|
|
.It Fl \-account Ar STR
|
|
Prepend
|
|
.Ar STR
|
|
to all accounts reported. That is, the option
|
|
.Fl \-account Ar \*q'Personal'\*q
|
|
would tack
|
|
.Ar Personal:
|
|
to the beginning of every account reported in a balance report or register report.
|
|
.It Fl \-account-width Ar INT
|
|
Set the width of the account column in the
|
|
.Ic register
|
|
report
|
|
to
|
|
.Ar INT
|
|
characters.
|
|
.It Fl \-actual Pq Fl L
|
|
Report only real transactions, with no automated or virtual
|
|
transactions used.
|
|
.It Fl \-add-budget
|
|
Show only un-budgeted postings.
|
|
.It Fl \-amount Ar EXPR Pq Fl t
|
|
Apply the given value expression to the posting amount. Using
|
|
.Fl \-amount Ar EXPR
|
|
you can apply an
|
|
arbitrary transformation to the postings.
|
|
.It Fl \-amount-data Pq Fl j
|
|
On a register report print only the dates and amount of postings.
|
|
Useful for graphing and spreadsheet applications.
|
|
.It Fl \-amount-width Ar INT
|
|
Set the width in characters of the amount column in the
|
|
.Ic register
|
|
report.
|
|
.It Fl \-anon
|
|
Anonymize registry output, mostly for sending in bug reports.
|
|
.It Fl \-args-only
|
|
Ignore init files and environment variables for the
|
|
.Nm
|
|
run.
|
|
.\".It Fl \-auto-match
|
|
.It Fl \-aux-date
|
|
Show auxiliary dates for all calculations.
|
|
Alias for
|
|
.Fl \-effective
|
|
.It Fl \-average Pq Fl A
|
|
Print average values over the number of transactions instead of
|
|
running totals.
|
|
.It Fl \-balance-format Ar FMT
|
|
Specify the format to use for the
|
|
.Ic balance
|
|
report.
|
|
.\".It Fl \-base
|
|
.It Fl \-basis Pq Fl B
|
|
Report the cost basis on all posting.
|
|
Alias for
|
|
.Fl \-cost
|
|
.It Fl \-begin Ar DATE Pq Fl b
|
|
Specify the start
|
|
.Ar DATE
|
|
of all calculations. Transactions before
|
|
that date will be ignored.
|
|
.It Fl \-bold-if Ar EXPR
|
|
Print the entire line in bold if the given value expression is true.
|
|
.It Fl \-budget
|
|
Only display budgeted items. In a
|
|
.Ic register
|
|
report this displays transaction in the budget, in a balance report this
|
|
displays accounts in the budget.
|
|
.It Fl \-budget-format Ar FMT
|
|
Specify the format to use for the
|
|
.Ic budget
|
|
report.
|
|
.It Fl \-by-payee Pq Fl P
|
|
Group postings in the register report by common payee names.
|
|
.\".It Fl \-cache Ar FILE
|
|
.It Fl \-check-payees
|
|
Enable strict and pedantic checking for payees as well as accounts,
|
|
commodities and tags.
|
|
.It Fl \-cleared Pq Fl C
|
|
Display only cleared postings.
|
|
.It Fl \-cleared-format Ar FMT
|
|
Specify the format to use for the
|
|
.Ic cleared
|
|
report
|
|
.It Fl \-collapse Pq Fl n
|
|
By default
|
|
.Nm
|
|
prints all accounts in an account tree. With
|
|
.Fl \-collapse
|
|
it prints only the top level account specified.
|
|
.It Fl \-collapse-if-zero
|
|
Collapse the account display only if it has a zero balance.
|
|
.It Fl \-color
|
|
Use color if the terminal supports it.
|
|
Alias for
|
|
.Fl \-ansi
|
|
.It Fl \-columns Ar INT
|
|
Specify the width of the
|
|
.Ic register
|
|
report in characters.
|
|
.It Fl \-cost
|
|
Report the cost basis on all posting.
|
|
Alias for
|
|
.Fl \-basis .
|
|
.It Fl \-count
|
|
Direct
|
|
.Nm
|
|
to report the number of items when appended to the
|
|
.Ic commodities ,
|
|
.Ic accounts
|
|
or
|
|
.Ic payees
|
|
commands.
|
|
.It Fl \-csv-format Ar FMT
|
|
Specify the format to use for the
|
|
.Ic csv
|
|
report
|
|
.It Fl \-current Pq Fl c
|
|
Shorthand for
|
|
.Fl \-limit Ar "'date <= today'" .
|
|
.It Fl \-daily Pq Fl D
|
|
Shorthand for
|
|
.Fl \-period Ar daily .
|
|
.It Fl \-date Ar EXPR
|
|
Transform the date of the transaction using
|
|
.Ar EXPR .
|
|
.It Fl \-date-format Ar DATEFMT Pq Fl y
|
|
Specify the format
|
|
.Nm
|
|
should use to print dates.
|
|
.\" .It Fl \-datetime-format Ar FMT
|
|
.It Fl \-date-width Ar INT
|
|
Specify the width, in characters, of the date column in the
|
|
.Ic register
|
|
report.
|
|
.\".It Fl \-day-break
|
|
.It Fl \-dc
|
|
Display register or balance in debit/credit format If you use
|
|
.Fl \-dc
|
|
with either the
|
|
.Ic register
|
|
or
|
|
.Ic balance
|
|
commands, you will now get separate columns for debits and credits.
|
|
.It Fl \-debug Ar STR
|
|
If
|
|
.Nm
|
|
has been built with debug options this will provide extra
|
|
data during the run.
|
|
.It Fl \-decimal-comma
|
|
Direct
|
|
.Nm
|
|
to parse journals using the European standard comma as
|
|
decimal separator, vice a period.
|
|
.It Fl \-depth Ar INT
|
|
Limit the depth of the account tree. In a balance report, for example,
|
|
a
|
|
.Fl \-depth 2
|
|
statement will print balances only for account with
|
|
two levels, i.e.
|
|
.Sy Expenses:Entertainment
|
|
but not
|
|
.Sy Expenses:entertainment:Dining .
|
|
This is a display predicate, which
|
|
means it only affects display, not the total calculations.
|
|
.It Fl \-deviation Pq Fl D
|
|
Report each posting's deviation from the average. It is only meaningful
|
|
in the register and prices reports.
|
|
.It Fl \-display Ar EXPR Pq Fl d
|
|
Display lines that satisfy the expression
|
|
.Ar EXPR .
|
|
.It Fl \-display-amount Ar EXPR
|
|
Apply a transformation to the
|
|
.Em displayed
|
|
amount. This occurs after
|
|
calculations occur.
|
|
.It Fl \-display-total Ar EXPR
|
|
Apply a transformation to the
|
|
.Em displayed
|
|
total. This occurs after
|
|
calculations occur.
|
|
.It Fl \-dow
|
|
Group transactions by the days of the week.
|
|
Alias for
|
|
.Fl \-days-of-week
|
|
.It Fl \-download
|
|
Cause quotes to be automagically downloaded, as needed, by running
|
|
a script named
|
|
.Em getquote
|
|
and expecting that script to return
|
|
a value understood by
|
|
.Nm .
|
|
A sample implementation of a
|
|
.Em getquote
|
|
script, implemented in Perl, is provided in the
|
|
distribution. Downloaded quote price are then appended to the price
|
|
database, usually specified using the environment variable
|
|
.Ev LEDGER_PRICE_DB .
|
|
.It Fl \-empty Pq Fl E
|
|
Include empty accounts in report.
|
|
.It Fl \-end Ar DATE Pq Fl e
|
|
Specify the end
|
|
.Ar DATE
|
|
for a transaction to be considered in the
|
|
report.
|
|
.It Fl \-equity
|
|
Related to the
|
|
.Ic equity
|
|
command. Gives current account balances in the form of a register
|
|
report.
|
|
.\".It Fl \-exact
|
|
.It Fl \-exchange Ar COMMODITY Oo , COMM, ... Oc Pq Fl X
|
|
Display values in terms of the given
|
|
.Ar COMMODITY .
|
|
The latest available price is used.
|
|
.\".It Fl \-explicit
|
|
.It Fl \-file Ar FILE
|
|
Read
|
|
.Ar FILE
|
|
as a
|
|
.Nm
|
|
file.
|
|
.\".It Fl \-full-help
|
|
.It Fl \-first Ar INT
|
|
Print the first
|
|
.Ar INT
|
|
entries. Opposite of
|
|
.Fl \-tail Ar INT .
|
|
Alias for
|
|
.Fl \-head .
|
|
.It Fl \-flat
|
|
Force the full names of accounts to be used in the balance report. The
|
|
balance report will not use an indented tree.
|
|
.It Fl \-force-color
|
|
Output TTY color codes even if the TTY doesn't support them. Useful
|
|
for TTYs that don't advertise their capabilities correctly.
|
|
.It Fl \-force-pager
|
|
Force
|
|
.Nm
|
|
to paginate its output.
|
|
.It Fl \-forecast-while Ar EXPR
|
|
Continue forecasting while
|
|
.Ar VEXPR
|
|
is true.
|
|
Alias for
|
|
.Fl \-forecast .
|
|
.It Fl \-forecast-years Ar INT
|
|
Forecast at most
|
|
.Ar INT
|
|
years into the future.
|
|
.It Fl \-format Ar FMT Pq Fl F
|
|
Use the given format string
|
|
.Ar FMT
|
|
to print output.
|
|
.It Fl \-gain Pq Fl G
|
|
Report net gain or loss for commodities that have a price history.
|
|
.It Fl \-generated
|
|
Include auto-generated postings (such as those from automated
|
|
transactions) in the report, in cases where you normally wouldn't want
|
|
them.
|
|
.It Fl \-group-by Ar EXPR
|
|
Group transaction together in the
|
|
.Ic register
|
|
report.
|
|
.Ar EXPR
|
|
can be anything, although most common would be
|
|
.Ar payee
|
|
or
|
|
.Ar commodity .
|
|
The
|
|
.Fn tags
|
|
function is also useful here.
|
|
.It Fl \-group-title-format Ar FMT
|
|
Set the format for the headers that separate reports section of
|
|
a grouped report. Only has effect with a
|
|
.Fl \-group-by Ar EXPR
|
|
register report.
|
|
.It Fl \-head Ar INT
|
|
Print the first
|
|
.Ar INT
|
|
entries. Opposite of
|
|
.Fl \-tail Ar INT .
|
|
Alias for
|
|
.Fl \-first
|
|
.It Fl \-help
|
|
Print a summary of all the options, and what they are used for. This
|
|
can be a handy way to remember which options do what. This help screen
|
|
is also printed if
|
|
.Nm
|
|
is run without a command.
|
|
.\".It Fl \-help-calc
|
|
.\".It Fl \-help-comm
|
|
.\".It Fl \-help-disp
|
|
.It Fl \-immediate
|
|
Instruct
|
|
.Nm
|
|
to evaluate calculations immediately rather than lazily.
|
|
.\".It Fl \-import
|
|
.It Fl \-init-file Ar FILE Pq Fl i
|
|
Causes
|
|
.Ar FILE
|
|
to be read by
|
|
.Nm
|
|
before any other
|
|
.Nm
|
|
file.
|
|
This file may not contain any postings, but it may contain option
|
|
settings. To specify options in the init file, use the same syntax as
|
|
the command-line, but put each option on its own line.
|
|
.It Fl \-inject Ar STR
|
|
Use
|
|
.Ar STR
|
|
amounts in calculations. In case you know
|
|
what amount a transaction should be, but the actual transaction has the
|
|
wrong value you can use metadata STR to specify the expected amount.
|
|
.It Fl \-input-date-format Ar DATEFMT
|
|
Specify the input date format for journal entries.
|
|
.It Fl \-invert
|
|
Change the sign of all reported values.
|
|
.It Fl \-last Ar INT
|
|
Report only the last
|
|
.Ar INT
|
|
entries. Only useful on a register
|
|
report.
|
|
Alias for
|
|
.Fl \-tail .
|
|
.It Fl \-leeway Ar INT Pq Fl Z
|
|
Alias for
|
|
.Fl \-price-expr .
|
|
.It Fl \-limit Ar EXPR Pq Fl l
|
|
Limit postings in calculations.
|
|
.It Fl \-lot-dates
|
|
Report the date on which each commodity in a balance report was
|
|
purchased.
|
|
.It Fl \-lot-notes
|
|
Report the tag attached to each commodity in a balance report.
|
|
.It Fl \-lot-prices
|
|
Report the price at which each commodity in a balance report was
|
|
purchased.
|
|
.It Fl \-lots
|
|
Report the date and price at which each commodity was purchased in
|
|
a balance report.
|
|
.\".It Fl \-lots-actual
|
|
.It Fl \-market Pq Fl V
|
|
Use the latest market value for all commodities.
|
|
.It Fl \-master-account Ar STR
|
|
Prepend all account names with
|
|
.Ar STR
|
|
.It Fl \-meta Ar EXPR
|
|
In the register report, prepend the transaction with the value of the given
|
|
.Ar TAG .
|
|
.It Fl \-meta-width Ar INT
|
|
Specify the width of the Meta column used for the
|
|
.Fl \-meta Ar TAG
|
|
options.
|
|
.It Fl \-monthly Pq Fl M
|
|
Shorthand for
|
|
.Fl \-period Ar monthly .
|
|
.It Fl \-no-aliases
|
|
Aliases are completely ignored.
|
|
.It Fl \-no-color
|
|
Suppress any color TTY output.
|
|
.It Fl \-no-pager
|
|
Disables the pager on TTY output.
|
|
.It Fl \-no-rounding
|
|
Don't output
|
|
.Qq Li <Rounding>
|
|
postings. Note that this will cause the
|
|
running total to often not add up! It's main use is for
|
|
.Fl \-amount-data Pq Fl j
|
|
and
|
|
.Fl \-total-data Pq Fl J
|
|
reports.
|
|
.It Fl \-no-titles
|
|
Suppress the output of group titles.
|
|
.It Fl \-no-total
|
|
Suppress printing the final total line in a balance report.
|
|
.It Fl \-now Ar DATE
|
|
Define the current date in case to you to do calculate in the past or
|
|
future using
|
|
.Fl \-current .
|
|
.It Fl \-only Ar EXPR
|
|
This is a postings predicate that applies after certain transforms have
|
|
been executed, such as periodic gathering.
|
|
.It Fl \-options
|
|
Display the options in effect for this
|
|
.Nm
|
|
invocation, along with
|
|
their values and the source of those values.
|
|
.It Fl \-output Ar FILE Pq Fl o
|
|
Redirect the output of
|
|
.Nm
|
|
to the file defined in
|
|
.Ar FILE .
|
|
.It Fl \-pager Ar STR
|
|
Specify the pager program to use as
|
|
.Ar STR .
|
|
.It Fl \-payee
|
|
Sets a value expression for formatting the payee. In the
|
|
.Ic register
|
|
report this prevents the second entry from having
|
|
a date and payee for each transaction.
|
|
.It Fl \-payee-width Ar INT
|
|
Set the number of columns dedicated to the payee in the register
|
|
report to
|
|
.Ar INT .
|
|
.It Fl \-pedantic
|
|
Accounts, tags or commodities not previously declared will cause errors.
|
|
.It Fl \-pending
|
|
Use only postings that are marked pending.
|
|
.It Fl \-percent Pq Fl \b'%'
|
|
Calculate the percentage value of each account in a balance reports.
|
|
Only works for account that have a single commodity.
|
|
.It Fl \-period Ar PERIOD Pq Fl p
|
|
Define a period expression that sets the time period during which
|
|
transactions are to be accounted. For a
|
|
.Ic register
|
|
report only
|
|
the transactions that satisfy the period expression with be displayed.
|
|
For a balance report only those transactions will be accounted in the
|
|
final balances.
|
|
.It Fl \-period-sort
|
|
Sort the posting within transactions using the given value expression.
|
|
.It Fl \-permissive
|
|
Quiet balance assertions.
|
|
.It Fl \-pivot Ar TAG
|
|
Produce a balance pivot report
|
|
.Qq around
|
|
the given
|
|
.Ar TAG .
|
|
.It Fl \-plot-amount-format Ar FMT
|
|
Define the output format for an amount data plot.
|
|
.It Fl \-plot-total-format Ar FMT
|
|
Define the output format for a total data plot.
|
|
.It Fl \-prepend-format Ar FMT
|
|
Prepend
|
|
.Ar FMT
|
|
to every line of the output.
|
|
.It Fl \-prepend-width Ar INT
|
|
Reserve
|
|
.Ar INT
|
|
spaces at the beginning of each line of the output.
|
|
.It Fl \-price Pq Fl I
|
|
Use the price of the commodity purchase for performing calculations.
|
|
.It Fl \-price-db Ar FILE
|
|
.It Fl \-price-exp Ar STR Pq Fl Z
|
|
Set the expected freshness of price quotes, in
|
|
.Ar INT
|
|
minutes. That
|
|
is, if the last known quote for any commodity is older than this value,
|
|
and if
|
|
.Fl \-download
|
|
is being used, then the Internet will be
|
|
consulted again for a newer price. Otherwise, the old price is still
|
|
considered to be fresh enough.
|
|
Alias for
|
|
.Fl \-leeway Ar INT Pq Fl Z
|
|
.It Fl \-prices-format Ar FMT
|
|
Set the format for the
|
|
.Ic prices
|
|
report.
|
|
.It Fl \-pricedb-format Ar FMT
|
|
Set the format expected for the historical price file.
|
|
.It Fl \-primary-date
|
|
Show primary dates for all calculations. Alias for
|
|
.Fl \-actual-dates
|
|
.It Fl \-quantity Pq Fl O
|
|
Report commodity totals (this is the default).
|
|
.It Fl \-quarterly
|
|
Shorthand for
|
|
.Fl \-period Ar quarterly .
|
|
.It Fl \-raw
|
|
In the
|
|
.Ic print
|
|
report, show transactions using the exact same syntax as
|
|
specified by the user in their data file. Don't do any massaging or
|
|
interpreting. Can be useful for minor cleanups, like just aligning
|
|
amounts.
|
|
.It Fl \-real Pq Fl R
|
|
Account using only real transactions ignoring virtual and automatic
|
|
transactions.
|
|
.It Fl \-recursive-aliases
|
|
Causes
|
|
.Nm
|
|
to try to expand aliases recursively, i.e. try to expand
|
|
the result of an earlier expansion again, until no more expansions apply.
|
|
.It Fl \-register-format Ar FMT
|
|
Define the output format for the
|
|
.Ic register
|
|
report.
|
|
.It Fl \-related Pq Fl r
|
|
In a register report show the related account. This is the other
|
|
.Em side
|
|
of the transaction.
|
|
.It Fl \-related-all
|
|
Show all postings in a transaction, similar to
|
|
.Fl \-related
|
|
but show
|
|
.Em both sides
|
|
of each transaction.
|
|
.\".It Fl \-revalued
|
|
.\".It Fl \-revalued-only
|
|
.\".It Fl \-revalued-total Ar EXPR
|
|
.\".It Fl \-rich-data
|
|
.It Fl \-seed Ar INT
|
|
Set the random seed to
|
|
.Ar INT
|
|
for the
|
|
.Ic generate
|
|
command. Used as part of development testing.
|
|
.It Fl \-script Ar FILE
|
|
Execute a
|
|
.Nm
|
|
script.
|
|
.It Fl \-sort Ar EXPR Pq Fl S
|
|
Sort the register report based on the value expression given to sort.
|
|
.\".It Fl \-sort-all
|
|
.It Fl \-sort-xacts
|
|
Sort the posting within transactions using the given value expression.
|
|
.It Fl \-start-of-week Ar STR
|
|
Tell
|
|
.Nm
|
|
to use a particular day of the week to start its
|
|
.Qq weekly
|
|
summary.
|
|
.Ar STR
|
|
can be day names, their abbreviations like
|
|
.Qq Mon ,
|
|
or the weekday number
|
|
starting at 0 for Sunday.
|
|
.It Fl \-strict
|
|
Accounts, tags or commodities not previously declared will cause warnings.
|
|
.It Fl \-subtotal Pq Fl s
|
|
Report register as a single subtotal.
|
|
.It Fl \-tail Ar INT
|
|
Report only the last
|
|
.Ar INT
|
|
entries. Only useful on a register report. Alias for
|
|
.Fl \-last Ar INT
|
|
.It Fl \-time-colon
|
|
Display the value for a seconds based commodity as real hours and minutes,
|
|
thus 8100 seconds will be displayed as 2:15h instead of 2.25h.
|
|
.\".It Fl \-time-report
|
|
.It Fl \-total Ar EXPR Pq Fl T
|
|
Define a value expression used to calculate the total in reports.
|
|
.It Fl \-total-data Pq Fl J
|
|
Show only dates and totals to format the output for plots.
|
|
.It Fl \-total-width Ar INT
|
|
Set the width of the total field in the register report.
|
|
.It Fl \-trace Ar INT
|
|
Enable tracing. The
|
|
.Ar INT
|
|
specifies the level of trace desired.
|
|
.It Fl \-truncate Ar STR
|
|
Indicates how truncation should happen when the contents of columns
|
|
exceed their width. Valid arguments are
|
|
.Ar leading ,
|
|
.Ar middle ,
|
|
and
|
|
.Ar trailing .
|
|
The default is smarter than any of these three,
|
|
as it considers sub-names within the account name (that style is
|
|
called
|
|
.Qq abbreviate ) .
|
|
.It Fl \-unbudgeted
|
|
Show only un-budgeted postings.
|
|
.It Fl \-uncleared Pq Fl U
|
|
Use only uncleared transactions in calculations and reports.
|
|
.It Fl \-unrealized
|
|
Show generated unrealized gain and loss accounts in the balance
|
|
report.
|
|
.It Fl \-unrealized-gains
|
|
Allow the user to specify what account name should be used for
|
|
unrealized gains. Defaults to
|
|
.Sy "Equity:Unrealized Gains" .
|
|
Often set in one's
|
|
.Pa ~/.ledgerrc
|
|
file to change the default.
|
|
.It Fl \-unrealized-losses
|
|
Allow the user to specify what account name should be used for
|
|
unrealized gains. Defaults to
|
|
.Sy "Equity:Unrealized Losses" .
|
|
Often set in one's
|
|
.Pa ~/.ledgerrc
|
|
file to change the default.
|
|
.It Fl \-unround
|
|
Perform all calculations without rounding and display results to full
|
|
precision.
|
|
.It Fl \-values
|
|
Shows the values used by each tag when used in combination with the
|
|
.Ic tags
|
|
command.
|
|
.\".It Fl \-value-expr Ar EXPR
|
|
.It Fl \-verbose
|
|
Print detailed information on the execution of
|
|
.Nm .
|
|
.It Fl \-verify
|
|
Enable additional assertions during run-time. This causes a significant
|
|
slowdown. When combined with
|
|
.Fl \-debug Ar CODE
|
|
.Nm
|
|
will produce memory trace information.
|
|
.\".It Fl \-verify-memory
|
|
.It Fl \-version
|
|
Print version information and exit.
|
|
.It Fl \-weekly Pq Fl W
|
|
Shorthand for
|
|
.Fl \-period Ar weekly .
|
|
.It Fl \-wide Pq Fl w
|
|
Assume 132 columns instead of 80.
|
|
.It Fl \-yearly Pq Fl Y
|
|
Shorthand for
|
|
.Fl \-period Ar yearly .
|
|
.El
|
|
.Sh PRE-COMMANDS
|
|
Pre-commands are useful when you aren't sure how a command or option
|
|
will work. The difference between a pre-command and a regular command
|
|
is that pre-commands ignore the journal data file completely, nor is
|
|
the user's init file read.
|
|
.Bl -tag -width -indent
|
|
.It Ic args / query
|
|
Evaluate the given arguments and report how
|
|
.Nm
|
|
interprets it against
|
|
the following model transaction.
|
|
.It Ic eval
|
|
Evaluate the given value expression against the model transaction.
|
|
.It Ic format
|
|
Print details of how
|
|
.Nm
|
|
uses the given formatting description and
|
|
apply it against a model transaction.
|
|
.It Ic parse / expr
|
|
Print details of how
|
|
.Nm
|
|
uses the given value expression description
|
|
and apply it against a model transaction.
|
|
.It Ic generate
|
|
Randomly generates syntactically valid
|
|
.Nm
|
|
data from a seed. Used
|
|
by the GenerateTests harness for development testing.
|
|
.It Ic period
|
|
Evaluate the given period and report how
|
|
.Nm
|
|
interprets it.
|
|
.It Ic script
|
|
.It Ic template
|
|
Shows the insertion template that the
|
|
.Ic xact
|
|
sub-command generates. This is a debugging command.
|
|
.El
|
|
.Sh QUERIES
|
|
The syntax for reporting queries can get somewhat complex. It is a series of
|
|
query terms with an implicit OR operator between them. The following terms
|
|
are accepted:
|
|
.Bl -tag -width "term and term"
|
|
.It Ar regex
|
|
A bare string is taken as a regular expression matching the full account name.
|
|
Thus, to report the current balance for all assets and liabilities, you would
|
|
use:
|
|
.Pp
|
|
.Dl ledger bal asset liab
|
|
.It Ic payee Ar regex Pq \&@ Ns Ar regex
|
|
Query on the payee, rather than the account.
|
|
.It Ic tag Ar regex Pq \&% Ns Ar regex
|
|
.It Ic note Ar regex Pq \&= Ns Ar regex
|
|
Query on anything found in an item's note.
|
|
.It Ic code Ar regex Pq \&# Ns Ar regex
|
|
Query on the xact's optional code (which can be any string the user wishes).
|
|
.It Ar term Cm and Ar term
|
|
Query terms are joined by an implicit OR operator. You can change this to AND
|
|
by using that keyword. For example, to show food expenditures occurring at
|
|
Shakee's Pizza, you could say:
|
|
.Pp
|
|
.Dl Li ledger reg food and @Shakee
|
|
.It Ar term Cm or Ar term
|
|
When you wish to be more explicit, use the OR operator.
|
|
.It Ic show
|
|
.It Cm not Ar term
|
|
Reverse the logical meaning of the following term. This can be used with
|
|
parentheses to great effect:
|
|
.Pp
|
|
.Dl Li ledger reg food and @Shakee and not dining
|
|
.It \&( Ar term No \&)
|
|
If you wish to mix OR and AND operators, it is often helpful to surround
|
|
logical units with parentheses. \fBNOTE\fR: Because of the way some shells
|
|
interpret parentheses, you should always escape them:
|
|
.Pp
|
|
.Dl Li ledger bal \e\\\&( assets or liab \e\\\&) and not food
|
|
.El
|
|
.Sh EXPRESSIONS
|
|
.Bl -tag -width "partial_account"
|
|
.It Fn abs value
|
|
Return the absolute value of the given
|
|
.Ar value .
|
|
.It Sy account
|
|
.It Sy account_base
|
|
.It Sy account_amount
|
|
.It Sy actual
|
|
.It Sy amount
|
|
.It Sy amount_expr
|
|
.It Fn ansify_if value color bool
|
|
Render the given
|
|
.Ar value
|
|
as a string, applying the proper ANSI escape codes to display it in the given
|
|
.Ar color
|
|
if
|
|
.Ar bool
|
|
is true. It typically checks the value of the option
|
|
.Fl \-color ,
|
|
for example:
|
|
.Dl Li ansify_if(amount, "blue", options.color)
|
|
.It Sy beg_line
|
|
Line number where entry for posting begins.
|
|
.It Sy beg_pos
|
|
Character position where entry for posting begins.
|
|
.It Sy calculated
|
|
.It Sy cleared
|
|
.It Sy code
|
|
Return the transaction code, the string between the parenthesis after the date.
|
|
.It Sy comment
|
|
.It Sy commodity
|
|
Return the commodity of the posting amount.
|
|
.It Sy cost
|
|
.It Sy count
|
|
.It Sy date
|
|
Return the date of the posting.
|
|
.It Sy depth
|
|
.It Sy depth_spacer
|
|
.It Sy display_amount
|
|
.It Sy display_total
|
|
.It Sy end_line
|
|
Line number where entry for posting ends.
|
|
.It Sy end_pos
|
|
Character position where entry for posting ends.
|
|
.It Sy filename
|
|
The name of the
|
|
.Nm
|
|
data file from whence the posting came.
|
|
.It Fn format_date date format
|
|
Return the
|
|
.Ar date
|
|
as a string using
|
|
.Ar format .
|
|
See
|
|
.Xr strftime 3
|
|
for format string details.
|
|
.It Sy get_at
|
|
.It Sy has_meta
|
|
.It Sy has_tag
|
|
.It Sy is_seq
|
|
.It Sy join
|
|
.It Sy market
|
|
.It Sy meta
|
|
.It Sy note
|
|
.It Sy null
|
|
.It Sy options
|
|
.It Sy partial_account
|
|
.It Sy payee
|
|
.It Sy pending
|
|
.It Fn percent value_a value_b
|
|
Return the percentage of
|
|
.Ar value_a
|
|
in relation to
|
|
.Ar value_b .
|
|
.It Sy post
|
|
.It Sy print
|
|
.It Sy quantity
|
|
.It Fn quoted expression
|
|
Surround
|
|
.Ar expression
|
|
with double-quotes.
|
|
.It Sy real
|
|
.It Sy rounded
|
|
.It Sy scrub
|
|
.It Sy status
|
|
.It Sy strip
|
|
.It Sy subcount
|
|
.It Sy tag
|
|
.It Sy today
|
|
.It Sy total
|
|
.It Sy total_expr
|
|
.It Sy truncate
|
|
.It Sy uncleared
|
|
.It Sy virtual
|
|
.It Sy xact
|
|
.El
|
|
.Sh ENTRIES
|
|
.Sh FORMATS
|
|
.Sh DEBUG COMMANDS
|
|
In addition to the regular reporting commands,
|
|
.Nm
|
|
also accepts several
|
|
debug commands:
|
|
.Bl -tag -width balance
|
|
.It Ic args Oo Ar report-query Oc
|
|
Accepts a
|
|
.Ar report-query
|
|
as its argument and displays it back to the user along with a complete
|
|
analysis of how
|
|
.Nm
|
|
interpreted it. Useful if you want to understand how
|
|
report queries are translated into value expressions.
|
|
.It Ic eval Oo Ar value-expression Oc
|
|
Evaluates the given
|
|
.Ar value-expression
|
|
and prints the result. For more on value expressions, see the section
|
|
.Sx EXPRESSIONS .
|
|
.It Ic format Oo Ar format-string Oc
|
|
Accepts a
|
|
.Ar format-string
|
|
and displays an analysis of how it was parsed, and what it would look like
|
|
applied to a sample transaction. For more on format strings, see the section
|
|
.Sx FORMATS .
|
|
.It Ic generate
|
|
Generates 50 randomly composed yet valid
|
|
.Nm
|
|
transactions.
|
|
.It Ic parse Oo Ar value-expression Oc
|
|
Parses the given
|
|
.Ar value-expression
|
|
and display an analysis of the expression tree and its evaluated value. For
|
|
more on value expressions, see the section
|
|
.Sx EXPRESSIONS .
|
|
.It Ic python Oo Ar file Oc
|
|
Invokes a Python interpreter to read the given
|
|
.Ar file .
|
|
What is special about this is that the
|
|
.Nm
|
|
module is builtin, not read from
|
|
disk, so it doesn't require
|
|
.Nm
|
|
to be installed anywhere, or the shared
|
|
library variants to be built.
|
|
.It Ic reload
|
|
Used only in the
|
|
.Tn REPL ,
|
|
it causes an immediate reloading of all data files for the current session.
|
|
.It Ic template Oo Ar draft-template Oc
|
|
Accepts a
|
|
.Ar draft-template
|
|
and displays information about how it was parsed. See the section on
|
|
.Sx DRAFTS .
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
Every option to
|
|
.Nm
|
|
may be set using an environment variable. If
|
|
an option has a long name for example,
|
|
.Fl \-account ,
|
|
setting the environment variable
|
|
.Ev LEDGER_ACCOUNT
|
|
will have the same effect as specifying that option on the command-line.
|
|
Options on the command-line always take precedence over environment variable
|
|
settings, however.
|
|
.Sh FILES
|
|
.Bl -tag -width -indent
|
|
.It Pa ~/.ledgerrc
|
|
Your personal
|
|
.Nm
|
|
initializations.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr beancount 1 ,
|
|
.Xr hledger 1
|
|
.Sh AUTHORS
|
|
.An "John Wiegley"
|
|
.Aq johnw@newartisans.com
|
|
.\" .Sh BUGS \" Document known, unremedied bugs
|
|
.\" .Sh HISTORY \" Document history if command behaves in a unique manner
|