simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-12-25 03:13:25 +03:00
Code Issues Projects Releases Wiki Activity

doc: regenerate manuals, removing some smart typography

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-01-24 15:37:40 -08:00
parent eac15369f2
commit 67dde9d4ae
11 changed files with 1052 additions and 682 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
hledger-lib/hledger_csv.5
View File

@ -29,7 +29,7 @@ conversion rules file named \f[C]FILE.csv.rules\f[] in the same
directory.
You can override this with the \f[C]\-\-rules\-file\f[] option.
If the rules file does not exist, hledger will auto\-create one with
some example rules, which you'll need to adjust.
some example rules, which you\[aq]ll need to adjust.
.PP
At minimum, the rules file must identify the \f[C]date\f[] and
\f[C]amount\f[] fields.
@ -90,7 +90,7 @@ ignored.
\f[C]skip\f[]\f[I]\f[CI]N\f[I]\f[]
.PP
Skip this number of CSV records at the beginning.
You'll need this whenever your CSV data contains header lines.
You\[aq]ll need this whenever your CSV data contains header lines.
Eg:
.IP
.nf
@ -104,8 +104,8 @@ skip\ 1
\f[C]date\-format\f[]\f[I]\f[CI]DATEFMT\f[I]\f[]
.PP
When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or
\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you'll need to specify
the format.
\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to
specify the format.
DATEFMT is a strptime\-like date parsing pattern, which must parse the
date field values completely.
Examples:
@ -140,7 +140,7 @@ date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
.SS field list
.PP
\f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[],
\f[I]\f[CI]FIELDNAME2\f[I]\f[]\&...
\f[I]\f[CI]FIELDNAME2\f[I]\f[]...
.PP
This (a) names the CSV fields, in order (names may not contain
whitespace; uninteresting names may be left blank), and (b) assigns them
@ -192,7 +192,7 @@ Field assignments can be used instead of or in addition to a field list.
.PD 0
.P
.PD
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&...
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]...
.PP
\f[C]if\f[]
.PD 0
@ -202,16 +202,16 @@ Field assignments can be used instead of or in addition to a field list.
.PD 0
.P
.PD
\f[I]\f[CI]PATTERN\f[I]\f[]\&...
\f[I]\f[CI]PATTERN\f[I]\f[]...
.PD 0
.P
.PD
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&...
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]...
.PP
This applies one or more field assignments, only to those CSV records
matched by one of the PATTERNs.
The patterns are case\-insensitive regular expressions which match
anywhere within the whole CSV record (it's not yet possible to match
anywhere within the whole CSV record (it\[aq]s not yet possible to match
within a specific field).
When there are multiple patterns they can be written on separate lines,
unindented.
@ -244,7 +244,7 @@ banking\ thru\ software
.PP
Include another rules file at this point.
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to
the current file's directory.
the current file\[aq]s directory.
Eg:
.IP
.nf
@ -261,9 +261,9 @@ Consider adding this rule if all of the following are true: you might be
processing just one day of data, your CSV records are in reverse
chronological order (newest first), and you care about preserving the
order of same\-day transactions.
It usually isn't needed, because hledger autodetects the CSV order, but
when all CSV records have the same date it will assume they are oldest
first.
It usually isn\[aq]t needed, because hledger autodetects the CSV order,
but when all CSV records have the same date it will assume they are
oldest first.
.SH CSV TIPS
.SS CSV ordering
.PP
@ -274,8 +274,9 @@ case where you might need \f[C]newest\-first\f[], see above).
.PP
Each journal entry will have two postings, to \f[C]account1\f[] and
\f[C]account2\f[] respectively.
It's not yet possible to generate entries with more than two postings.
It's conventional and recommended to use \f[C]account1\f[] for the
It\[aq]s not yet possible to generate entries with more than two
postings.
It\[aq]s conventional and recommended to use \f[C]account1\f[] for the
account whose CSV we are reading.
.SS CSV amounts
.PP

204
hledger-lib/hledger_journal.5
View File

@ -6,29 +6,31 @@
.SH NAME
.PP
Journal \- hledger's default file format, representing a General Journal
Journal \- hledger\[aq]s default file format, representing a General
Journal
.SH DESCRIPTION
.PP
hledger's usual data source is a plain text file containing journal
hledger\[aq]s usual data source is a plain text file containing journal
entries in hledger journal format.
This file represents a standard accounting general journal.
I use file names ending in \f[C]\&.journal\f[], but that's not required.
I use file names ending in \f[C]\&.journal\f[], but that\[aq]s not
required.
The journal file contains a number of transaction entries, each
describing a transfer of money (or any commodity) between two or more
named accounts, in a simple format readable by both hledger and humans.
.PP
hledger's journal format is a compatible subset, mostly, of ledger's
journal format, so hledger can work with compatible ledger journal files
as well.
It's safe, and encouraged, to run both hledger and ledger on the same
journal file, eg to validate the results you're getting.
hledger\[aq]s journal format is a compatible subset, mostly, of
ledger\[aq]s journal format, so hledger can work with compatible ledger
journal files as well.
It\[aq]s safe, and encouraged, to run both hledger and ledger on the
same journal file, eg to validate the results you\[aq]re getting.
.PP
You can use hledger without learning any more about this file; just use
the add or web commands to create and update it.
Many users, though, also edit the journal file directly with a text
editor, perhaps assisted by the helper modes for emacs or vim.
.PP
Here's an example:
Here\[aq]s an example:
.IP
.nf
\f[C]
@ -81,7 +83,7 @@ line or a semicolon)
semicolon until end of line)
.PP
Then comes zero or more (but usually at least 2) indented lines
representing\&...
representing...
.SS Postings
.PP
A posting is an addition of some amount to, or removal of some amount
@ -134,12 +136,12 @@ The primary date, on the left, is used by default; the secondary date,
on the right, is used when the \f[C]\-\-date2\f[] flag is specified
(\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work).
.PP
The meaning of secondary dates is up to you, but it's best to follow a
consistent rule.
Eg write the bank's clearing date as primary, and when needed, the date
the transaction was initiated as secondary.
The meaning of secondary dates is up to you, but it\[aq]s best to follow
a consistent rule.
Eg write the bank\[aq]s clearing date as primary, and when needed, the
date the transaction was initiated as secondary.
.PP
Here's an example.
Here\[aq]s an example.
Note that a secondary date will use the year of the primary date if
unspecified.
.IP
@ -203,14 +205,14 @@ $\ hledger\ \-f\ t.j\ register\ checking
.fi
.PP
DATE should be a simple date; if the year is not specified it will use
the year of the transaction's date.
the year of the transaction\[aq]s date.
You can set the secondary date similarly, with \f[C]date2:DATE2\f[].
The \f[C]date:\f[] or \f[C]date2:\f[] tags must have a valid simple date
value if they are present, eg a \f[C]date:\f[] tag with no value is not
allowed.
.PP
Ledger's earlier, more compact bracketed date syntax is also supported:
\f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[].
Ledger\[aq]s earlier, more compact bracketed date syntax is also
supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[].
hledger will attempt to parse any square\-bracketed sequence of the
\f[C]0123456789/\-.=\f[] characters in this way.
With this syntax, DATE infers its year from the transaction and DATE2
@ -254,11 +256,11 @@ When reporting, you can filter by status with the
\f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in
hledger\-ui.
.PP
Note, in Ledger and in older versions of hledger, the \[lq]unmarked\[rq]
state is called \[lq]uncleared\[rq].
Note, in Ledger and in older versions of hledger, the "unmarked" state
is called "uncleared".
As of hledger 1.3 we have renamed it to unmarked for clarity.
.PP
To replicate Ledger and old hledger's behaviour of also matching
To replicate Ledger and old hledger\[aq]s behaviour of also matching
pending, combine \-U and \-P.
.PP
Status marks are optional, but can be helpful eg for reconciling with
@ -268,9 +270,8 @@ status.
Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c
C\-e, or posting status with C\-c C\-c.
.PP
What \[lq]uncleared\[rq], \[lq]pending\[rq], and \[lq]cleared\[rq]
actually mean is up to you.
Here's one suggestion:
What "uncleared", "pending", and "cleared" actually mean is up to you.
Here\[aq]s one suggestion:
.PP
.TS
tab(@);
@ -304,10 +305,10 @@ bank soon (like uncashed checks), and no flags to see the most
up\-to\-date state of your finances.
.SS Description
.PP
A transaction's description is the rest of the line following the date
and status mark (or until a comment begins).
Sometimes called the \[lq]narration\[rq] in traditional bookkeeping, it
can be used for whatever you wish, or left blank.
A transaction\[aq]s description is the rest of the line following the
date and status mark (or until a comment begins).
Sometimes called the "narration" in traditional bookkeeping, it can be
used for whatever you wish, or left blank.
Transaction descriptions can be queried, unlike comments.
.SS Payee and note
.PP
@ -380,8 +381,8 @@ Some examples:
.PP
As you can see, the amount format is somewhat flexible:
.IP \[bu] 2
amounts are a number (the \[lq]quantity\[rq]) and optionally a currency
symbol/commodity name (the \[lq]commodity\[rq]).
amounts are a number (the "quantity") and optionally a currency
symbol/commodity name (the "commodity").
.IP \[bu] 2
the commodity is a symbol, word, or phrase, on the left or right, with
or without a separating space.
@ -400,8 +401,8 @@ from digit groups separator
.IP \[bu] 2
scientific E\-notation is allowed.
Be careful not to use a digit group separator character in scientific
notation, as it's not supported and it might get mistaken for a decimal
point.
notation, as it\[aq]s not supported and it might get mistaken for a
decimal point.
(Declaring the digit group separator character explicitly with a
commodity directive will prevent this.)
.PP
@ -439,13 +440,13 @@ will be the maximum from all posting amounts in that commmodity
or if there are no such amounts in the journal, a default format is used
(like \f[C]$1000.00\f[]).
.PP
Price amounts and amounts in \f[C]D\f[] directives usually don't affect
amount format inference, but in some situations they can do so
Price amounts and amounts in \f[C]D\f[] directives usually don\[aq]t
affect amount format inference, but in some situations they can do so
indirectly.
(Eg when D's default commodity is applied to a commodity\-less amount,
or when an amountless posting is balanced using a price's commodity, or
when \-V is used.) If you find this causing problems, set the desired
format with a commodity directive.
(Eg when D\[aq]s default commodity is applied to a commodity\-less
amount, or when an amountless posting is balanced using a price\[aq]s
commodity, or when \-V is used.) If you find this causing problems, set
the desired format with a commodity directive.
.SS Virtual Postings
.PP
When you parenthesise the account name in a posting, we call that a
@ -456,7 +457,7 @@ it is ignored when checking that the transaction is balanced
it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used,
or the \f[C]real:1\f[] query.
.PP
You could use this, eg, to set an account's opening balance without
You could use this, eg, to set an account\[aq]s opening balance without
needing to use the \f[C]equity:opening\ balances\f[] account:
.IP
.nf
@ -490,7 +491,8 @@ which is more correct and provides better error checking.
.SS Balance Assertions
.PP
hledger supports Ledger\-style balance assertions in journal files.
These look like \f[C]=EXPECTEDBALANCE\f[] following a posting's amount.
These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
amount.
Eg in this example we assert the expected dollar balance in accounts a
and b after each posting:
.IP
@ -515,7 +517,7 @@ You can disable them temporarily with the
troubleshooting or for reading Ledger files.
.SS Assertions and ordering
.PP
hledger sorts an account's postings and assertions first by date and
hledger sorts an account\[aq]s postings and assertions first by date and
then (for postings on the same day) by parse order.
Note this is different from Ledger, which sorts assertions only by parse
order.
@ -534,31 +536,31 @@ intra\-day balances.
With included files, things are a little more complicated.
Including preserves the ordering of postings and assertions.
If you have multiple postings to an account on the same day, split
across different files, and you also want to assert the account's
balance on the same day, you'll have to put the assertion in the right
file.
across different files, and you also want to assert the account\[aq]s
balance on the same day, you\[aq]ll have to put the assertion in the
right file.
.SS Assertions and multiple \-f options
.PP
Balance assertions don't work well across files specified with multiple
\-f options.
Balance assertions don\[aq]t work well across files specified with
multiple \-f options.
Use include or concatenate the files instead.
.SS Assertions and commodities
.PP
The asserted balance must be a simple single\-commodity amount, and in
fact the assertion checks only this commodity's balance within the
fact the assertion checks only this commodity\[aq]s balance within the
(possibly multi\-commodity) account balance.
.PD 0
.P
.PD
This is how assertions work in Ledger also.
We could call this a \[lq]partial\[rq] balance assertion.
We could call this a "partial" balance assertion.
.PP
To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance.
write multiple postings, each asserting one commodity\[aq]s balance.
.PP
You can make a stronger kind of balance assertion, by writing a double
equals sign (\f[C]==EXPECTEDBALANCE\f[]).
This \[lq]complete\[rq] balance assertion asserts the absence of other
This "complete" balance assertion asserts the absence of other
commodities (or, that their balance is 0, which to hledger is
equivalent.)
.IP
@ -581,8 +583,8 @@ equivalent.)
\f[]
.fi
.PP
It's not yet possible to make a complete assertion about a balance that
has multiple commodities.
It\[aq]s not yet possible to make a complete assertion about a balance
that has multiple commodities.
One workaround is to isolate each commodity into its own subaccount:
.IP
.nf
@ -605,7 +607,7 @@ the meaning of that would be unclear.
.SS Assertions and subaccounts
.PP
Balance assertions do not count the balance from subaccounts; they check
the posted account's exclusive balance.
the posted account\[aq]s exclusive balance.
For example:
.IP
.nf
@ -617,7 +619,7 @@ For example:
\f[]
.fi
.PP
The balance report's flat mode shows these exclusive balances more
The balance report\[aq]s flat mode shows these exclusive balances more
clearly:
.IP
.nf
@ -673,16 +675,16 @@ or when adjusting a balance to reality:
\f[]
.fi
.PP
The calculated amount depends on the account's balance in the commodity
at that point (which depends on the previously\-dated postings of the
commodity to that account since the last balance assertion or
The calculated amount depends on the account\[aq]s balance in the
commodity at that point (which depends on the previously\-dated postings
of the commodity to that account since the last balance assertion or
assignment).
Note that using balance assignments makes your journal a little less
explicit; to know the exact amount posted, you have to run hledger or do
the calculations yourself, instead of just reading it.
.SS Transaction prices
.PP
Within a transaction, you can note an amount's price in another
Within a transaction, you can note an amount\[aq]s price in another
commodity.
This can be used to document the cost (in a purchase) or selling price
(in a sale).
@ -736,8 +738,8 @@ hledger infer the price that balances the transaction:
\f[C]{=UNITPRICE}\f[], which hledger currently ignores).
.PP
Use the \f[C]\-B/\-\-cost\f[] flag to convert amounts to their
transaction price's commodity, if any.
(mnemonic: \[lq]B\[rq] is from \[lq]cost Basis\[rq], as in Ledger).
transaction price\[aq]s commodity, if any.
(mnemonic: "B" is from "cost Basis", as in Ledger).
Eg here is how \-B affects the balance report for the example above:
.IP
.nf
@ -754,7 +756,7 @@ $\ hledger\ bal\ \-N\ \-\-flat\ \-B
Note \-B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last
amount.
So if example 3's postings are reversed, while the transaction is
So if example 3\[aq]s postings are reversed, while the transaction is
equivalent, \-B shows something different:
.IP
.nf
@ -837,7 +839,8 @@ comma or end of line, with leading/trailing whitespace removed:
\f[]
.fi
.PP
Note this means hledger's tag values can not contain commas or newlines.
Note this means hledger\[aq]s tag values can not contain commas or
newlines.
Ending at commas means you can write multiple short tags on one line,
comma separated:
.IP
@ -849,13 +852,12 @@ comma separated:
.PP
Here,
.IP \[bu] 2
\[lq]\f[C]a\ comment\ containing\f[]\[rq] is just comment text, not a
tag
"\f[C]a\ comment\ containing\f[]" is just comment text, not a tag
.IP \[bu] 2
\[lq]\f[C]tag1\f[]\[rq] is a tag with no value
"\f[C]tag1\f[]" is a tag with no value
.IP \[bu] 2
\[lq]\f[C]tag2\f[]\[rq] is another tag, whose value is
\[lq]\f[C]some\ value\ ...\f[]\[rq]
"\f[C]tag2\f[]" is another tag, whose value is
"\f[C]some\ value\ ...\f[]"
.PP
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
@ -871,18 +873,19 @@ For example, the following transaction has three tags (\f[C]A\f[],
\f[]
.fi
.PP
Tags are like Ledger's metadata feature, except hledger's tag values are
simple strings.
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are simple strings.
.SS Directives
.PP
A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed.
hledger's directives are based on a subset of Ledger's, but there are
many differences (and also some differences between hledger versions).
hledger\[aq]s directives are based on a subset of Ledger\[aq]s, but
there are many differences (and also some differences between hledger
versions).
.PP
Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with links
to more detailed docs.
Directives\[aq] behaviour and interactions can get a little bit complex,
so here is a table summarising the directives and their effects, with
links to more detailed docs.
.PP
.TS
tab(@);
@ -1064,8 +1067,8 @@ The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files.
.SS Default year
.PP
You can set a default year to be used for subsequent dates which don't
specify a year.
You can set a default year to be used for subsequent dates which
don\[aq]t specify a year.
This is a line beginning with \f[C]Y\f[] followed by the year.
Eg:
.IP
@ -1105,7 +1108,7 @@ commodity\ 1,000.0000\ AAAA
\f[]
.fi
.PP
or on multiple lines, using the \[lq]format\[rq] subdirective.
or on multiple lines, using the "format" subdirective.
In this case the commodity symbol appears twice and should be the same
in both places:
.IP
@ -1134,7 +1137,7 @@ digits).
.PP
The \f[C]D\f[] directive sets a default commodity (and display format),
to be used for amounts without a commodity symbol (ie, plain numbers).
(Note this differs from Ledger's default commodity directive.) The
(Note this differs from Ledger\[aq]s default commodity directive.) The
commodity and display format will be applied to all subsequent
commodity\-less amounts, or until the next \f[C]D\f[] directive.
.IP
@ -1156,9 +1159,9 @@ written with a decimal point.
.PP
The \f[C]P\f[] directive declares a market price, which is an exchange
rate between two commodities on a certain date.
(In Ledger, they are called \[lq]historical prices\[rq].) These are
often obtained from a stock exchange, cryptocurrency exchange, or the
foreign exchange market.
(In Ledger, they are called "historical prices".) These are often
obtained from a stock exchange, cryptocurrency exchange, or the foreign
exchange market.
.PP
Here is the format:
.IP
@ -1198,7 +1201,7 @@ reference.
They can store extra information about accounts (account numbers, notes,
etc.)
.IP \[bu] 2
They can help hledger know your accounts' types (asset, liability,
They can help hledger know your accounts\[aq] types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
.IP \[bu] 2
@ -1268,7 +1271,7 @@ If you name your top\-level accounts with some variation of
detected automatically.
.SS Account types declared with tags
.PP
More generally, you can declare an account's type with an account
More generally, you can declare an account\[aq]s type with an account
directive, by writing a \f[C]type:\f[] tag in a comment, followed by one
of the words \f[C]Asset\f[], \f[C]Liability\f[], \f[C]Equity\f[],
\f[C]Revenue\f[], \f[C]Expense\f[], or one of the letters \f[C]ALERX\f[]
@ -1332,7 +1335,7 @@ account\ expenses
\f[]
.fi
.PP
you'll see those accounts displayed in declaration order, not
you\[aq]ll see those accounts displayed in declaration order, not
alphabetically:
.IP
.nf
@ -1358,13 +1361,14 @@ account\ other:zoo
\f[]
.fi
.PP
would influence the position of \f[C]zoo\f[] among \f[C]other\f[]'s
would influence the position of \f[C]zoo\f[] among \f[C]other\f[]\[aq]s
subaccounts, but not the position of \f[C]other\f[] among the top\-level
accounts.
This means: \- you will sometimes declare parent accounts (eg
\f[C]account\ other\f[] above) that you don't intend to post to, just to
customize their display order \- sibling accounts stay together (you
couldn't display \f[C]x:y\f[] in between \f[C]a:b\f[] and \f[C]a:c\f[]).
\f[C]account\ other\f[] above) that you don\[aq]t intend to post to,
just to customize their display order \- sibling accounts stay together
(you couldn\[aq]t display \f[C]x:y\f[] in between \f[C]a:b\f[] and
\f[C]a:c\f[]).
.SS Rewriting accounts
.PP
You can define account alias rules which rewrite your account names, or
@ -1403,7 +1407,7 @@ alias\ OLD\ =\ NEW
Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the
command line.
This affects all entries.
It's useful for trying out aliases interactively.
It\[aq]s useful for trying out aliases interactively.
.PP
OLD and NEW are case sensitive full account names.
hledger will replace any occurrence of the old account name with the new
@ -1549,8 +1553,8 @@ Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but
.PP
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not).
They will be relative to today's date, unless a Y default year directive
is in effect, in which case they will be relative to Y/1/1.
They will be relative to today\[aq]s date, unless a Y default year
directive is in effect, in which case they will be relative to Y/1/1.
.SS Two spaces after the period expression
.PP
If the period expression is followed by a transaction description, these
@ -1593,9 +1597,9 @@ journal, or today if there are no normal transactions.
ends on the report end date if specified with \-e/\-p/date:, or 180 days
from today.
.PP
where \[lq]today\[rq] means the current date at report time.
The \[lq]later of\[rq] rule ensures that forecast transactions do not
overlap normal transactions in time; they will begin only after normal
where "today" means the current date at report time.
The "later of" rule ensures that forecast transactions do not overlap
normal transactions in time; they will begin only after normal
transactions end.
.PP
Forecasting can be useful for estimating balances into the future, and
@ -1627,14 +1631,14 @@ and Forecasting.
.PP
Transaction modifier rules describe changes that should be applied
automatically to certain transactions.
Currently, this means adding extra postings (also known as
\[lq]automated postings\[rq]).
Currently, this means adding extra postings (also known as "automated
postings").
Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag.
.PP
A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that matches
certain postings (mnemonic: \f[C]=\f[] suggests matching).
And each \[lq]posting\[rq] is actually a posting\-generating rule:
And each "posting" is actually a posting\-generating rule:
.IP
.nf
\f[C]
@ -1656,13 +1660,13 @@ The commodity symbol (if any) from the matched posting will be added to
this.
.IP \[bu] 2
a numeric multiplier, eg \f[C]*2\f[] (a star followed by a number N).
The matched posting's amount (and total price, if any) will be
The matched posting\[aq]s amount (and total price, if any) will be
multiplied by N.
.IP \[bu] 2
a multiplier with a commodity symbol, eg \f[C]*$2\f[] (a star, number N,
and symbol S).
The matched posting's amount will be multiplied by N, and its commodity
symbol will be replaced with S.
The matched posting\[aq]s amount will be multiplied by N, and its
commodity symbol will be replaced with S.
.PP
Some examples:
.IP

6
hledger-lib/hledger_timeclock.5
View File

@ -9,7 +9,7 @@ Timeclock \- the time logging format of timeclock.el, as read by hledger
.SH DESCRIPTION
.PP
hledger can read timeclock files.
As with Ledger, these are (a subset of) timeclock.el's format,
As with Ledger, these are (a subset of) timeclock.el\[aq]s format,
containing clock\-in and clock\-out entries as in the example below.
The date is a simple date.
The time format is HH:MM[:SS][+\-ZZZZ].
@ -67,8 +67,8 @@ at the command line, use these bash aliases:
.IP \[bu] 2
or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x
repository.
These rely on a \[lq]timeclock\[rq] executable which I think is just the
ledger 2 executable renamed.
These rely on a "timeclock" executable which I think is just the ledger
2 executable renamed.
.SH "REPORTING BUGS"

12
hledger-lib/hledger_timedot.5
View File

@ -5,7 +5,7 @@
.SH NAME
.PP
Timedot \- hledger's human\-friendly time logging format
Timedot \- hledger\[aq]s human\-friendly time logging format
.SH DESCRIPTION
.PP
Timedot is a plain text format for logging dated, categorised quantities
@ -16,10 +16,10 @@ precise or too interruptive.
It can be formatted like a bar chart, making clear at a glance where
time was spent.
.PP
Though called \[lq]timedot\[rq], this format is read by hledger as
commodityless quantities, so it could be used to represent dated
quantities other than time.
In the docs below we'll assume it's time.
Though called "timedot", this format is read by hledger as commodityless
quantities, so it could be used to represent dated quantities other than
time.
In the docs below we\[aq]ll assume it\[aq]s time.
.SH FILE FORMAT
.PP
A timedot file contains a series of day entries.
@ -34,7 +34,7 @@ Quantities can be written as:
.IP \[bu] 2
a sequence of dots (.) representing quarter hours.
Spaces may optionally be used for grouping and readability.
Eg: \&....
Eg: ....
\&..
.IP \[bu] 2
an integral or decimal number, representing hours.

61
hledger-ui/hledger-ui.1
View File

@ -20,17 +20,17 @@ other commodity, using double\-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger\-ui is hledger's curses\-style interface, providing an efficient
full\-window text UI for viewing accounts and transactions, and some
limited data entry capability.
It is easier than hledger's command\-line interface, and sometimes
hledger\-ui is hledger\[aq]s curses\-style interface, providing an
efficient full\-window text UI for viewing accounts and transactions,
and some limited data entry capability.
It is easier than hledger\[aq]s command\-line interface, and sometimes
quicker and more convenient than the web interface.
.PP
Note hledger\-ui has some different defaults: \- it generates
rule\-based transactions and postings by default (\[en]forecast and
\[en]auto are always on).
rule\-based transactions and postings by default (\-\-forecast and
\-\-auto are always on).
\- it hides transactions dated in the future by default (change this
with \[en]future or the F key).
with \-\-future or the F key).
Experimental.
.PP
Like hledger, it reads data from one or more files in hledger journal,
@ -57,7 +57,7 @@ use this custom display theme
.RE
.TP
.B \f[C]\-\-register=ACCTREGEX\f[]
start in the (first) matched account's register screen
start in the (first) matched account\[aq]s register screen
.RS
.RE
.TP
@ -96,7 +96,7 @@ Conversion rules file to use when reading CSV (default: FILE.rules)
.RE
.TP
.B \f[C]\-\-separator=CHAR\f[]
Field separator to expect when reading CSV (default: `,')
Field separator to expect when reading CSV (default: \[aq],\[aq])
.RS
.RE
.TP
@ -264,7 +264,7 @@ Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style
movement keys are also supported.
A tip: movement speed is limited by your keyboard repeat rate, to move
faster you may want to adjust it.
(If you're on a mac, the Karabiner app is one way to do that.)
(If you\[aq]re on a mac, the Karabiner app is one way to do that.)
.PP
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
@ -272,9 +272,9 @@ the transactions to be shown (by default, all are shown).
report period durations: year, quarter, month, week, day.
Then, \f[C]shift\-left/right\f[] moves to the previous/next period.
\f[C]t\f[] sets the report period to today.
With the \f[C]\-\-watch\f[] option, when viewing a \[lq]current\[rq]
period (the current day, week, month, quarter, or year), the period will
move automatically to track the current date.
With the \f[C]\-\-watch\f[] option, when viewing a "current" period (the
current day, week, month, quarter, or year), the period will move
automatically to track the current date.
To set a non\-standard period, you can use \f[C]/\f[] and a
\f[C]date:\f[] query.
.PP
@ -299,8 +299,8 @@ convenient.
Or, it cancels a minibuffer edit or help dialog in progress.
.PP
\f[C]CTRL\-l\f[] redraws the screen and centers the selection if
possible (selections near the top won't be centered, since we don't
scroll above the top).
possible (selections near the top won\[aq]t be centered, since we
don\[aq]t scroll above the top).
.PP
\f[C]g\f[] reloads from the data file(s) and updates the current screen
and any previous screens.
@ -310,7 +310,7 @@ and any previous screens.
Disabling balance assertions temporarily can be useful for
troubleshooting.
.PP
\f[C]a\f[] runs command\-line hledger's add command, and reloads the
\f[C]a\f[] runs command\-line hledger\[aq]s add command, and reloads the
updated file.
This allows some basic data entry.
.PP
@ -333,7 +333,8 @@ Additional screen\-specific keys are described below.
.SS Accounts screen
.PP
This is normally the first screen displayed.
It lists accounts and their balances, like hledger's balance command.
It lists accounts and their balances, like hledger\[aq]s balance
command.
By default, it shows all accounts and their latest ending balances
(including the balances of subaccounts).
if you specify a query on the command line, it shows just the matched
@ -380,8 +381,8 @@ all three, the filter is removed.)
balances are shown (hledger\-ui shows zero items by default, unlike
command\-line hledger).
.PP
Press \f[C]right\f[] or \f[C]enter\f[] to view an account's transactions
register.
Press \f[C]right\f[] or \f[C]enter\f[] to view an account\[aq]s
transactions register.
.SS Register screen
.PP
This screen shows the transactions affecting a particular account, like
@ -392,7 +393,7 @@ the other account(s) involved, in abbreviated form.
(If there are both real and virtual postings, it shows only the accounts
affected by real postings.)
.IP \[bu] 2
the overall change to the current account's balance; positive for an
the overall change to the current account\[aq]s balance; positive for an
inflow to this account, negative for an outflow.
.IP \[bu] 2
the running historical total or period total for the current account,
@ -405,10 +406,10 @@ If the historical total is not disturbed by a filter query, it will be
the running historical balance you would see on a bank register for the
current account.
.PP
Transactions affecting this account's subaccounts will be included in
the register if the accounts screen is in tree mode, or if it's in flat
mode but this account has subaccounts which are not shown due to a depth
limit.
Transactions affecting this account\[aq]s subaccounts will be included
in the register if the accounts screen is in tree mode, or if it\[aq]s
in flat mode but this account has subaccounts which are not shown due to
a depth limit.
In other words, the register always shows the transactions contributing
to the balance shown on the accounts screen.
.PD 0
@ -435,10 +436,10 @@ transaction in detail.
.SS Transaction screen
.PP
This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format
similar to hledger\[aq]s print command and journal format
(hledger_journal(5)).
.PP
The transaction's date(s) and any cleared flag, transaction code,
The transaction\[aq]s date(s) and any cleared flag, transaction code,
description, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in
certain cases, fewer).
@ -449,9 +450,9 @@ In the title bar, the numbers in parentheses show your position within
that account register.
They will vary depending on which account register you came from
(remember most transactions appear in multiple account registers).
The #N number preceding them is the transaction's position within the
complete unfiltered journal, which is a more stable id (at least until
the next reload).
The #N number preceding them is the transaction\[aq]s position within
the complete unfiltered journal, which is a more stable id (at least
until the next reload).
.SS Error screen
.PP
This screen will appear if there is a problem, such as a parse error,
@ -479,7 +480,7 @@ perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward.
.PP
\f[C]\-f\-\f[] doesn't work (hledger\-ui can't read from stdin).
\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-ui can\[aq]t read from stdin).
.PP
\f[C]\-V\f[] affects only the accounts screen.
.PP

6
hledger-ui/hledger-ui.txt
View File

@ -23,9 +23,9 @@ DESCRIPTION
web interface.
Note hledger-ui has some different defaults: - it generates rule-based
transactions and postings by default (-forecast and -auto are always
transactions and postings by default (--forecast and --auto are always
on). - it hides transactions dated in the future by default (change
this with -future or the F key). Experimental.
this with --future or the F key). Experimental.
Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE,
@ -73,7 +73,7 @@ OPTIONS
FILE.rules)
--separator=CHAR
Field separator to expect when reading CSV (default: `,')
Field separator to expect when reading CSV (default: ',')
--alias=OLD=NEW
rename accounts named OLD to NEW

18
hledger-web/hledger-web.1
View File

@ -20,7 +20,7 @@ other commodity, using double\-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger\-web is hledger's web interface.
hledger\-web is hledger\[aq]s web interface.
It starts a simple web application for browsing and adding transactions,
and optionally opens it in a web browser window if possible.
It provides a more user\-friendly UI than the hledger CLI or hledger\-ui
@ -42,8 +42,8 @@ timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
For more about this see hledger(1), hledger_journal(5) etc.
.PP
By default, hledger\-web starts the web app in \[lq]transient mode\[rq]
and also opens it in your default web browser if possible.
By default, hledger\-web starts the web app in "transient mode" and also
opens it in your default web browser if possible.
In this mode the web app will keep running for as long as you have it
open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it).
@ -61,8 +61,9 @@ if you are running multiple hledger\-web instances.
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
port and path that appear in hyperlinks, useful eg for integrating
hledger\-web within a larger website.
The default is \f[C]http://HOST:PORT/\f[] using the server's configured
host address and TCP port (or \f[C]http://HOST\f[] if PORT is 80).
The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
80).
.PP
With \f[C]\-\-file\-url\f[] you can set a different base url for static
files, eg for better caching or cookie\-less serving on high performance
@ -90,7 +91,7 @@ Note: if invoking hledger\-web as a hledger subcommand, write
\f[C]\-\-\f[] before options as shown above.
.TP
.B \f[C]\-\-serve\f[]
serve and log requests, don't browse or auto\-exit
serve and log requests, don\[aq]t browse or auto\-exit
.RS
.RE
.TP
@ -134,7 +135,7 @@ Conversion rules file to use when reading CSV (default: FILE.rules)
.RE
.TP
.B \f[C]\-\-separator=CHAR\f[]
Field separator to expect when reading CSV (default: `,')
Field separator to expect when reading CSV (default: \[aq],\[aq])
.RS
.RE
.TP
@ -302,7 +303,8 @@ perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward.
.PP
\f[C]\-f\-\f[] doesn't work (hledger\-web can't read from stdin).
\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-web can\[aq]t read from
stdin).
.PP
Query arguments and some hledger options are ignored.
.PP

2
hledger-web/hledger-web.txt
View File

@ -106,7 +106,7 @@ OPTIONS
FILE.rules)
--separator=CHAR
Field separator to expect when reading CSV (default: `,')
Field separator to expect when reading CSV (default: ',')
--alias=OLD=NEW
rename accounts named OLD to NEW

518
hledger/hledger.1
View File

File diff suppressed because it is too large Load Diff

422
hledger/hledger.info
View File

@ -520,7 +520,7 @@ need to write the date _after_ the last day you want to include.
Examples:
'-b 2016/3/17' begin on St. Patrick's day 2016
'-b 2016/3/17' begin on St. Patrick's day 2016
'-e 12/1' end at the start of december 1st of the current year (11/30 will be the last date included)
'-b thismonth' all transactions on or after the 1st of the current month
'-p thismonth' all transactions in the current month
@ -1220,6 +1220,10 @@ Show accounts and their balances. Aliases: b, bal.
'-O FMT --output-format=FMT'
select the output format. Supported formats: txt, csv, html.
'--transpose'
transposes rows and columns in multi-column reports. Supported
formats: txt, csv
'-o FILE --output-file=FILE'
write output to FILE. A file extension matching one of the above
@ -1585,42 +1589,158 @@ expense categories to construct a minimal monthly budget:
$ hledger balance -M --budget
Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
======================++=================================================
<unbudgeted> || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
expenses:bus || $49 [98% of $50] $53 [106% of $50]
expenses:food || $396 [99% of $400] $412 [103% of $400]
expenses:movies || $30 [100% of $30] 0 [0% of $30]
income || $1950 [98% of $2000] $2100 [105% of $2000]
----------------------++-------------------------------------------------
|| 0 0
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
By default, only accounts with budget goals during the report period
are shown. '--show-unbudgeted' shows unbudgeted accounts as well.
Top-level accounts with no budget goals anywhere below them are grouped
under '<unbudgeted>'.
are shown. In the example above, transactions in 'expenses:gifts' and
'expenses:supplies' are counted towards 'expenses' budget, but accounts
'expenses:gifts' and 'expenses:supplies' are not shown, as they don't
have any budgets.
You can use '--show-unbudgeted' shows unbudgeted accounts as well:
$ hledger balance -M --budget --show-unbudgeted
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:gifts || 0 $100
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
expenses:supplies || $20 0
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
You can roll over unspent budgets to next period with '--cumulative':
$ hledger balance -M --budget --cumulative
Budget performance in 2017/11/01-2017/12/31:
|| 2017/11/30 2017/12/31
======================++=================================================
<unbudgeted> || $20 $120
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
expenses:bus || $49 [98% of $50] $102 [102% of $100]
expenses:food || $396 [99% of $400] $808 [101% of $800]
expenses:movies || $30 [100% of $30] $30 [50% of $60]
income || $1950 [98% of $2000] $4050 [101% of $4000]
----------------------++-------------------------------------------------
|| 0 0
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
Note, the '-S/--sort-amount' flag is not yet fully supported with
'--budget'.
For more examples, see Budgeting and Forecasting.
* Menu:
* Nested budgets::

File: hledger.info, Node: Nested budgets, Up: Budget report
4.4.7.1 Nested budgets
......................
You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then
budget(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave.
In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well.
To illustrate this, consider the following budget:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicity
means that budget for both 'expenses:personal' and 'expenses' is $1100.
Transactions in 'expenses:personal:electronics' will be counted both
towards its $100 budget and $1100 of 'expenses:personal' , and
transactions in any other subaccount of 'expenses:personal' would be
counted towards only towards the budget of 'expenses:personal'.
For example, let's consider these transactions:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
2019/01/01 Google home hub
expenses:personal:electronics $90.00
liabilities $-90.00
2019/01/02 Phone screen protector
expenses:personal:electronics:upgrades $10.00
liabilities
2019/01/02 Weekly train ticket
expenses:personal:train tickets $153.00
liabilities
2019/01/03 Flowers
expenses:personal $30.00
liabilities
As you can see, we have transactions in
'expenses:personal:electronics:upgrades' and 'expenses:personal:train
tickets', and since both of these accounts are without explicitly
defined budget, these transactions would be counted towards budgets of
'expenses:personal:electronics' and 'expenses:personal' accordingly:
$ hledger balance --budget -M
Budget performance in 2019/01:
|| Jan
===============================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
liabilities || $-283.00 [ 26% of $-1100.00]
-------------------------------++-------------------------------
|| 0 [ 0]
And with '--show-unbudgeted', we can get a better picture of budget
allocation and consumption:
$ hledger balance --budget -M --show-unbudgeted
Budget performance in 2019/01:
|| Jan
========================================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
expenses:personal:electronics:upgrades || $10.00
expenses:personal:train tickets || $153.00
liabilities || $-283.00 [ 26% of $-1100.00]
----------------------------------------++-------------------------------
|| 0 [ 0]
4.4.8 Output format
-------------------
@ -1851,15 +1971,11 @@ File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMAND
4.10 close
==========
close, equity
Prints a "closing balances" transaction and an "opening balances"
transaction, that bring account balances to and from zero, respectively.
Useful for, eg:
* bringing asset/liability balances forward into a new journal file
* closing out revenues/expenses to retained earnings at the end of a
period
close, equity Prints a "closing balances" transaction and an "opening
balances" transaction that bring account balances to and from zero,
respectively. Useful for bringing asset/liability balances forward into
a new journal file, or for closing out revenues/expenses to retained
earnings at the end of a period.
The closing transaction transfers balances to "equity:closing
balances". The opening transaction transfers balances from
@ -1881,7 +1997,7 @@ register reports; you can exclude them with a query like
"close the books" at the end of an accounting period, transferring
income statement account balances to retained earnings. (You may want
to change the equity account name to something like "equity:retained
earnings" for clarity.)
earnings".)
By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is
@ -1900,7 +2016,7 @@ require -auto.
Examples:
Carrying asset/liability balances into a new file for 2019, all from
command line.
command line:
_Warning: we use '>>' here to append; be careful not to type a single
'>' which would wipe your journal!_
@ -2660,122 +2776,124 @@ Node: Smart dates14210
Ref: #smart-dates14351
Node: Report start & end date15757
Ref: #report-start-end-date15929
Node: Report intervals16994
Ref: #report-intervals17159
Node: Period expressions17560
Ref: #period-expressions17720
Node: Depth limiting21677
Ref: #depth-limiting21821
Node: Pivoting22163
Ref: #pivoting22281
Node: Cost23957
Ref: #cost24065
Node: Market value24183
Ref: #market-value24318
Node: Combining -B and -V25684
Ref: #combining--b-and--v25847
Node: Output destination25994
Ref: #output-destination26156
Node: Output format26439
Ref: #output-format26591
Node: Regular expressions26976
Ref: #regular-expressions27113
Node: QUERIES28474
Ref: #queries28576
Node: COMMANDS32538
Ref: #commands32650
Node: accounts33650
Ref: #accounts33748
Node: activity34994
Ref: #activity35104
Node: add35464
Ref: #add35563
Node: balance38224
Ref: #balance38335
Node: Classic balance report41418
Ref: #classic-balance-report41591
Node: Customising the classic balance report42960
Ref: #customising-the-classic-balance-report43188
Node: Colour support45262
Ref: #colour-support45429
Node: Flat mode45602
Ref: #flat-mode45750
Node: Depth limited balance reports46163
Ref: #depth-limited-balance-reports46363
Node: Multicolumn balance report46819
Ref: #multicolumn-balance-report47017
Node: Budget report52197
Ref: #budget-report52340
Ref: #output-format-155374
Node: balancesheet55452
Ref: #balancesheet55588
Node: balancesheetequity57899
Ref: #balancesheetequity58048
Node: cashflow58585
Ref: #cashflow58713
Node: check-dates60836
Ref: #check-dates60963
Node: check-dupes61080
Ref: #check-dupes61204
Node: close61341
Ref: #close61449
Node: files64891
Ref: #files64992
Node: help65133
Ref: #help65233
Node: import66307
Ref: #import66421
Node: incomestatement67151
Ref: #incomestatement67285
Node: prices69689
Ref: #prices69804
Node: print70076
Ref: #print70186
Node: print-unique75080
Ref: #print-unique75206
Node: register75274
Ref: #register75401
Node: Custom register output79902
Ref: #custom-register-output80031
Node: register-match81261
Ref: #register-match81395
Node: rewrite81578
Ref: #rewrite81693
Node: roi81762
Ref: #roi81860
Node: stats81976
Ref: #stats82075
Node: tags82945
Ref: #tags83043
Node: test83279
Ref: #test83363
Node: ADD-ON COMMANDS84071
Ref: #add-on-commands84181
Node: Official add-ons85468
Ref: #official-add-ons85608
Node: api85695
Ref: #api85784
Node: ui85836
Ref: #ui85935
Node: web85993
Ref: #web86082
Node: Third party add-ons86128
Ref: #third-party-add-ons86303
Node: diff86438
Ref: #diff86535
Node: iadd86634
Ref: #iadd86748
Node: interest86831
Ref: #interest86952
Node: irr87047
Ref: #irr87145
Node: Experimental add-ons87276
Ref: #experimental-add-ons87428
Node: autosync87708
Ref: #autosync87819
Node: chart88058
Ref: #chart88177
Node: check88248
Ref: #check88350
Node: Report intervals16995
Ref: #report-intervals17160
Node: Period expressions17561
Ref: #period-expressions17721
Node: Depth limiting21678
Ref: #depth-limiting21822
Node: Pivoting22164
Ref: #pivoting22282
Node: Cost23958
Ref: #cost24066
Node: Market value24184
Ref: #market-value24319
Node: Combining -B and -V25685
Ref: #combining--b-and--v25848
Node: Output destination25995
Ref: #output-destination26157
Node: Output format26440
Ref: #output-format26592
Node: Regular expressions26977
Ref: #regular-expressions27114
Node: QUERIES28475
Ref: #queries28577
Node: COMMANDS32539
Ref: #commands32651
Node: accounts33651
Ref: #accounts33749
Node: activity34995
Ref: #activity35105
Node: add35465
Ref: #add35564
Node: balance38225
Ref: #balance38336
Node: Classic balance report41526
Ref: #classic-balance-report41699
Node: Customising the classic balance report43068
Ref: #customising-the-classic-balance-report43296
Node: Colour support45370
Ref: #colour-support45537
Node: Flat mode45710
Ref: #flat-mode45858
Node: Depth limited balance reports46271
Ref: #depth-limited-balance-reports46471
Node: Multicolumn balance report46927
Ref: #multicolumn-balance-report47125
Node: Budget report52305
Ref: #budget-report52448
Node: Nested budgets57152
Ref: #nested-budgets57264
Ref: #output-format-160764
Node: balancesheet60842
Ref: #balancesheet60978
Node: balancesheetequity63289
Ref: #balancesheetequity63438
Node: cashflow63975
Ref: #cashflow64103
Node: check-dates66226
Ref: #check-dates66353
Node: check-dupes66470
Ref: #check-dupes66594
Node: close66731
Ref: #close66839
Node: files70253
Ref: #files70354
Node: help70495
Ref: #help70595
Node: import71669
Ref: #import71783
Node: incomestatement72513
Ref: #incomestatement72647
Node: prices75051
Ref: #prices75166
Node: print75438
Ref: #print75548
Node: print-unique80442
Ref: #print-unique80568
Node: register80636
Ref: #register80763
Node: Custom register output85264
Ref: #custom-register-output85393
Node: register-match86623
Ref: #register-match86757
Node: rewrite86940
Ref: #rewrite87055
Node: roi87124
Ref: #roi87222
Node: stats87338
Ref: #stats87437
Node: tags88307
Ref: #tags88405
Node: test88641
Ref: #test88725
Node: ADD-ON COMMANDS89433
Ref: #add-on-commands89543
Node: Official add-ons90830
Ref: #official-add-ons90970
Node: api91057
Ref: #api91146
Node: ui91198
Ref: #ui91297
Node: web91355
Ref: #web91444
Node: Third party add-ons91490
Ref: #third-party-add-ons91665
Node: diff91800
Ref: #diff91897
Node: iadd91996
Ref: #iadd92110
Node: interest92193
Ref: #interest92314
Node: irr92409
Ref: #irr92507
Node: Experimental add-ons92638
Ref: #experimental-add-ons92790
Node: autosync93070
Ref: #autosync93181
Node: chart93420
Ref: #chart93539
Node: check93610
Ref: #check93712

End Tag Table

454
hledger/hledger.txt
View File

@ -135,7 +135,7 @@ OPTIONS
FILE.rules)
--separator=CHAR
Field separator to expect when reading CSV (default: `,')
Field separator to expect when reading CSV (default: ',')
--alias=OLD=NEW
rename accounts named OLD to NEW
@ -444,8 +444,8 @@ OPTIONS
Examples:
-b 2016/3/17 begin on St. Patrick's day
2016
-b 2016/3/17 begin on St. Patrick's
day 2016
-e 12/1 end at the start of decem-
ber 1st of the current
year (11/30 will be the
@ -538,10 +538,10 @@ OPTIONS
For example:
-p "weekly from 2009/1/1 to 2009/4/1" -
starts on 2008/12/29, closest preceed-
ing Monday
-p "monthly in 2008/11/25" - starts on
-p "weekly from 2009/1/1 to 2009/4/1"
-- starts on 2008/12/29, closest pre-
ceeding Monday
-p "monthly in 2008/11/25" -- starts on
2018/11/01
-p "quar-
terly from 2009-05-05 to 2009-06-01" -
@ -561,14 +561,14 @@ OPTIONS
Examples:
-p "bimonthly from 2008" - periods will
have boundaries on 2008/01/01,
-p "bimonthly from 2008" -- periods
will have boundaries on 2008/01/01,
2008/03/01, ...
-p "every 2 weeks" - starts on closest
-p "every 2 weeks" -- starts on closest
preceeding Monday
-p "every 5 month from 2009/03" - peri-
ods will have boundaries on 2009/03/01,
2009/08/01, ...
-p "every 5 month from 2009/03" --
periods will have boundaries on
2009/03/01, 2009/08/01, ...
If you want intervals that start on arbitrary day of your choosing and
span a week, month or year, you need to use any of the following:
@ -580,18 +580,18 @@ OPTIONS
Examples:
-p "every 2nd day of week" - periods
-p "every 2nd day of week" -- periods
will go from Tue to Tue
-p "every Tue" - same
-p "every 15th day" - period boundaries
will be on 15th of each month
-p "every 2nd Monday" - period bound-
-p "every Tue" -- same
-p "every 15th day" -- period bound-
aries will be on 15th of each month
-p "every 2nd Monday" -- period bound-
aries will be on second Monday of each
month
-p "every 11/05" - yearly periods with
-p "every 11/05" -- yearly periods with
boundaries on 5th of Nov
-p "every 5th Nov" - same
-p "every Nov 5th" - same
-p "every 5th Nov" -- same
-p "every Nov 5th" -- same
Show historical balances at end of 15th each month (N is exclusive end
date):
@ -714,7 +714,7 @@ OPTIONS
the prices on each column's end date.)
Combining -B and -V
Using -B/-cost and -V/-value together is currently allowed, but the
Using -B/--cost and -V/--value together is currently allowed, but the
results are probably not meaningful. Let us know if you find a use for
this.
@ -918,7 +918,7 @@ COMMANDS
in flat mode: omit N leading account name parts
This command lists account names, either declared with account direc-
tives (-declared), posted to (-used), or both (default). With query
tives (--declared), posted to (--used), or both (default). With query
arguments, only matched account names and account names referenced by
matched postings are shown. It shows a flat list by default. With
--tree, it uses indentation to show the account hierarchy. In flat
@ -1088,15 +1088,19 @@ COMMANDS
-O FMT --output-format=FMT
select the output format. Supported formats: txt, csv, html.
--transpose
transposes rows and columns in multi-column reports. Supported
formats: txt, csv
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
--pretty-tables
use unicode to display prettier tables.
--sort-amount
sort by amount instead of account code/name (in flat mode).
sort by amount instead of account code/name (in flat mode).
With multiple columns, sorts by the row total, or by row average
if that is displayed.
@ -1104,36 +1108,36 @@ COMMANDS
display all amounts with reversed sign
--budget
show performance compared to budget goals defined by periodic
show performance compared to budget goals defined by periodic
transactions
--show-unbudgeted
with -budget, show unbudgeted accounts also
with --budget, show unbudgeted accounts also
The balance command is hledger's most versatile command. Note, despite
the name, it is not always used for showing real-world account bal-
ances; the more accounting-aware balancesheet and incomestatement may
the name, it is not always used for showing real-world account bal-
ances; the more accounting-aware balancesheet and incomestatement may
be more convenient for that.
By default, it displays all accounts, and each account's change in bal-
ance during the entire period of the journal. Balance changes are cal-
culated by adding up the postings in each account. You can limit the
postings matched, by a query, to see fewer accounts, changes over a
culated by adding up the postings in each account. You can limit the
postings matched, by a query, to see fewer accounts, changes over a
different time period, changes from only cleared transactions, etc.
If you include an account's complete history of postings in the report,
the balance change is equivalent to the account's current ending bal-
ance. For a real-world account, typically you won't have all transac-
the balance change is equivalent to the account's current ending bal-
ance. For a real-world account, typically you won't have all transac-
tions in the journal; instead you'll have all transactions after a cer-
tain date, and an "opening balances" transaction setting the correct
starting balance on that date. Then the balance command will show
real-world account balances. In some cases the -H/-historical flag is
tain date, and an "opening balances" transaction setting the correct
starting balance on that date. Then the balance command will show
real-world account balances. In some cases the -H/--historical flag is
used to ensure this (more below).
The balance command can produce several styles of report:
Classic balance report
This is the original balance report, as found in Ledger. It usually
This is the original balance report, as found in Ledger. It usually
looks like this:
$ hledger balance
@ -1150,23 +1154,23 @@ COMMANDS
--------------------
0
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. At each level of the tree, accounts are
sorted by account code if any, then by account name. Or with
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. At each level of the tree, accounts are
sorted by account code if any, then by account name. Or with
-S/--sort-amount, by their balance amount.
"Boring" accounts, which contain a single interesting subaccount and no
balance of their own, are elided into the following line for more com-
pact output. (Eg above, the "liabilities" account.) Use --no-elide to
balance of their own, are elided into the following line for more com-
pact output. (Eg above, the "liabilities" account.) Use --no-elide to
prevent this.
Account balances are "inclusive" - they include the balances of any
Account balances are "inclusive" - they include the balances of any
subaccounts.
Accounts which have zero balance (and no non-zero subaccounts) are
Accounts which have zero balance (and no non-zero subaccounts) are
omitted. Use -E/--empty to show them.
A final total is displayed by default; use -N/--no-total to suppress
A final total is displayed by default; use -N/--no-total to suppress
it, eg:
$ hledger balance -p 2008/6 expenses --no-total
@ -1175,7 +1179,7 @@ COMMANDS
$1 supplies
Customising the classic balance report
You can customise the layout of classic balance reports with --for-
You can customise the layout of classic balance reports with --for-
mat FMT:
$ hledger balance --format "%20(account) %12(total)"
@ -1193,7 +1197,7 @@ COMMANDS
0
The FMT format string (plus a newline) specifies the formatting applied
to each account/balance pair. It may contain any suitable text, with
to each account/balance pair. It may contain any suitable text, with
data fields interpolated like so:
%[MIN][.MAX](FIELDNAME)
@ -1204,14 +1208,14 @@ COMMANDS
o FIELDNAME must be enclosed in parentheses, and can be one of:
o depth_spacer - a number of spaces equal to the account's depth, or
o depth_spacer - a number of spaces equal to the account's depth, or
if MIN is specified, MIN * depth spaces.
o account - the account's name
o total - the account's balance/posted total, right justified
Also, FMT can begin with an optional prefix to control how multi-com-
Also, FMT can begin with an optional prefix to control how multi-com-
modity amounts are rendered:
o %_ - render on multiple lines, bottom-aligned (the default)
@ -1220,7 +1224,7 @@ COMMANDS
o %, - render on one line, comma-separated
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
effect, instead %(account) has indentation built in.
Experimentation may be needed to get pleasing results.
@ -1228,14 +1232,14 @@ COMMANDS
o %(total) - the account's total
o %-20.20(account) - the account's name, left justified, padded to 20
o %-20.20(account) - the account's name, left justified, padded to 20
characters and clipped at 20 characters
o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
one line
o %20(total) %2(depth_spacer)%-(account) - the default format for the
o %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report
Colour support
@ -1246,9 +1250,9 @@ COMMANDS
o the output is not being redirected or piped anywhere
Flat mode
To see a flat list instead of the default hierarchical display, use
--flat. In this mode, accounts (unless depth-clipped) show their full
names and "exclusive" balance, excluding any subaccount balances. In
To see a flat list instead of the default hierarchical display, use
--flat. In this mode, accounts (unless depth-clipped) show their full
names and "exclusive" balance, excluding any subaccount balances. In
this mode, you can also use --drop N to omit the first few account name
components.
@ -1257,8 +1261,8 @@ COMMANDS
$1 supplies
Depth limited balance reports
With --depth N or depth:N or just -N, balance reports show accounts
only to the specified numeric depth. This is very useful to summarise
With --depth N or depth:N or just -N, balance reports show accounts
only to the specified numeric depth. This is very useful to summarise
a complex set of accounts and get an overview.
$ hledger balance -N -1
@ -1271,17 +1275,17 @@ COMMANDS
inclusive balances at the depth limit.
Multicolumn balance report
Multicolumn or tabular balance reports are a very useful hledger fea-
ture, and usually the preferred style. They share many of the above
features, but they show the report as a table, with columns represent-
ing time periods. This mode is activated by providing a reporting
Multicolumn or tabular balance reports are a very useful hledger fea-
ture, and usually the preferred style. They share many of the above
features, but they show the report as a table, with columns represent-
ing time periods. This mode is activated by providing a reporting
interval.
There are three types of multicolumn balance report, showing different
There are three types of multicolumn balance report, showing different
information:
1. By default: each column shows the sum of postings in that period, ie
the account's change of balance in that period. This is useful eg
the account's change of balance in that period. This is useful eg
for a monthly income statement:
$ hledger balance --quarterly income expenses -E
@ -1296,8 +1300,8 @@ COMMANDS
-------------------++---------------------------------
|| $-1 $1 0 0
2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
the report start date:
$ hledger balance --quarterly income expenses -E --cumulative
@ -1313,8 +1317,8 @@ COMMANDS
|| $-1 0 0 0
3. With --historical/-H: 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
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:
@ -1330,26 +1334,26 @@ COMMANDS
----------------------++-------------------------------------
|| 0 0 0
Multicolumn balance reports display accounts in flat mode by default;
Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass
With a reporting interval (like --quarterly 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 peri-
ods will be "full" and comparable to the others.
The -E/--empty 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
The -E/--empty 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 oth-
erwise would be omitted).
The -T/--row-total flag adds an additional column showing the total for
each row.
The -A/--average flag adds a column showing the average value in each
The -A/--average flag adds a column showing the average value in each
row.
Here's an example of all three:
@ -1373,20 +1377,20 @@ COMMANDS
Limitations:
In multicolumn reports the -V/--value flag uses the market price on the
report end date, for all columns (not the price on each column's end
report end date, for all columns (not the price on each column's end
date).
Eliding of boring parent accounts in tree mode, as in the classic bal-
Eliding of boring parent accounts in tree mode, as in the classic bal-
ance report, is not yet supported in multicolumn reports.
Budget report
With --budget, extra columns are displayed showing budget goals for
each account and period, if any. Budget goals are defined by periodic
transactions. This is very useful for comparing planned and actual
income, expenses, time usage, etc. -budget is most often combined with
a report interval.
With --budget, extra columns are displayed showing budget goals for
each account and period, if any. Budget goals are defined by periodic
transactions. This is very useful for comparing planned and actual
income, expenses, time usage, etc. --budget is most often combined
with a report interval.
For example, you can take average monthly expenses in the common
For example, you can take average monthly expenses in the common
expense categories to construct a minimal monthly budget:
;; Budget
@ -1418,43 +1422,151 @@ COMMANDS
$ hledger balance -M --budget
Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
======================++=================================================
<unbudgeted> || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
expenses:bus || $49 [98% of $50] $53 [106% of $50]
expenses:food || $396 [99% of $400] $412 [103% of $400]
expenses:movies || $30 [100% of $30] 0 [0% of $30]
income || $1950 [98% of $2000] $2100 [105% of $2000]
----------------------++-------------------------------------------------
|| 0 0
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
By default, only accounts with budget goals during the report period
are shown. --show-unbudgeted shows unbudgeted accounts as well.
Top-level accounts with no budget goals anywhere below them are grouped
under <unbudgeted>.
By default, only accounts with budget goals during the report period
are shown. In the example above, transactions in expenses:gifts and
expenses:supplies are counted towards expenses budget, but accounts
expenses:gifts and expenses:supplies are not shown, as they don't have
any budgets.
You can use --show-unbudgeted shows unbudgeted accounts as well:
$ hledger balance -M --budget --show-unbudgeted
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:gifts || 0 $100
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
expenses:supplies || $20 0
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
You can roll over unspent budgets to next period with --cumulative:
$ hledger balance -M --budget --cumulative
Budget performance in 2017/11/01-2017/12/31:
|| 2017/11/30 2017/12/31
======================++=================================================
<unbudgeted> || $20 $120
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
expenses:bus || $49 [98% of $50] $102 [102% of $100]
expenses:food || $396 [99% of $400] $808 [101% of $800]
expenses:movies || $30 [100% of $30] $30 [50% of $60]
income || $1950 [98% of $2000] $4050 [101% of $4000]
----------------------++-------------------------------------------------
|| 0 0
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
Note, the -S/--sort-amount flag is not yet fully supported with --bud-
get.
For more examples, see Budgeting and Forecasting.
Nested budgets
You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then bud-
get(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave.
In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well.
To illustrate this, consider the following budget:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicity
means that budget for both expenses:personal and expenses is $1100.
Transactions in expenses:personal:electronics will be counted both
towards its $100 budget and $1100 of expenses:personal , and transac-
tions in any other subaccount of expenses:personal would be counted
towards only towards the budget of expenses:personal.
For example, let's consider these transactions:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
2019/01/01 Google home hub
expenses:personal:electronics $90.00
liabilities $-90.00
2019/01/02 Phone screen protector
expenses:personal:electronics:upgrades $10.00
liabilities
2019/01/02 Weekly train ticket
expenses:personal:train tickets $153.00
liabilities
2019/01/03 Flowers
expenses:personal $30.00
liabilities
As you can see, we have transactions in expenses:personal:electron-
ics:upgrades and expenses:personal:train tickets, and since both of
these accounts are without explicitly defined budget, these transac-
tions would be counted towards budgets of expenses:personal:electronics
and expenses:personal accordingly:
$ hledger balance --budget -M
Budget performance in 2019/01:
|| Jan
===============================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
liabilities || $-283.00 [ 26% of $-1100.00]
-------------------------------++-------------------------------
|| 0 [ 0]
And with --show-unbudgeted, we can get a better picture of budget allo-
cation and consumption:
$ hledger balance --budget -M --show-unbudgeted
Budget performance in 2019/01:
|| Jan
========================================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
expenses:personal:electronics:upgrades || $10.00
expenses:personal:train tickets || $153.00
liabilities || $-283.00 [ 26% of $-1100.00]
----------------------------------------++-------------------------------
|| 0 [ 0]
Output format
The balance command supports output destination and output format
selection.
@ -1646,58 +1758,53 @@ COMMANDS
example: http://stefanorodighiero.net/software/hledger-dupes.html
close
close, equity
close, equity Prints a "closing balances" transaction and an "opening
balances" transaction that bring account balances to and from zero,
respectively. Useful for bringing asset/liability balances forward
into a new journal file, or for closing out revenues/expenses to
retained earnings at the end of a period.
Prints a "closing balances" transaction and an "opening balances"
transaction, that bring account balances to and from zero, respec-
tively. Useful for, eg:
o bringing asset/liability balances forward into a new journal file
o closing out revenues/expenses to retained earnings at the end of a
period
The closing transaction transfers balances to "equity:closing bal-
ances". The opening transaction transfers balances from "equity:open-
ing balances". You can chose to print just one of the transactions by
The closing transaction transfers balances to "equity:closing bal-
ances". The opening transaction transfers balances from "equity:open-
ing balances". You can chose to print just one of the transactions by
using the --opening or --closing flag.
If you split your journal files by time (eg yearly), you will typically
run this command at the end of the year, and save the closing transac-
tion as last entry of the old file, and the opening transaction as the
first entry of the new file. This makes the files self contained, so
that correct balances are reported no matter which of them are loaded.
Ie, if you load just one file, the balances are initialised correctly;
or if you load several files, the redundant closing/opening transac-
tions cancel each other out. (They will show up in print or register
reports; you can exclude them with a query like not:desc:'(open-
run this command at the end of the year, and save the closing transac-
tion as last entry of the old file, and the opening transaction as the
first entry of the new file. This makes the files self contained, so
that correct balances are reported no matter which of them are loaded.
Ie, if you load just one file, the balances are initialised correctly;
or if you load several files, the redundant closing/opening transac-
tions cancel each other out. (They will show up in print or register
reports; you can exclude them with a query like not:desc:'(open-
ing|closing) balances'.)
If you're running a business, you might also use this command to "close
the books" at the end of an accounting period, transferring income
statement account balances to retained earnings. (You may want to
the books" at the end of an accounting period, transferring income
statement account balances to retained earnings. (You may want to
change the equity account name to something like "equity:retained earn-
ings" for clarity.)
ings".)
By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is
dated today. To close on some other date, use: hledger close -e OPEN-
INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is
dated today. To close on some other date, use: hledger close -e OPEN-
INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
You can also use -p or date:PERIOD (any starting date is ignored).
Both transactions will include balance assertions for the
closed/reopened accounts. You probably shouldn't use status or real-
ness filters (like -C or -R or status:) with this command, or the gen-
closed/reopened accounts. You probably shouldn't use status or real-
ness filters (like -C or -R or status:) with this command, or the gen-
erated balance assertions will depend on these flags. Likewise, if you
run this command with -auto, the balance assertions will probably
always require -auto.
run this command with --auto, the balance assertions will probably
always require --auto.
Examples:
Carrying asset/liability balances into a new file for 2019, all from
command line.
Carrying asset/liability balances into a new file for 2019, all from
command line:
Warning: we use >> here to append; be careful not to type a single >
Warning: we use >> here to append; be careful not to type a single >
which would wipe your journal!
$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal
@ -1729,19 +1836,19 @@ COMMANDS
assets:checking
files
List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown.
List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown.
help
Show any of the hledger manuals.
The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide
The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide
a full or partial manual name to select one.
hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can
hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can
force a particular viewer with the --info, --man, --pager, --cat flags.
$ hledger help
@ -1765,7 +1872,7 @@ COMMANDS
...
import
Read new transactions added to each FILE since last run, and add them
Read new transactions added to each FILE since last run, and add them
to the main journal file.
--dry-run
@ -1775,28 +1882,28 @@ COMMANDS
each one. So eg to add new transactions from all CSV files to the main
journal, it's just: hledger import *.csv
New transactions are detected in the same way as print -new: by assum-
New transactions are detected in the same way as print --new: by assum-
ing transactions are always added to the input files in increasing date
order, and by saving .latest.FILE state files.
The -dry-run output is in journal format, so you can filter it, eg to
The --dry-run output is in journal format, so you can filter it, eg to
see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
incomestatement
This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements,
This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements,
unlike balance/print/register) (experimental). (is)
--change
show balance change in each period (default)
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@ -1830,8 +1937,8 @@ COMMANDS
--sort-amount
sort by amount instead of account code/name
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.)
$ hledger incomestatement
@ -1856,18 +1963,19 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical.
This command also supports output destination and output format selec-
This command also supports output destination and output format selec-
tion.
prices
Print market price directives from the journal. With -costs, also
print synthetic market prices based on transaction prices. With
-inverted-costs, also print inverse prices based on transaction prices.
Prices (and postings providing prices) can be filtered by a query.
Print market price directives from the journal. With --costs, also
print synthetic market prices based on transaction prices. With
--inverted-costs, also print inverse prices based on transaction
prices. Prices (and postings providing prices) can be filtered by a
query.
print
Show transactions from the journal. Aliases: p, txns.
@ -1997,7 +2105,7 @@ COMMANDS
-A --average
show running average of posting amounts instead of total
(implies -empty)
(implies --empty)
-r --related
show postings' siblings instead
@ -2087,7 +2195,7 @@ COMMANDS
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's argument, comma-separated:
description width as part of --width's argument, comma-separated:
--width W,D . Here's a diagram:
<--------------------------------- width (W) ---------------------------------->
@ -2285,7 +2393,7 @@ TROUBLESHOOTING
remember you can also seek help from the IRC channel, mail list or bug
tracker):
Successfully installed, but "No command `hledger' found"
Successfully installed, but "No command 'hledger' found"
stack and cabal install binaries into a special directory, which should
be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively.