simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-09-16 00:37:33 +03:00
Code Issues Projects Releases Wiki Activity

doc: generate man pages for each package (#282)

Browse Source 
There are now six man pages, one for each main executable and file
format, generated from markdown by the mighty pandoc. They are basically
the content of the user manual, split up and moved into the appropriate
package directory.  I've also committed the generated man files.

The man pages' markdown source (hledger/hledger.1.md,
hledger-lib/hledger_journal.5.md etc.) are now the master documentation
files. The plan is to concatenate them (with a little munging) to form
the all-in-one user manual for the website, at release time.  This also
separates the hledger.org user manual from the latest doc commits, which
should simplify website management.
This commit is contained in:
Simon Michael 2015-10-20 06:26:09 -07:00
parent 77cf3a83da
commit 191c2e533f
14 changed files with 4021 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
Makefile
View File

@ -1033,6 +1033,34 @@ haddock: \
# # cd site/api && \
# # hoogle --convert=main.txt --output=default.hoo
# in subsequent rules, allow automatic variables to be used in prerequisites (use $$)
.SECONDEXPANSION:
MANPAGES=\
hledger-lib/hledger_csv.5 \
hledger-lib/hledger_journal.5 \
hledger-lib/hledger_timelog.5 \
hledger/hledger.1 \
hledger-ui/hledger-ui.1 \
hledger-web/hledger-web.1 \
manpages: $(MANPAGES) \
$(call def-help,manpages, generate man pages from markdown )
%.1 %.5: $$@.md doc/manpage.template
pandoc $< -t man -s --template doc/manpage.template -o $@ \
--filter tools/pandocCapitalizeHeaders.hs \
--filter tools/pandocRemoveNotes.hs \
--filter tools/pandocRemoveLinks.hs
# --filter tools/pandocCapitalizeHeaders \
# --filter tools/pandocRemoveNotes \
# --filter tools/pandocRemoveLinks
# faster when compiled
clean-manpages:
rm -f $(MANPAGES)
###############################################################################
$(call def-help-subsection,RELEASING:)
#$(call def-help-subsection,see also developer guide -> how to -> do a release)
@ -1321,9 +1349,6 @@ tagrelease: \
###############################################################################
$(call def-help-subsection,MISCELLANEOUS:)
# allow automatic variables (using $$) in the prerequisites of subsequent rules
.SECONDEXPANSION:
# XXX enable for all cabal files when hpack is a little better
# gencabalfiles: $$(CABALFILES)
gencabalfiles: doc/site/hakyll-std.cabal \
@ -1386,7 +1411,7 @@ cleanghc: cleanghco \
clean: cleanghco \
$(call def-help,clean, default cleanup (ghc build leftovers) )
Clean: stackclean cabalclean cleanghc cleantags \
Clean: stackclean cabalclean cleanghc cleantags clean-manpages \
$(call def-help,Clean, thorough cleanup (stack/cabal/ghc builds and tags) )
# reverse = $(if $(wordlist 2,2,$(1)),$(call reverse,$(wordlist 2,$(words $(1)),$(1))) $(firstword $(1)),$(1))

42
doc/manpage.template Normal file
View File

@ -0,0 +1,42 @@
$if(has-tables)$
.\"t
$endif$
.TH "$title$" "$section$" "$date$" "$footer$" "hledger User Manuals"
$for(header-includes)$
$header-includes$
$endfor$
$for(include-before)$
$include-before$
$endfor$
$body$
$for(include-after)$
$include-after$
$endfor$
.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org.
.SH AUTHORS
$if(author)$
$for(author)$$author$$sep$; $endfor$.
$else$
Simon Michael <simon@joyful.com>
$endif$
.SH COPYRIGHT
Copyright (C) 2007-2015 Simon Michael.
.br
Released under GNU GPLv3+.
.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
.br
hledger_csv(5), hledger_journal(5), hledger_timelog(5)
For more information, see http://hledger.org.

258
hledger-lib/hledger_csv.5 Normal file
View File

@ -0,0 +1,258 @@
.TH "hledger_csv" "5" "October 2015" "" "hledger User Manuals"
.SH NAME
.PP
hledger_csv \- reading CSV files with hledger, and the CSV rules file
format
.SH DESCRIPTION
.PP
hledger can read CSV files, converting each CSV record into a journal
entry (transaction), if you provide some conversion hints in a "rules
file".
This file should be named like the CSV file with an additional
\f[C]\&.rules\f[] suffix (eg: \f[C]mybank.csv.rules\f[]); or, you can
specify the file with \f[C]\-\-rules\-file\ PATH\f[].
hledger will create it if necessary, with some default rules which
you\[aq]ll need to adjust.
At minimum, the rules file must specify the \f[C]date\f[] and
\f[C]amount\f[] fields.
For an example, see How to read CSV files.
.PP
(For CSV output, see CSV output.)
.SH CSV RULES
.PP
The following six kinds of rule can appear in the rules file, in any
order.
Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are
ignored.
.PP
\f[B]\f[C]skip\f[] \f[I]N\f[]\f[]
.PD 0
.P
.PD
Skip this number of CSV records at the beginning.
You\[aq]ll need this when your CSV contains header lines.
Eg:
.IP
.nf
\f[C]
#\ ignore\ the\ first\ CSV\ line
skip\ 1
\f[]
.fi
.PP
\f[B]\f[C]date\-format\f[] \f[I]DATEFMT\f[]\f[]
.PD 0
.P
.PD
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\[aq]ll need to
specify the format.
DATEFMT is a strptime\-like date parsing pattern, which must parse the
date field values completely.
Examples:
.IP
.nf
\f[C]
#\ parses\ "6/11/2013":
date\-format\ %\-d/%\-m/%Y
\f[]
.fi
.IP
.nf
\f[C]
#\ parses\ "11/06/2013":
date\-format\ %m/%d/%Y
\f[]
.fi
.IP
.nf
\f[C]
#\ parses\ "2013\-Nov\-06":
date\-format\ %Y\-%h\-%d
\f[]
.fi
.IP
.nf
\f[C]
#\ parses\ "11/6/2013\ 11:32\ PM":
date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
\f[]
.fi
.PP
\f[B]\f[C]fields\f[] \f[I]CSVFIELDNAME1\f[],
\f[I]CSVFIELDNAME2\f[]...\f[]
.PD 0
.P
.PD
(Field list)
.PD 0
.P
.PD
This (a) names the CSV fields (names may not contain whitespace), and
(b) assigns them to journal entry fields if you use any of these
standard field names: \f[C]date\f[], \f[C]date2\f[], \f[C]status\f[],
\f[C]code\f[], \f[C]description\f[], \f[C]comment\f[],
\f[C]account1\f[], \f[C]account2\f[], \f[C]amount\f[],
\f[C]amount\-in\f[], \f[C]amount\-out\f[], \f[C]currency\f[].
Eg:
.IP
.nf
\f[C]
#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\ date,\ description\ and\ amount
#\ give\ the\ 7th\ and\ 8th\ fields\ custom\ names\ for\ later\ reference
fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield
\f[]
.fi
.PP
\f[B]\f[I]ENTRYFIELDNAME\f[] \f[I]FIELDVALUE\f[]\f[]
.PD 0
.P
.PD
(Field assignment)
.PD 0
.P
.PD
This sets a journal entry field (one of the standard names above) to the
given text value, which can include CSV field values interpolated by
name (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]).
Field assignments can be used instead of or in addition to a field
list.
Eg:
.IP
.nf
\f[C]
#\ set\ the\ amount\ to\ the\ 4th\ CSV\ field\ with\ "USD\ "\ prepended
amount\ USD\ %4
\f[]
.fi
.IP
.nf
\f[C]
#\ combine\ three\ fields\ to\ make\ a\ comment\ (containing\ two\ tags)
comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1
\f[]
.fi
.PP
\f[B]\f[C]if\f[] \f[I]PATTERN\f[]
.PD 0
.P
.PD
\ \ \ \ \f[I]FIELDASSIGNMENTS\f[]...\f[]
.PD 0
.P
.PD
or
.PD 0
.P
.PD
\f[B]\f[C]if\f[]
.PD 0
.P
.PD
\f[I]PATTERN\f[]
.PD 0
.P
.PD
\f[I]PATTERN\f[]...
.PD 0
.P
.PD
\ \ \ \ \f[I]FIELDASSIGNMENTS\f[]...\f[]
.PD 0
.P
.PD
(Conditional block)
.PD 0
.P
.PD
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\[aq]s not yet possible to match
within a specific field).
When there are multiple patterns they should be written on separate
lines, unindented.
The field assignments are on separate lines indented by at least one
space.
Examples:
.IP
.nf
\f[C]
#\ if\ the\ CSV\ record\ contains\ "groceries",\ set\ account2\ to\ "expenses:groceries"
if\ groceries
\ account2\ expenses:groceries
\f[]
.fi
.IP
.nf
\f[C]
#\ if\ the\ CSV\ record\ contains\ any\ of\ these\ patterns,\ set\ account2\ and\ comment\ as\ shown
if
monthly\ service\ fee
atm\ transaction\ fee
banking\ thru\ software
\ account2\ expenses:business:banking
\ comment\ \ XXX\ deductible\ ?\ check
\f[]
.fi
.PP
\f[B]\f[C]include\f[] \f[I]RULESFILE\f[]\f[]
.PD 0
.P
.PD
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\[aq]s directory.
Eg:
.IP
.nf
\f[C]
#\ rules\ reused\ with\ several\ CSV\ files
include\ common.rules
\f[]
.fi
.SS Other CSV tips
.PP
Each generated journal entry will have two postings, to
\f[C]account1\f[] and \f[C]account2\f[] respectively.
Currently it\[aq]s not possible to generate entries with more than two
postings.
.PP
If the CSV has debit/credit amounts in separate fields, assign to the
\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead of
\f[C]amount\f[].
.PP
If the CSV has the currency in a separate field, assign that to the
\f[C]currency\f[] pseudo field which will be automatically prepended to
the amount.
(Or you can do the same thing with a field assignment.)
.PP
If an amount value is parenthesised, it will be de\-parenthesised and
sign\-flipped automatically.
.PP
The generated journal entries will be sorted by date.
The original order of same\-day entries will be preserved, usually.
.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org.
.SH AUTHORS
Simon Michael <simon@joyful.com>
.SH COPYRIGHT
Copyright (C) 2007-2015 Simon Michael.
.br
Released under GNU GPLv3+.
.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
.br
hledger_csv(5), hledger_journal(5), hledger_timelog(5)
For more information, see http://hledger.org.

147
hledger-lib/hledger_csv.5.md Normal file
View File

@ -0,0 +1,147 @@
% hledger_csv(5)
%
% October 2015
# NAME
hledger_csv - reading CSV files with hledger, and the CSV rules file format
# DESCRIPTION
hledger can read
[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) files,
converting each CSV record into a journal entry (transaction),
if you provide some conversion hints in a "rules file".
This file should be named like the CSV file with an additional `.rules` suffix (eg: `mybank.csv.rules`);
or, you can specify the file with `--rules-file PATH`.
hledger will create it if necessary, with some default rules which you'll need to adjust.
At minimum, the rules file must specify the `date` and `amount` fields.
For an example, see [How to read CSV files](how-to-read-csv-files.html).
(For CSV output, see [CSV output](#csv-output).)
# CSV rules
The following six kinds of rule can appear in the rules file, in any order.
Blank lines and lines beginning with `#` or `;` are ignored.
**`skip` *N***\
Skip this number of CSV records at the beginning.
You'll need this when your CSV contains header lines. Eg:
<!-- XXX -->
<!-- hledger tries to skip initial CSV header lines automatically. -->
<!-- If it guesses wrong, use this directive to skip exactly N lines. -->
<!-- This can also be used in a conditional block to ignore certain CSV records. -->
```rules
# ignore the first CSV line
skip 1
```
**`date-format` *DATEFMT***\
When your CSV date fields are not formatted like `YYYY/MM/DD` (or `YYYY-MM-DD` or `YYYY.MM.DD`),
you'll need to specify the format.
DATEFMT is a [strptime-like date parsing pattern](http://hackage.haskell.org/packages/archive/time/latest/doc/html/Data-Time-Format.html#v:formatTime),
which must parse the date field values completely. Examples:
``` {.rules .display-table}
# parses "6/11/2013":
date-format %-d/%-m/%Y
```
``` {.rules .display-table}
# parses "11/06/2013":
date-format %m/%d/%Y
```
``` {.rules .display-table}
# parses "2013-Nov-06":
date-format %Y-%h-%d
```
``` {.rules .display-table}
# parses "11/6/2013 11:32 PM":
date-format %-m/%-d/%Y %l:%M %p
```
**`fields` *CSVFIELDNAME1*, *CSVFIELDNAME2*...**\
(Field list)\
This (a) names the CSV fields (names may not contain whitespace),
and (b) assigns them to journal entry fields if you use any of these standard field names:
`date`, `date2`, `status`, `code`, `description`, `comment`, `account1`, `account2`, `amount`, `amount-in`, `amount-out`, `currency`.
Eg:
```rules
# use the 1st, 2nd and 4th CSV fields as the entry date, description and amount
# give the 7th and 8th fields custom names for later reference
fields date, description, , amount, , , somefield, anotherfield
```
***ENTRYFIELDNAME* *FIELDVALUE***\
(Field assignment)\
This sets a journal entry field (one of the standard names above) to the given text value,
which can include CSV field values interpolated by name (`%CSVFIELDNAME`) or 1-based position (`%N`).
<!-- Whitespace before or after the value is ignored. -->
Field assignments can be used instead of or in addition to a field list.
Eg:
```{.rules .display-table}
# set the amount to the 4th CSV field with "USD " prepended
amount USD %4
```
```{.rules .display-table}
# combine three fields to make a comment (containing two tags)
comment note: %somefield - %anotherfield, date: %1
```
**`if` *PATTERN*\
&nbsp;&nbsp;&nbsp;&nbsp;*FIELDASSIGNMENTS*...**\
or\
**`if`\
*PATTERN*\
*PATTERN*...\
&nbsp;&nbsp;&nbsp;&nbsp;*FIELDASSIGNMENTS*...**\
(Conditional block)\
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 within a
specific field). When there are multiple patterns they should be written
on separate lines, unindented.
The field assignments are on separate lines indented by at least one space.
Examples:
```{.rules .display-table}
# if the CSV record contains "groceries", set account2 to "expenses:groceries"
if groceries
account2 expenses:groceries
```
```{.rules .display-table}
# if the CSV record contains any of these patterns, set account2 and comment as shown
if
monthly service fee
atm transaction fee
banking thru software
account2 expenses:business:banking
comment XXX deductible ? check
```
**`include` *RULESFILE***\
Include another rules file at this point. `RULESFILE` is either an absolute file path or
a path relative to the current file's directory. Eg:
```rules
# rules reused with several CSV files
include common.rules
```
## Other CSV tips
Each generated journal entry will have two postings, to `account1` and `account2` respectively.
Currently it's not possible to generate entries with more than two postings.
If the CSV has debit/credit amounts in separate fields, assign to the `amount-in` and `amount-out` pseudo fields instead of `amount`.
If the CSV has the currency in a separate field, assign that to the `currency` pseudo field which will be automatically prepended to the amount.
(Or you can do the same thing with a field assignment.)
If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically.
The generated journal entries will be sorted by date.
The original order of same-day entries will be preserved, usually.
<!-- (by reversing the CSV entries if they seem to be in reverse date order). -->

800
hledger-lib/hledger_journal.5 Normal file
View File

@ -0,0 +1,800 @@
.TH "hledger_journal" "5" "October 2015" "" "hledger User Manuals"
.SH NAME
.PP
hledger_journal \- reference for hledger\[aq]s journal file format
.SH DESCRIPTION
.PP
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\[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\[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\[aq]s an example:
.IP
.nf
\f[C]
;\ A\ sample\ journal\ file.\ This\ is\ a\ comment.
2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ transaction\[aq]s\ first\ line\ starts\ in\ column\ 0,\ contains\ date\ and\ description
\ \ \ \ assets:bank:checking\ \ $1\ \ \ \ ;\ <\-\ posting\ lines\ start\ with\ whitespace,\ each\ contains\ an\ account\ name
\ \ \ \ income:salary\ \ \ \ \ \ \ \ $\-1\ \ \ \ ;\ \ \ \ followed\ by\ at\ least\ two\ spaces\ and\ an\ amount
2008/06/01\ gift
\ \ \ \ assets:bank:checking\ \ $1\ \ \ \ ;\ <\-\ at\ least\ two\ postings\ in\ a\ transaction
\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ ;\ <\-\ their\ amounts\ must\ balance\ to\ 0
2008/06/02\ save
\ \ \ \ assets:bank:saving\ \ \ \ $1
\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ ;\ <\-\ one\ amount\ may\ be\ omitted;\ here\ $\-1\ is\ inferred
2008/06/03\ eat\ &\ shop\ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ description\ can\ be\ anything
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ $1
\ \ \ \ expenses:supplies\ \ \ \ \ $1\ \ \ \ ;\ <\-\ this\ transaction\ debits\ two\ expense\ accounts
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ $\-2\ inferred
2008/12/31\ *\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ an\ optional\ *\ or\ !\ after\ the\ date\ means\ "cleared"\ (or\ anything\ you\ want)
\ \ \ \ liabilities:debts\ \ \ \ \ $1
\ \ \ \ assets:bank:checking
\f[]
.fi
.PP
Now let\[aq]s explore the available journal file syntax in detail.
.SH TRANSACTIONS
.PP
Transactions are represented by journal entries.
Each begins with a simple date in column 0, followed by three optional
fields with spaces between them:
.IP \[bu] 2
a status flag, which can be empty or \f[C]!\f[] or \f[C]*\f[] (meaning
"uncleared", "pending" and "cleared", or whatever you want)
.IP \[bu] 2
a transaction code (eg a check number),
.IP \[bu] 2
and/or a description
.PP
then some number of postings, of some amount to some account, each on
its own line.
Usually there are at least two postings, though one or even none is
possible.
.PP
The (real) posting amounts within a transaction must always balance, ie
add up to 0.
Optionally one amount can be left blank, in which case it will be
inferred.
.SH DATES
.SS Simple dates
.PP
Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D)
Leading zeroes are optional.
The year may be omitted, in which case it defaults to the current year,
or you can set the default year with a default year directive.
.PP
Some examples: \f[C]2010/01/31\f[], \f[C]1/31\f[],
\f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[].
.SS Secondary dates
.PP
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, write both
dates separated by an equals sign.
The \f[I]primary date\f[], on the left, is used by default; the
\f[I]secondary date\f[], on the right, is used when the
\f[C]\-\-date2\f[] flag is specified (For Ledger compatibility,
\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work.)
.PP
Their meaning 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\[aq]s an example.
Note that a secondary date will use the year of the primary date if
unspecified.
.IP
.nf
\f[C]
2010/2/23=2/19\ movie\ ticket
\ \ expenses:cinema\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10
\ \ assets:checking
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ register\ checking
2010/02/23\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ register\ checking\ \-\-date2
2010/02/19\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10
\f[]
.fi
.PP
Secondary dates require some effort: you must use them consistently in
your journal entries and remember whether to use or not use the
\f[C]\-\-date2\f[] flag for your reports.
Arguably they are now obsolete, superseded by...
.SS Posting dates
.PP
You can give individual postings a different date from their parent
transaction, by adding a posting tag (see below) like
\f[C]date:DATE\f[], where DATE is a simple 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 easy bank
reconciliation:
.IP
.nf
\f[C]
2015/5/30
\ \ \ \ expenses:food\ \ \ \ \ $10\ \ \ ;\ food\ purchased\ on\ saturday\ 5/30
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ ;\ bank\ cleared\ it\ on\ monday,\ date:6/1
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ \-f\ tt.j\ register\ food
2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ \-f\ tt.j\ register\ checking
2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10
\f[]
.fi
.PP
A posting date will use the year of the transaction date if unspecified.
.PP
You can also set the secondary date, with \f[C]date2:DATE2\f[].
For compatibility, Ledger\[aq]s older posting date syntax is also
supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]
in a posting comment.
.PP
When using any of these forms, be sure to provide a valid simple date or
you\[aq]ll get a parse error.
Eg a \f[C]date:\f[] tag with no value is not allowed.
.SH ACCOUNT NAMES
.PP
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: \f[C]assets\f[], \f[C]liabilities\f[],
\f[C]income\f[], \f[C]expenses\f[], and \f[C]equity\f[].
.PP
Account names may contain single spaces, eg:
\f[C]assets:accounts\ receivable\f[].
Because of this, they must always be followed by at least two spaces (or
newline).
.PP
Account names can be aliased.
.SH AMOUNTS
.PP
After the account name, there is usually an amount.
Important: between account name and amount, there must be \f[B]two or
more\f[] spaces.
.PP
The amount is a number, optionally with a currency symbol or commodity
name on either the left or right.
Negative amounts may have the minus sign either before or after the
currency symbol (\f[C]\-$1\f[] or \f[C]$\-1\f[]).
Commodity names which contain more than just letters should be enclosed
in double quotes (\f[C]1\ "person\ hours"\f[]).
.SS Decimal points and digit groups
.PP
hledger supports flexible decimal point and digit group separator
styles, to support international variations.
Numbers can use either a period (\f[C]\&.\f[]) or a comma (\f[C],\f[])
as decimal point.
They can also have digit group separators at any position (eg thousands
separators) which can be comma or period \- whichever one you did not
use as a decimal point.
If you use digit group separators, you must also include a decimal point
in at least one number in the same commodity, so that hledger knows
which character is which.
Eg, write \f[C]$1,000.00\f[] or \f[C]$1.000,00\f[].
.SS Amount display styles
.PP
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that
commodity.
Amount styles include:
.IP \[bu] 2
the position (left or right) and spacing (space or no separator) of the
commodity symbol
.IP \[bu] 2
the digit group separator character (comma or period) and digit group
sizes, if any
.IP \[bu] 2
the decimal point character (period or comma)
.IP \[bu] 2
the display precision (number of decimal places displayed)
.PP
The canonical style is generally the style of the first posting amount
seen in a commodity.
However the display precision will be the highest precision seen in all
posting amounts in that commmodity.
.PP
The precisions used in a price amount, or a D directive, don\[aq]t
affect the canonical display precision directly, but they can affect it
indirectly, 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 (actually this last case does not influence the
canonical display precision but probably should).
.SH VIRTUAL POSTINGS
.PP
When you parenthesise the account name in a posting, that posting is
considered \f[I]virtual\f[], which means:
.IP \[bu] 2
it is ignored when checking that the transaction is balanced
.IP \[bu] 2
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\[aq]s opening balance without
needing to use the \f[C]equity:opening\ balances\f[] account:
.IP
.nf
\f[C]
1/1\ special\ unbalanced\ posting\ to\ set\ initial\ balance
\ \ (assets:checking)\ \ \ $1000
\f[]
.fi
.SS Balanced Virtual Postings
.PP
When the account name is bracketed, the posting is \f[I]balanced
virtual\f[], which is just like a virtual posting except the balanced
virtual postings in a transaction must balance to 0, like the real
postings (but separately from them).
Balanced virtual postings are also excluded by \f[C]\-\-real/\-R\f[] or
\f[C]real:1\f[].
.PP
Virtual postings are a feature inherited from Ledger can can
occasionally be useful, but they can be a crutch and you should think
twice or three times before using them.
You can almost always find an equivalent journal entry using two or more
real postings that will be more correct and more error\-proof.
.SH BALANCE ASSERTIONS
.PP
hledger supports ledger\-style balance assertions in journal files.
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
.nf
\f[C]
2013/1/1
\ \ a\ \ \ $1\ \ =$1
\ \ b\ \ \ \ \ \ \ =$\-1
2013/1/2
\ \ a\ \ \ $1\ \ =$2
\ \ b\ \ $\-1\ \ =$\-2
\f[]
.fi
.PP
After reading a journal file, hledger will check all balance assertions
and report an error if any of them fail.
Balance assertions can protect you from, eg, inadvertently disrupting
reconciled balances while cleaning up old entries.
You can disable them temporarily with the
\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for
troubleshooting or for reading Ledger files.
.SS Assertions and ordering
.PP
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.
(Also, Ledger assertions do not see the accumulated effect of repeated
postings to the same account within a transaction.)
.PP
So, hledger balance assertions keep working if you reorder
differently\-dated transactions within the journal.
But if you reorder same\-dated transactions or postings, assertions
might break and require updating.
This order dependence does bring an advantage: precise control over the
order of postings and assertions within a day, so you can assert
intra\-day balances.
.PP
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\[aq]s
balance on the same day, you\[aq]ll have to put the assertion in the
right file.
.SS Assertions and commodities
.PP
The asserted balance must be a simple single\-commodity amount, and in
fact the assertion checks only this commodity\[aq]s balance within the
(possibly multi\-commodity) account balance.
We could call this a partial balance assertion.
This is compatible with Ledger, and makes it possible to make assertions
about accounts containing multiple commodities.
.PP
To assert each commodity\[aq]s balance in such a multi\-commodity
account, you can add multiple postings (with amount 0 if necessary).
But note that no matter how many assertions you add, you can\[aq]t be
sure the account does not contain some unexpected commodity.
(We\[aq]ll add support for this kind of total balance assertion if
there\[aq]s demand.)
.SS Assertions and subaccounts
.PP
Balance assertions do not count the balance from subaccounts; they check
the posted account\[aq]s exclusive balance.
For example:
.IP
.nf
\f[C]
1/1
\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1
\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1
\ \ equity
\f[]
.fi
.PP
The balance report\[aq]s flat mode shows these exclusive balances more
clearly:
.IP
.nf
\f[C]
$\ hledger\ bal\ checking\ \-\-flat
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2
\f[]
.fi
.SS Assertions and virtual postings
.PP
Balance assertions are checked against all postings, both real and
virtual.
They are not affected by the \f[C]\-\-real/\-R\f[] flag or
\f[C]real:\f[] query.
.SH PRICES
.SS Transaction prices
.PP
When recording a transaction, you can also record an amount\[aq]s price
in another commodity.
This documents the exchange rate, cost (of a purchase), or selling price
(of a sale) that was in effect within this particular transaction (or
more precisely, within the particular posting).
These transaction prices are fixed, and do not change.
.PP
Such priced amounts can be displayed in their transaction price\[aq]s
commodity, by using the \f[C]\-\-cost/\-B\f[] flag (B for "cost Basis"),
supported by most hledger commands.
.PP
There are three ways to specify a transaction price:
.IP "1." 3
Write the unit price (aka exchange rate), as \f[C]\@\ UNITPRICE\f[]
after the amount:
.RS 4
.IP
.nf
\f[C]
2009/1/1
\ \ assets:foreign\ currency\ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ at\ $1.35\ each
\ \ assets:cash
\f[]
.fi
.RE
.IP "2." 3
Or write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount:
.RS 4
.IP
.nf
\f[C]
2009/1/1
\ \ assets:foreign\ currency\ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ at\ $135\ for\ the\ lot
\ \ assets:cash
\f[]
.fi
.RE
.IP "3." 3
Or let hledger infer the price so as to balance the transaction.
To permit this, you must fully specify all posting amounts, and their
sum must have a non\-zero amount in exactly two commodities:
.RS 4
.IP
.nf
\f[C]
2009/1/1
\ \ assets:foreign\ currency\ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ exchanged\ for\ $135
\f[]
.fi
.RE
.PP
With any of the above examples we get:
.IP
.nf
\f[C]
$\ hledger\ print\ \-B
2009/01/01
\ \ \ \ assets:foreign\ currency\ \ \ \ \ \ \ $135.00
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135.00
\f[]
.fi
.PP
Example use for transaction prices: recording the effective conversion
rate of purchases made in a foreign currency.
.SS Market prices
.PP
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities, usually from some
public market which publishes such rates.
.PP
When market prices are known, the \f[C]\-V/\-\-value\f[] option will use
them to convert reported amounts to their market value as of the report
end date.
This option is currently available only with the balance command.
.PP
You record market prices (Ledger calls them historical prices) with a P
directive, in the journal or perhaps in a separate included file.
Market price directives have the format:
.IP
.nf
\f[C]
P\ DATE\ COMMODITYSYMBOL\ UNITPRICE
\f[]
.fi
.PP
For example, the following directives say that the euro\[aq]s exchange
rate was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and
unknown before 2009).
.IP
.nf
\f[C]
P\ 2009/1/1\ €\ $1.35
P\ 2010/1/1\ €\ $1.40
\f[]
.fi
.PP
Example use for market prices: tracking the value of stocks.
.SH COMMENTS
.PP
Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash
(\f[C]#\f[]) or asterisk (\f[C]*\f[]) are comments, and will be ignored.
(Asterisk comments make it easy to treat your journal like an org\-mode
outline in emacs.)
.PP
Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[]
directives is a (multi\-line) comment.
If there is no \f[C]end\ comment\f[], the comment extends to the end of
the file.
.PP
You can attach comments to a transaction by writing them after the
description 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.
.PP
Some examples:
.IP
.nf
\f[C]
#\ a\ journal\ comment
;\ also\ a\ journal\ comment
comment
This\ is\ a\ multiline\ comment,
which\ continues\ until\ a\ line
where\ the\ "end\ comment"\ string
appears\ on\ its\ own.
end\ comment
2012/5/14\ something\ \ ;\ a\ transaction\ comment
\ \ \ \ ;\ the\ transaction\ comment,\ continued
\ \ \ \ posting1\ \ 1\ \ ;\ a\ comment\ for\ posting\ 1
\ \ \ \ posting2
\ \ \ \ ;\ a\ comment\ for\ posting\ 2
\ \ \ \ ;\ another\ comment\ line\ for\ posting\ 2
;\ a\ journal\ comment\ (because\ not\ indented)
\f[]
.fi
.SH TAGS
.PP
A \f[I]tag\f[] is a word followed by a full colon inside a transaction
or posting comment.
You can write multiple tags, comma separated.
Eg: \f[C];\ a\ comment\ containing\ sometag:,\ anothertag:\f[].
You can search for tags with the \f[C]tag:\f[] query.
.PP
A tag can also have a value, which is any text between the colon and the
next comma or newline, excluding leading/trailing whitespace.
(So hledger tag values can not contain commas or newlines).
.PP
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
third\-tag) and the posting has four (A, TAG2, third\-tag,
posting\-tag):
.IP
.nf
\f[C]
1/1\ a\ transaction\ \ ;\ A:,\ TAG2:
\ \ \ \ ;\ third\-tag:\ a\ third\ transaction\ tag,\ this\ time\ with\ a\ value
\ \ \ \ (a)\ \ $1\ \ ;\ posting\-tag:
\f[]
.fi
.PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are always simple strings.
.SH DIRECTIVES
.SS Account aliases
.PP
You can define aliases which rewrite your account names (after reading
the journal, before generating reports).
hledger\[aq]s account aliases can be useful for:
.IP \[bu] 2
expanding shorthand account names to their full form, allowing easier
data entry and a less verbose journal
.IP \[bu] 2
adapting old journals to your current chart of accounts
.IP \[bu] 2
experimenting with new account organisations, like a new hierarchy or
combining two accounts into one
.IP \[bu] 2
customising reports
.PP
See also How to use account aliases.
.SS Basic aliases
.PP
To set an account alias, use the \f[C]alias\f[] 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:
.IP
.nf
\f[C]
alias\ OLD\ =\ NEW
\f[]
.fi
.PP
Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the
command line.
This affects all entries.
It\[aq]s useful for trying out aliases interactively.
.PP
OLD and NEW are full account names.
hledger will replace any occurrence of the old account name with the new
one.
Subaccounts are also affected.
Eg:
.IP
.nf
\f[C]
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"
\f[]
.fi
.SS Regex aliases
.PP
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes.
(This was the default behaviour in hledger 0.24\-0.25):
.IP
.nf
\f[C]
alias\ /REGEX/\ =\ REPLACEMENT
\f[]
.fi
.PP
or \f[C]\-\-alias\ \[aq]/REGEX/=REPLACEMENT\[aq]\f[].
.PP
REGEX is a case\-insensitive regular expression.
Anywhere it matches inside an account name, the matched part will be
replaced by REPLACEMENT.
If REGEX contains parenthesised match groups, these can be referenced by
the usual numeric backreferences in REPLACEMENT.
Note, currently regular expression aliases may cause noticeable
slow\-downs.
(And if you use Ledger on your hledger file, they will be ignored.) Eg:
.IP
.nf
\f[C]
alias\ /^(.+):bank:([^:]+)(.*)/\ =\ \\1:\\2\ \\3
#\ rewrites\ "assets:bank:wells\ fargo:checking"\ to\ \ "assets:wells\ fargo\ checking"
\f[]
.fi
.SS Multiple aliases
.PP
You can define as many aliases as you like using directives or
command\-line options.
Aliases are recursive \- each alias sees the result of applying previous
ones.
(This is different from Ledger, where aliases are non\-recursive by
default).
Aliases are applied in the following order:
.IP "1." 3
alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
.IP "2." 3
alias options, in the order they appear on the command line
.SS end aliases
.PP
You can clear (forget) all currently defined aliases with the
\f[C]end\ aliases\f[] directive:
.IP
.nf
\f[C]
end\ aliases
\f[]
.fi
.SS Multi\-line comments
.PP
A line containing just \f[C]comment\f[] starts a multi\-line comment,
and a line containing just \f[C]end\ comment\f[] ends it.
See comments.
.SS Default commodity
.PP
You can set a default commodity, to be used for amounts without one.
Use the D directive with a sample amount.
The commodity (and the sample amount\[aq]s display style) will be
applied to all subsequent commodity\-less amounts, up to the next D
directive.
(Note this is different from Ledger\[aq]s default commodity directive.)
.PP
Also note the directive itself does not influence the commodity\[aq]s
default display style, but the amount it is applied to might.
Here\[aq]s an example:
.IP
.nf
\f[C]
;\ set\ £\ as\ the\ default\ commodity
D\ £1,000.00
2010/1/1
\ \ a\ \ 2340
\ \ b
2014/1/1
\ \ c\ \ £1000
\ \ d
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ print
2010/01/01
\ \ \ \ a\ \ \ \ \ £2,340.00
\ \ \ \ b\ \ \ \ £\-2,340.00
2014/01/01
\ \ \ \ c\ \ \ \ \ £1,000.00
\ \ \ \ d\ \ \ \ £\-1,000.00
\f[]
.fi
.SS Default parent account
.PP
You can specify a parent account which will be prepended to all accounts
within a section of the journal.
Use the \f[C]account\f[] directive like so:
.IP
.nf
\f[C]
account\ home
2010/1/1
\ \ \ \ food\ \ \ \ $10
\ \ \ \ cash
end
\f[]
.fi
.PP
If \f[C]end\f[] is omitted, the effect lasts to the end of the file.
The above is equivalent to:
.IP
.nf
\f[C]
2010/01/01
\ \ \ \ home:food\ \ \ \ \ \ \ \ \ \ \ $10
\ \ \ \ home:cash\ \ \ \ \ \ \ \ \ \ $\-10
\f[]
.fi
.PP
Included files are also affected, eg:
.IP
.nf
\f[C]
account\ business
include\ biz.journal
end
account\ personal
include\ personal.journal
end
\f[]
.fi
.SS Default year
.PP
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
.nf
\f[C]
Y2009\ \ \ \ \ \ ;\ set\ default\ year\ to\ 2009
12/15\ \ \ \ \ \ ;\ equivalent\ to\ 2009/12/15
\ \ expenses\ \ 1
\ \ assets
Y2010\ \ \ \ \ \ ;\ change\ default\ year\ to\ 2010
2009/1/30\ \ ;\ specifies\ the\ year,\ not\ affected
\ \ expenses\ \ 1
\ \ assets
1/31\ \ \ \ \ \ \ ;\ equivalent\ to\ 2010/1/31
\ \ expenses\ \ 1
\ \ assets
\f[]
.fi
.SS Including other files
.PP
You can pull in the content of additional journal files by writing an
include directive, like this:
.IP
.nf
\f[C]
include\ path/to/file.journal
\f[]
.fi
.PP
If the path does not begin with a slash, it is relative to the current
file.
.PP
The \f[C]include\f[] directive may only be used in journal files, and
currently it may only include other journal files (eg, not CSV or
timelog files.)
.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org.
.SH AUTHORS
Simon Michael <simon@joyful.com>
.SH COPYRIGHT
Copyright (C) 2007-2015 Simon Michael.
.br
Released under GNU GPLv3+.
.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
.br
hledger_csv(5), hledger_journal(5), hledger_timelog(5)
For more information, see http://hledger.org.

666
hledger-lib/hledger_journal.5.md Normal file
View File

@ -0,0 +1,666 @@
% hledger_journal(5)
%
% October 2015
# NAME
hledger_journal - reference for hledger's journal file format
# 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](http://en.wikipedia.org/wiki/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](faq.html#file-format-differences),
of [ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format),
so hledger can work with [compatible](faq.html#file-format-differences) 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.
You can use hledger without learning any more about this file;
just use the [add](#add) or [web](#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.
Here's an example:
```journal
; A sample journal file. This is a comment.
2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description
assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name
income:salary $-1 ; followed by at least two spaces and an amount
2008/06/01 gift
assets:bank:checking $1 ; <- at least two postings in a transaction
income:gifts $-1 ; <- their amounts must balance to 0
2008/06/02 save
assets:bank:saving $1
assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred
2008/06/03 eat & shop ; <- description can be anything
expenses:food $1
expenses:supplies $1 ; <- this transaction debits two expense accounts
assets:cash ; <- $-2 inferred
2008/12/31 * pay off ; <- an optional * or ! after the date means "cleared" (or anything you want)
liabilities:debts $1
assets:bank:checking
```
Now let's explore the available journal file syntax in detail.
# Transactions
Transactions are represented by journal entries. Each begins with a
[simple date](#simple-dates) in column 0, followed by three optional
fields with spaces between them:
- a status flag, which can be empty or `!` or `*` (meaning "uncleared", "pending" and "cleared", or whatever you want)
- a transaction code (eg a check number),
- and/or a description
then some number of postings, of some amount to some account, each on
its own line. Usually there are at least two postings, though one or
even none is possible.
The ([real](#virtual-postings)) posting amounts within a transaction
must always balance, ie add up to 0. Optionally one amount can be
left blank, in which case it will be inferred.
# Dates
## Simple dates
Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
Leading zeroes are optional.
The year may be omitted, in which case it defaults to the current
year, or you can set the default year with a
[default year directive](#default-year).
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 date
you write a cheque, and the date it clears in your bank. When you want to
model this, eg for more accurate balances, write both dates 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 specified
(For Ledger compatibility, `--aux-date` or `--effective` also work.)
Their meaning 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
primary date if unspecified.
```journal
2010/2/23=2/19 movie ticket
expenses:cinema $10
assets:checking
```
<div style="clear:both;"></div>
```{.shell}
$ hledger register checking
2010/02/23 movie ticket assets:checking $-10 $-10
```
<div style="clear:both;"></div>
```{.shell}
$ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10
```
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. Arguably they are now obsolete,
superseded by...
## Posting dates
You can give individual postings a different date from their parent
transaction, by adding a [posting tag](#tags) (see below) like
`date:DATE`, where DATE is a [simple date](#simple-dates). 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 easy bank reconciliation:
``` {.journal}
2015/5/30
expenses:food $10 ; food purchased on saturday 5/30
assets:checking ; bank cleared it on monday, date:6/1
```
<div style="clear:both;"></div>
```{.shell}
$ hledger -f tt.j register food
2015/05/30 expenses:food $10 $10
```
<div style="clear:both;"></div>
```{.shell}
$ hledger -f tt.j register checking
2015/06/01 assets:checking $-10 $-10
```
A posting date will use the year of the transaction date if unspecified.
You can also set the secondary date, with `date2:DATE2`.
For compatibility, Ledger's older posting date syntax is also
supported: `[DATE]`, `[DATE=DATE2]` or `[=DATE2]` in a posting
comment.
When using any of these forms, be sure to provide a valid simple date
or you'll get a parse error. Eg a `date:` tag with no value is not
allowed.
# 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-level
accounts: `assets`, `liabilities`, `income`, `expenses`, and `equity`.
Account names may contain single spaces, eg: `assets:accounts receivable`.
Because of this, they must always be followed by at least two spaces (or newline).
Account names can be [aliased](#account-aliases).
# Amounts
After the account name, there is usually an amount.
Important: between account name and amount, there must be **two or more** spaces.
The amount is a number, optionally with a currency symbol or commodity name on either the left or right.
Negative amounts may have the minus sign either before or after the currency symbol (`-$1` or `$-1`).
Commodity names which contain more than just letters should be enclosed in double quotes (`1 "person hours"`).
## Decimal points and digit groups
hledger supports flexible decimal point and digit group separator styles,
to support international variations. Numbers can use either a period (`.`)
or a comma (`,`) as decimal point. They can also have digit group
separators at any position (eg thousands separators) which can be comma or
period - whichever one you did not use as a decimal point. If you use
digit group separators, you must also include a decimal point in at least
one number in the same commodity, so that hledger knows which character is
which. Eg, write `$1,000.00` or `$1.000,00`.
## Amount display styles
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that
commodity. Amount styles include:
- the position (left or right) and spacing (space or no separator) of the commodity symbol
- the digit group separator character (comma or period) and digit group sizes, if any
- the decimal point character (period or comma)
- the display precision (number of decimal places displayed)
The canonical style is generally the style of the first posting amount seen in a commodity.
However the display precision will be the highest precision seen in all posting amounts in that commmodity.
The precisions used in a price amount, or a D directive, don't affect the canonical display precision directly, but they can affect it 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 (actually this last case does not influence the canonical display precision but probably should).
# Virtual Postings
When you parenthesise the account name in a posting, that posting is considered *virtual*, which
means:
- it is ignored when checking that the transaction is balanced
- it is excluded from reports when the `--real/-R` flag is used, or the `real:1` query.
You could use this, eg, to set an account's opening balance without needing to use the
`equity:opening balances` account:
```journal
1/1 special unbalanced posting to set initial balance
(assets:checking) $1000
```
## Balanced Virtual Postings
When the account name is bracketed, the posting is *balanced virtual*, which is just like a virtual posting except the balanced virtual postings in a transaction must balance to 0, like the real postings (but separately from them). Balanced virtual postings are also excluded by `--real/-R` or `real:1`.
Virtual postings are a feature inherited from Ledger can can occasionally be useful, but they can be a crutch and you should think twice or three times before using them. You can almost always find an equivalent journal entry using two or more real postings that will be more correct and more error-proof.
# Balance Assertions
hledger supports ledger-style
[balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions)
in journal files.
These look like `=EXPECTEDBALANCE` following a posting's amount. Eg in
this example we assert the expected dollar balance in accounts a and b after
each posting:
``` {.journal}
2013/1/1
a $1 =$1
b =$-1
2013/1/2
a $1 =$2
b $-1 =$-2
```
After reading a journal file, hledger will check all balance
assertions and report an error if any of them fail. Balance assertions
can protect you from, eg, inadvertently disrupting reconciled balances
while cleaning up old entries. You can disable them temporarily with
the `--ignore-assertions` flag, which can be useful for
troubleshooting or for reading Ledger files.
## Assertions and ordering
hledger sorts an account'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. (Also, Ledger assertions do not see the accumulated effect of
repeated postings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder
differently-dated transactions within the journal. But if you reorder
same-dated transactions or postings, assertions might break and require
updating. This order dependence does bring an advantage: precise
control over the order of postings and assertions within a day, so you
can assert intra-day balances.
With [included files](#including-other-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.
## Assertions and commodities
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a
partial balance assertion. This is compatible with Ledger, and makes
it possible to make assertions about accounts containing multiple
commodities.
To assert each commodity's balance in such a multi-commodity account,
you can add multiple postings (with amount 0 if necessary). But note
that no matter how many assertions you add, you can't be sure the
account does not contain some unexpected commodity. (We'll add support
for this kind of total balance assertion if there's demand.)
## Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they check
the posted account's exclusive balance. For example:
``` {.journal}
1/1
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
equity
```
The balance report's flat mode shows these exclusive balances more clearly:
```shell
$ hledger bal checking --flat
1 checking
1 checking:fund
--------------------
2
```
### Assertions and virtual postings
Balance assertions are checked against all postings, both real and
[virtual](#virtual-postings). They are not affected by the `--real/-R`
flag or `real:` query.
# Prices
## Transaction prices
When recording a transaction, you can also record an amount's price in another commodity.
This documents the exchange rate, cost (of a purchase), or selling price (of a sale) that was in effect within this particular transaction (or more precisely, within the particular posting).
These transaction prices are fixed, and do not change.
Such priced amounts can be displayed in their transaction price's
commodity, by using the `--cost/-B` flag (B for "cost Basis"),
supported by most hledger commands.
There are three ways to specify a transaction price:
1. Write the unit price (aka exchange rate), as `@ UNITPRICE` after the amount:
```journal
2009/1/1
assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each
assets:cash
```
2. Or write the total price, as `@@ TOTALPRICE` after the amount:
```journal
2009/1/1
assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot
assets:cash
```
3. Or let hledger infer the price so as to balance the transaction.
To permit this, you must fully specify all posting amounts, and
their sum must have a non-zero amount in exactly two commodities:
```journal
2009/1/1
assets:foreign currency €100 ; one hundred euros
assets:cash $-135 ; exchanged for $135
```
With any of the above examples we get:
```shell
$ hledger print -B
2009/01/01
assets:foreign currency $135.00
assets:cash $-135.00
```
Example use for transaction prices: recording the effective conversion
rate of purchases made in a foreign currency.
## Market prices
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities, usually from some
public market which publishes such rates.
When market prices are known, the `-V/--value` option will use them to
convert reported amounts to their market value as of the report end
date. This option is currently available only with the
[balance](#balance) command.
You record market prices (Ledger calls them historical prices) with a
P directive, in the journal or perhaps in a separate
[included](#including-other-files) file. Market price directives have
the format:
```journal
P DATE COMMODITYSYMBOL UNITPRICE
```
<!-- (A time and numeric time zone are allowed but ignored, like ledger.) -->
For example, the following directives say that the euro's exchange rate was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and unknown before 2009).
```journal
P 2009/1/1 € $1.35
P 2010/1/1 € $1.40
```
Example use for market prices: tracking the value of stocks.
<!--
This is different from Ledger, where transaction prices fluctuate by
default. Ledger has a different syntax for specifying
[fixed prices](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices):
`{=PRICE}`. hledger parses that syntax, and (currently) ignores it.
-->
<!-- hledger treats this as an alternate spelling of `@ PRICE`, for greater compatibility with Ledger files. -->
# Comments
Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or
asterisk (`*`) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.)
Also, anything between [`comment` and `end comment` directives](#multi-line-comments) is a (multi-line) comment.
If there is no `end comment`, the comment extends to the end of the file.
You can attach comments to a transaction by writing them after the
description 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.
Some examples:
```journal
# a journal comment
; also a journal comment
comment
This is a multiline comment,
which continues until a line
where the "end comment" string
appears on its own.
end comment
2012/5/14 something ; a transaction comment
; the transaction comment, continued
posting1 1 ; a comment for posting 1
posting2
; a comment for posting 2
; another comment line for posting 2
; a journal comment (because not indented)
```
# Tags
A *tag* is a word followed by a full colon inside a transaction or
posting [comment](#comments). You can write multiple tags, comma
separated. Eg: `; a comment containing sometag:, anothertag:`. You can search for tags
with the [`tag:` query](manual#queries).
A tag can also have a value, which is any text between the colon and
the next comma or newline, excluding leading/trailing whitespace.
(So hledger tag values can not contain commas or newlines).
Tags in a transaction comment affect the transaction and all of its postings,
while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third-tag)
and the posting has four (A, TAG2, third-tag, posting-tag):
``` {.journal}
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, this time with a value
(a) $1 ; posting-tag:
```
Tags are like Ledger's
[metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
feature, except hledger's tag values are always simple strings.
# Directives
## Account aliases
You can define aliases which rewrite your account names (after reading the journal,
before generating reports). hledger's account aliases can be useful for:
- expanding shorthand account names to their full form, allowing easier data entry and a less verbose journal
- adapting old journals to your current chart of accounts
- experimenting with new account organisations, like a new hierarchy or combining two accounts into one
- customising reports
See also [How to use account aliases](how-to-use-account-aliases.html).
### 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
[included files](#including-other-files).
The spaces around the = are optional:
``` {.journal}
alias OLD = NEW
```
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 full account names.
hledger will replace any occurrence of the old account name with the
new one. Subaccounts are also affected. Eg:
``` {.journal}
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"
```
### Regex aliases
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. (This was the default behaviour in hledger 0.24-0.25):
``` {.journal}
alias /REGEX/ = REPLACEMENT
```
or `--alias '/REGEX/=REPLACEMENT'`.
<!-- (Can also be written `'/REGEX/REPLACEMENT/'`). -->
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by
REPLACEMENT.
If REGEX contains parenthesised match groups, these can be referenced
by the usual numeric backreferences in REPLACEMENT.
Note, currently regular expression aliases may cause noticeable slow-downs.
(And if you use Ledger on your hledger file, they will be ignored.)
Eg:
``` {.journal}
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
```
### Multiple aliases
You can define as many aliases as you like using directives or command-line options.
Aliases are recursive - each alias sees the result of applying previous ones.
(This is different from Ledger, where aliases are non-recursive by default).
Aliases are applied in the following order:
1. alias directives, most recently seen first (recent directives take precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
### end aliases
You can clear (forget) all currently defined aliases with the `end aliases` directive:
``` {.journal}
end aliases
```
## Multi-line comments
A line containing just `comment` starts a multi-line comment, and a
line containing just `end comment` ends it. See [comments](#comments).
## Default commodity
You can set a default commodity, to be used for amounts without one.
Use the D directive with a sample amount.
The commodity (and the sample amount's display style) will be applied to all subsequent commodity-less amounts, up to the next D directive.
(Note this is different from Ledger's default commodity directive.)
Also note the directive itself does not influence the commodity's default
[display style](#amount-display-styles), but the amount it is
applied to might. Here's an example:
```journal
; set £ as the default commodity
D £1,000.00
2010/1/1
a 2340
b
2014/1/1
c £1000
d
```
```{.shell}
$ hledger print
2010/01/01
a £2,340.00
b £-2,340.00
2014/01/01
c £1,000.00
d £-1,000.00
```
## Default parent account
You can specify a parent account which will be prepended to all accounts
within a section of the journal. Use the `account` directive like so:
``` {.journal}
account home
2010/1/1
food $10
cash
end
```
If `end` is omitted, the effect lasts to the end of the file.
The above is equivalent to:
``` {.journal}
2010/01/01
home:food $10
home:cash $-10
```
Included files are also affected, eg:
``` {.journal}
account business
include biz.journal
end
account personal
include personal.journal
end
```
## Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with `Y` followed by the year. Eg:
``` {.journal}
Y2009 ; set default year to 2009
12/15 ; equivalent to 2009/12/15
expenses 1
assets
Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected
expenses 1
assets
1/31 ; equivalent to 2010/1/31
expenses 1
assets
```
## Including other files
You can pull in the content of additional journal files by writing an
include directive, like this:
``` {.journal}
include path/to/file.journal
```
If the path does not begin with a slash, it is relative to the current file.
The `include` directive may only be used in journal files, and currently
it may only include other journal files (eg, not CSV or timelog files.)

99
hledger-lib/hledger_timelog.5 Normal file
View File

@ -0,0 +1,99 @@
.TH "hledger_timelog" "5" "October 2015" "" "hledger User Manuals"
.SH NAME
.PP
hledger_timelog \- hledger\[aq]s timelog file format
.SH DESCRIPTION
.PP
hledger can read timelog files.
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 (also, default year directives work).
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).
.IP
.nf
\f[C]
i\ 2015/03/30\ 09:00:00\ some:account\ name\ \ optional\ description\ after\ two\ spaces
o\ 2015/03/30\ 09:20:00
i\ 2015/03/31\ 22:21:45\ another\ account
o\ 2015/04/01\ 02:00:34
\f[]
.fi
.PP
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, \f[C]hledger\ print\f[] generates these journal
entries:
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.timelog\ print
2015/03/30\ *\ optional\ description\ after\ two\ spaces
\ \ \ \ (some:account\ name)\ \ \ \ \ \ \ \ \ 0.33h
2015/03/31\ *\ 22:21\-23:59
\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 1.64h
2015/04/01\ *\ 00:00\-02:00
\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 2.01h
\f[]
.fi
.PP
Here is a sample.timelog to download and some queries to try:
.IP
.nf
\f[C]
$\ hledger\ \-f\ sample.timelog\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ current\ time\ balances
$\ hledger\ \-f\ sample.timelog\ register\ \-p\ 2009/3\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ sessions\ in\ march\ 2009
$\ hledger\ \-f\ sample.timelog\ register\ \-p\ weekly\ \-\-depth\ 1\ \-\-empty\ \ #\ time\ summary\ by\ week
\f[]
.fi
.PP
To generate time logs, ie to clock in and clock out, you could:
.IP \[bu] 2
use emacs and the built\-in timeclock.el, or the extended
timeclock\-x.el and perhaps the extras in ledgerutils.el
.IP \[bu] 2
at the command line, use these bash aliases:
.RS 2
.IP
.nf
\f[C]
alias\ ti="echo\ i\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ \\$*\ >>$TIMELOG"
alias\ to="echo\ o\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ >>$TIMELOG"
\f[]
.fi
.RE
.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 "timeclock" executable which I think is just the ledger
2 executable renamed.
.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org.
.SH AUTHORS
Simon Michael <simon@joyful.com>
.SH COPYRIGHT
Copyright (C) 2007-2015 Simon Michael.
.br
Released under GNU GPLv3+.
.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
.br
hledger_csv(5), hledger_journal(5), hledger_timelog(5)
For more information, see http://hledger.org.

68
hledger-lib/hledger_timelog.5.md Normal file
View File

@ -0,0 +1,68 @@
% hledger_timelog(5)
%
% October 2015
# NAME
hledger_timelog - hledger's timelog file format
# DESCRIPTION
hledger can read timelog files.
[As with Ledger](http://ledger-cli.org/3.0/doc/ledger3.html#Time-Keeping),
these are (a subset of)
[timeclock.el](http://www.emacswiki.org/emacs/TimeClock)'s format,
containing clock-in and clock-out entries as in the example below.
The date is a [simple date](#simple-dates) (also, [default year directives](#default-year) work).
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).
```timelog
i 2015/03/30 09:00:00 some:account name optional description after two spaces
o 2015/03/30 09:20:00
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
the above time log, `hledger print` generates these journal entries:
``` {.shell}
$ hledger -f t.timelog print
2015/03/30 * optional description after two spaces
(some:account name) 0.33h
2015/03/31 * 22:21-23:59
(another account) 1.64h
2015/04/01 * 00:00-02:00
(another account) 2.01h
```
Here is a
[sample.timelog](https://raw.github.com/simonmichael/hledger/master/data/sample.timelog) to
download and some queries to try:
```shell
$ hledger -f sample.timelog balance # current time balances
$ hledger -f sample.timelog register -p 2009/3 # sessions in march 2009
$ hledger -f sample.timelog register -p weekly --depth 1 --empty # time summary by week
```
To generate time logs, ie to clock in and clock out, you could:
- use emacs and the built-in timeclock.el, or
the extended [timeclock-x.el](http://www.emacswiki.org/emacs/timeclock-x.el)
and perhaps the extras in [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el)
- 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 '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
```
- or use the old `ti` and `to` scripts in the [ledger 2.x repository](https://github.com/ledger/ledger/tree/maint/scripts).
These rely on a "timeclock" executable which I think is just the ledger 2 executable renamed.

204
hledger-ui/hledger-ui.1 Normal file
View File

@ -0,0 +1,204 @@
.TH "hledger\-ui" "1" "October 2015" "" "hledger User Manuals"
.SH NAME
.PP
hledger\-ui \- curses\-style interface for the hledger accounting tool
.SH SYNOPSIS
.PP
\f[C]hledger\-ui\ [OPTIONS]\ [QUERYARGS]\f[]
.PD 0
.P
.PD
\f[C]hledger\ ui\ \-\-\ [OPTIONS]\ [QUERYARGS]\f[]
.SH DESCRIPTION
.PP
hledger is a cross\-platform program for tracking money, time, or any
other commodity, using double\-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger\-ui is hledger\[aq]s curses\-style interface.
It reads a hledger journal file (~/.hledger.journal, $LEDGER_FILE, or
\-f FILE) and provides a simple full\-screen console interface for
viewing account balances and transactions.
It is simpler and more efficient for browsing than the hledger CLI, but
lighter and faster than hledger\-web.
.PP
The journal file is \f[C]~/.hledger.journal\f[], \f[C]$LEDGER_FILE\f[],
or another file specified with \-f.
For more about the format, see hledger(1) or hledger_journal(5).
.SH OPTIONS
.PP
Note: if invoking hledger\-ui as a hledger subcommand, write
\f[C]\-\-\f[] before options as shown above.
.PP
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
.TP
.B \f[C]\-\-flat\f[]
show full account names, unindented
.RS
.RE
.TP
.B \f[C]\-\-no\-elide\f[]
don\[aq]t compress empty parent accounts on one line
.RS
.RE
.TP
.B \f[C]\-\-register=ACCTREGEX\f[]
start in the (first) matched account\[aq]s register screen
.RS
.RE
.TP
.B \f[C]\-\-theme=default|terminal|greenterm\f[]
use this custom display theme
.RS
.RE
.TP
.B \f[C]\-V\ \-\-value\f[]
show amounts as their current market value in their default valuation
commodity (accounts screen only)
.RS
.RE
.TP
.B \f[C]\-h\ \-\-help\f[]
show help
.RS
.RE
.TP
.B \f[C]\-\-version\f[]
show version information
.RS
.RE
.SS hledger options:
.PP
The following common hledger options should also work:
.TP
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[]
use a different input file.
For stdin, use \-
.RS
.RE
.TP
.B \f[C]\-\-rules\-file=RULESFILE\f[]
Conversion rules file to use when reading CSV (default: FILE.rules)
.RS
.RE
.TP
.B \f[C]\-\-alias=OLD=NEW\f[]
display accounts named OLD as NEW
.RS
.RE
.TP
.B \f[C]\-\-ignore\-assertions\f[]
ignore any failing balance assertions in the journal
.RS
.RE
.TP
.B \f[C]\-\-debug=N\f[]
show debug output if N is 1\-9 (default: 0)
.RS
.RE
.TP
.B \f[C]\-b\ \-\-begin=DATE\f[]
include postings/txns on or after this date
.RS
.RE
.TP
.B \f[C]\-e\ \-\-end=DATE\f[]
include postings/txns before this date
.RS
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.RS
.RE
.TP
.B \f[C]\-C\ \-\-cleared\f[]
include only cleared postings/txns
.RS
.RE
.TP
.B \f[C]\-\-pending\f[]
include only pending postings/txns
.RS
.RE
.TP
.B \f[C]\-U\ \-\-uncleared\f[]
include only uncleared (and pending) postings/txns
.RS
.RE
.TP
.B \f[C]\-R\ \-\-real\f[]
include only non\-virtual postings
.RS
.RE
.TP
.B \f[C]\-\-depth=N\f[]
hide accounts/postings deeper than N
.RS
.RE
.TP
.B \f[C]\-E\ \-\-empty\f[]
show empty/zero things which are normally omitted
.RS
.RE
.TP
.B \f[C]\-B\ \-\-cost\f[]
show amounts in their cost price\[aq]s commodity
.RS
.RE
.SH ENVIRONMENT
.PP
\f[B]LEDGER_FILE\f[] sets the default journal file path.
If not set, it is \f[C]~/.hledger.journal\f[].
.PP
\f[B]COLUMNS\f[] sets the screen width to use (normally the full
terminal width).
.SH FILES
.PP
Reads data from a hledger journal file (\f[C]$LEDGER_FILE\f[] or
\f[C]~/.hledger.journal\f[] by default), or a CSV file plus associated
CSV rules file.
.SH BUGS
.PP
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward.
.PP
\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-ui can\[aq]t read from stdin).
.PP
\f[C]\-V\f[] doesn\[aq]t affect the register screen.
.PP
If you reload while in the register screen, when you return to the
accounts screen it will be showing old data, and pressing g again will
not reload it; you must adjust depth to force it (eg press 0).
.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org.
.SH AUTHORS
Simon Michael <simon@joyful.com>
.SH COPYRIGHT
Copyright (C) 2007-2015 Simon Michael.
.br
Released under GNU GPLv3+.
.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
.br
hledger_csv(5), hledger_journal(5), hledger_timelog(5)
For more information, see http://hledger.org.

134
hledger-ui/hledger-ui.1.md Normal file
View File

@ -0,0 +1,134 @@
% hledger-ui(1)
%
% October 2015
# NAME
hledger-ui - curses-style interface for the hledger accounting tool
# SYNOPSIS
`hledger-ui [OPTIONS] [QUERYARGS]`\
`hledger ui -- [OPTIONS] [QUERYARGS]`
# DESCRIPTION
hledger is a cross-platform program for tracking money, time, or any other commodity,
using double-entry accounting and a simple, editable file format.
hledger is inspired by and largely compatible with ledger(1).
hledger-ui is hledger's curses-style interface.
It reads a hledger journal file (~/.hledger.journal, $LEDGER_FILE, or -f FILE) and
provides a simple full-screen console interface for viewing account
balances and transactions. It is simpler and more efficient for
browsing than the hledger CLI, but lighter and faster than
hledger-web.
The journal file is `~/.hledger.journal`, `$LEDGER_FILE`, or another file specified with -f.
For more about the format, see hledger(1) or hledger_journal(5).
# OPTIONS
Note: if invoking hledger-ui as a hledger subcommand, write `--` before options as shown above.
Any QUERYARGS are interpreted as a hledger search query which filters the data.
`--flat`
: show full account names, unindented
`--no-elide`
: don't compress empty parent accounts on one line
`--register=ACCTREGEX`
: start in the (first) matched account's register screen
`--theme=default|terminal|greenterm`
: use this custom display theme
`-V --value`
: show amounts as their current market value in their default valuation commodity
(accounts screen only)
`-h --help`
: show help
`--version`
: show version information
## hledger options:
The following common hledger options should also work:
`-f FILE --file=FILE`
: use a different input file. For stdin, use -
`--rules-file=RULESFILE`
: Conversion rules file to use when reading CSV (default: FILE.rules)
`--alias=OLD=NEW`
: display accounts named OLD as NEW
`--ignore-assertions`
: ignore any failing balance assertions in the journal
`--debug=N`
: show debug output if N is 1-9 (default: 0)
`-b --begin=DATE`
: include postings/txns on or after this date
`-e --end=DATE`
: include postings/txns before this date
`-p --period=PERIODEXP`
: set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date`
: use postings/txns' secondary dates instead
`-C --cleared`
: include only cleared postings/txns
`--pending`
: include only pending postings/txns
`-U --uncleared`
: include only uncleared (and pending) postings/txns
`-R --real`
: include only non-virtual postings
`--depth=N`
: hide accounts/postings deeper than N
`-E --empty`
: show empty/zero things which are normally omitted
`-B --cost`
: show amounts in their cost price's commodity
# ENVIRONMENT
**LEDGER_FILE**
sets the default journal file path. If not set, it is `~/.hledger.journal`.
**COLUMNS**
sets the screen width to use (normally the full terminal width).
# FILES
Reads data from a hledger journal file (`$LEDGER_FILE` or
`~/.hledger.journal` by default), or a CSV file plus associated CSV
rules file.
# BUGS
The need to precede options with `--` when invoked from hledger is awkward.
`-f-` doesn't work (hledger-ui can't read from stdin).
`-V` doesn't affect the register screen.
If you reload while in the register screen, when you return to the
accounts screen it will be showing old data, and pressing g again will
not reload it; you must adjust depth to force it (eg press 0).

219
hledger-web/hledger-web.1 Normal file
View File

@ -0,0 +1,219 @@
.TH "hledger\-web" "1" "October 2015" "" "hledger User Manuals"
.SH NAME
.PP
hledger\-web \- web interface for the hledger accounting tool
.SH SYNOPSIS
.PP
\f[C]hledger\-web\ [OPTIONS]\f[]
.PD 0
.P
.PD
\f[C]hledger\ web\ \-\-\ [OPTIONS]\f[]
.SH DESCRIPTION
.PP
hledger is a cross\-platform program for tracking money, time, or any
other commodity, using double\-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger\-web is hledger\[aq]s web interface.
It starts a simple web application for browsing and adding transactions
in a hledger journal file, and also (unless started with \-\-server)
opens the app in a new web browser window if possible, and exits after
two minutes of inactivity.
.PP
hledger\-web 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.
.PP
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 should put it behind
a suitable web proxy.
As a small protection against data loss when running an unprotected
instance, it writes a numbered backup of the main journal file (only ?)
on every edit.
.PP
The journal file is \f[C]~/.hledger.journal\f[], \f[C]$LEDGER_FILE\f[],
or another file specified with \-f.
For more about the format, see hledger(1) or hledger_journal(5).
.SH OPTIONS
.PP
Note: if invoking hledger\-web as a hledger subcommand, write
\f[C]\-\-\f[] before options as shown above.
.TP
.B \f[C]\-\-server\f[]
disable browser\-opening and auto\-exit\-on\-idle, and log all requests
to stdout
.RS
.RE
.TP
.B \f[C]\-\-port=PORT\f[]
set the TCP port to listen on (default: 5000)
.RS
.RE
.TP
.B \f[C]\-\-base\-url=URL\f[]
set the base url (default: http://localhost:PORT).
You would change this when sharing over the network, or integrating
within a larger website.
.RS
.RE
.TP
.B \f[C]\-\-file\-url=URL\f[]
set the static files url (default: BASEURL/static).
hledger\-web normally serves static files itself, but if you wanted to
serve them from another server for efficiency, you would set the url
with this.
.RS
.RE
.TP
.B \f[C]\-h\ \-\-help\f[]
show help
.RS
.RE
.TP
.B \f[C]\-\-version\f[]
show version information
.RS
.RE
.SS hledger options:
.PP
The following common hledger options should also work:
.TP
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[]
use a different input file.
For stdin, use \-
.RS
.RE
.TP
.B \f[C]\-\-rules\-file=RULESFILE\f[]
Conversion rules file to use when reading CSV (default: FILE.rules)
.RS
.RE
.TP
.B \f[C]\-\-alias=OLD=NEW\f[]
display accounts named OLD as NEW
.RS
.RE
.TP
.B \f[C]\-\-ignore\-assertions\f[]
ignore any failing balance assertions in the journal
.RS
.RE
.TP
.B \f[C]\-\-debug=N\f[]
show debug output if N is 1\-9 (default: 0)
.RS
.RE
.TP
.B \f[C]\-b\ \-\-begin=DATE\f[]
include postings/txns on or after this date
.RS
.RE
.TP
.B \f[C]\-e\ \-\-end=DATE\f[]
include postings/txns before this date
.RS
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.RS
.RE
.TP
.B \f[C]\-C\ \-\-cleared\f[]
include only cleared postings/txns
.RS
.RE
.TP
.B \f[C]\-\-pending\f[]
include only pending postings/txns
.RS
.RE
.TP
.B \f[C]\-U\ \-\-uncleared\f[]
include only uncleared (and pending) postings/txns
.RS
.RE
.TP
.B \f[C]\-R\ \-\-real\f[]
include only non\-virtual postings
.RS
.RE
.TP
.B \f[C]\-\-depth=N\f[]
hide accounts/postings deeper than N
.RS
.RE
.TP
.B \f[C]\-E\ \-\-empty\f[]
show empty/zero things which are normally omitted
.RS
.RE
.TP
.B \f[C]\-B\ \-\-cost\f[]
show amounts in their cost price\[aq]s commodity
.RS
.RE
.SH ENVIRONMENT
.PP
\f[B]LEDGER_FILE\f[] sets the default journal file path.
If not set, it is \f[C]~/.hledger.journal\f[].
.SH FILES
.PP
Reads data from a hledger journal file (\f[C]$LEDGER_FILE\f[] or
\f[C]~/.hledger.journal\f[] by default), or a CSV file plus associated
CSV rules file.
.SH BUGS
.PP
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward.
.PP
\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-web can\[aq]t read from
stdin).
.PP
Query arguments and some applicable hledger options probably aren\[aq]t
supported.
.PP
Does not work in text\-mode browsers.
.PP
Does not work well on small screens.
.PP
The auto\-exit feature was added to avoid leaving stray processes, eg on
Windows.
It is not well tested.
.PP
If you start two instances on the same port, the second one will appear
to run normally, but you will be seeing pages served from the first one.
.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org.
.SH AUTHORS
Simon Michael <simon@joyful.com>
.SH COPYRIGHT
Copyright (C) 2007-2015 Simon Michael.
.br
Released under GNU GPLv3+.
.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
.br
hledger_csv(5), hledger_journal(5), hledger_timelog(5)
For more information, see http://hledger.org.

146
hledger-web/hledger-web.1.md Normal file
View File

@ -0,0 +1,146 @@
% hledger-web(1)
%
% October 2015
# NAME
hledger-web - web interface for the hledger accounting tool
# SYNOPSIS
`hledger-web [OPTIONS]`\
`hledger web -- [OPTIONS]`
# DESCRIPTION
hledger is a cross-platform program for tracking money, time, or any other commodity,
using double-entry accounting and a simple, editable file format.
hledger is inspired by and largely compatible with ledger(1).
hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions in a hledger journal
file, and also (unless started with --server) opens the app in a new
web browser window if possible, and exits after two minutes of
inactivity.
hledger-web 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.
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 should put it
behind a suitable web proxy. As a small protection against data loss
when running an unprotected instance, it writes a numbered backup of
the main journal file (only ?) on every edit.
The journal file is `~/.hledger.journal`, `$LEDGER_FILE`, or another file specified with -f.
For more about the format, see hledger(1) or hledger_journal(5).
# OPTIONS
Note: if invoking hledger-web as a hledger subcommand, write `--` before options as shown above.
`--server`
: disable browser-opening and auto-exit-on-idle, and log all requests to stdout
`--port=PORT`
: set the TCP port to listen on (default: 5000)
`--base-url=URL`
: set the base url (default: http://localhost:PORT).
You would change this when sharing over the network, or integrating within a larger website.
`--file-url=URL`
: set the static files url (default: BASEURL/static).
hledger-web normally serves static files itself, but if you wanted to
serve them from another server for efficiency, you would set the url with this.
`-h --help`
: show help
`--version`
: show version information
## hledger options:
The following common hledger options should also work:
`-f FILE --file=FILE`
: use a different input file. For stdin, use -
`--rules-file=RULESFILE`
: Conversion rules file to use when reading CSV (default: FILE.rules)
`--alias=OLD=NEW`
: display accounts named OLD as NEW
`--ignore-assertions`
: ignore any failing balance assertions in the journal
`--debug=N`
: show debug output if N is 1-9 (default: 0)
`-b --begin=DATE`
: include postings/txns on or after this date
`-e --end=DATE`
: include postings/txns before this date
`-p --period=PERIODEXP`
: set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date`
: use postings/txns' secondary dates instead
`-C --cleared`
: include only cleared postings/txns
`--pending`
: include only pending postings/txns
`-U --uncleared`
: include only uncleared (and pending) postings/txns
`-R --real`
: include only non-virtual postings
`--depth=N`
: hide accounts/postings deeper than N
`-E --empty`
: show empty/zero things which are normally omitted
`-B --cost`
: show amounts in their cost price's commodity
# ENVIRONMENT
**LEDGER_FILE**
sets the default journal file path. If not set, it is `~/.hledger.journal`.
# FILES
Reads data from a hledger journal file (`$LEDGER_FILE` or
`~/.hledger.journal` by default), or a CSV file plus associated CSV
rules file.
# BUGS
The need to precede options with `--` when invoked from hledger is awkward.
`-f-` doesn't work (hledger-web can't read from stdin).
Query arguments and some applicable hledger options probably aren't supported.
Does not work in text-mode browsers.
Does not work well on small screens.
The auto-exit feature was added to avoid leaving stray processes, eg on Windows.
It is not well tested.
If you start two instances on the same port, the second one will
appear to run normally, but you will be seeing pages served from the
first one.

699
hledger/hledger.1 Normal file
View File

@ -0,0 +1,699 @@
.TH "hledger" "1" "October 2015" "hledger 0.26.98" "hledger User Manuals"
.SH NAME
.PP
hledger \- a command\-line accounting tool
.SH SYNOPSIS
.PP
\f[C]hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [CMDARGS]\f[]
.PD 0
.P
.PD
\f[C]hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [CMDARGS]\f[]
.SH DESCRIPTION
.PP
hledger is a cross\-platform program for tracking money, time, or any
other commodity, using double\-entry accounting and a simple, editable
file format.
It is inspired by and largely compatible with ledger(1).
hledger aims to be a reliable, practical tool for daily use.
This man page is a quick reference and introduction; for more complete
docs, see http://hledger.org/manual.
.PP
This is hledger's command\-line interface (there are also curses and web
interfaces).
Its basic function is to read a plain text file describing financial
transactions (in accounting terms, a general journal) and print useful
reports on standard output, or export them as CSV.
hledger can also read CSV files, converting them semi\-automatically to
journal format.
Additionally, hledger lists other hledger\-* executables found in the
user's $PATH and can invoke them as subcommands.
.PP
The journal file is \f[C]~/.hledger.journal\f[] by default, or another
file path specified by \f[C]$LEDGER_FILE\f[].
You can also specify a file with \f[C]\-f\ FILE\f[], or standard input
with \f[C]\-f\-\f[].
.PP
Transactions are dated movements of money between two (or more) named
accounts, and are recorded with journal entries like this:
.IP
.nf
\f[C]
2015/10/16\ bought\ food
\ expenses:food\ \ \ \ \ \ \ \ \ \ $10
\ assets:cash
\f[]
.fi
.PP
For more about the format, see hledger_journal(5).
.PP
Most users use a text editor to edit the journal, usually with an editor
mode such as ledger\-mode for added convenience.
hledger's interactive add command is another way to record new
transactions.
hledger never changes existing transactions.
.PP
To get started, you can either save some entries like the above in
\f[C]~/.hledger.journal\f[], or run \f[C]hledger\ add\f[] and follow the
prompts.
Then try some commands like \f[C]hledger\ print\f[] or
\f[C]hledger\ balance\f[].
See COMMANDS and EXAMPLES below.
.SH OPTIONS
.PP
To see general help and the command list: \f[C]hledger\ \-\-help\f[] or
\f[C]hledger\f[]
.PP
To see all options available with a command:
\f[C]hledger\ COMMAND\ \-\-help\f[]
.PP
Except for the General options below, options must be written after
COMMAND, not before it.
.PP
Also, when invoking external add\-on commands, their options must be
written after a double hyphen.
(Or, you can invoke the external command directly.) Eg:
.IP
.nf
\f[C]
$\ hledger\ ui\ \-\-\ \-\-register\ cash
$\ hledger\-ui\ \-\-register\ cash
\f[]
.fi
.PP
Options and command arguments can be intermixed.
Arguments are usually interpreted as a search query which filters the
data, see QUERIES.
.SS General flags:
.PP
These can appear anywhere in the command line.
.TP
.B \f[C]\-h\ \-\-help\f[]
show general help or (after command) command help
.RS
.RE
.TP
.B \f[C]\-\-version\f[]
show version information
.RS
.RE
.TP
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[]
use a different input file.
For stdin, use \-
.RS
.RE
.TP
.B \f[C]\-\-rules\-file=RULESFILE\f[]
Conversion rules file to use when reading CSV (default: FILE.rules)
.RS
.RE
.TP
.B \f[C]\-\-alias=OLD=NEW\f[]
display accounts named OLD as NEW
.RS
.RE
.TP
.B \f[C]\-\-ignore\-assertions\f[]
ignore any failing balance assertions in the journal
.RS
.RE
.TP
.B \f[C]\-\-debug=N\f[]
: show debug output if N is 1\-9 (default: 0)
.RS
.RE
.SS Common reporting flags:
.PP
These are supported by most commands, where applicable.
They must be written after the command name.
Additional command\-specific flags are described in COMMANDS below.
.TP
.B \f[C]\-b\ \-\-begin=DATE\f[]
include postings/txns on or after this date
.RS
.RE
.TP
.B \f[C]\-e\ \-\-end=DATE\f[]
include postings/txns before this date
.RS
.RE
.TP
.B \f[C]\-D\ \-\-daily\f[]
multiperiod/multicolumn report by day
.RS
.RE
.TP
.B \f[C]\-W\ \-\-weekly\f[]
multiperiod/multicolumn report by week
.RS
.RE
.TP
.B \f[C]\-M\ \-\-monthly\f[]
multiperiod/multicolumn report by month
.RS
.RE
.TP
.B \f[C]\-Q\ \-\-quarterly\f[]
multiperiod/multicolumn report by quarter
.RS
.RE
.TP
.B \f[C]\-Y\ \-\-yearly\f[]
multiperiod/multicolumn report by year
.RS
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
.RS
.RE
.TP
.B \f[C]\-\-date2\ \-\-aux\-date\f[]
use postings/txns\[aq] secondary dates instead
.RS
.RE
.TP
.B \f[C]\-C\ \-\-cleared\f[]
include only cleared postings/txns
.RS
.RE
.TP
.B \f[C]\-\-pending\f[]
include only pending postings/txns
.RS
.RE
.TP
.B \f[C]\-U\ \-\-uncleared\f[]
include only uncleared (and pending) postings/txns
.RS
.RE
.TP
.B \f[C]\-R\ \-\-real\f[]
include only non\-virtual postings
.RS
.RE
.TP
.B \f[C]\-\-depth=N\f[]
hide accounts/postings deeper than N
.RS
.RE
.TP
.B \f[C]\-E\ \-\-empty\f[]
show empty/zero things which are normally omitted
.RS
.RE
.TP
.B \f[C]\-B\ \-\-cost\f[]
show amounts in their cost price\[aq]s commodity
.RS
.RE
.PP
If a reporting option is repeated, the last one takes precedence.
Eg \-p jan \-p feb is equivalent to \-p feb.
.SH COMMANDS
.PP
COMMAND selects one of hledger\[aq]s subcommands; omit it to list
available commands.
To save typing, some commands have a short form; any unique prefix also
works.
.PP
Here is a summary (see http://hledger.org/manual#commands for the full
command help):
.SS Data entry:
.SS add
.PP
prompt for transactions and add them to the journal.
.PP
This is the only hledger command that writes to the journal file.
It appends only, existing transactions are not changed.
.TP
.B \f[C]\-\-no\-new\-accounts\f[]
don\[aq]t allow creating new accounts; helps prevent typos when entering
account names
.RS
.RE
.SS Reporting:
.SS accounts
.PP
show account names
.TP
.B \f[C]\-\-tree\f[]
show short account names, as a tree
.RS
.RE
.TP
.B \f[C]\-\-flat\f[]
show full account names, as a list (default)
.RS
.RE
.TP
.B \f[C]\-\-drop=N\f[]
in flat mode: omit N leading account name parts
.RS
.RE
.SS activity
.PP
show an ascii barchart of posting counts per interval (default: daily)
.SS balance, bal
.PP
show accounts and balances
.TP
.B \f[C]\-\-tree\f[]
show short account names, as a tree
.RS
.RE
.TP
.B \f[C]\-\-flat\f[]
show full account names, as a list (default)
.RS
.RE
.TP
.B \f[C]\-\-drop=N\f[]
in flat mode: omit N leading account name parts
.RS
.RE
.TP
.B \f[C]\-\-format=LINEFORMAT\f[]
in single\-column balance reports: use this custom line format
.RS
.RE
.TP
.B \f[C]\-\-no\-elide\f[]
in tree mode: don\[aq]t squash boring parent accounts
.RS
.RE
.TP
.B \f[C]\-H\ \-\-historical\f[]
in multicolumn mode: show historical ending balances
.RS
.RE
.TP
.B \f[C]\-\-cumulative\f[]
in multicolumn mode: show accumulated ending balances
.RS
.RE
.TP
.B \f[C]\-A\ \-\-average\f[]
in multicolumn mode: show a row average column
.RS
.RE
.TP
.B \f[C]\-T\ \-\-row\-total\f[]
in multicolumn mode: show a row total column
.RS
.RE
.TP
.B \f[C]\-N\ \-\-no\-total\f[]
don\[aq]t show the final total row
.RS
.RE
.TP
.B \f[C]\-V\ \-\-value\f[]
show amounts as their current market value in their default valuation
commodity
.RS
.RE
.TP
.B \f[C]\-o\ FILE[.FMT]\ \-\-output\-file=FILE[.FMT]\f[]
write output to FILE instead of stdout.
A recognised FMT suffix influences the format.
.RS
.RE
.TP
.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[]
select the output format.
Supported formats: txt, csv.
.RS
.RE
.SS balancesheet, bs
.PP
show a balance sheet
.TP
.B \f[C]\-\-flat\f[]
show full account names, as a list (default)
.RS
.RE
.TP
.B \f[C]\-\-drop=N\f[]
in flat mode: omit N leading account name parts
.RS
.RE
.SS cashflow, cf
.PP
show a cashflow statement
.TP
.B \f[C]\-\-flat\f[]
show full account names, as a list (default)
.RS
.RE
.TP
.B \f[C]\-\-drop=N\f[]
in flat mode: omit N leading account name parts
.RS
.RE
.SS incomestatement, is
.PP
show an income statement
.TP
.B \f[C]\-\-flat\f[]
show full account names, as a list (default)
.RS
.RE
.TP
.B \f[C]\-\-drop=N\f[]
in flat mode: omit N leading account name parts
.RS
.RE
.SS print
.PP
show transactions from the journal
.TP
.B \f[C]\-m\ STR\ \-\-match=STR\f[]
show the transaction whose description is most similar to STR, and is
most recent
.RS
.RE
.TP
.B \f[C]\-o\ FILE[.FMT]\ \-\-output\-file=FILE[.FMT]\f[]
write output to FILE instead of stdout.
A recognised FMT suffix influences the format.
.RS
.RE
.TP
.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[]
select the output format.
Supported formats: txt, csv.
.RS
.RE
.SS register, reg
.PP
show postings and running total
.TP
.B \f[C]\-H\ \-\-historical\f[]
include prior postings in the running total
.RS
.RE
.TP
.B \f[C]\-A\ \-\-average\f[]
show a running average instead of the running total (implies \-\-empty)
.RS
.RE
.TP
.B \f[C]\-r\ \-\-related\f[]
show postings\[aq] siblings instead
.RS
.RE
.TP
.B \f[C]\-w\ N\ \-\-width=N\f[]
set output width (default: terminal width or COLUMNS.
\-wN,M sets description width as well)
.RS
.RE
.TP
.B \f[C]\-o\ FILE[.FMT]\ \-\-output\-file=FILE[.FMT]\f[]
write output to FILE instead of stdout.
A recognised FMT suffix influences the format.
.RS
.RE
.TP
.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[]
select the output format.
Supported formats: txt, csv.
.RS
.RE
.SS stats
.PP
show some journal statistics
.TP
.B \f[C]\-o\ FILE[.FMT]\ \-\-output\-file=FILE[.FMT]\f[]
write output to FILE instead of stdout.
A recognised FMT suffix influences the format.
.RS
.RE
.SS Add\-on commands:
.PP
Additional commands will be available when executables or scripts named
"\f[C]hledger\-\f[]CMD" are installed in the PATH.
These are often provided by a package of the same name, or you can make
your own custom scripts (haskell scripts can use hledger\-lib allowing
tight integration).
Some available add\-ons are:
.SS autosync
.PP
download OFX bank data and/or convert OFX to hledger journal format
.SS diff
.PP
show transactions present in one journal file but not another
.SS interest
.PP
generate interest transactions
.SS irr
.PP
calculate internal rate of return
.SS ui
.PP
curses\-style interface, see hledger\-ui(1)
.SS web
.PP
web interface, see hledger\-web(1)
.SH QUERIES
.PP
Most commands accept an optional query expression, written as arguments
after the command name, to filter the data by date, account name or
other criteria.
The syntax is similar to a web search: one or more space\-separated
search terms, quotes to enclose whitespace, optional prefixes to match
specific fields.
Multiple search terms are combined as follows:
.PP
All commands except print: show transactions/postings/accounts which
match (or negatively match)
.IP \[bu] 2
any of the description terms AND
.IP \[bu] 2
any of the account terms AND
.IP \[bu] 2
all the other terms.
.PP
The print command: show transactions which
.IP \[bu] 2
match any of the description terms AND
.IP \[bu] 2
have any postings matching any of the positive account terms AND
.IP \[bu] 2
have no postings matching any of the negative account terms AND
.IP \[bu] 2
match all the other terms.
.PP
The following kinds of search terms can be used:
.TP
.B \f[B]\f[C]REGEX\f[]\f[]
match account names by this regular expression
.RS
.RE
.TP
.B \f[B]\f[C]acct:REGEX\f[]\f[]
same as above
.RS
.RE
.TP
.B \f[B]\f[C]amt:N,\ amt:<N,\ amt:<=N,\ amt:>N,\ amt:>=N\f[]\f[]
match postings with a single\-commodity amount that is equal to, less
than, or greater than N.
(Multi\-commodity amounts are not tested, and will always match.) The
comparison has two modes: if N is preceded by a + or \- sign (or is 0),
the two signed numbers are compared.
Otherwise, the absolute magnitudes are compared, ignoring sign.
.RS
.RE
.TP
.B \f[B]\f[C]code:REGEX\f[]\f[]
match by transaction code (eg check number)
.RS
.RE
.TP
.B \f[B]\f[C]cur:REGEX\f[]\f[]
match postings or transactions including any amounts whose
currency/commodity symbol is fully matched by REGEX.
(For a partial match, use \f[C]\&.*REGEX.*\f[]).
Note, to match characters which are regex\-significant, like the dollar
sign (\f[C]$\f[]), you need to prepend \f[C]\\\f[].
And when using the command line you need to add one more level of
quoting to hide it from the shell, so eg do:
\f[C]hledger\ print\ cur:\[aq]\\$\[aq]\f[] or
\f[C]hledger\ print\ cur:\\\\$\f[].
.RS
.RE
.TP
.B \f[B]\f[C]desc:REGEX\f[]\f[]
match transaction descriptions
.RS
.RE
.TP
.B \f[B]\f[C]date:PERIODEXPR\f[]\f[]
match dates within the specified period (which should not include a
reporting interval
.RS
.RE
.TP
.B \f[B]\f[C]date2:PERIODEXPR\f[]\f[]
as above, but match secondary dates
.RS
.RE
.TP
.B \f[B]\f[C]depth:N\f[]\f[]
match (or display, depending on command) accounts at or above this depth
.RS
.RE
.TP
.B \f[B]\f[C]real:,\ real:0\f[]\f[]
match real or virtual postings respectively
.RS
.RE
.TP
.B \f[B]\f[C]status:*,\ status:!,\ status:\f[]\f[]
match cleared, pending, or uncleared/pending transactions respectively
.RS
.RE
.TP
.B \f[B]\f[C]tag:REGEX[=REGEX]\f[]\f[]
match by tag name, and optionally also by tag value.
Note a tag: query is considered to match a transaction if it matches any
of the postings.
Also remember that postings inherit the tags of their parent
transaction.
.RS
.RE
.TP
.B \f[B]\f[C]not:\f[]\f[]
before any of the above negates the match.
.RS
.RE
.SH EXAMPLES
.PP
Two simple transactions in hledger journal format:
.IP
.nf
\f[C]
2015/9/30\ gift\ received
\ \ assets:cash\ \ \ $20
\ \ income:gifts
2015/10/16\ farmers\ market
\ \ expenses:food\ \ \ \ $10
\ \ assets:cash
\f[]
.fi
.PP
Some basic reports:
.IP
.nf
\f[C]
$\ hledger\ print
2015/09/30\ gift\ received
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ $20
\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ $\-20
2015/10/16\ farmers\ market
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ $10
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ $\-10
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ accounts\ \-\-tree
assets
\ \ cash
expenses
\ \ food
income
\ \ gifts
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ balance
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ assets:cash
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ expenses:food
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-20\ \ income:gifts
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ register\ cash
2015/09/30\ gift\ received\ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ $20
2015/10/16\ farmers\ market\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ \ $10
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ available\ commands
$\ hledger\ add\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ add\ more\ transactions\ to\ the\ journal\ file
$\ hledger\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ all\ accounts\ with\ aggregated\ balances
$\ hledger\ balance\ \-\-help\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ help\ for\ balance\ command
$\ hledger\ balance\ \-\-depth\ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ only\ top\-level\ accounts
$\ hledger\ register\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ account\ postings,\ with\ running\ total
$\ hledger\ reg\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ postings\ to/from\ income\ accounts
$\ hledger\ reg\ \[aq]assets:some\ bank:checking\[aq]\ #\ show\ postings\ to/from\ this\ checking\ account
$\ hledger\ print\ desc:shop\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transactions\ with\ shop\ in\ the\ description
$\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transaction\ counts\ per\ week\ as\ a\ bar\ chart
\f[]
.fi
.SH ENVIRONMENT
.PP
\f[B]LEDGER_FILE\f[] sets the default journal file path.
If not set, it is \f[C]~/.hledger.journal\f[].
.PP
\f[B]COLUMNS\f[] sets the default width used by the register command
(normally the full terminal width).
.SH FILES
.PP
Reads data from a hledger journal file (\f[C]$LEDGER_FILE\f[] or
\f[C]~/.hledger.journal\f[] by default), or a CSV file plus associated
CSV rules file.
.SH BUGS
.PP
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward.
.PP
hledger can\[aq]t render non\-ascii characters when run from a Windows
command prompt (up to Windows 7 at least).
.PP
When input data contains non\-ascii characters, a suitable system locale
must be configured (or there will be an unhelpful error).
Eg on POSIX, set LANG to something other than C.
.SH REPORTING BUGS
.PP
Report bugs at http://bugs.hledger.org.
.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org.
.SH AUTHORS
Simon Michael <simon@joyful.com>
.SH COPYRIGHT
Copyright (C) 2007-2015 Simon Michael.
.br
Released under GNU GPLv3+.
.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
.br
hledger_csv(5), hledger_journal(5), hledger_timelog(5)
For more information, see http://hledger.org.

510
hledger/hledger.1.md Normal file
View File

@ -0,0 +1,510 @@
% hledger(1) hledger 0.26.98
%
% October 2015
# NAME
hledger - a command-line accounting tool
# SYNOPSIS
`hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS]`\
`hledger [-f FILE] ADDONCMD -- [OPTIONS] [CMDARGS]`
# DESCRIPTION
hledger is a cross-platform program for tracking money, time, or any
other commodity, using double-entry accounting and a simple, editable
file format. It is inspired by and largely compatible with ledger(1).
hledger aims to be a reliable, practical tool for daily use. This man
page is a quick reference and introduction; for more complete docs, see
http://hledger.org/manual.
This is hledger’s command-line interface (there are also curses and web
interfaces). Its basic function is to read a plain text file describing
financial transactions (in accounting terms, a general journal) and
print useful reports on standard output, or export them as CSV. hledger
can also read CSV files, converting them semi-automatically to journal
format. Additionally, hledger lists other hledger-\* executables found
in the user’s \$PATH and can invoke them as subcommands.
The journal file is `~/.hledger.journal` by default, or another file path
specified by `$LEDGER_FILE`. You can also specify a file with `-f FILE`,
or standard input with `-f-`.
Transactions are dated movements of money between two (or more) named
accounts, and are recorded with journal entries like this:
```journal
2015/10/16 bought food
expenses:food $10
assets:cash
```
For more about the format, see hledger_journal(5).
Most users use a text editor to edit the journal, usually with an editor
mode such as ledger-mode for added convenience. hledger’s interactive
add command is another way to record new transactions. hledger never
changes existing transactions.
To get started, you can either save some entries like the above in
`~/.hledger.journal`, or run `hledger add` and follow the prompts. Then
try some commands like `hledger print` or `hledger balance`.
See COMMANDS and EXAMPLES below.
# OPTIONS
To see general help and the command list: `hledger --help` or `hledger`
To see all options available with a command: `hledger COMMAND --help`
Except for the General options below, options must be written after
COMMAND, not before it.
Also, when invoking external add-on commands, their options must be
written after a double hyphen. (Or, you can invoke the external command
directly.) Eg:
```{.shell .bold}
$ hledger ui -- --register cash
$ hledger-ui --register cash
```
Options and command arguments can be intermixed. Arguments are usually
interpreted as a search query which filters the data, see QUERIES.
## General flags:
These can appear anywhere in the command line.
`-h --help`
: show general help or (after command) command help
`--version`
: show version information
`-f FILE --file=FILE`
: use a different input file. For stdin, use -
`--rules-file=RULESFILE`
: Conversion rules file to use when reading CSV (default: FILE.rules)
`--alias=OLD=NEW`
: display accounts named OLD as NEW
`--ignore-assertions`
: ignore any failing balance assertions in the journal
`--debug=N`
: : show debug output if N is 1-9 (default: 0)
## Common reporting flags:
These are supported by most commands, where applicable.
They must be written after the command name.
Additional command-specific flags are described in COMMANDS below.
`-b --begin=DATE `
: include postings/txns on or after this date
`-e --end=DATE `
: include postings/txns before this date
`-D --daily `
: multiperiod/multicolumn report by day
`-W --weekly `
: multiperiod/multicolumn report by week
`-M --monthly `
: multiperiod/multicolumn report by month
`-Q --quarterly `
: multiperiod/multicolumn report by quarter
`-Y --yearly `
: multiperiod/multicolumn report by year
`-p --period=PERIODEXP `
: set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date`
: use postings/txns' secondary dates instead
`-C --cleared `
: include only cleared postings/txns
`--pending`
: include only pending postings/txns
`-U --uncleared `
: include only uncleared (and pending) postings/txns
`-R --real `
: include only non-virtual postings
`--depth=N`
: hide accounts/postings deeper than N
`-E --empty `
: show empty/zero things which are normally omitted
`-B --cost `
: show amounts in their cost price's commodity
If a reporting option is repeated, the last one takes precedence. Eg -p jan -p
feb is equivalent to -p feb.
# COMMANDS
COMMAND selects one of hledger's subcommands; omit it to list available commands.
To save typing, some commands have a short form; any unique prefix also works.
Here is a summary (see http://hledger.org/manual#commands for the full command help):
## Data entry:
### add
prompt for transactions and add them to the journal.
This is the only hledger command that writes to the journal file.
It appends only, existing transactions are not changed.
`--no-new-accounts`
: don't allow creating new accounts; helps prevent typos when entering account names
## Reporting:
### accounts
show account names
`--tree`
: show short account names, as a tree
`--flat`
: show full account names, as a list (default)
`--drop=N`
: in flat mode: omit N leading account name parts
### activity
show an ascii barchart of posting counts per interval
(default: daily)
### balance, bal
show accounts and balances
`--tree`
: show short account names, as a tree
`--flat`
: show full account names, as a list (default)
`--drop=N`
: in flat mode: omit N leading account name parts
`--format=LINEFORMAT`
: in single-column balance reports: use this custom line format
`--no-elide`
: in tree mode: don't squash boring parent accounts
`-H --historical`
: in multicolumn mode: show historical ending balances
`--cumulative`
: in multicolumn mode: show accumulated ending balances
`-A --average`
: in multicolumn mode: show a row average column
`-T --row-total`
: in multicolumn mode: show a row total column
`-N --no-total`
: don't show the final total row
`-V --value`
: show amounts as their current market value in their default valuation commodity
`-o FILE[.FMT] --output-file=FILE[.FMT]`
: write output to FILE instead of stdout. A recognised FMT suffix influences the format.
`-O FMT --output-format=FMT `
: select the output format. Supported formats:
txt, csv.
### balancesheet, bs
show a balance sheet
`--flat`
: show full account names, as a list (default)
`--drop=N`
: in flat mode: omit N leading account name parts
### cashflow, cf
show a cashflow statement
`--flat`
: show full account names, as a list (default)
`--drop=N`
: in flat mode: omit N leading account name parts
### incomestatement, is
show an income statement
`--flat`
: show full account names, as a list (default)
`--drop=N`
: in flat mode: omit N leading account name parts
### print
show transactions from the journal
`-m STR --match=STR `
: show the transaction whose description is most similar to STR, and is most recent
`-o FILE[.FMT] --output-file=FILE[.FMT]`
: write output to FILE instead of stdout. A recognised FMT suffix influences the format.
`-O FMT --output-format=FMT `
: select the output format. Supported formats:
txt, csv.
### register, reg
show postings and running total
`-H --historical`
: include prior postings in the running total
`-A --average`
: show a running average instead of the running total (implies --empty)
`-r --related`
: show postings' siblings instead
`-w N --width=N`
: set output width (default: terminal width or COLUMNS. -wN,M sets description width as well)
`-o FILE[.FMT] --output-file=FILE[.FMT]`
: write output to FILE instead of stdout. A recognised FMT suffix influences the format.
`-O FMT --output-format=FMT `
: select the output format. Supported formats:
txt, csv.
### stats
show some journal statistics
`-o FILE[.FMT] --output-file=FILE[.FMT]`
: write output to FILE instead of stdout. A recognised FMT suffix influences the format.
## Add-on commands:
Additional commands will be available when executables or scripts
named "`hledger-`CMD" are installed in the PATH. These are often
provided by a package of the same name, or you can make your own custom scripts
(haskell scripts can use hledger-lib allowing tight integration).
Some available add-ons are:
### autosync
download OFX bank data and/or convert OFX to hledger journal format
### diff
show transactions present in one journal file but not another
### interest
generate interest transactions
### irr
calculate internal rate of return
### ui
curses-style interface, see hledger-ui(1)
### web
web interface, see hledger-web(1)
# QUERIES
Most commands accept an optional query expression, written as arguments after the command name,
to filter the data by date, account name or other criteria.
The syntax is similar to a web search:
one or more space-separated search terms,
quotes to enclose whitespace,
optional prefixes to match specific fields.
Multiple search terms are combined as follows:
All commands except print: show transactions/postings/accounts which match (or negatively match)
- any of the description terms AND
- any of the account terms AND
- all the other terms.
The print command: show transactions which
- match any of the description terms AND
- have any postings matching any of the positive account terms AND
- have no postings matching any of the negative account terms AND
- match all the other terms.
The following kinds of search terms can be used:
**`REGEX`**
: match account names by this regular expression
**`acct:REGEX`**
: same as above
**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**
: match postings with a single-commodity amount that is equal to, less
than, or greater than N. (Multi-commodity amounts are not tested, and
will always match.) The comparison has two modes: if N is preceded by
a + or - sign (or is 0), the two signed numbers are
compared. Otherwise, the absolute magnitudes are compared, ignoring
sign.
**`code:REGEX`**
: match by transaction code (eg check number)
**`cur:REGEX`**
: match postings or transactions including any amounts whose
currency/commodity symbol is fully matched by REGEX. (For a partial
match, use `.*REGEX.*`). Note, to match characters which are
regex-significant, like the dollar sign (`$`), you need to prepend `\`.
And when using the command line you need to add one more level of
quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
or `hledger print cur:\\$`.
**`desc:REGEX`**
: match transaction descriptions
**`date:PERIODEXPR`**
: match dates within the specified period (which should not include a
reporting interval
**`date2:PERIODEXPR`**
: as above, but match secondary dates
**`depth:N`**
: match (or display, depending on command) accounts at or above this depth
**`real:, real:0`**
: match real or virtual postings respectively
**`status:*, status:!, status:`**
: match cleared, pending, or uncleared/pending transactions respectively
**`tag:REGEX[=REGEX]`**
: match by tag name, and optionally also by tag value. Note a
tag: query is considered to match a transaction if it matches any of
the postings. Also remember that postings inherit the tags of their
parent transaction.
**`not:`**
: before any of the above negates the match.
# EXAMPLES
Two simple transactions in hledger journal format:
```journal
2015/9/30 gift received
assets:cash $20
income:gifts
2015/10/16 farmers market
expenses:food $10
assets:cash
```
Some basic reports:
```shell
$ hledger print
2015/09/30 gift received
assets:cash $20
income:gifts $-20
2015/10/16 farmers market
expenses:food $10
assets:cash $-10
```
```shell
$ hledger accounts --tree
assets
cash
expenses
food
income
gifts
```
```shell
$ hledger balance
$10 assets:cash
$10 expenses:food
$-20 income:gifts
--------------------
0
```
```shell
$ hledger register cash
2015/09/30 gift received assets:cash $20 $20
2015/10/16 farmers market assets:cash $-10 $10
```
```{.shell .bold}
$ hledger # show available commands
$ hledger add # add more transactions to the journal file
$ hledger balance # all accounts with aggregated balances
$ hledger balance --help # show help for balance command
$ hledger balance --depth 1 # only top-level accounts
$ hledger register # show account postings, with running total
$ hledger reg income # show postings to/from income accounts
$ hledger reg 'assets:some bank:checking' # show postings to/from this checking account
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
```
# ENVIRONMENT
**LEDGER_FILE**
sets the default journal file path. If not set, it is `~/.hledger.journal`.
**COLUMNS**
sets the default width used by the register command (normally the full terminal width).
# FILES
Reads data from a hledger journal file (`$LEDGER_FILE` or
`~/.hledger.journal` by default), or a CSV file plus associated CSV
rules file.
# BUGS
The need to precede options with `--` when invoked from hledger is awkward.
hledger can't render non-ascii characters when run from a Windows command prompt (up to Windows 7 at least).
When input data contains non-ascii characters, a suitable system locale must be configured (or there will be an unhelpful error).
Eg on POSIX, set LANG to something other than C.
# REPORTING BUGS
Report bugs at http://bugs.hledger.org.