;doc: regen manuals

[ci skip]
This commit is contained in:
Simon Michael 2019-09-02 11:11:56 -07:00
parent 68262c59ed
commit 16a3c96da0
11 changed files with 2230 additions and 1988 deletions

View File

@ -24,9 +24,9 @@ DESCRIPTION
When reading a CSV file named FILE.csv, hledger looks for a conversion
rules file named FILE.csv.rules in the same directory. You can over-
ride this with the --rules-file option. If the rules file does not
exist, hledger will auto-create one with some example rules, which
you'll need to adjust.
ride this with the --rules-file option. If the rules file does not ex-
ist, hledger will auto-create one with some example rules, which you'll
need to adjust.
At minimum, the rules file must identify the date and amount fields.
It's often necessary to specify the date format, and the number of
@ -178,33 +178,33 @@ CSV RULES
newest-first
newest-first
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
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.
CSV TIPS
CSV ordering
The generated journal entries will be sorted by date. The order of
same-day entries will be preserved (except in the special case where
The generated journal entries will be sorted by date. The order of
same-day entries will be preserved (except in the special case where
you might need newest-first, see above).
CSV accounts
Each journal entry will have two postings, to account1 and account2
respectively. It's not yet possible to generate entries with more than
two postings. It's conventional and recommended to use account1 for
Each journal entry will have two postings, to account1 and account2 re-
spectively. It's not yet possible to generate entries with more than
two postings. It's conventional and recommended to use account1 for
the account whose CSV we are reading.
CSV amounts
A transaction amount must be set, in one of these ways:
o with an amount field assignment, which sets the first posting's
o with an amount field assignment, which sets the first posting's
amount
o (When the CSV has debit and credit amounts in separate fields:)
with field assignments for the amount-in and amount-out pseudo fields
with field assignments for the amount-in and amount-out pseudo fields
(both of them). Whichever one has a value will be used, with appropri-
ate sign. If both contain a value, it might not work so well.
@ -212,30 +212,30 @@ CSV TIPS
There is some special handling for sign in amounts:
o If an amount value is parenthesised, it will be de-parenthesised and
o If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped.
o If an amount value begins with a double minus sign, those will cancel
out and be removed.
If the currency/commodity symbol is provided as a separate CSV field,
If the currency/commodity symbol is provided as a separate CSV field,
assign it to the currency pseudo field; the symbol will be prepended to
the amount (TODO: when there is an amount). Or, you can use an amount
the amount (TODO: when there is an amount). Or, you can use an amount
field assignment for more control, eg:
fields date,description,currency,amount
amount %amount %currency
CSV balance assertions/assignments
If the CSV includes a running balance, you can assign that to one of
the pseudo fields balance (or balance1) or balance2. This will gener-
ate a balance assertion (or if the amount is left empty, a balance
assignment), on the first or second posting, whenever the running bal-
ance field is non-empty. (TODO: #1000)
If the CSV includes a running balance, you can assign that to one of
the pseudo fields balance (or balance1) or balance2. This will gener-
ate a balance assertion (or if the amount is left empty, a balance as-
signment), on the first or second posting, whenever the running balance
field is non-empty. (TODO: #1000)
Reading multiple CSV files
You can read multiple CSV files at once using multiple -f arguments on
the command line, and hledger will look for a correspondingly-named
You can read multiple CSV files at once using multiple -f arguments on
the command line, and hledger will look for a correspondingly-named
rules file for each. Note if you use the --rules-file option, this one
rules file will be used for all the CSV files being read.
@ -254,7 +254,7 @@ CSV TIPS
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -268,7 +268,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

View File

@ -1175,8 +1175,8 @@ commodity-less amounts, or until the next \f[C]D\f[R] directive.
.IP
.nf
\f[C]
# commodity-less amounts should be treated as dollars
# (and displayed with symbol on the left, thousands separators and two decimal places)
; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places)
D $1,000.00
1/1
@ -1450,7 +1450,7 @@ Eg:
.nf
\f[C]
alias checking = assets:bank:wells fargo:checking
# rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq]
; rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq]
\f[R]
.fi
.SS Regex aliases
@ -1476,7 +1476,7 @@ Eg:
.nf
\f[C]
alias /\[ha](.+):bank:([\[ha]:]+)(.*)/ = \[rs]1:\[rs]2 \[rs]3
# rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq]
; rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq]
\f[R]
.fi
.PP

View File

@ -1042,8 +1042,8 @@ this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
amounts, or until the next 'D' directive.
# commodity-less amounts should be treated as dollars
# (and displayed with symbol on the left, thousands separators and two decimal places)
; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places)
D $1,000.00
1/1
@ -1289,7 +1289,7 @@ replace any occurrence of the old account name with the new one.
Subaccounts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"

File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts
@ -1310,7 +1310,7 @@ REPLACEMENT. If REGEX contains parenthesised match groups, these can be
referenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on
command line, to end of option argument), so it can contain trailing

View File

@ -7,24 +7,24 @@ NAME
Journal - hledger's default file format, representing a General Journal
DESCRIPTION
hledger'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 .journal, but
hledger's usual data source is a plain text file containing journal en-
tries in hledger journal format. This file represents a standard ac-
counting general journal. I use file names ending in .journal, but
that'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.
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
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 get-
ting.
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.
the add or web commands to create and update it. Many users, though,
also edit the journal file directly with a text editor, perhaps as-
sisted by the helper modes for emacs or vim.
Here's an example:
@ -57,73 +57,73 @@ DESCRIPTION
FILE FORMAT
Transactions
Transactions are movements of some quantity of commodities between
named accounts. Each transaction is represented by a journal entry
beginning with a simple date in column 0. This can be followed by any
of the following, separated by spaces:
Transactions are movements of some quantity of commodities between
named accounts. Each transaction is represented by a journal entry be-
ginning with a simple date in column 0. This can be followed by any of
the following, separated by spaces:
o (optional) a status character (empty, !, or *)
o (optional) a transaction code (any short number or text, enclosed in
o (optional) a transaction code (any short number or text, enclosed in
parentheses)
o (optional) a transaction description (any remaining text until end of
line or a semicolon)
o (optional) a transaction comment (any remaining text following a
o (optional) a transaction comment (any remaining text following a
semicolon until end of line)
Then comes zero or more (but usually at least 2) indented lines repre-
Then comes zero or more (but usually at least 2) indented lines repre-
senting...
Postings
A posting is an addition of some amount to, or removal of some amount
from, an account. Each posting line begins with at least one space or
A posting is an addition of some amount to, or removal of some amount
from, an account. Each posting line begins with at least one space or
tab (2 or 4 spaces is common), followed by:
o (optional) a status character (empty, !, or *), followed by a space
o (required) an account name (any text, optionally containing single
o (required) an account name (any text, optionally containing single
spaces, until end of line or a double space)
o (optional) two or more spaces or tabs followed by an amount.
Positive amounts are being added to the account, negative amounts are
Positive amounts are being added to the account, negative amounts are
being removed.
The amounts within a transaction must always sum up to zero. As a con-
venience, one amount may be left blank; it will be inferred so as to
venience, one amount may be left blank; it will be inferred so as to
balance the transaction.
Be sure to note the unusual two-space delimiter between account name
and amount. This makes it easy to write account names containing spa-
ces. But if you accidentally leave only one space (or tab) before the
Be sure to note the unusual two-space delimiter between account name
and amount. This makes it easy to write account names containing spa-
ces. But if you accidentally leave only one space (or tab) before the
amount, the amount will be considered part of the account name.
Dates
Simple dates
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
Leading zeros are optional. The year may be omitted, in which case it
will be inferred from the context - the current transaction, the
default year set with a default year directive, or the current date
when the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31,
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
Leading zeros are optional. The year may be omitted, in which case it
will be inferred from the context - the current transaction, the de-
fault year set with a default year directive, or the current date when
the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31,
2010.1.31.
Secondary dates
Real-life transactions sometimes involve more than one date - eg the
Real-life transactions sometimes involve more than one date - eg the
date you write a cheque, and the date it clears in your bank. When you
want to model this, eg for more accurate balances, you can specify
individual posting dates, which I recommend. Or, you can use the sec-
ondary dates (aka auxiliary/effective dates) feature, supported for
want to model this, eg for more accurate balances, you can specify in-
dividual posting dates, which I recommend. Or, you can use the sec-
ondary dates (aka auxiliary/effective dates) feature, supported for
compatibility with Ledger.
A secondary date can be written after the primary date, separated by an
equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the --date2 flag is speci-
equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the --date2 flag is speci-
fied (--aux-date or --effective also work).
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
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.
Here's an example. Note that a secondary date will use the year of the
@ -139,18 +139,18 @@ FILE FORMAT
$ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10
Secondary dates require some effort; you must use them consistently in
Secondary dates require some effort; you must use them consistently in
your journal entries and remember whether to use or not use the --date2
flag for your reports. They are included in hledger for Ledger compat-
ibility, but posting dates are a more powerful and less confusing
alternative.
ibility, but posting dates are a more powerful and less confusing al-
ternative.
Posting dates
You can give individual postings a different date from their parent
transaction, by adding a posting comment containing a tag (see below)
You can give individual postings a different date from their parent
transaction, by adding a posting comment containing a tag (see below)
like date:DATE. This is probably the best way to control posting dates
precisely. Eg in this example the expense should appear in May
reports, and the deduction from checking should be reported on 6/1 for
precisely. Eg in this example the expense should appear in May re-
ports, and the deduction from checking should be reported on 6/1 for
easy bank reconciliation:
2015/5/30
@ -163,24 +163,23 @@ FILE FORMAT
$ hledger -f t.j register checking
2015/06/01 assets:checking $-10 $-10
DATE should be a simple date; if the year is not specified it will use
the year of the transaction's date. You can set the secondary date
similarly, with date2:DATE2. The date: or date2: tags must have a
valid simple date value if they are present, eg a date: tag with no
DATE should be a simple date; if the year is not specified it will use
the year of the transaction's date. You can set the secondary date
similarly, with date2:DATE2. The date: or date2: tags must have a
valid simple date value if they are present, eg a date: tag with no
value is not allowed.
Ledger's earlier, more compact bracketed date syntax is also supported:
[DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any
[DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any
square-bracketed sequence of the 0123456789/-.= characters in this way.
With this syntax, DATE infers its year from the transaction and DATE2
With this syntax, DATE infers its year from the transaction and DATE2
infers its year from DATE.
Status
Transactions, or individual postings within a transaction, can have a
status mark, which is a single character before the transaction
description or posting account name, separated from it by a space,
indicating one of three statuses:
Transactions, or individual postings within a transaction, can have a
status mark, which is a single character before the transaction de-
scription or posting account name, separated from it by a space, indi-
cating one of three statuses:
mark status
------------------
@ -188,26 +187,25 @@ FILE FORMAT
! pending
* cleared
When reporting, you can filter by status with the -U/--unmarked,
-P/--pending, and -C/--cleared flags; or the status:, status:!, and
When reporting, you can filter by status with the -U/--unmarked,
-P/--pending, and -C/--cleared flags; or the status:, status:!, and
status:* queries; or the U, P, C keys in hledger-ui.
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.
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 un-
marked for clarity.
To replicate Ledger and old hledger's behaviour of also matching pend-
To replicate Ledger and old hledger's behaviour of also matching pend-
ing, combine -U and -P.
Status marks are optional, but can be helpful eg for reconciling with
Status marks are optional, but can be helpful eg for reconciling with
real-world accounts. Some editor modes provide highlighting and short-
cuts for working with status. Eg in Emacs ledger-mode, you can toggle
cuts for working with status. Eg in Emacs ledger-mode, you can toggle
transaction status with C-c C-e, or posting status with C-c C-c.
What "uncleared", "pending", and "cleared" actually mean is up to you.
What "uncleared", "pending", and "cleared" actually mean is up to you.
Here's one suggestion:
status meaning
--------------------------------------------------------------------------
uncleared recorded but not yet reconciled; needs review
@ -216,33 +214,33 @@ FILE FORMAT
cleared complete, reconciled as far as possible, and considered cor-
rect
With this scheme, you would use -PC to see the current balance at your
bank, -U to see things which will probably hit your bank soon (like
uncashed checks), and no flags to see the most up-to-date state of your
With this scheme, you would use -PC to see the current balance at your
bank, -U to see things which will probably hit your bank soon (like un-
cashed checks), and no flags to see the most up-to-date state of your
finances.
Description
A transaction's description is the rest of the line following the date
and status mark (or until a comment begins). Sometimes called the
A transaction'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
wish, or left blank. Transaction descriptions can be queried, unlike
comments.
Payee and note
You can optionally include a | (pipe) character in descriptions to sub-
divide the description into separate fields for payee/payer name on the
left (up to the first |) and an additional note field on the right
(after the first |). This may be worthwhile if you need to do more
precise querying and pivoting by payee or by note.
left (up to the first |) and an additional note field on the right (af-
ter the first |). This may be worthwhile if you need to do more pre-
cise querying and pivoting by payee or by note.
Account names
Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can
be anything you like, but in finance there are traditionally five top-
Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can
be anything you like, but in finance there are traditionally five top-
level accounts: assets, liabilities, income, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more
spaces (or newline).
Account names can be aliased.
@ -251,7 +249,7 @@ FILE FORMAT
After the account name, there is usually an amount. Important: between
account name and amount, there must be two or more spaces.
Amounts consist of a number and (usually) a currency symbol or commod-
Amounts consist of a number and (usually) a currency symbol or commod-
ity name. Some examples:
2.00001
@ -267,35 +265,35 @@ FILE FORMAT
As you can see, the amount format is somewhat flexible:
o amounts are a number (the "quantity") and optionally a currency sym-
o amounts are a number (the "quantity") and optionally a currency sym-
bol/commodity name (the "commodity").
o the commodity is a symbol, word, or phrase, on the left or right,
with or without a separating space. If the commodity contains num-
bers, spaces or non-word punctuation it must be enclosed in double
o the commodity is a symbol, word, or phrase, on the left or right,
with or without a separating space. If the commodity contains num-
bers, spaces or non-word punctuation it must be enclosed in double
quotes.
o negative amounts with a commodity on the left can have the minus sign
before or after it
o digit groups (thousands, or any other grouping) can be separated by
space or comma or period and should be used as separator between all
o digit groups (thousands, or any other grouping) can be separated by
space or comma or period and should be used as separator between all
groups
o decimal part can be separated by comma or period and should be dif-
o decimal part can be separated by comma or period and should be dif-
ferent from digit groups separator
o scientific E-notation is allowed. Be careful not to use a digit
group separator character in scientific notation, as it's not sup-
o scientific E-notation is allowed. Be careful not to use a digit
group separator character in scientific notation, as it's not sup-
ported and it might get mistaken for a decimal point. (Declaring the
digit group separator character explicitly with a commodity directive
will prevent this.)
You can use any of these variations when recording data. However,
there is some ambiguous way of representing numbers like $1.000 and
$1,000 both may mean either one thousand or one dollar. By default
hledger will assume that this is sole delimiter is used only for deci-
mals. On the other hand commodity format declared prior to that line
You can use any of these variations when recording data. However,
there is some ambiguous way of representing numbers like $1.000 and
$1,000 both may mean either one thousand or one dollar. By default
hledger will assume that this is sole delimiter is used only for deci-
mals. On the other hand commodity format declared prior to that line
will help to resolve that ambiguity differently:
commodity $1,000.00
@ -304,9 +302,9 @@ FILE FORMAT
expenses:gifts $1,000
assets
Though journal may contain mixed styles to represent amount, when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
Though journal may contain mixed styles to represent amount, when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
o if there is a commodity directive specifying the format, that is used
@ -582,11 +580,11 @@ FILE FORMAT
nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
Transaction and posting comments must begin with a semicolon (;).
You can attach comments to a transaction by writing them after the de-
scription and/or indented on the following lines (before the postings).
Similarly, you can attach comments to an individual posting by writing
them after the amount and/or indented on the following lines. Transac-
tion and posting comments must begin with a semicolon (;).
Some examples:
@ -662,47 +660,48 @@ FILE FORMAT
here is a table summarising the directives and their effects, with
links to more detailed docs.
direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06)
direc- end di- subdi- purpose can affect (as of
tive rective rec- 2018/06)
tives
------------------------------------------------------------------------------------
account any document account names, all entries in all
text declare account types & dis- files, before or
account any document account names, de- all entries in all
text clare account types & dis- files, before or
play order after
alias end rewrite account names following
aliases inline/included
entries until end
of current file or
end directive
apply end apply prepend a common parent to following
account account account names inline/included
entries until end
of current file or
end directive
comment end com- ignore part of journal following
ment inline/included
entries until end
of current file or
end directive
commod- format declare a commodity and its number notation:
alias end rewrite account names following in-
aliases line/included en-
tries until end of
current file or end
directive
apply end apply prepend a common parent to following in-
account account account names line/included en-
tries until end of
current file or end
directive
comment end com- ignore part of journal following in-
ment line/included en-
tries until end of
current file or end
directive
commod- format declare a commodity and its number notation:
ity number notation & display following entries
style in that commodity
in all files; dis-
in all files; dis-
play style: amounts
of that commodity
in reports
D declare a commodity, number commodity: all com-
D declare a commodity, number commodity: all com-
notation & display style for modityless entries
commodityless amounts in all files; num-
ber notation: fol-
commodityless amounts in all files; num-
ber notation: fol-
lowing commodity-
less entries and
less entries and
entries in that
commodity in all
commodity in all
files; display
style: amounts of
that commodity in
@ -710,22 +709,21 @@ FILE FORMAT
include include entries/directives what the included
from another file directives affect
P declare a market price for a amounts of that
commodity commodity in
reports, when -V is
commodity commodity in re-
ports, when -V is
used
Y declare a year for yearless following
dates inline/included
entries until end
of current file
Y declare a year for yearless following in-
dates line/included en-
tries until end of
current file
And some definitions:
subdirec- optional indented directive line immediately following a par-
tive ent directive
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
@ -733,8 +731,8 @@ FILE FORMAT
scope are affected by a directive
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
affect, and whether they are focussed on input (parsing) or output (re-
ports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
@ -758,8 +756,8 @@ FILE FORMAT
file. The include file path may contain common glob patterns (e.g.
*).
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
The include directive can only be used in journal files. It can in-
clude journal, timeclock or timedot files, but not CSV files.
Default year
You can set a default year to be used for subsequent dates which don't
@ -815,8 +813,8 @@ FILE FORMAT
Normally the display format is inferred from journal entries, but this
can be unpredictable; declaring it with a commodity directive overrides
this and removes ambiguity. Towards this end, amounts in commodity
directives must always be written with a decimal point (a period or
this and removes ambiguity. Towards this end, amounts in commodity di-
rectives must always be written with a decimal point (a period or
comma, followed by 0 or more decimal digits).
Commodity directives do not affect how amounts are parsed; the parser
@ -829,8 +827,8 @@ FILE FORMAT
and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
# (and displayed with symbol on the left, thousands separators and two decimal places)
; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places)
D $1,000.00
1/1
@ -841,8 +839,8 @@ FILE FORMAT
a decimal point.
Market prices
The P directive declares a market price, which is an exchange rate
between two commodities on a certain date. (In Ledger, they are called
The P directive declares a market price, which is an exchange rate be-
tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market.
@ -867,8 +865,8 @@ FILE FORMAT
commodity using these prices.
Declaring accounts
account directives can be used to pre-declare accounts. Though not
required, they can provide several benefits:
account directives can be used to pre-declare accounts. Though not re-
quired, they can provide several benefits:
o They can document your intended chart of accounts, providing a refer-
ence.
@ -927,8 +925,8 @@ FILE FORMAT
detected automatically.
Account types declared with tags
More generally, you can declare an account's type with an account
directive, by writing a type: tag in a comment, followed by one of the
More generally, you can declare an account's type with an account di-
rective, by writing a type: tag in a comment, followed by one of the
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive):
@ -984,16 +982,16 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
sibling accounts stay together (you couldn't display x:y in between a:b
and a:c).
@ -1012,14 +1010,14 @@ FILE FORMAT
o customising reports
Account aliases also rewrite account names in account directives. They
do not affect account names being entered via hledger add or hledger-
do not affect account names being entered via hledger add or hledger-
web.
See also Cookbook: Rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@ -1027,12 +1025,12 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are case sensitive full account names. hledger will
replace any occurrence of the old account name with the new one. Sub-
accounts are also affected. Eg:
OLD and NEW are case sensitive full account names. hledger will re-
place any occurrence of the old account name with the new one. Subac-
counts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases
There is also a more powerful variant that uses a regular expression,
@ -1048,7 +1046,7 @@ FILE FORMAT
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
@ -1080,23 +1078,23 @@ FILE FORMAT
o aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde-
This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde-
pendent of which files are being read and in which order.
In case of trouble, adding --debug=6 to the command line will show
In case of trouble, adding --debug=6 to the command line will show
which aliases are being applied when.
end aliases
You can clear (forget) all currently defined aliases with the end
You can clear (forget) all currently defined aliases with the end
aliases directive:
end aliases
Default parent account
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
end apply account directives like so:
You can specify a parent account which will be prepended to all ac-
counts within a section of the journal. Use the apply account and end
apply account directives like so:
apply account home
@ -1112,7 +1110,7 @@ FILE FORMAT
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@ -1121,19 +1119,19 @@ FILE FORMAT
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
account.
Periodic transactions
Periodic transaction rules describe transactions that recur. They
allow you to generate future transactions for forecasting, without hav-
ing to write them out explicitly in the journal (with --forecast).
Secondly, they also can be used to define budget goals (with --budget).
Periodic transaction rules describe transactions that recur. They al-
low you to generate future transactions for forecasting, without having
to write them out explicitly in the journal (with --forecast). Sec-
ondly, they also can be used to define budget goals (with --budget).
A periodic transaction rule looks like a normal journal entry, with the
date replaced by a tilde (~) followed by a period expression (mnemonic:
@ -1166,8 +1164,8 @@ FILE FORMAT
income:acme inc
Forecasting with periodic transactions
With the --forecast flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not
With the --forecast flag, each periodic transaction rule generates fu-
ture transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag:
@ -1225,7 +1223,6 @@ FILE FORMAT
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
Auto postings / transaction modifiers
Transaction modifier rules, AKA auto posting rules, describe changes to
be applied automatically to certain matched transactions. Currently
@ -1304,12 +1301,12 @@ FILE FORMAT
tions
Currently, transaction modifiers are applied / auto postings are added:
o after missing amounts are inferred, and transactions are checked for
o after missing amounts are inferred, and transactions are checked for
balancedness,
o but before balance assertions are checked.
Note this means that journal entries must be balanced both before and
Note this means that journal entries must be balanced both before and
after auto postings are added. This changed in hledger 1.12+; see #893
for background.
@ -1319,11 +1316,11 @@ FILE FORMAT
o generated-posting:= QUERY - shows this was generated by an auto post-
ing rule, and the query
o _generated-posting:= QUERY - a hidden tag, which does not appear in
o _generated-posting:= QUERY - a hidden tag, which does not appear in
hledger's output. This can be used to match postings generated "just
now", rather than generated in the past and saved to the journal.
Also, any transaction that has been changed by transaction modifier
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
o modified: - this transaction was modified
@ -1332,18 +1329,18 @@ FILE FORMAT
tion was modified "just now".
EDITOR SUPPORT
Helper modes exist for popular text editors, which make working with
Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the [[Cookbook]] at hledger.org for the latest informa-
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the [[Cookbook]] at hledger.org for the latest informa-
tion.
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -1357,7 +1354,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

View File

@ -7,11 +7,11 @@ NAME
Timeclock - the time logging format of timeclock.el, as read by hledger
DESCRIPTION
hledger can read timeclock files. As with Ledger, these are (a subset
hledger can read timeclock files. As with Ledger, these are (a subset
of) timeclock.el'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]. Seconds and timezone are optional. The timezone,
if present, must be four digits and is ignored (currently the time is
in the example below. The date is a simple date. The time format is
HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone,
if present, must be four digits and is ignored (currently the time is
always interpreted as a local time).
i 2015/03/30 09:00:00 some:account name optional description after two spaces
@ -19,9 +19,9 @@ DESCRIPTION
i 2015/03/31 22:21:45 another account
o 2015/04/01 02:00:34
hledger treats each clock-in/clock-out pair as a transaction posting
some number of hours to an account. Or if the session spans more than
one day, it is split into several transactions, one for each day. For
hledger treats each clock-in/clock-out pair as a transaction posting
some number of hours to an account. Or if the session spans more than
one day, it is split into several transactions, one for each day. For
the above time log, hledger print generates these journal entries:
$ hledger -f t.timeclock print
@ -42,21 +42,21 @@ DESCRIPTION
To generate time logs, ie to clock in and clock out, you could:
o use emacs and the built-in timeclock.el, or the extended timeclock-
o use emacs and the built-in timeclock.el, or the extended timeclock-
x.el and perhaps the extras in ledgerutils.el
o at the command line, use these bash aliases: shell alias ti="echo i
`date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date
`date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date
'+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
o or use the old ti and to scripts in the ledger 2.x repository. These
rely on a "timeclock" executable which I think is just the ledger 2
rely on a "timeclock" executable which I think is just the ledger 2
executable renamed.
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -70,7 +70,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

View File

@ -28,8 +28,8 @@ FILE FORMAT
Quantities can be written as:
o a sequence of dots (.) representing quarter hours. Spaces may
optionally be used for grouping and readability. Eg: .... ..
o a sequence of dots (.) representing quarter hours. Spaces may op-
tionally be used for grouping and readability. Eg: .... ..
o an integral or decimal number, representing hours. Eg: 1.5

View File

@ -117,8 +117,8 @@ OPTIONS
using period expressions syntax
--date2
match the secondary date instead (see command help for other
effects)
match the secondary date instead (see command help for other ef-
fects)
-U --unmarked
include only unmarked postings/txns (can combine with -P or -C)
@ -204,8 +204,8 @@ KEYS
BACKSPACE or DELETE removes all filters, showing all transactions.
As mentioned above, hledger-ui shows auto-generated periodic transac-
tions, and hides future transactions (auto-generated or not) by
default. F toggles showing and hiding these future transactions. This
tions, and hides future transactions (auto-generated or not) by de-
fault. F toggles showing and hiding these future transactions. This
is similar to using a query like date:-tomorrow, but more convenient.
(experimental)
@ -227,8 +227,8 @@ KEYS
file. This allows some basic data entry.
A is like a, but runs the hledger-iadd tool, which provides a curses-
style interface. This key will be available if hledger-iadd is
installed in $PATH.
style interface. This key will be available if hledger-iadd is in-
stalled in $PATH.
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
-nw) on the journal file. With some editors (emacs, vi), the cursor
@ -250,36 +250,35 @@ SCREENS
Account names are shown as a flat list by default. Press T to toggle
tree mode. In flat mode, account balances are exclusive of subac-
counts, except where subaccounts are hidden by a depth limit (see
below). In tree mode, all account balances are inclusive of subac-
counts.
counts, except where subaccounts are hidden by a depth limit (see be-
low). In tree mode, all account balances are inclusive of subaccounts.
To see less detail, press a number key, 1 to 9, to set a depth limit.
To see less detail, press a number key, 1 to 9, to set a depth limit.
Or use - to decrease and +/= to increase the depth limit. 0 shows even
less detail, collapsing all accounts to a single total. To remove the
depth limit, set it higher than the maximum account depth, or press
ESCAPE.
less detail, collapsing all accounts to a single total. To remove the
depth limit, set it higher than the maximum account depth, or press ES-
CAPE.
H toggles between showing historical balances or period balances. His-
torical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date
(filtered by the filter query if any), including transactions before
the start of the report period. In other words, historical balances
are what you would see on a bank statement for that account (unless
disturbed by a filter query). Period balances ignore transactions
before the report start date, so they show the change in balance during
torical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date
(filtered by the filter query if any), including transactions before
the start of the report period. In other words, historical balances
are what you would see on a bank statement for that account (unless
disturbed by a filter query). Period balances ignore transactions be-
fore the report start date, so they show the change in balance during
the report period. They are more useful eg when viewing a time log.
U toggles filtering by unmarked status, including or excluding unmarked
postings in the balances. Similarly, P toggles pending postings, and C
toggles cleared postings. (By default, balances include all postings;
if you activate one or two status filters, only those postings are
included; and if you activate all three, the filter is removed.)
toggles cleared postings. (By default, balances include all postings;
if you activate one or two status filters, only those postings are in-
cluded; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored.
Z toggles nonzero mode, in which only accounts with nonzero balances
are shown (hledger-ui shows zero items by default, unlike command-line
Z toggles nonzero mode, in which only accounts with nonzero balances
are shown (hledger-ui shows zero items by default, unlike command-line
hledger).
Press right or enter to view an account's transactions register.
@ -288,32 +287,32 @@ SCREENS
This screen shows the transactions affecting a particular account, like
a check register. Each line represents one transaction and shows:
o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected
o 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.)
o the overall change to the current account's balance; positive for an
o the overall change to the current account's balance; positive for an
inflow to this account, negative for an outflow.
o the running historical total or period total for the current account,
after the transaction. This can be toggled with H. Similar to the
accounts screen, the historical total is affected by transactions
(filtered by the filter query) before the report start date, while
after the transaction. This can be toggled with H. Similar to the
accounts screen, the historical total is affected by transactions
(filtered by the filter query) before the report start date, while
the period total is not. If the historical total is not disturbed by
a filter query, it will be the running historical balance you would
a filter query, it will be the running historical balance you would
see on a bank register for the current account.
Transactions affecting this account's subaccounts will be included in
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. In other words, the register always shows the transac-
mode but this account has subaccounts which are not shown due to a
depth limit. In other words, the register always shows the transac-
tions contributing to the balance shown on the accounts screen.
Tree mode/flat mode can be toggled with T here also.
U toggles filtering by unmarked status, showing or hiding unmarked
U toggles filtering by unmarked status, showing or hiding unmarked
transactions. Similarly, P toggles pending transactions, and C toggles
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
tions are shown; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored.
@ -329,16 +328,16 @@ SCREENS
similar to hledger's print command and journal format (hledger_jour-
nal(5)).
The transaction'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).
The transaction's date(s) and any cleared flag, transaction code, de-
scription, 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).
up and down will step through all transactions listed in the previous
account register screen. 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 trans-
actions appear in multiple account registers). The #N number preceding
show your position within that account register. They will vary de-
pending on which account register you came from (remember most transac-
tions appear in multiple account registers). The #N number preceding
them is the transaction's position within the complete unfiltered jour-
nal, which is a more stable id (at least until the next reload).

View File

@ -19,9 +19,9 @@ DESCRIPTION
hledger-web is hledger's web interface. It starts a simple web appli-
cation 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 interface, showing more at once
(accounts, the current account register, balance charts) and allowing
history-aware data entry, interactive searching, and bookmarking.
than the hledger CLI or hledger-ui interface, showing more at once (ac-
counts, the current account register, balance charts) and allowing his-
tory-aware data entry, interactive searching, and bookmarking.
hledger-web also lets you share a ledger with multiple users, or even
the public web. There is no access control, so if you need that you
@ -127,8 +127,8 @@ OPTIONS
using period expressions syntax
--date2
match the secondary date instead (see command help for other
effects)
match the secondary date instead (see command help for other ef-
fects)
-U --unmarked
include only unmarked postings/txns (can combine with -P or -C)
@ -208,14 +208,14 @@ OPTIONS
for better caching or cookie-less serving on high performance websites.
PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the
By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local
machine.
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local ma-
chine.
o putting it behind an authenticating proxy, using eg apache or nginx
@ -224,54 +224,54 @@ PERMISSIONS
You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is
one or more of the following capabilities. The default value is
view,add:
o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or
included files
o manage - allows editing, uploading or downloading the main or in-
cluded files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it
includes.
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it in-
cludes.
Note, unlike any other hledger command, in this mode you (or any visi-
Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.)
RELOADING
hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message
until the file has been fixed.
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message un-
til the file has been fixed.
(Note: if you are viewing files mounted from another machine, make sure
that both machine clocks are roughly in step.)
JSON API
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. Currently these are same ones
provided by the hledger-api tool, but hledger-web will likely receive
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. Currently these are same ones
provided by the hledger-api tool, but hledger-web will likely receive
more attention than hledger-api in future:
/accountnames
@ -281,17 +281,17 @@ JSON API
/accounts
/accounttransactions/#AccountName
Also, you can append a new transaction to the journal by sending a PUT
request to /add (hledger-web only). As with the web UI's add form,
hledger-web must be started with the add capability for this (enabled
Also, you can append a new transaction to the journal by sending a PUT
request to /add (hledger-web only). As with the web UI's add form,
hledger-web must be started with the add capability for this (enabled
by default).
The payload should be a valid hledger transaction as JSON, similar to
The payload should be a valid hledger transaction as JSON, similar to
what you get from /transactions or /accounttransactions.
Another way to generate test data is with the readJsonFile/writeJson-
File helpers in Hledger.Web.Json, which read or write any of hledger's
JSON-capable types from or to a file. Eg here we write the first
Another way to generate test data is with the readJsonFile/writeJson-
File helpers in Hledger.Web.Json, which read or write any of hledger's
JSON-capable types from or to a file. Eg here we write the first
transaction of a sample journal:
$ make ghci-web
@ -306,23 +306,23 @@ JSON API
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
By default, both the server-side HTML UI and the JSON API are served.
Running with --serve-api disables the former, useful if you only want
By default, both the server-side HTML UI and the JSON API are served.
Running with --serve-api disables the former, useful if you only want
to serve the API.
ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede options with -- when invoked from hledger is awk-
The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-web can't read from stdin).
@ -336,7 +336,7 @@ BUGS
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -350,7 +350,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

View File

@ -1013,36 +1013,32 @@ This flag is equivalent to \f[C]--value=cost\f[R], described below.
.SS -V: Market value
.PP
The \f[C]-V/--market\f[R] flag converts reported amounts to their market
value in a default valuation commodity, using the historical market
prices in effect on a default valuation date.
value in a default valuation commodity, using the market prices in
effect on a default valuation date.
For single period reports, the valuation date is today; for multiperiod
reports, it is the last day of each subperiod.
It is equivalent to \f[C]--value=now\f[R] or \f[C]--value=end\f[R] (see
below).
.PP
For single period reports, the valuation date is today.
For multiperiod reports, it is the last day of each subperiod.
.PP
The valuation commodity will be the one referenced in the latest
The default valuation commodity is the one referenced in the latest
applicable market price dated on or before the valuation date.
If most of your P declarations lead to a single home currency, this will
usually be what you want.
.PP
Unlike the similar flag in Ledger, it does not infer market prices from
transaction prices.
In hledger, -B uses transaction prices, -V and -X use market prices.
.PP
It is equivalent to \f[C]--value=now\f[R] or \f[C]--value=end\f[R].
(To specify the commodity, see -X below.)
.PP
Here\[aq]s a quick example:
.IP
.nf
\f[C]
# one euro is worth this many dollars from nov 1
; one euro is worth this many dollars from nov 1
P 2016/11/01 \[Eu] $1.10
# purchase some euros on nov 3
; purchase some euros on nov 3
2016/11/3
assets:euros \[Eu]100
assets:checking
# the euro is worth fewer dollars by dec 21
; the euro is worth fewer dollars by dec 21
P 2016/12/21 \[Eu] $1.03
\f[R]
.fi
@ -1074,15 +1070,19 @@ $ hledger -f t.j bal -N euros -V
$103.00 assets:euros
\f[R]
.fi
.PP
Note that in hledger, market prices are always declared explicitly with
P directives; we do not infer them from transaction prices as Ledger
does.
.SS -X: Market value in specified commodity
.PP
The \f[C]-X/--exchange\f[R] option is like \f[C]-V/--market\f[R] except
it takes a commodity symbol argument, so that you can select a different
target commodity.
It is similar to the same option in Ledger, with the same caveat
mentioned for \f[C]-V\f[R]/\f[C]--value\f[R] above.
mentioned above.
It is equivalent to \f[C]--value=now,COMM\f[R] or
\f[C]--value=end,COMM\f[R]; for more details, read on.
\f[C]--value=end,COMM\f[R].
.SS --value
.PP
\f[I](experimental, added 201905)\f[R]
@ -2628,6 +2628,65 @@ Here\[aq]s one way to resolve that:
assets:checking
\f[R]
.fi
.SS commodities
.PP
commodities
.PD 0
.P
.PD
List all commodity/currency symbols used or declared in the journal.
.SS descriptions
.PP
descriptions Show descriptions.
.PP
This command lists all descriptions that appear in transactions.
.PP
Examples:
.IP
.nf
\f[C]
$ hledger descriptions
Store Name
Gas Station | Petrol
Person A
\f[R]
.fi
.SS diff
.PP
diff
.PD 0
.P
.PD
Compares a particular account\[aq]s transactions in two input files.
It shows any transactions to this account which are in one file but not
in the other.
.PP
More precisely, for each posting affecting this account in either file,
it looks for a corresponding posting in the other file which posts the
same amount to the same account (ignoring date, description, etc.) Since
postings not transactions are compared, this also works when multiple
bank transactions have been combined into a single journal entry.
.PP
This is useful eg if you have downloaded an account\[aq]s transactions
from your bank (eg as CSV data).
When hledger and your bank disagree about the account balance, you can
compare the bank data with your journal to find out the cause.
.PP
Examples:
.IP
.nf
\f[C]
$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
These transactions are in the first file only:
2014/01/01 Opening Balances
assets:bank:giro EUR ...
...
equity:opening balances EUR -...
These transactions are in the second file only:
\f[R]
.fi
.SS files
.PP
files
@ -2785,6 +2844,37 @@ with multicolumn balance reports you can alter the report mode with
.PP
This command also supports output destination and output format
selection.
.SS notes
.PP
notes Show notes.
.PP
This command lists all notes that appear in transactions.
.PP
Examples:
.IP
.nf
\f[C]
$ hledger notes
Petrol
Snacks
\f[R]
.fi
.SS payees
.PP
payees Show payee names.
.PP
This command lists all payee names that appear in transactions.
.PP
Examples:
.IP
.nf
\f[C]
$ hledger payees
Store Name
Gas Station
Person A
\f[R]
.fi
.SS prices
.PP
prices

View File

@ -773,34 +773,27 @@ File: hledger.info, Node: -V Market value, Next: -X Market value in specified
-----------------------
The '-V/--market' flag converts reported amounts to their market value
in a default valuation commodity, using the historical market prices in
effect on a default valuation date.
in a default valuation commodity, using the market prices in effect on a
default valuation date. For single period reports, the valuation date
is today; for multiperiod reports, it is the last day of each subperiod.
It is equivalent to '--value=now' or '--value=end' (see below).
For single period reports, the valuation date is today. For
multiperiod reports, it is the last day of each subperiod.
The valuation commodity will be the one referenced in the latest
The default valuation commodity is the one referenced in the latest
applicable market price dated on or before the valuation date. If most
of your P declarations lead to a single home currency, this will usually
be what you want.
Unlike the similar flag in Ledger, it does not infer market prices
from transaction prices. In hledger, -B uses transaction prices, -V and
-X use market prices.
It is equivalent to '--value=now' or '--value=end'.
be what you want. (To specify the commodity, see -X below.)
Here's a quick example:
# one euro is worth this many dollars from nov 1
; one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
# purchase some euros on nov 3
; purchase some euros on nov 3
2016/11/3
assets:euros €100
assets:checking
# the euro is worth fewer dollars by dec 21
; the euro is worth fewer dollars by dec 21
P 2016/12/21 € $1.03
How many euros do I have ?
@ -819,6 +812,10 @@ specified, defaults to today)
$ hledger -f t.j bal -N euros -V
$103.00 assets:euros
Note that in hledger, market prices are always declared explicitly
with P directives; we do not infer them from transaction prices as
Ledger does.

File: hledger.info, Node: -X Market value in specified commodity, Next: --value, Prev: -V Market value, Up: Valuation
@ -828,8 +825,8 @@ File: hledger.info, Node: -X Market value in specified commodity, Next: --valu
The '-X/--exchange' option is like '-V/--market' except it takes a
commodity symbol argument, so that you can select a different target
commodity. It is similar to the same option in Ledger, with the same
caveat mentioned for '-V'/'--value' above. It is equivalent to
'--value=now,COMM' or '--value=end,COMM'; for more details, read on.
caveat mentioned above. It is equivalent to '--value=now,COMM' or
'--value=end,COMM'.

File: hledger.info, Node: --value, Next: Combining -B -V -X --value, Prev: -X Market value in specified commodity, Up: Valuation
@ -1294,10 +1291,15 @@ detailed command help.
* check-dates::
* check-dupes::
* close::
* commodities::
* descriptions::
* diff::
* files::
* help::
* import::
* incomestatement::
* notes::
* payees::
* prices::
* print::
* print-unique::
@ -2110,7 +2112,7 @@ the default journal file, or another specified as an argument.
An example: http://stefanorodighiero.net/software/hledger-dupes.html

File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMANDS
File: hledger.info, Node: close, Next: commodities, Prev: check-dupes, Up: COMMANDS
4.10 close
==========
@ -2199,9 +2201,70 @@ breaking balance assertions:
assets:checking

File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS
File: hledger.info, Node: commodities, Next: descriptions, Prev: close, Up: COMMANDS
4.11 files
4.11 commodities
================
commodities
List all commodity/currency symbols used or declared in the journal.

File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS
4.12 descriptions
=================
descriptions Show descriptions.
This command lists all descriptions that appear in transactions.
Examples:
$ hledger descriptions
Store Name
Gas Station | Petrol
Person A

File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS
4.13 diff
=========
diff
Compares a particular account's transactions in two input files. It
shows any transactions to this account which are in one file but not in
the other.
More precisely, for each posting affecting this account in either
file, it looks for a corresponding posting in the other file which posts
the same amount to the same account (ignoring date, description, etc.)
Since postings not transactions are compared, this also works when
multiple bank transactions have been combined into a single journal
entry.
This is useful eg if you have downloaded an account's transactions
from your bank (eg as CSV data). When hledger and your bank disagree
about the account balance, you can compare the bank data with your
journal to find out the cause.
Examples:
$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
These transactions are in the first file only:
2014/01/01 Opening Balances
assets:bank:giro EUR ...
...
equity:opening balances EUR -...
These transactions are in the second file only:

File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS
4.14 files
==========
files
@ -2211,7 +2274,7 @@ file names matching the regular expression (case sensitive) are shown.

File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS
4.12 help
4.15 help
=========
help
@ -2251,7 +2314,7 @@ DESCRIPTION

File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS
4.13 import
4.16 import
===========
import
@ -2279,7 +2342,7 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions

File: hledger.info, Node: Importing balance assignments, Up: import
4.13.1 Importing balance assignments
4.16.1 Importing balance assignments
------------------------------------
Entries added by import will have their posting amounts made explicit
@ -2296,9 +2359,9 @@ $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
please test it and send a pull request.)

File: hledger.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS
File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS
4.14 incomestatement
4.17 incomestatement
====================
incomestatement, is
@ -2343,9 +2406,42 @@ report mode with '--change'/'--cumulative'/'--historical'.
selection.

File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS
File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS
4.15 prices
4.18 notes
==========
notes Show notes.
This command lists all notes that appear in transactions.
Examples:
$ hledger notes
Petrol
Snacks

File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS
4.19 payees
===========
payees Show payee names.
This command lists all payee names that appear in transactions.
Examples:
$ hledger payees
Store Name
Gas Station
Person A

File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS
4.20 prices
===========
prices
@ -2357,7 +2453,7 @@ Prices (and postings providing prices) can be filtered by a query.

File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS
4.16 print
4.21 print
==========
print, txns, p
@ -2458,7 +2554,7 @@ $ hledger print -Ocsv

File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS
4.17 print-unique
4.22 print-unique
=================
print-unique
@ -2479,7 +2575,7 @@ $ LEDGER_FILE=unique.journal hledger print-unique

File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS
4.18 register
4.23 register
=============
register, reg, r
@ -2569,7 +2665,7 @@ length and comparable to the others in the report.

File: hledger.info, Node: Custom register output, Up: register
4.18.1 Custom register output
4.23.1 Custom register output
-----------------------------
register uses the full terminal width by default, except on windows.
@ -2600,7 +2696,7 @@ selection.

File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS
4.19 register-match
4.24 register-match
===================
register-match
@ -2613,7 +2709,7 @@ ledger-autosync detect already-seen transactions when importing.

File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS
4.20 rewrite
4.25 rewrite
============
rewrite
@ -2665,7 +2761,7 @@ commodity.

File: hledger.info, Node: Re-write rules in a file, Up: rewrite
4.20.1 Re-write rules in a file
4.25.1 Re-write rules in a file
-------------------------------
During the run this tool will execute so called "Automated Transactions"
@ -2708,7 +2804,7 @@ postings.

File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file
4.20.1.1 Diff output format
4.25.1.1 Diff output format
...........................
To use this tool for batch modification of your journal files you may
@ -2749,7 +2845,7 @@ output from 'hledger print'.

File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file
4.20.1.2 rewrite vs. print -auto
4.25.1.2 rewrite vs. print -auto
................................
This command predates print -auto, and currently does much the same
@ -2769,7 +2865,7 @@ thing, but with these differences:

File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS
4.21 roi
4.26 roi
========
roi
@ -2797,7 +2893,7 @@ regardless of the length of reporting interval.

File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS
4.22 stats
4.27 stats
==========
stats
@ -2828,7 +2924,7 @@ selection.

File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS
4.23 tags
4.28 tags
=========
tags
@ -2841,7 +2937,7 @@ instead.

File: hledger.info, Node: test, Prev: tags, Up: COMMANDS
4.24 test
4.29 test
=========
test
@ -2957,9 +3053,6 @@ hledger release.
* interest::
* irr::

File: hledger.info, Node: diff, Next: iadd, Up: Third party add-ons
5.2.1 diff
----------
@ -2967,7 +3060,7 @@ hledger-diff shows differences in an account's transactions between one
journal file and another.

File: hledger.info, Node: iadd, Next: interest, Prev: diff, Up: Third party add-ons
File: hledger.info, Node: iadd, Next: interest, Prev: , Up: Third party add-ons
5.2.2 iadd
----------
@ -3084,132 +3177,141 @@ Node: -B Cost25145
Ref: #b-cost25256
Node: -V Market value25454
Ref: #v-market-value25628
Node: -X Market value in specified commodity27034
Ref: #x-market-value-in-specified-commodity27254
Node: --value27594
Ref: #value27759
Node: Valuation type28560
Ref: #valuation-type28696
Node: Valuation commodity29581
Ref: #valuation-commodity29752
Node: --value examples30452
Ref: #value-examples30629
Node: Effect of --value on reports32612
Ref: #effect-of---value-on-reports32785
Node: Combining -B -V -X --value35476
Ref: #combining--b--v--x---value35638
Node: Output destination35674
Ref: #output-destination35826
Node: Output format36109
Ref: #output-format36261
Node: Regular expressions36646
Ref: #regular-expressions36783
Node: QUERIES38144
Ref: #queries38246
Node: COMMANDS42208
Ref: #commands42320
Node: accounts43321
Ref: #accounts43419
Node: activity44118
Ref: #activity44228
Node: add44611
Ref: #add44710
Node: balance47455
Ref: #balance47566
Node: Classic balance report49008
Ref: #classic-balance-report49181
Node: Customising the classic balance report50550
Ref: #customising-the-classic-balance-report50778
Node: Colour support52854
Ref: #colour-support53021
Node: Flat mode53194
Ref: #flat-mode53342
Node: Depth limited balance reports53755
Ref: #depth-limited-balance-reports53955
Node: Multicolumn balance report54411
Ref: #multicolumn-balance-report54609
Node: Budget report59923
Ref: #budget-report60066
Node: Nested budgets65268
Ref: #nested-budgets65380
Ref: #output-format-168860
Node: balancesheet68938
Ref: #balancesheet69074
Node: balancesheetequity70389
Ref: #balancesheetequity70538
Node: cashflow71099
Ref: #cashflow71227
Node: check-dates72255
Ref: #check-dates72382
Node: check-dupes72661
Ref: #check-dupes72785
Node: close73078
Ref: #close73186
Node: files76773
Ref: #files76874
Node: help77021
Ref: #help77121
Node: import78214
Ref: #import78328
Node: Importing balance assignments79116
Ref: #importing-balance-assignments79264
Node: incomestatement79913
Ref: #incomestatement80047
Node: prices81383
Ref: #prices81498
Node: print81777
Ref: #print81887
Node: print-unique86380
Ref: #print-unique86506
Node: register86791
Ref: #register86918
Node: Custom register output91090
Ref: #custom-register-output91219
Node: register-match92481
Ref: #register-match92615
Node: rewrite92966
Ref: #rewrite93081
Node: Re-write rules in a file94936
Ref: #re-write-rules-in-a-file95070
Node: Diff output format96280
Ref: #diff-output-format96449
Node: rewrite vs print --auto97541
Ref: #rewrite-vs.-print---auto97720
Node: roi98276
Ref: #roi98374
Node: stats99386
Ref: #stats99485
Node: tags100273
Ref: #tags100371
Node: test100665
Ref: #test100749
Node: ADD-ON COMMANDS101510
Ref: #add-on-commands101620
Node: Official add-ons102908
Ref: #official-add-ons103048
Node: api103136
Ref: #api103225
Node: ui103277
Ref: #ui103376
Node: web103434
Ref: #web103523
Node: Third party add-ons103569
Ref: #third-party-add-ons103744
Node: diff103880
Ref: #diff103977
Node: iadd104076
Ref: #iadd104190
Node: interest104273
Ref: #interest104394
Node: irr104489
Ref: #irr104587
Node: Experimental add-ons104718
Ref: #experimental-add-ons104870
Node: autosync105151
Ref: #autosync105262
Node: chart105501
Ref: #chart105620
Node: check105691
Ref: #check105793
Node: -X Market value in specified commodity27058
Ref: #x-market-value-in-specified-commodity27278
Node: --value27572
Ref: #value27737
Node: Valuation type28538
Ref: #valuation-type28674
Node: Valuation commodity29559
Ref: #valuation-commodity29730
Node: --value examples30430
Ref: #value-examples30607
Node: Effect of --value on reports32590
Ref: #effect-of---value-on-reports32763
Node: Combining -B -V -X --value35454
Ref: #combining--b--v--x---value35616
Node: Output destination35652
Ref: #output-destination35804
Node: Output format36087
Ref: #output-format36239
Node: Regular expressions36624
Ref: #regular-expressions36761
Node: QUERIES38122
Ref: #queries38224
Node: COMMANDS42186
Ref: #commands42298
Node: accounts43362
Ref: #accounts43460
Node: activity44159
Ref: #activity44269
Node: add44652
Ref: #add44751
Node: balance47496
Ref: #balance47607
Node: Classic balance report49049
Ref: #classic-balance-report49222
Node: Customising the classic balance report50591
Ref: #customising-the-classic-balance-report50819
Node: Colour support52895
Ref: #colour-support53062
Node: Flat mode53235
Ref: #flat-mode53383
Node: Depth limited balance reports53796
Ref: #depth-limited-balance-reports53996
Node: Multicolumn balance report54452
Ref: #multicolumn-balance-report54650
Node: Budget report59964
Ref: #budget-report60107
Node: Nested budgets65309
Ref: #nested-budgets65421
Ref: #output-format-168901
Node: balancesheet68979
Ref: #balancesheet69115
Node: balancesheetequity70430
Ref: #balancesheetequity70579
Node: cashflow71140
Ref: #cashflow71268
Node: check-dates72296
Ref: #check-dates72423
Node: check-dupes72702
Ref: #check-dupes72826
Node: close73119
Ref: #close73233
Node: commodities76820
Ref: #commodities76947
Node: descriptions77029
Ref: #descriptions77157
Node: diff77338
Ref: #diff77444
Node: files78491
Ref: #files78591
Node: help78738
Ref: #help78838
Node: import79931
Ref: #import80045
Node: Importing balance assignments80833
Ref: #importing-balance-assignments80981
Node: incomestatement81630
Ref: #incomestatement81763
Node: notes83099
Ref: #notes83212
Node: payees83338
Ref: #payees83444
Node: prices83602
Ref: #prices83708
Node: print83987
Ref: #print84097
Node: print-unique88590
Ref: #print-unique88716
Node: register89001
Ref: #register89128
Node: Custom register output93300
Ref: #custom-register-output93429
Node: register-match94691
Ref: #register-match94825
Node: rewrite95176
Ref: #rewrite95291
Node: Re-write rules in a file97146
Ref: #re-write-rules-in-a-file97280
Node: Diff output format98490
Ref: #diff-output-format98659
Node: rewrite vs print --auto99751
Ref: #rewrite-vs.-print---auto99930
Node: roi100486
Ref: #roi100584
Node: stats101596
Ref: #stats101695
Node: tags102483
Ref: #tags102581
Node: test102875
Ref: #test102959
Node: ADD-ON COMMANDS103720
Ref: #add-on-commands103830
Node: Official add-ons105118
Ref: #official-add-ons105258
Node: api105346
Ref: #api105435
Node: ui105487
Ref: #ui105586
Node: web105644
Ref: #web105733
Node: Third party add-ons105779
Ref: #third-party-add-ons105954
Ref: #diff-1106113
Node: iadd106212
Ref: #iadd106322
Node: interest106405
Ref: #interest106526
Node: irr106621
Ref: #irr106719
Node: Experimental add-ons106850
Ref: #experimental-add-ons107002
Node: autosync107283
Ref: #autosync107394
Node: chart107633
Ref: #chart107752
Node: check107823
Ref: #check107925

End Tag Table

File diff suppressed because it is too large Load Diff