doc: update man pages
This commit is contained in:
Simon Michael
parent
5ef67e0d4d
commit
8ee0c7fa76
@ -33,7 +33,7 @@ $endif$
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
@ -61,7 +61,7 @@ Simon Michael <simon@joyful.com> and contributors
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
@ -20,20 +20,19 @@ At minimum, the rules file must specify the \f[C]date\f[] and
|
|||||||
\f[C]amount\f[] fields.
|
\f[C]amount\f[] fields.
|
||||||
For an example, see How to read CSV files.
|
For an example, see How to read CSV files.
|
||||||
.PP
|
.PP
|
||||||
(For CSV output, see CSV output.)
|
To learn about \f[I]exporting\f[] CSV, see CSV output.
|
||||||
.SS CSV rules
|
.SH CSV RULES
|
||||||
.PP
|
.PP
|
||||||
The following six kinds of rule can appear in the rules file, in any
|
The following six kinds of rule can appear in the rules file, in any
|
||||||
order.
|
order.
|
||||||
Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are
|
Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are
|
||||||
ignored.
|
ignored.
|
||||||
|
.SS skip
|
||||||
|
.PP
|
||||||
|
\f[C]skip\f[]\f[I]\f[C]N\f[]\f[]
|
||||||
.PP
|
.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.
|
Skip this number of CSV records at the beginning.
|
||||||
You\[aq]ll need this when your CSV contains header lines.
|
You\[aq]ll need this whenever your CSV data contains header lines.
|
||||||
Eg:
|
Eg:
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
@ -42,11 +41,10 @@ Eg:
|
|||||||
skip\ 1
|
skip\ 1
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
|
.SS date\-format
|
||||||
|
.PP
|
||||||
|
\f[C]date\-format\f[]\f[I]\f[C]DATEFMT\f[]\f[]
|
||||||
.PP
|
.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
|
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
|
\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to
|
||||||
specify the format.
|
specify the format.
|
||||||
@ -56,71 +54,63 @@ Examples:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
#\ parses\ "6/11/2013":
|
#\ for\ dates\ like\ "6/11/2013":
|
||||||
date\-format\ %\-d/%\-m/%Y
|
date\-format\ %\-d/%\-m/%Y
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
#\ parses\ "11/06/2013":
|
#\ for\ dates\ like\ "11/06/2013":
|
||||||
date\-format\ %m/%d/%Y
|
date\-format\ %m/%d/%Y
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
#\ parses\ "2013\-Nov\-06":
|
#\ for\ dates\ like\ "2013\-Nov\-06":
|
||||||
date\-format\ %Y\-%h\-%d
|
date\-format\ %Y\-%h\-%d
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
#\ parses\ "11/6/2013\ 11:32\ PM":
|
#\ for\ dates\ like\ "11/6/2013\ 11:32\ PM":
|
||||||
date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
|
date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
|
.SS field list
|
||||||
.PP
|
.PP
|
||||||
\f[B]\f[C]fields\f[] \f[I]CSVFIELDNAME1\f[],
|
\f[C]fields\f[]\f[I]\f[C]FIELDNAME1\f[]\f[],
|
||||||
\f[I]CSVFIELDNAME2\f[]...\f[]
|
\f[I]\f[C]FIELDNAME2\f[]\f[]...
|
||||||
.PD 0
|
.PP
|
||||||
.P
|
This (a) names the CSV fields, in order (names may not contain
|
||||||
.PD
|
whitespace, but may be omitted), and (b) assigns them to journal entry
|
||||||
(Field list)
|
fields if you use any of these standard field names: \f[C]date\f[],
|
||||||
.PD 0
|
\f[C]date2\f[], \f[C]status\f[], \f[C]code\f[], \f[C]description\f[],
|
||||||
.P
|
\f[C]comment\f[], \f[C]account1\f[], \f[C]account2\f[], \f[C]amount\f[],
|
||||||
.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[].
|
\f[C]amount\-in\f[], \f[C]amount\-out\f[], \f[C]currency\f[].
|
||||||
Eg:
|
Eg:
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\ date,\ description\ and\ amount
|
#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\[aq]s\ date,\ description\ and\ amount,
|
||||||
#\ give\ the\ 7th\ and\ 8th\ fields\ custom\ names\ for\ later\ reference
|
#\ and\ give\ the\ 7th\ and\ 8th\ fields\ meaningful\ names\ for\ later\ reference:
|
||||||
|
#
|
||||||
|
#\ CSV\ field:
|
||||||
|
#\ \ \ \ \ \ 1\ \ \ \ \ 2\ \ \ \ \ \ \ \ \ \ \ \ 3\ 4\ \ \ \ \ \ \ 5\ 6\ 7\ \ \ \ \ \ \ \ \ \ 8
|
||||||
|
#\ entry\ field:
|
||||||
fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield
|
fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
|
.SS field assignment
|
||||||
|
.PP
|
||||||
|
\f[I]\f[C]ENTRYFIELDNAME\f[]\f[] \f[I]\f[C]FIELDVALUE\f[]\f[]
|
||||||
.PP
|
.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
|
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
|
given text value, which can include CSV field values interpolated by
|
||||||
name (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]).
|
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
|
Eg:
|
||||||
list.
|
|
||||||
Eg:
|
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
@ -136,38 +126,29 @@ comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1
|
|||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
\f[B]\f[C]if\f[] \f[I]PATTERN\f[]
|
Field assignments can be used instead of or in addition to a field list.
|
||||||
|
.SS conditional block
|
||||||
|
.PP
|
||||||
|
\f[C]if\f[] \f[I]\f[C]PATTERN\f[]\f[]
|
||||||
.PD 0
|
.PD 0
|
||||||
.P
|
.P
|
||||||
.PD
|
.PD
|
||||||
\ \ \ \ \f[I]FIELDASSIGNMENTS\f[]...\f[]
|
\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
|
||||||
|
.PP
|
||||||
|
\f[C]if\f[]
|
||||||
.PD 0
|
.PD 0
|
||||||
.P
|
.P
|
||||||
.PD
|
.PD
|
||||||
or
|
\f[I]\f[C]PATTERN\f[]\f[]
|
||||||
.PD 0
|
.PD 0
|
||||||
.P
|
.P
|
||||||
.PD
|
.PD
|
||||||
\f[B]\f[C]if\f[]
|
\f[I]\f[C]PATTERN\f[]\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
|
.PD 0
|
||||||
.P
|
.P
|
||||||
.PD
|
.PD
|
||||||
|
\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
|
||||||
|
.PP
|
||||||
This applies one or more field assignments, only to those CSV records
|
This applies one or more field assignments, only to those CSV records
|
||||||
matched by one of the PATTERNs.
|
matched by one of the PATTERNs.
|
||||||
The patterns are case\-insensitive regular expressions which match
|
The patterns are case\-insensitive regular expressions which match
|
||||||
@ -195,14 +176,13 @@ monthly\ service\ fee
|
|||||||
atm\ transaction\ fee
|
atm\ transaction\ fee
|
||||||
banking\ thru\ software
|
banking\ thru\ software
|
||||||
\ account2\ expenses:business:banking
|
\ account2\ expenses:business:banking
|
||||||
\ comment\ \ XXX\ deductible\ ?\ check
|
\ comment\ \ XXX\ deductible\ ?\ check\ it
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
|
.SS include
|
||||||
|
.PP
|
||||||
|
\f[C]include\f[]\f[I]\f[C]RULESFILE\f[]\f[]
|
||||||
.PP
|
.PP
|
||||||
\f[B]\f[C]include\f[] \f[I]RULESFILE\f[]\f[]
|
|
||||||
.PD 0
|
|
||||||
.P
|
|
||||||
.PD
|
|
||||||
Include another rules file at this point.
|
Include another rules file at this point.
|
||||||
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to
|
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to
|
||||||
the current file\[aq]s directory.
|
the current file\[aq]s directory.
|
||||||
@ -214,7 +194,7 @@ Eg:
|
|||||||
include\ common.rules
|
include\ common.rules
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
.SS CSV tips
|
.SH TIPS
|
||||||
.PP
|
.PP
|
||||||
Each generated journal entry will have two postings, to
|
Each generated journal entry will have two postings, to
|
||||||
\f[C]account1\f[] and \f[C]account2\f[] respectively.
|
\f[C]account1\f[] and \f[C]account2\f[] respectively.
|
||||||
@ -248,7 +228,7 @@ Simon Michael <simon@joyful.com> and contributors
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
@ -1,3 +1,4 @@
|
|||||||
|
.\"t
|
||||||
|
|
||||||
.TH "hledger_journal" "5" "April 2016" "" "hledger User Manuals"
|
.TH "hledger_journal" "5" "April 2016" "" "hledger User Manuals"
|
||||||
|
|
||||||
@ -57,8 +58,7 @@ Here\[aq]s an example:
|
|||||||
\ \ \ \ assets:bank:checking
|
\ \ \ \ assets:bank:checking
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.SH FILE FORMAT
|
||||||
Now let\[aq]s explore the available journal file syntax in detail.
|
|
||||||
.SS Transactions
|
.SS Transactions
|
||||||
.PP
|
.PP
|
||||||
Transactions are represented by journal entries.
|
Transactions are represented by journal entries.
|
||||||
@ -806,6 +806,46 @@ Glob patterns (\f[C]*\f[]) are not currently supported.
|
|||||||
The \f[C]include\f[] directive may only be used in journal files, and
|
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
|
currently it may only include other journal files (eg, not CSV or
|
||||||
timelog files.)
|
timelog files.)
|
||||||
|
.SH EDITOR SUPPORT
|
||||||
|
.PP
|
||||||
|
Add\-on modes exist for various text editors, to make working with
|
||||||
|
journal files easier.
|
||||||
|
They add colour, navigation aids and helpful commands.
|
||||||
|
For hledger users who edit the journal file directly (the majority),
|
||||||
|
using one of these modes is quite recommended.
|
||||||
|
.PP
|
||||||
|
These were written with Ledger in mind, but also work with hledger
|
||||||
|
files:
|
||||||
|
.PP
|
||||||
|
.TS
|
||||||
|
tab(@);
|
||||||
|
lw(16.5n) lw(51.5n).
|
||||||
|
T{
|
||||||
|
Emacs
|
||||||
|
T}@T{
|
||||||
|
http://www.ledger\-cli.org/3.0/doc/ledger\-mode.html
|
||||||
|
T}
|
||||||
|
T{
|
||||||
|
Vim
|
||||||
|
T}@T{
|
||||||
|
https://github.com/ledger/ledger/wiki/Getting\-started
|
||||||
|
T}
|
||||||
|
T{
|
||||||
|
Sublime Text
|
||||||
|
T}@T{
|
||||||
|
https://github.com/ledger/ledger/wiki/Using\-Sublime\-Text
|
||||||
|
T}
|
||||||
|
T{
|
||||||
|
Textmate
|
||||||
|
T}@T{
|
||||||
|
https://github.com/ledger/ledger/wiki/Using\-TextMate\-2
|
||||||
|
T}
|
||||||
|
T{
|
||||||
|
Text Wrangler \
|
||||||
|
T}@T{
|
||||||
|
https://github.com/ledger/ledger/wiki/Editing\-Ledger\-files\-with\-TextWrangler
|
||||||
|
T}
|
||||||
|
.TE
|
||||||
|
|
||||||
|
|
||||||
.SH "REPORTING BUGS"
|
.SH "REPORTING BUGS"
|
||||||
@ -819,7 +859,7 @@ Simon Michael <simon@joyful.com> and contributors
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
@ -136,7 +136,7 @@ Simon Michael <simon@joyful.com> and contributors
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
@ -90,7 +90,7 @@ Simon Michael <simon@joyful.com> and contributors
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
@ -320,7 +320,7 @@ Simon Michael <simon@joyful.com> and contributors
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
@ -245,7 +245,7 @@ Simon Michael <simon@joyful.com> and contributors
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
@ -20,9 +20,8 @@ hledger is a cross\-platform program for tracking money, time, or any
|
|||||||
other commodity, using double\-entry accounting and a simple, editable
|
other commodity, using double\-entry accounting and a simple, editable
|
||||||
file format.
|
file format.
|
||||||
It is inspired by and largely compatible with ledger(1).
|
It is inspired by and largely compatible with ledger(1).
|
||||||
hledger aims to be a reliable, practical tool for daily use.
|
Tested on unix, mac, windows, hledger aims to be a reliable, practical
|
||||||
This man page is a quick reference and introduction; for more complete
|
tool for daily use.
|
||||||
docs, see http://hledger.org/manual.
|
|
||||||
.PP
|
.PP
|
||||||
This is hledger's command\-line interface (there are also curses and web
|
This is hledger's command\-line interface (there are also curses and web
|
||||||
interfaces).
|
interfaces).
|
||||||
@ -463,6 +462,52 @@ Examples:
|
|||||||
\-p\ "every\ 4th\ day\ of\ week"
|
\-p\ "every\ 4th\ day\ of\ week"
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
|
.SS Regular Expressions
|
||||||
|
.PP
|
||||||
|
hledger uses regular expressions in a number of places:
|
||||||
|
.IP \[bu] 2
|
||||||
|
query terms, on the command line and in the hledger\-web search form:
|
||||||
|
\f[C]REGEX\f[], \f[C]desc:REGEX\f[], \f[C]cur:REGEX\f[],
|
||||||
|
\f[C]tag:...=REGEX\f[]
|
||||||
|
.IP \[bu] 2
|
||||||
|
CSV rules conditional blocks: \f[C]if\ REGEX\ ...\f[]
|
||||||
|
.IP \[bu] 2
|
||||||
|
account alias directives and options:
|
||||||
|
\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[],
|
||||||
|
\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[]
|
||||||
|
.PP
|
||||||
|
hledger\[aq]s regular expressions come from the regex\-tdfa library.
|
||||||
|
In general they:
|
||||||
|
.IP \[bu] 2
|
||||||
|
are case insensitive
|
||||||
|
.IP \[bu] 2
|
||||||
|
are infix matching (do not need to match the entire thing being matched)
|
||||||
|
.IP \[bu] 2
|
||||||
|
are POSIX extended regular expressions
|
||||||
|
.IP \[bu] 2
|
||||||
|
also support GNU word boundaries (\\<, \\>, \\b, \\B)
|
||||||
|
.IP \[bu] 2
|
||||||
|
and parenthesised capturing groups and numeric backreferences in
|
||||||
|
replacement strings
|
||||||
|
.IP \[bu] 2
|
||||||
|
do not support mode modifiers like (?s)
|
||||||
|
.PP
|
||||||
|
Some things to note:
|
||||||
|
.IP \[bu] 2
|
||||||
|
In the \f[C]alias\f[] directive and \f[C]\-\-alias\f[] option, regular
|
||||||
|
expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[]).
|
||||||
|
Elsewhere in hledger, these are not required.
|
||||||
|
.IP \[bu] 2
|
||||||
|
To match a regular expression metacharacter like \f[C]$\f[] as a literal
|
||||||
|
character, prepend a backslash.
|
||||||
|
Eg to search for amounts with the dollar sign in hledger\-web, write
|
||||||
|
\f[C]cur:\\$\f[].
|
||||||
|
.IP \[bu] 2
|
||||||
|
On the command line, some metacharacters like \f[C]$\f[] have a special
|
||||||
|
meaning to the shell and so must be escaped a second time, with single
|
||||||
|
or double quotes or another backslash.
|
||||||
|
Eg, to match amounts with the dollar sign from the command line, write
|
||||||
|
\f[C]cur:\[aq]\\$\[aq]\f[] or \f[C]cur:\\\\$\f[].
|
||||||
.SH QUERIES
|
.SH QUERIES
|
||||||
.PP
|
.PP
|
||||||
One of hledger\[aq]s strengths is being able to quickly report on
|
One of hledger\[aq]s strengths is being able to quickly report on
|
||||||
@ -579,11 +624,13 @@ before any of the above negates the match.
|
|||||||
.RS
|
.RS
|
||||||
.RE
|
.RE
|
||||||
.PP
|
.PP
|
||||||
Some of the above can also be expressed as command\-line options (eg
|
* * * * *
|
||||||
|
.PP
|
||||||
|
Some of these can also be expressed as command\-line options (eg
|
||||||
\f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]).
|
\f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]).
|
||||||
Generally you can mix options and query arguments, and the resulting
|
Generally you can mix options and query arguments, and the resulting
|
||||||
query will be their intersection (aside from the \f[C]\-p/\-\-period\f[]
|
query will be their intersection (perhaps excluding the
|
||||||
option).
|
\f[C]\-p/\-\-period\f[] option).
|
||||||
.SH COMMANDS
|
.SH COMMANDS
|
||||||
.PP
|
.PP
|
||||||
hledger provides a number of subcommands; \f[C]hledger\f[] with no
|
hledger provides a number of subcommands; \f[C]hledger\f[] with no
|
||||||
@ -694,6 +741,85 @@ $\ hledger\ activity\ \-\-quarterly
|
|||||||
2008\-10\-01\ **
|
2008\-10\-01\ **
|
||||||
\f[]
|
\f[]
|
||||||
.fi
|
.fi
|
||||||
|
.SS add
|
||||||
|
.PP
|
||||||
|
Prompt for transactions and add them to the journal.
|
||||||
|
.TP
|
||||||
|
.B \f[C]\-\-no\-new\-accounts\f[]
|
||||||
|
don\[aq]t allow creating new accounts; helps prevent typos when entering
|
||||||
|
account names
|
||||||
|
.RS
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
Many hledger users edit their journals directly with a text editor, or
|
||||||
|
generate them from CSV.
|
||||||
|
For more interactive data entry, there is the \f[C]add\f[] command,
|
||||||
|
which prompts interactively on the console for new transactions, and
|
||||||
|
appends them to the journal file (existing transactions are not
|
||||||
|
changed).
|
||||||
|
This is the only hledger command that writes to the journal file.
|
||||||
|
.PP
|
||||||
|
To use it, just run \f[C]hledger\ add\f[] and follow the prompts.
|
||||||
|
You can add as many transactions as you like; when you are finished,
|
||||||
|
enter \f[C]\&.\f[] or press control\-d or control\-c to exit.
|
||||||
|
.PP
|
||||||
|
Features:
|
||||||
|
.IP \[bu] 2
|
||||||
|
add tries to provide useful defaults, using the most similar recent
|
||||||
|
transaction (by description) as a template.
|
||||||
|
.IP \[bu] 2
|
||||||
|
You can also set the initial defaults with command line arguments.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Readline\-style edit keys can be used during data entry.
|
||||||
|
.IP \[bu] 2
|
||||||
|
The tab key will auto\-complete whenever possible \- accounts,
|
||||||
|
descriptions, dates (\f[C]yesterday\f[], \f[C]today\f[],
|
||||||
|
\f[C]tomorrow\f[]).
|
||||||
|
If the input area is empty, it will insert the default value.
|
||||||
|
.IP \[bu] 2
|
||||||
|
If the journal defines a default commodity, it will be added to any bare
|
||||||
|
numbers entered.
|
||||||
|
.IP \[bu] 2
|
||||||
|
A parenthesised transaction code may be entered following a date.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Comments and tags may be entered following a description or amount.
|
||||||
|
.IP \[bu] 2
|
||||||
|
If you make a mistake, enter \f[C]<\f[] at any prompt to restart the
|
||||||
|
transaction.
|
||||||
|
.IP \[bu] 2
|
||||||
|
Input prompts are displayed in a different colour when the terminal
|
||||||
|
supports it.
|
||||||
|
.PP
|
||||||
|
Example (see the tutorial for a detailed explanation):
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
$\ hledger\ add
|
||||||
|
Adding\ transactions\ to\ journal\ file\ /src/hledger/data/sample.journal
|
||||||
|
Any\ command\ line\ arguments\ will\ be\ used\ as\ defaults.
|
||||||
|
Use\ tab\ key\ to\ complete,\ readline\ keys\ to\ edit,\ enter\ to\ accept\ defaults.
|
||||||
|
An\ optional\ (CODE)\ may\ follow\ transaction\ dates.
|
||||||
|
An\ optional\ ;\ COMMENT\ may\ follow\ descriptions\ or\ amounts.
|
||||||
|
If\ you\ make\ a\ mistake,\ enter\ <\ at\ any\ prompt\ to\ restart\ the\ transaction.
|
||||||
|
To\ end\ a\ transaction,\ enter\ .\ when\ prompted.
|
||||||
|
To\ quit,\ enter\ .\ at\ a\ date\ prompt\ or\ press\ control\-d\ or\ control\-c.
|
||||||
|
Date\ [2015/05/22]:\
|
||||||
|
Description:\ supermarket
|
||||||
|
Account\ 1:\ expenses:food
|
||||||
|
Amount\ \ 1:\ $10
|
||||||
|
Account\ 2:\ assets:checking
|
||||||
|
Amount\ \ 2\ [$\-10.0]:\
|
||||||
|
Account\ 3\ (or\ .\ or\ enter\ to\ finish\ this\ transaction):\ .
|
||||||
|
2015/05/22\ supermarket
|
||||||
|
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ $10
|
||||||
|
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ $\-10.0
|
||||||
|
|
||||||
|
Save\ this\ transaction\ to\ the\ journal\ ?\ [y]:\
|
||||||
|
Saved.
|
||||||
|
Starting\ the\ next\ transaction\ (.\ or\ ctrl\-D/ctrl\-C\ to\ quit)
|
||||||
|
Date\ [2015/05/22]:\ <CTRL\-D>\ $
|
||||||
|
\f[]
|
||||||
|
.fi
|
||||||
.SS balance
|
.SS balance
|
||||||
.PP
|
.PP
|
||||||
Show accounts and their balances.
|
Show accounts and their balances.
|
||||||
@ -1088,85 +1214,6 @@ charts in a spreadsheet.
|
|||||||
This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by
|
This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by
|
||||||
specifying a \f[C]\&.csv\f[] file extension with
|
specifying a \f[C]\&.csv\f[] file extension with
|
||||||
\f[C]\-o/\-\-output\-file\f[].
|
\f[C]\-o/\-\-output\-file\f[].
|
||||||
.SS add
|
|
||||||
.PP
|
|
||||||
Prompt for transactions and add them to the journal.
|
|
||||||
.TP
|
|
||||||
.B \f[C]\-\-no\-new\-accounts\f[]
|
|
||||||
don\[aq]t allow creating new accounts; helps prevent typos when entering
|
|
||||||
account names
|
|
||||||
.RS
|
|
||||||
.RE
|
|
||||||
.PP
|
|
||||||
Many hledger users edit their journals directly with a text editor, or
|
|
||||||
generate them from CSV.
|
|
||||||
For more interactive data entry, there is the \f[C]add\f[] command,
|
|
||||||
which prompts interactively on the console for new transactions, and
|
|
||||||
appends them to the journal file (existing transactions are not
|
|
||||||
changed).
|
|
||||||
This is the only hledger command that writes to the journal file.
|
|
||||||
.PP
|
|
||||||
To use it, just run \f[C]hledger\ add\f[] and follow the prompts.
|
|
||||||
You can add as many transactions as you like; when you are finished,
|
|
||||||
enter \f[C]\&.\f[] or press control\-d or control\-c to exit.
|
|
||||||
.PP
|
|
||||||
Features:
|
|
||||||
.IP \[bu] 2
|
|
||||||
add tries to provide useful defaults, using the most similar recent
|
|
||||||
transaction (by description) as a template.
|
|
||||||
.IP \[bu] 2
|
|
||||||
You can also set the initial defaults with command line arguments.
|
|
||||||
.IP \[bu] 2
|
|
||||||
Readline\-style edit keys can be used during data entry.
|
|
||||||
.IP \[bu] 2
|
|
||||||
The tab key will auto\-complete whenever possible \- accounts,
|
|
||||||
descriptions, dates (\f[C]yesterday\f[], \f[C]today\f[],
|
|
||||||
\f[C]tomorrow\f[]).
|
|
||||||
If the input area is empty, it will insert the default value.
|
|
||||||
.IP \[bu] 2
|
|
||||||
If the journal defines a default commodity, it will be added to any bare
|
|
||||||
numbers entered.
|
|
||||||
.IP \[bu] 2
|
|
||||||
A parenthesised transaction code may be entered following a date.
|
|
||||||
.IP \[bu] 2
|
|
||||||
Comments and tags may be entered following a description or amount.
|
|
||||||
.IP \[bu] 2
|
|
||||||
If you make a mistake, enter \f[C]<\f[] at any prompt to restart the
|
|
||||||
transaction.
|
|
||||||
.IP \[bu] 2
|
|
||||||
Input prompts are displayed in a different colour when the terminal
|
|
||||||
supports it.
|
|
||||||
.PP
|
|
||||||
Example (see the tutorial for a detailed explanation):
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
$\ hledger\ add
|
|
||||||
Adding\ transactions\ to\ journal\ file\ /src/hledger/data/sample.journal
|
|
||||||
Any\ command\ line\ arguments\ will\ be\ used\ as\ defaults.
|
|
||||||
Use\ tab\ key\ to\ complete,\ readline\ keys\ to\ edit,\ enter\ to\ accept\ defaults.
|
|
||||||
An\ optional\ (CODE)\ may\ follow\ transaction\ dates.
|
|
||||||
An\ optional\ ;\ COMMENT\ may\ follow\ descriptions\ or\ amounts.
|
|
||||||
If\ you\ make\ a\ mistake,\ enter\ <\ at\ any\ prompt\ to\ restart\ the\ transaction.
|
|
||||||
To\ end\ a\ transaction,\ enter\ .\ when\ prompted.
|
|
||||||
To\ quit,\ enter\ .\ at\ a\ date\ prompt\ or\ press\ control\-d\ or\ control\-c.
|
|
||||||
Date\ [2015/05/22]:\
|
|
||||||
Description:\ supermarket
|
|
||||||
Account\ 1:\ expenses:food
|
|
||||||
Amount\ \ 1:\ $10
|
|
||||||
Account\ 2:\ assets:checking
|
|
||||||
Amount\ \ 2\ [$\-10.0]:\
|
|
||||||
Account\ 3\ (or\ .\ or\ enter\ to\ finish\ this\ transaction):\ .
|
|
||||||
2015/05/22\ supermarket
|
|
||||||
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ $10
|
|
||||||
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ $\-10.0
|
|
||||||
|
|
||||||
Save\ this\ transaction\ to\ the\ journal\ ?\ [y]:\
|
|
||||||
Saved.
|
|
||||||
Starting\ the\ next\ transaction\ (.\ or\ ctrl\-D/ctrl\-C\ to\ quit)
|
|
||||||
Date\ [2015/05/22]:\ <CTRL\-D>\ $
|
|
||||||
\f[]
|
|
||||||
.fi
|
|
||||||
.SS balancesheet
|
.SS balancesheet
|
||||||
.PP
|
.PP
|
||||||
Show a balance sheet.
|
Show a balance sheet.
|
||||||
@ -1941,6 +1988,116 @@ Curses\-style interface, see hledger\-ui.
|
|||||||
.SS web
|
.SS web
|
||||||
.PP
|
.PP
|
||||||
Web interface, see hledger\-web.
|
Web interface, see hledger\-web.
|
||||||
|
.SH TROUBLESHOOTING
|
||||||
|
.SS Run\-time problems
|
||||||
|
.PP
|
||||||
|
Here are some issues you might encounter when you run hledger (and
|
||||||
|
remember you can also seek help from the IRC channel, mail list or bug
|
||||||
|
tracker):
|
||||||
|
.PP
|
||||||
|
\f[B]Successfully installed, but "No command \[aq]hledger\[aq]
|
||||||
|
found"\f[]
|
||||||
|
.PD 0
|
||||||
|
.P
|
||||||
|
.PD
|
||||||
|
stack and cabal install binaries into a special directory, which should
|
||||||
|
be added to your PATH environment variable.
|
||||||
|
Eg on unix\-like systems, that is ~/.local/bin and ~/.cabal/bin
|
||||||
|
respectively.
|
||||||
|
.PP
|
||||||
|
\f[B]I set a custom LEDGER_FILE, but hledger is still using the default
|
||||||
|
file\f[]
|
||||||
|
.PD 0
|
||||||
|
.P
|
||||||
|
.PD
|
||||||
|
\f[C]LEDGER_FILE\f[] should be a real environment variable, not just a
|
||||||
|
shell variable.
|
||||||
|
The command \f[C]env\ |\ grep\ LEDGER_FILE\f[] should show it.
|
||||||
|
You may need to use \f[C]export\f[].
|
||||||
|
Here\[aq]s an explanation.
|
||||||
|
.PP
|
||||||
|
\f[B]"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
|
||||||
|
character" errors\f[]
|
||||||
|
.PD 0
|
||||||
|
.P
|
||||||
|
.PD
|
||||||
|
In order to handle non\-ascii letters and symbols (like £), hledger
|
||||||
|
needs an appropriate locale.
|
||||||
|
This is usually configured system\-wide; you can also configure it
|
||||||
|
temporarily.
|
||||||
|
The locale may need to be one that supports UTF\-8, if you built hledger
|
||||||
|
with GHC < 7.2 (or possibly always, I\[aq]m not sure yet).
|
||||||
|
.PP
|
||||||
|
Here\[aq]s an example of setting the locale temporarily, on ubuntu
|
||||||
|
gnu/linux:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
$\ file\ my.journal
|
||||||
|
my.journal:\ UTF\-8\ Unicode\ text\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ the\ file\ is\ UTF8\-encoded
|
||||||
|
$\ locale\ \-a
|
||||||
|
C
|
||||||
|
en_US.utf8\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ a\ UTF8\-aware\ locale\ is\ available
|
||||||
|
POSIX
|
||||||
|
$\ LANG=en_US.utf8\ hledger\ \-f\ my.journal\ print\ \ \ #\ <\-\ use\ it\ for\ this\ command
|
||||||
|
\f[]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Here\[aq]s one way to set it permanently, there are probably better
|
||||||
|
ways:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
$\ echo\ "export\ LANG=en_US.UTF\-8"\ >>~/.bash_profile
|
||||||
|
$\ bash\ \-\-login
|
||||||
|
\f[]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
If we preferred to use eg \f[C]fr_FR.utf8\f[], we might have to install
|
||||||
|
that first:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
$\ apt\-get\ install\ language\-pack\-fr
|
||||||
|
$\ locale\ \-a
|
||||||
|
C
|
||||||
|
en_US.utf8
|
||||||
|
fr_BE.utf8
|
||||||
|
fr_CA.utf8
|
||||||
|
fr_CH.utf8
|
||||||
|
fr_FR.utf8
|
||||||
|
fr_LU.utf8
|
||||||
|
POSIX
|
||||||
|
$\ LANG=fr_FR.utf8\ hledger\ \-f\ my.journal\ print
|
||||||
|
\f[]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Note some platforms allow variant locale spellings, but not all (ubuntu
|
||||||
|
accepts \f[C]fr_FR.UTF8\f[], mac osx requires exactly
|
||||||
|
\f[C]fr_FR.UTF\-8\f[]).
|
||||||
|
.SS Known limitations
|
||||||
|
.PP
|
||||||
|
\f[B]Command line interface\f[]
|
||||||
|
.PP
|
||||||
|
Add\-on command options, unless they are also understood by the main
|
||||||
|
hledger executable, must be written after \f[C]\-\-\f[], like this:
|
||||||
|
\f[C]hledger\ web\ \-\-\ \-\-server\f[]
|
||||||
|
.PP
|
||||||
|
\f[B]Differences from Ledger\f[]
|
||||||
|
.PP
|
||||||
|
Not all of Ledger\[aq]s journal file syntax is supported.
|
||||||
|
See file format differences.
|
||||||
|
.PP
|
||||||
|
hledger is slower than Ledger, and uses more memory, on large data
|
||||||
|
files.
|
||||||
|
.PP
|
||||||
|
\f[B]Windows limitations\f[]
|
||||||
|
.PP
|
||||||
|
In a windows CMD window, non\-ascii characters and colours are not
|
||||||
|
supported.
|
||||||
|
.PP
|
||||||
|
In a windows Cygwin/MSYS/Mintty window, the tab key is not supported in
|
||||||
|
hledger add.
|
||||||
.SH ENVIRONMENT
|
.SH ENVIRONMENT
|
||||||
.PP
|
.PP
|
||||||
\f[B]LEDGER_FILE\f[] sets the default journal file path.
|
\f[B]LEDGER_FILE\f[] sets the default journal file path.
|
||||||
@ -1977,7 +2134,7 @@ Simon Michael <simon@joyful.com> and contributors
|
|||||||
|
|
||||||
Copyright (C) 2007-2016 Simon Michael.
|
Copyright (C) 2007-2016 Simon Michael.
|
||||||
.br
|
.br
|
||||||
Released under GNU GPLv3+.
|
Released under GNU GPL v3 or later.
|
||||||
|
|
||||||
.SH SEE ALSO
|
.SH SEE ALSO
|
||||||
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user