slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: regen manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-02-07 10:45:57 -08:00
parent 6885dddd0e
commit fd64d7bb3a
14 changed files with 3041 additions and 1964 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
hledger-lib/hledger_journal.5
View File

@ -302,14 +302,13 @@ Some examples:
.nf .nf
\f[C] \f[C]
# a file comment # a file comment
; another file comment
; also a file comment * also a file comment, useful in org/orgstruct mode
comment comment
This is a multiline file comment, A multiline file comment, which continues
which continues until a line until a line containing just \[dq]end comment\[dq]
where the \[dq]end comment\[dq] string (or end of file).
appears on its own (or end of file).
end comment end comment
2012/5/14 something ; a transaction comment 2012/5/14 something ; a transaction comment
@ -1793,6 +1792,17 @@ N, and symbol S).
The matched posting\[aq]s amount will be multiplied by N, and its The matched posting\[aq]s amount will be multiplied by N, and its
commodity symbol will be replaced with S. commodity symbol will be replaced with S.
.PP .PP
A query term containing spaces must be enclosed in single or double
quotes, as on the command line.
Eg, note the quotes around the second query term below:
.IP
.nf
\f[C]
= expenses:groceries \[aq]expenses:dining out\[aq]
(budget:funds:dining out) *-1
\f[R]
.fi
.PP
These rules have global effect - a rule appearing anywhere in your data These rules have global effect - a rule appearing anywhere in your data
can potentially affect any transaction, including transactions recorded can potentially affect any transaction, including transactions recorded
above it or in another file. above it or in another file.

202
hledger-lib/hledger_journal.info
View File

@ -284,14 +284,13 @@ Transaction and posting comments must begin with a semicolon (';').
Some examples: Some examples:
# a file comment # a file comment
; another file comment
; also a file comment * also a file comment, useful in org/orgstruct mode
comment comment
This is a multiline file comment, A multiline file comment, which continues
which continues until a line until a line containing just "end comment"
where the "end comment" string (or end of file).
appears on its own (or end of file).
end comment end comment
2012/5/14 something ; a transaction comment 2012/5/14 something ; a transaction comment
@ -1632,6 +1631,13 @@ amount can be:
and symbol S). The matched posting's amount will be multiplied by and symbol S). The matched posting's amount will be multiplied by
N, and its commodity symbol will be replaced with S. N, and its commodity symbol will be replaced with S.
A query term containing spaces must be enclosed in single or double
quotes, as on the command line. Eg, note the quotes around the second
query term below:
= expenses:groceries 'expenses:dining out'
(budget:funds:dining out) *-1
These rules have global effect - a rule appearing anywhere in your These rules have global effect - a rule appearing anywhere in your
data can potentially affect any transaction, including transactions data can potentially affect any transaction, including transactions
recorded above it or in another file. recorded above it or in another file.
@ -1743,98 +1749,98 @@ Node: Payee and note9229
Ref: #payee-and-note9343 Ref: #payee-and-note9343
Node: Comments9678 Node: Comments9678
Ref: #comments9804 Ref: #comments9804
Node: Tags10974 Node: Tags10998
Ref: #tags11089 Ref: #tags11113
Node: Postings12482 Node: Postings12506
Ref: #postings12610 Ref: #postings12634
Node: Virtual Postings13636 Node: Virtual Postings13660
Ref: #virtual-postings13753 Ref: #virtual-postings13777
Node: Account names15059 Node: Account names15083
Ref: #account-names15200 Ref: #account-names15224
Node: Amounts15687 Node: Amounts15711
Ref: #amounts15826 Ref: #amounts15850
Node: Digit group marks16759 Node: Digit group marks16783
Ref: #digit-group-marks16908 Ref: #digit-group-marks16932
Node: Amount display format17846 Node: Amount display format17870
Ref: #amount-display-format18003 Ref: #amount-display-format18027
Node: Transaction prices19028 Node: Transaction prices19052
Ref: #transaction-prices19194 Ref: #transaction-prices19218
Node: Balance Assertions21460 Node: Balance Assertions21484
Ref: #balance-assertions21640 Ref: #balance-assertions21664
Node: Assertions and ordering22673 Node: Assertions and ordering22697
Ref: #assertions-and-ordering22861 Ref: #assertions-and-ordering22885
Node: Assertions and included files23561 Node: Assertions and included files23585
Ref: #assertions-and-included-files23804 Ref: #assertions-and-included-files23828
Node: Assertions and multiple -f options24137 Node: Assertions and multiple -f options24161
Ref: #assertions-and-multiple--f-options24393 Ref: #assertions-and-multiple--f-options24417
Node: Assertions and commodities24525 Node: Assertions and commodities24549
Ref: #assertions-and-commodities24757 Ref: #assertions-and-commodities24781
Node: Assertions and prices25913 Node: Assertions and prices25937
Ref: #assertions-and-prices26127 Ref: #assertions-and-prices26151
Node: Assertions and subaccounts26567 Node: Assertions and subaccounts26591
Ref: #assertions-and-subaccounts26796 Ref: #assertions-and-subaccounts26820
Node: Assertions and virtual postings27120 Node: Assertions and virtual postings27144
Ref: #assertions-and-virtual-postings27362 Ref: #assertions-and-virtual-postings27386
Node: Assertions and precision27504 Node: Assertions and precision27528
Ref: #assertions-and-precision27697 Ref: #assertions-and-precision27721
Node: Balance Assignments27964 Node: Balance Assignments27988
Ref: #balance-assignments28138 Ref: #balance-assignments28162
Node: Balance assignments and prices29303 Node: Balance assignments and prices29327
Ref: #balance-assignments-and-prices29475 Ref: #balance-assignments-and-prices29499
Node: Directives29699 Node: Directives29723
Ref: #directives29858 Ref: #directives29882
Node: Comment blocks35537 Node: Comment blocks35561
Ref: #comment-blocks35682 Ref: #comment-blocks35706
Node: Including other files35858 Node: Including other files35882
Ref: #including-other-files36038 Ref: #including-other-files36062
Node: Default year36446 Node: Default year36470
Ref: #default-year36615 Ref: #default-year36639
Node: Declaring commodities37022 Node: Declaring commodities37046
Ref: #declaring-commodities37205 Ref: #declaring-commodities37229
Node: Default commodity38866 Node: Default commodity38890
Ref: #default-commodity39042 Ref: #default-commodity39066
Node: Market prices39676 Node: Market prices39700
Ref: #market-prices39841 Ref: #market-prices39865
Node: Declaring accounts40682 Node: Declaring accounts40706
Ref: #declaring-accounts40858 Ref: #declaring-accounts40882
Node: Account comments41783 Node: Account comments41807
Ref: #account-comments41946 Ref: #account-comments41970
Node: Account subdirectives42370 Node: Account subdirectives42394
Ref: #account-subdirectives42565 Ref: #account-subdirectives42589
Node: Account types42878 Node: Account types42902
Ref: #account-types43062 Ref: #account-types43086
Node: Account display order44704 Node: Account display order44728
Ref: #account-display-order44874 Ref: #account-display-order44898
Node: Rewriting accounts46025 Node: Rewriting accounts46049
Ref: #rewriting-accounts46210 Ref: #rewriting-accounts46234
Node: Basic aliases46936 Node: Basic aliases46960
Ref: #basic-aliases47082 Ref: #basic-aliases47106
Node: Regex aliases47786 Node: Regex aliases47810
Ref: #regex-aliases47958 Ref: #regex-aliases47982
Node: Combining aliases48676 Node: Combining aliases48700
Ref: #combining-aliases48854 Ref: #combining-aliases48878
Node: end aliases50130 Node: end aliases50154
Ref: #end-aliases50278 Ref: #end-aliases50302
Node: Default parent account50379 Node: Default parent account50403
Ref: #default-parent-account50545 Ref: #default-parent-account50569
Node: Periodic transactions51429 Node: Periodic transactions51453
Ref: #periodic-transactions51628 Ref: #periodic-transactions51652
Node: Periodic rule syntax53500 Node: Periodic rule syntax53524
Ref: #periodic-rule-syntax53706 Ref: #periodic-rule-syntax53730
Node: Two spaces between period expression and description!54410 Node: Two spaces between period expression and description!54434
Ref: #two-spaces-between-period-expression-and-description54729 Ref: #two-spaces-between-period-expression-and-description54753
Node: Forecasting with periodic transactions55413 Node: Forecasting with periodic transactions55437
Ref: #forecasting-with-periodic-transactions55718 Ref: #forecasting-with-periodic-transactions55742
Node: Budgeting with periodic transactions57744 Node: Budgeting with periodic transactions57768
Ref: #budgeting-with-periodic-transactions57983 Ref: #budgeting-with-periodic-transactions58007
Node: Auto postings / transaction modifiers58432 Node: Auto postings / transaction modifiers58456
Ref: #auto-postings-transaction-modifiers58644 Ref: #auto-postings-transaction-modifiers58668
Node: Auto postings and dates60873 Node: Auto postings and dates61153
Ref: #auto-postings-and-dates61130 Ref: #auto-postings-and-dates61410
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61305 Node: Auto postings and transaction balancing / inferred amounts / balance assertions61585
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61680 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61960
Node: Auto posting tags62058 Node: Auto posting tags62338
Ref: #auto-posting-tags62297 Ref: #auto-posting-tags62577
 
End Tag Table End Tag Table

21
hledger-lib/hledger_journal.txt
View File

@ -211,14 +211,13 @@ FILE FORMAT
Some examples: Some examples:
# a file comment # a file comment
; another file comment
; also a file comment * also a file comment, useful in org/orgstruct mode
comment comment
This is a multiline file comment, A multiline file comment, which continues
which continues until a line until a line containing just "end comment"
where the "end comment" string (or end of file).
appears on its own (or end of file).
end comment end comment
2012/5/14 something ; a transaction comment 2012/5/14 something ; a transaction comment
@ -661,9 +660,6 @@ FILE FORMAT
tive rective rec- 2018/06) tive rective rec- 2018/06)
tives tives
------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------
account any document account names, de- all entries in all account any document account names, de- all entries in all
text clare account types & dis- files, before or text clare account types & dis- files, before or
play order after play order after
@ -1304,6 +1300,13 @@ FILE FORMAT
symbol S). The matched posting's amount will be multiplied by N, and symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S. its commodity symbol will be replaced with S.
A query term containing spaces must be enclosed in single or double
quotes, as on the command line. Eg, note the quotes around the second
query term below:
= expenses:groceries 'expenses:dining out'
(budget:funds:dining out) *-1
These rules have global effect - a rule appearing anywhere in your data These rules have global effect - a rule appearing anywhere in your data
can potentially affect any transaction, including transactions recorded can potentially affect any transaction, including transactions recorded
above it or in another file. above it or in another file.

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

@ -428,6 +428,27 @@ Default: the full terminal width.
\f[C]-f\f[R]. \f[C]-f\f[R].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[R]). \f[C]C:/Users/USER/.hledger.journal\f[R]).
.PP
A typical value is \f[C]\[ti]/DIR/YYYY.journal\f[R], where DIR is a
version-controlled finance directory and YYYY is the current year.
Or \f[C]\[ti]/DIR/current.journal\f[R], where current.journal is a
symbolic link to YYYY.journal.
.PP
On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon).
Eg on MacOS Catalina I have a \f[C]\[ti]/.MacOSX/environment.plist\f[R]
file containing
.IP
.nf
\f[C]
{
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/current.journal\[dq]
}
\f[R]
.fi
.PP
To see the effect you may need to \f[C]killall Dock\f[R], or reboot.
.SH FILES .SH FILES
.PP .PP
Reads data from one or more files in hledger journal, timeclock, Reads data from one or more files in hledger journal, timeclock,

24
hledger-ui/hledger-ui.info
View File

@ -446,6 +446,22 @@ File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: SCREENS, Up: To
Default: '~/.hledger.journal' (on windows, perhaps Default: '~/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). 'C:/Users/USER/.hledger.journal').
A typical value is '~/DIR/YYYY.journal', where DIR is a
version-controlled finance directory and YYYY is the current year. Or
'~/DIR/current.journal', where current.journal is a symbolic link to
YYYY.journal.
On Mac computers, you can set this and other environment variables in
a more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
'~/.MacOSX/environment.plist' file containing
{
"LEDGER_FILE" : "~/finance/current.journal"
}
To see the effect you may need to 'killall Dock', or reboot.
 
File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
@ -504,10 +520,10 @@ Node: Error screen15173
Ref: #error-screen15295 Ref: #error-screen15295
Node: ENVIRONMENT15539 Node: ENVIRONMENT15539
Ref: #environment15653 Ref: #environment15653
Node: FILES15880 Node: FILES16460
Ref: #files15979 Ref: #files16559
Node: BUGS16192 Node: BUGS16772
Ref: #bugs16269 Ref: #bugs16849
 
End Tag Table End Tag Table

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

@ -378,6 +378,21 @@ ENVIRONMENT
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal). nal).
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
rent.journal, where current.journal is a symbolic link to YYYY.journal.
On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en-
vironment.plist file containing
{
"LEDGER_FILE" : "~/finance/current.journal"
}
To see the effect you may need to killall Dock, or reboot.
FILES FILES
Reads data from one or more files in hledger journal, timeclock, time- Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or dot, or CSV format specified with -f, or $LEDGER_FILE, or

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

@ -375,6 +375,27 @@ only want to serve the API.
\f[C]-f\f[R]. \f[C]-f\f[R].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[R]). \f[C]C:/Users/USER/.hledger.journal\f[R]).
.PP
A typical value is \f[C]\[ti]/DIR/YYYY.journal\f[R], where DIR is a
version-controlled finance directory and YYYY is the current year.
Or \f[C]\[ti]/DIR/current.journal\f[R], where current.journal is a
symbolic link to YYYY.journal.
.PP
On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon).
Eg on MacOS Catalina I have a \f[C]\[ti]/.MacOSX/environment.plist\f[R]
file containing
.IP
.nf
\f[C]
{
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/current.journal\[dq]
}
\f[R]
.fi
.PP
To see the effect you may need to \f[C]killall Dock\f[R], or reboot.
.SH FILES .SH FILES
.PP .PP
Reads data from one or more files in hledger journal, timeclock, Reads data from one or more files in hledger journal, timeclock,

24
hledger-web/hledger-web.info
View File

@ -379,6 +379,22 @@ File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: JSON API, Up:
Default: '~/.hledger.journal' (on windows, perhaps Default: '~/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). 'C:/Users/USER/.hledger.journal').
A typical value is '~/DIR/YYYY.journal', where DIR is a
version-controlled finance directory and YYYY is the current year. Or
'~/DIR/current.journal', where current.journal is a symbolic link to
YYYY.journal.
On Mac computers, you can set this and other environment variables in
a more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a
'~/.MacOSX/environment.plist' file containing
{
"LEDGER_FILE" : "~/finance/current.journal"
}
To see the effect you may need to 'killall Dock', or reboot.
 
File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
@ -422,10 +438,10 @@ Node: JSON API11063
Ref: #json-api11177 Ref: #json-api11177
Node: ENVIRONMENT12618 Node: ENVIRONMENT12618
Ref: #environment12734 Ref: #environment12734
Node: FILES12887 Node: FILES13467
Ref: #files12987 Ref: #files13567
Node: BUGS13200 Node: BUGS13780
Ref: #bugs13278 Ref: #bugs13858
 
End Tag Table End Tag Table

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

@ -333,6 +333,21 @@ ENVIRONMENT
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal). nal).
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
rent.journal, where current.journal is a symbolic link to YYYY.journal.
On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en-
vironment.plist file containing
{
"LEDGER_FILE" : "~/finance/current.journal"
}
To see the effect you may need to killall Dock, or reboot.
FILES FILES
Reads data from one or more files in hledger journal, timeclock, time- Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or dot, or CSV format specified with -f, or $LEDGER_FILE, or

2
hledger/Hledger/Cli/Commands/Balance.txt
View File

@ -289,7 +289,7 @@ Balance changes in 2008:
------------++--------------------------------------------------- ------------++---------------------------------------------------
|| $-1 $1 0 0 0 0 || $-1 $1 0 0 0 0
# Average is rounded to the dollar here since all journal amounts are (Average is rounded to the dollar here since all journal amounts are)
Limitations: Limitations:

2
hledger/Hledger/Cli/Commands/Print.txt
View File

@ -63,7 +63,7 @@ ignoring already-seen entries in import data, such as downloaded CSV
files. Eg: files. Eg:
$ hledger -f bank1.csv print --new $ hledger -f bank1.csv print --new
# shows transactions added since last print --new on this file (shows transactions added since last print --new on this file)
This assumes that transactions added to FILE always have same or This assumes that transactions added to FILE always have same or
increasing dates, and that transactions on the same day do not get increasing dates, and that transactions on the same day do not get

704
hledger/hledger.1
View File

@ -68,84 +68,439 @@ follow the prompts.
Then try some commands like \f[C]hledger print\f[R] or Then try some commands like \f[C]hledger print\f[R] or
\f[C]hledger balance\f[R]. \f[C]hledger balance\f[R].
Run \f[C]hledger\f[R] with no arguments for a list of commands. Run \f[C]hledger\f[R] with no arguments for a list of commands.
.SH EXAMPLES .SH COMMON TASKS
.PP .PP
Two simple transactions in hledger journal format: Here are some quick examples of how to do some basic tasks with hledger.
For more details, see the reference section below, the
hledger_journal(5) manual, or the more extensive docs at
https://hledger.org.
.SS Get help
.IP .IP
.nf .nf
\f[C] \f[C]
2015/9/30 gift received $ hledger # show available commands
assets:cash $20 $ hledger --help # show common options
income:gifts $ hledger CMD --help # show common and command options, and command help
$ hledger help # show available manuals/topics
2015/10/16 farmers market $ hledger help hledger # show hledger manual as info/man/text (auto-chosen)
expenses:food $10 $ hledger help journal --man # show the journal manual as a man page
assets:cash $ hledger help --help # show more detailed help for the help command
\f[R] \f[R]
.fi .fi
.PP .PP
Some basic reports: Find more docs, chat, mail list, reddit, issue tracker:
https://hledger.org#help-feedback
.SS Starting a Journal
.PP
hledger looks for your accounting data in a journal file,
\f[C]$HOME/.hledger.journal\f[R] by default:
.IP
.nf
\f[C]
$ hledger stats
The hledger journal file \[dq]/Users/simon/.hledger.journal\[dq] was not found.
Please create it first, eg with \[dq]hledger add\[dq] or a text editor.
Or, specify an existing journal file with -f or LEDGER_FILE.
\f[R]
.fi
.PP
You can override this by setting the \f[C]LEDGER_FILE\f[R] environment
variable.
It\[aq]s a good practice to keep this important file under version
control, and to start a new file each year.
So you could do something like this:
.IP
.nf
\f[C]
$ mkdir \[ti]/finance
$ cd \[ti]/finance
$ git init
Initialized empty Git repository in /Users/simon/finance/.git/
$ touch 2020.journal
$ echo \[dq]export LEDGER_FILE=$HOME/finance/2020.journal\[dq] >> \[ti]/.bashrc
$ source \[ti]/.bashrc
$ hledger stats
Main file : /Users/simon/finance/2020.journal
Included files :
Transactions span : to (0 days)
Last transaction : none
Transactions : 0 (0.0 per day)
Transactions last 30 days: 0 (0.0 per day)
Transactions last 7 days : 0 (0.0 per day)
Payees/descriptions : 0
Accounts : 0 (depth 0)
Commodities : 0 ()
Market prices : 0 ()
\f[R]
.fi
.SS Setting Opening Balances
.PP
Pick a starting date for which you can look up the balances of some
real-world assets (bank accounts, wallet..) and liabilities (credit
cards..).
.PP
To avoid a lot of data entry, you may want to start with just one or two
accounts, like your checking account or cash wallet; and pick a recent
starting date, like today or the start of the week.
You can always come back later and add more accounts and older
transactions, eg going back to january 1st.
.PP
Add an opening balances transaction to the journal, declaring the
balances on this date.
Here are two ways to do it:
.IP \[bu] 2
The first way: open the journal in any text editor and save an entry
like this:
.RS 2
.IP
.nf
\f[C]
2020-01-01 * opening balances
assets:bank:checking $1000 = $1000
assets:bank:savings $2000 = $2000
assets:cash $100 = $100
liabilities:creditcard $-50 = $-$50
equity:opening/closing balances
\f[R]
.fi
.PP
These are start-of-day balances, ie whatever was in the account at the
end of the previous day.
.PP
The * after the date is an optional status flag.
Here it means \[dq]cleared & confirmed\[dq].
.PP
The currency symbols are optional, but usually a good idea as you\[aq]ll
be dealing with multiple currencies sooner or later.
.PP
The = amounts are optional balance assertions, providing extra error
checking.
.RE
.IP \[bu] 2
The second way: run \f[C]hledger add\f[R] and follow the prompts to
record a similar transaction:
.RS 2
.IP
.nf
\f[C]
$ hledger add
Adding transactions to journal file /Users/simon/finance/2020.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 go one step backward.
To end a transaction, enter . when prompted.
To quit, enter . at a date prompt or press control-d or control-c.
Date [2020-02-07]: 2020-01-01
Description: * opening balances
Account 1: assets:bank:checking
Amount 1: $1000
Account 2: assets:bank:savings
Amount 2 [$-1000]: $2000
Account 3: assets:cash
Amount 3 [$-3000]: $100
Account 4: liabilities:creditcard
Amount 4 [$-3100]: $-50
Account 5: equity:opening/closing balances
Amount 5 [$-3050]:
Account 6 (or . or enter to finish this transaction): .
2020-01-01 * opening balances
assets:bank:checking $1000
assets:bank:savings $2000
assets:cash $100
liabilities:creditcard $-50
equity:opening/closing balances $-3050
Save this transaction to the journal ? [y]:
Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2020-01-01]: .
\f[R]
.fi
.RE
.PP
If you\[aq]re using version control, this could be a good time to commit
the journal.
Eg:
.IP
.nf
\f[C]
$ git commit -am \[aq]initial balances\[aq] 2020.journal
\f[R]
.fi
.SS Recording Transactions
.PP
As you spend or receive money, you can record these transactions using
one of the methods above (text editor, hledger add) or by using the
hledger-iadd or hledger-web add-ons, or by using the import command to
convert CSV data downloaded from your bank.
.PP
Here are some simple transactions, see the hledger_journal(5) manual and
hledger.org for more ideas:
.IP
.nf
\f[C]
2020/1/10 * gift received
assets:cash $20
income:gifts
2020.1.12 * farmers market
expenses:food $13
assets:cash
2020-01-15 paycheck
income:salary
assets:bank:checking $1000
\f[R]
.fi
.SS Reconciling
.PP
Periodically you should reconcile - compare your hledger-reported
balances against external sources of truth, like bank statements or your
bank\[aq]s website - to be sure that your ledger accurately represents
the real-world balances (and, that the real-world institutions have not
made a mistake!).
This gets easy and fast with (1) practice and (2) frequency.
If you do it daily, it can take 2-10 minutes.
If you let it pile up, expect it to take longer as you hunt down errors
and discrepancies.
.PP
A typical workflow:
.IP "1." 3
Reconcile cash.
Count what\[aq]s in your wallet.
Compare with what hledger reports (\f[C]hledger bal cash\f[R]).
If they are different, try to remember the missing transaction, or look
for the error in the already-recorded transactions.
A register report can be helpful (\f[C]hledger reg cash\f[R]).
If you can\[aq]t find the error, add an adjustment transaction.
Eg if you have $105 after the above, and can\[aq]t explain the missing
$2, it could be:
.RS 4
.IP
.nf
\f[C]
2020-01-16 * adjust cash
assets:cash $-2 = $105
expenses:misc
\f[R]
.fi
.RE
.IP "2." 3
Reconcile checking.
Log in to your bank\[aq]s website.
Compare today\[aq]s (cleared) balance with hledger\[aq]s cleared balance
(\f[C]hledger bal checking -C\f[R]).
If they are different, track down the error or record the missing
transaction(s) or add an adjustment transaction, similar to the above.
Unlike the cash case, you can usually compare the transaction history
and running balance from your bank with the one reported by
\f[C]hledger reg checking -C\f[R].
This will be easier if you generally record transaction dates quite
similar to your bank\[aq]s clearing dates.
.IP "3." 3
Repeat for other asset/liability accounts.
.PP
Tip: instead of the register command, use hledger-ui to see a
live-updating register while you edit the journal:
\f[C]hledger-ui --watch --register checking -C\f[R]
.PP
After reconciling, it could be a good time to mark the reconciled
transactions\[aq] status as \[dq]cleared and confirmed\[dq], if you want
to track that, by adding the \f[C]*\f[R] marker.
Eg in the paycheck transaction above, insert \f[C]*\f[R] between
\f[C]2020-01-15\f[R] and \f[C]paycheck\f[R]
.PP
If you\[aq]re using version control, this can be another good time to
commit:
.IP
.nf
\f[C]
$ git commit -am \[aq]txns\[aq] 2020.journal
\f[R]
.fi
.SS Reporting
.PP
Here are some basic reports.
.PP
Show all transactions:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger print $ hledger print
2015-09-30 gift received 2020-01-01 * opening balances
assets:cash $20 assets:bank:checking $1000
income:gifts $-20 assets:bank:savings $2000
assets:cash $100
liabilities:creditcard $-50
equity:opening/closing balances $-3050
2015-10-16 farmers market 2020-01-10 * gift received
expenses:food $10 assets:cash $20
assets:cash $-10 income:gifts
2020-01-12 * farmers market
expenses:food $13
assets:cash
2020-01-15 * paycheck
income:salary
assets:bank:checking $1000
2020-01-16 * adjust cash
assets:cash $-2 = $105
expenses:misc
\f[R] \f[R]
.fi .fi
.PP
Show account names, and their hierarchy:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger accounts --tree $ hledger accounts --tree
assets assets
bank
checking
savings
cash cash
equity
opening/closing balances
expenses expenses
food food
misc
income income
gifts gifts
salary
liabilities
creditcard
\f[R] \f[R]
.fi .fi
.PP
Show all account totals:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger balance $ hledger balance
$10 assets:cash $4105 assets
$10 expenses:food $4000 bank
$-20 income:gifts $2000 checking
$2000 savings
$105 cash
$-3050 equity:opening/closing balances
$15 expenses
$13 food
$2 misc
$-1020 income
$-20 gifts
$-1000 salary
$-50 liabilities:creditcard
-------------------- --------------------
0 0
\f[R] \f[R]
.fi .fi
.PP
Show only asset and liability balances, as a flat list, limited to depth
2:
.IP
.nf
\f[C]
$ hledger bal assets liabilities --flat -2
$4000 assets:bank
$105 assets:cash
$-50 liabilities:creditcard
--------------------
$4055
\f[R]
.fi
.PP
Show the same thing without negative numbers, formatted as a simple
balance sheet:
.IP
.nf
\f[C]
$ hledger bs --flat -2
Balance Sheet 2020-01-16
|| 2020-01-16
========================++============
Assets ||
------------------------++------------
assets:bank || $4000
assets:cash || $105
------------------------++------------
|| $4105
========================++============
Liabilities ||
------------------------++------------
liabilities:creditcard || $50
------------------------++------------
|| $50
========================++============
Net: || $4055
\f[R]
.fi
.PP
The final total is your \[dq]net worth\[dq] on the end date.
(Or use \f[C]bse\f[R] for a full balance sheet with equity.)
.PP
Show income and expense totals, formatted as an income statement:
.IP
.nf
\f[C]
hledger is
Income Statement 2020-01-01-2020-01-16
|| 2020-01-01-2020-01-16
===============++=======================
Revenues ||
---------------++-----------------------
income:gifts || $20
income:salary || $1000
---------------++-----------------------
|| $1020
===============++=======================
Expenses ||
---------------++-----------------------
expenses:food || $13
expenses:misc || $2
---------------++-----------------------
|| $15
===============++=======================
Net: || $1005
\f[R]
.fi
.PP
The final total is your net income during this period.
.PP
Show transactions affecting your wallet, with running total:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger register cash $ hledger register cash
2015-09-30 gift received assets:cash $20 $20 2020-01-01 opening balances assets:cash $100 $100
2015-10-16 farmers market assets:cash $-10 $10 2020-01-10 gift received assets:cash $20 $120
2020-01-12 farmers market assets:cash $-13 $107
2020-01-16 adjust cash assets:cash $-2 $105
\f[R] \f[R]
.fi .fi
.PP .PP
More commands: Show weekly posting counts as a bar chart:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger # show available commands $ hledger activity -W
$ hledger add # add more transactions to the journal file 2019-12-30 *****
$ hledger balance # all accounts with aggregated balances 2020-01-06 ****
$ hledger balance --help # show detailed help for balance command 2020-01-13 ****
$ 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[R] \f[R]
.fi .fi
.SS Starting a New File
.PP
At the end of the year, you may want to continue your journal in a new
file, so that old transactions don\[aq]t slow down or clutter your
reports, and to help ensure the integrity of your accounting history.
See the close command.
.SH OPTIONS .SH OPTIONS
.SS General options .SS General options
.PP .PP
@ -273,7 +628,6 @@ Or, you can run the addon executable directly:
.PP .PP
Most hledger commands accept arguments after the command name, which are Most hledger commands accept arguments after the command name, which are
often a query, filtering the data in some way. often a query, filtering the data in some way.
.SS Argument files
.PP .PP
You can save a set of command line options/arguments in a file, and then You can save a set of command line options/arguments in a file, and then
reuse them by writing \f[C]\[at]FILENAME\f[R] as a command line reuse them by writing \f[C]\[at]FILENAME\f[R] as a command line
@ -326,6 +680,120 @@ Good:
.fi .fi
.PP .PP
See also: Save frequently used options. See also: Save frequently used options.
.SS Queries
.PP
One of hledger\[aq]s strengths is being able to quickly report on
precise subsets of your data.
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, prefixes to match specific
fields, a not: prefix to negate the match.
.PP
We do not yet support arbitrary boolean combinations of search terms;
instead most commands 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
any of the status terms AND
.IP \[bu] 2
all the other terms.
.PP
The print command instead shows 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.
Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R], eg
to exclude a particular subaccount.
.TP
\f[B]\f[R]\f[C]REGEX\f[R]\f[B], \f[R]\f[C]acct:REGEX\f[R]\f[B]\f[R]
match account names by this regular expression.
(With no prefix, \f[C]acct:\f[R] is assumed.)
same as above
.TP
\f[B]\f[R]\f[C]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[R]\f[B]\f[R]
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.
.TP
\f[B]\f[R]\f[C]code:REGEX\f[R]\f[B]\f[R]
match by transaction code (eg check number)
.TP
\f[B]\f[R]\f[C]cur:REGEX\f[R]\f[B]\f[R]
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[R]).
Note, to match characters which are regex-significant, like the dollar
sign (\f[C]$\f[R]), you need to prepend \f[C]\[rs]\f[R].
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]\[rs]$\[aq]\f[R] or
\f[C]hledger print cur:\[rs]\[rs]$\f[R].
.TP
\f[B]\f[R]\f[C]desc:REGEX\f[R]\f[B]\f[R]
match transaction descriptions.
.TP
\f[B]\f[R]\f[C]date:PERIODEXPR\f[R]\f[B]\f[R]
match dates within the specified period.
PERIODEXPR is a period expression (with no report interval).
Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R],
\f[C]date:2000/2/1-2/15\f[R], \f[C]date:lastweek-\f[R].
If the \f[C]--date2\f[R] command line flag is present, this matches
secondary dates instead.
.TP
\f[B]\f[R]\f[C]date2:PERIODEXPR\f[R]\f[B]\f[R]
match secondary dates within the specified period.
.TP
\f[B]\f[R]\f[C]depth:N\f[R]\f[B]\f[R]
match (or display, depending on command) accounts at or above this depth
.TP
\f[B]\f[R]\f[C]note:REGEX\f[R]\f[B]\f[R]
match transaction notes (part of description right of \f[C]|\f[R], or
whole description when there\[aq]s no \f[C]|\f[R])
.TP
\f[B]\f[R]\f[C]payee:REGEX\f[R]\f[B]\f[R]
match transaction payee/payer names (part of description left of
\f[C]|\f[R], or whole description when there\[aq]s no \f[C]|\f[R])
.TP
\f[B]\f[R]\f[C]real:, real:0\f[R]\f[B]\f[R]
match real or virtual postings respectively
.TP
\f[B]\f[R]\f[C]status:, status:!, status:*\f[R]\f[B]\f[R]
match unmarked, pending, or cleared transactions respectively
.TP
\f[B]\f[R]\f[C]tag:REGEX[=REGEX]\f[R]\f[B]\f[R]
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.
.PP
The following special search term is used automatically in hledger-web,
only:
.TP
\f[B]\f[R]\f[C]inacct:ACCTNAME\f[R]\f[B]\f[R]
tells hledger-web to show the transaction register for this account.
Can be filtered further with \f[C]acct\f[R] etc.
.PP
Some of these can also be expressed as command-line options (eg
\f[C]depth:2\f[R] is equivalent to \f[C]--depth 2\f[R]).
Generally you can mix options and query arguments, and the resulting
query will be their intersection (perhaps excluding the
\f[C]-p/--period\f[R] option).
.SS Special characters in arguments and queries .SS Special characters in arguments and queries
.PP .PP
In shell command lines, option and argument values which contain In shell command lines, option and argument values which contain
@ -1650,120 +2118,6 @@ Eg to search for amounts with the dollar sign in hledger-web, write
On the command line, some metacharacters like \f[C]$\f[R] have a special On the command line, some metacharacters like \f[C]$\f[R] have a special
meaning to the shell and so must be escaped at least once more. meaning to the shell and so must be escaped at least once more.
See Special characters. See Special characters.
.SH QUERIES
.PP
One of hledger\[aq]s strengths is being able to quickly report on
precise subsets of your data.
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, prefixes to match specific
fields, a not: prefix to negate the match.
.PP
We do not yet support arbitrary boolean combinations of search terms;
instead most commands 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
any of the status terms AND
.IP \[bu] 2
all the other terms.
.PP
The print command instead shows 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.
Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R], eg
to exclude a particular subaccount.
.TP
\f[B]\f[R]\f[C]REGEX\f[R]\f[B], \f[R]\f[C]acct:REGEX\f[R]\f[B]\f[R]
match account names by this regular expression.
(With no prefix, \f[C]acct:\f[R] is assumed.)
same as above
.TP
\f[B]\f[R]\f[C]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[R]\f[B]\f[R]
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.
.TP
\f[B]\f[R]\f[C]code:REGEX\f[R]\f[B]\f[R]
match by transaction code (eg check number)
.TP
\f[B]\f[R]\f[C]cur:REGEX\f[R]\f[B]\f[R]
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[R]).
Note, to match characters which are regex-significant, like the dollar
sign (\f[C]$\f[R]), you need to prepend \f[C]\[rs]\f[R].
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]\[rs]$\[aq]\f[R] or
\f[C]hledger print cur:\[rs]\[rs]$\f[R].
.TP
\f[B]\f[R]\f[C]desc:REGEX\f[R]\f[B]\f[R]
match transaction descriptions.
.TP
\f[B]\f[R]\f[C]date:PERIODEXPR\f[R]\f[B]\f[R]
match dates within the specified period.
PERIODEXPR is a period expression (with no report interval).
Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R],
\f[C]date:2000/2/1-2/15\f[R], \f[C]date:lastweek-\f[R].
If the \f[C]--date2\f[R] command line flag is present, this matches
secondary dates instead.
.TP
\f[B]\f[R]\f[C]date2:PERIODEXPR\f[R]\f[B]\f[R]
match secondary dates within the specified period.
.TP
\f[B]\f[R]\f[C]depth:N\f[R]\f[B]\f[R]
match (or display, depending on command) accounts at or above this depth
.TP
\f[B]\f[R]\f[C]note:REGEX\f[R]\f[B]\f[R]
match transaction notes (part of description right of \f[C]|\f[R], or
whole description when there\[aq]s no \f[C]|\f[R])
.TP
\f[B]\f[R]\f[C]payee:REGEX\f[R]\f[B]\f[R]
match transaction payee/payer names (part of description left of
\f[C]|\f[R], or whole description when there\[aq]s no \f[C]|\f[R])
.TP
\f[B]\f[R]\f[C]real:, real:0\f[R]\f[B]\f[R]
match real or virtual postings respectively
.TP
\f[B]\f[R]\f[C]status:, status:!, status:*\f[R]\f[B]\f[R]
match unmarked, pending, or cleared transactions respectively
.TP
\f[B]\f[R]\f[C]tag:REGEX[=REGEX]\f[R]\f[B]\f[R]
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.
.PP
The following special search term is used automatically in hledger-web,
only:
.TP
\f[B]\f[R]\f[C]inacct:ACCTNAME\f[R]\f[B]\f[R]
tells hledger-web to show the transaction register for this account.
Can be filtered further with \f[C]acct\f[R] etc.
.PP
Some of these can also be expressed as command-line options (eg
\f[C]depth:2\f[R] is equivalent to \f[C]--depth 2\f[R]).
Generally you can mix options and query arguments, and the resulting
query will be their intersection (perhaps excluding the
\f[C]-p/--period\f[R] option).
.SH COMMANDS .SH COMMANDS
.PP .PP
hledger provides a number of subcommands; \f[C]hledger\f[R] with no hledger provides a number of subcommands; \f[C]hledger\f[R] with no
@ -2284,7 +2638,7 @@ Balance changes in 2008:
------------++--------------------------------------------------- ------------++---------------------------------------------------
|| $-1 $1 0 0 0 0 || $-1 $1 0 0 0 0
# Average is rounded to the dollar here since all journal amounts are (Average is rounded to the dollar here since all journal amounts are)
\f[R] \f[R]
.fi .fi
.PP .PP
@ -3170,7 +3524,7 @@ Eg:
.nf .nf
\f[C] \f[C]
$ hledger -f bank1.csv print --new $ hledger -f bank1.csv print --new
# shows transactions added since last print --new on this file (shows transactions added since last print --new on this file)
\f[R] \f[R]
.fi .fi
.PP .PP
@ -3677,7 +4031,7 @@ $ hledger test -- -pData.Amount --color=never
.PP .PP
For help on these, see https://github.com/feuerbach/tasty#options For help on these, see https://github.com/feuerbach/tasty#options
(\f[C]-- --help\f[R] currently doesn\[aq]t show them). (\f[C]-- --help\f[R] currently doesn\[aq]t show them).
.SH ADD-ON COMMANDS .SS Add-on Commands
.PP .PP
hledger also searches for external add-on commands, and will include hledger also searches for external add-on commands, and will include
these in the commands list. these in the commands list.
@ -3708,20 +4062,17 @@ advantage: they can use the same hledger (and haskell) library functions
that built-in commands do, for command-line options, journal parsing, that built-in commands do, for command-line options, journal parsing,
reporting, etc. reporting, etc.
.PP .PP
Here are some hledger add-ons available: Two important add-ons are the hledger-ui and hledger-web user
.SS Official add-ons interfaces.
.PP These are maintained and released along with hledger:
These are maintained and released along with hledger.
.SS ui .SS ui
.PP .PP
hledger-ui provides an efficient terminal interface. hledger-ui provides an efficient terminal interface.
.SS web .SS web
.PP .PP
hledger-web provides a simple web interface. hledger-web provides a simple web interface.
.SS Third party add-ons
.PP .PP
These are maintained separately, and usually updated shortly after a Third party add-ons, maintained separately from hledger, include:
hledger release.
.SS iadd .SS iadd
.PP .PP
hledger-iadd is a more interactive, terminal UI replacement for the add hledger-iadd is a more interactive, terminal UI replacement for the add
@ -3730,22 +4081,10 @@ command.
.PP .PP
hledger-interest generates interest transactions for an account hledger-interest generates interest transactions for an account
according to various schemes. according to various schemes.
.SS Experimental add-ons
.PP .PP
These are available in source form in the hledger repo\[aq]s bin/ A few more experimental or old add-ons can be found in hledger\[aq]s
directory. bin/ directory.
They may be less mature and documented than built-in commands. These are typically prototypes and not guaranteed to work.
Reading and tweaking these is a good way to start making your own!
.SS autosync
.PP
hledger-autosync is a symbolic link for easily running ledger-autosync,
if installed.
ledger-autosync does deduplicating conversion of OFX data and some CSV
formats, and can also download the data if your bank offers OFX Direct
Connect.
.SS chart
.PP
hledger-chart.hs is an old very basic pie chart generator.
.SH ENVIRONMENT .SH ENVIRONMENT
.PP .PP
\f[B]COLUMNS\f[R] The screen width used by the register command. \f[B]COLUMNS\f[R] The screen width used by the register command.
@ -3755,6 +4094,27 @@ Default: the full terminal width.
\f[C]-f\f[R]. \f[C]-f\f[R].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[R]). \f[C]C:/Users/USER/.hledger.journal\f[R]).
.PP
A typical value is \f[C]\[ti]/DIR/YYYY.journal\f[R], where DIR is a
version-controlled finance directory and YYYY is the current year.
Or \f[C]\[ti]/DIR/current.journal\f[R], where current.journal is a
symbolic link to YYYY.journal.
.PP
On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon).
Eg on MacOS Catalina I have a \f[C]\[ti]/.MacOSX/environment.plist\f[R]
file containing
.IP
.nf
\f[C]
{
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/current.journal\[dq]
}
\f[R]
.fi
.PP
To see the effect you may need to \f[C]killall Dock\f[R], or reboot.
.SH FILES .SH FILES
.PP .PP
Reads data from one or more files in hledger journal, timeclock, Reads data from one or more files in hledger journal, timeclock,

1244
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

620
hledger/hledger.txt
View File

@ -52,59 +52,355 @@ DESCRIPTION
try some commands like hledger print or hledger balance. Run hledger try some commands like hledger print or hledger balance. Run hledger
with no arguments for a list of commands. with no arguments for a list of commands.
EXAMPLES COMMON TASKS
Two simple transactions in hledger journal format: Here are some quick examples of how to do some basic tasks with
hledger. For more details, see the reference section below, the
hledger_journal(5) manual, or the more extensive docs at
https://hledger.org.
2015/9/30 gift received Get help
$ hledger # show available commands
$ hledger --help # show common options
$ hledger CMD --help # show common and command options, and command help
$ hledger help # show available manuals/topics
$ hledger help hledger # show hledger manual as info/man/text (auto-chosen)
$ hledger help journal --man # show the journal manual as a man page
$ hledger help --help # show more detailed help for the help command
Find more docs, chat, mail list, reddit, issue tracker:
https://hledger.org#help-feedback
Starting a Journal
hledger looks for your accounting data in a journal file,
$HOME/.hledger.journal by default:
$ hledger stats
The hledger journal file "/Users/simon/.hledger.journal" was not found.
Please create it first, eg with "hledger add" or a text editor.
Or, specify an existing journal file with -f or LEDGER_FILE.
You can override this by setting the LEDGER_FILE environment variable.
It's a good practice to keep this important file under version control,
and to start a new file each year. So you could do something like
this:
$ mkdir ~/finance
$ cd ~/finance
$ git init
Initialized empty Git repository in /Users/simon/finance/.git/
$ touch 2020.journal
$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc
$ source ~/.bashrc
$ hledger stats
Main file : /Users/simon/finance/2020.journal
Included files :
Transactions span : to (0 days)
Last transaction : none
Transactions : 0 (0.0 per day)
Transactions last 30 days: 0 (0.0 per day)
Transactions last 7 days : 0 (0.0 per day)
Payees/descriptions : 0
Accounts : 0 (depth 0)
Commodities : 0 ()
Market prices : 0 ()
Setting Opening Balances
Pick a starting date for which you can look up the balances of some
real-world assets (bank accounts, wallet..) and liabilities (credit
cards..).
To avoid a lot of data entry, you may want to start with just one or
two accounts, like your checking account or cash wallet; and pick a re-
cent starting date, like today or the start of the week. You can al-
ways come back later and add more accounts and older transactions, eg
going back to january 1st.
Add an opening balances transaction to the journal, declaring the bal-
ances on this date. Here are two ways to do it:
o The first way: open the journal in any text editor and save an entry
like this:
2020-01-01 * opening balances
assets:bank:checking $1000 = $1000
assets:bank:savings $2000 = $2000
assets:cash $100 = $100
liabilities:creditcard $-50 = $-$50
equity:opening/closing balances
These are start-of-day balances, ie whatever was in the account at
the end of the previous day.
The * after the date is an optional status flag. Here it means
"cleared & confirmed".
The currency symbols are optional, but usually a good idea as you'll
be dealing with multiple currencies sooner or later.
The = amounts are optional balance assertions, providing extra error
checking.
o The second way: run hledger add and follow the prompts to record a
similar transaction:
$ hledger add
Adding transactions to journal file /Users/simon/finance/2020.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 go one step backward.
To end a transaction, enter . when prompted.
To quit, enter . at a date prompt or press control-d or control-c.
Date [2020-02-07]: 2020-01-01
Description: * opening balances
Account 1: assets:bank:checking
Amount 1: $1000
Account 2: assets:bank:savings
Amount 2 [$-1000]: $2000
Account 3: assets:cash
Amount 3 [$-3000]: $100
Account 4: liabilities:creditcard
Amount 4 [$-3100]: $-50
Account 5: equity:opening/closing balances
Amount 5 [$-3050]:
Account 6 (or . or enter to finish this transaction): .
2020-01-01 * opening balances
assets:bank:checking $1000
assets:bank:savings $2000
assets:cash $100
liabilities:creditcard $-50
equity:opening/closing balances $-3050
Save this transaction to the journal ? [y]:
Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2020-01-01]: .
If you're using version control, this could be a good time to commit
the journal. Eg:
$ git commit -am 'initial balances' 2020.journal
Recording Transactions
As you spend or receive money, you can record these transactions using
one of the methods above (text editor, hledger add) or by using the
hledger-iadd or hledger-web add-ons, or by using the import command to
convert CSV data downloaded from your bank.
Here are some simple transactions, see the hledger_journal(5) manual
and hledger.org for more ideas:
2020/1/10 * gift received
assets:cash $20 assets:cash $20
income:gifts income:gifts
2015/10/16 farmers market 2020.1.12 * farmers market
expenses:food $10 expenses:food $13
assets:cash assets:cash
Some basic reports: 2020-01-15 paycheck
income:salary
assets:bank:checking $1000
Reconciling
Periodically you should reconcile - compare your hledger-reported bal-
ances against external sources of truth, like bank statements or your
bank's website - to be sure that your ledger accurately represents the
real-world balances (and, that the real-world institutions have not
made a mistake!). This gets easy and fast with (1) practice and (2)
frequency. If you do it daily, it can take 2-10 minutes. If you let
it pile up, expect it to take longer as you hunt down errors and dis-
crepancies.
A typical workflow:
1. Reconcile cash. Count what's in your wallet. Compare with what
hledger reports (hledger bal cash). If they are different, try to
remember the missing transaction, or look for the error in the al-
ready-recorded transactions. A register report can be helpful
(hledger reg cash). If you can't find the error, add an adjustment
transaction. Eg if you have $105 after the above, and can't explain
the missing $2, it could be:
2020-01-16 * adjust cash
assets:cash $-2 = $105
expenses:misc
2. Reconcile checking. Log in to your bank's website. Compare today's
(cleared) balance with hledger's cleared balance (hledger bal check-
ing -C). If they are different, track down the error or record the
missing transaction(s) or add an adjustment transaction, similar to
the above. Unlike the cash case, you can usually compare the trans-
action history and running balance from your bank with the one re-
ported by hledger reg checking -C. This will be easier if you gen-
erally record transaction dates quite similar to your bank's clear-
ing dates.
3. Repeat for other asset/liability accounts.
Tip: instead of the register command, use hledger-ui to see a live-up-
dating register while you edit the journal: hledger-ui --watch --regis-
ter checking -C
After reconciling, it could be a good time to mark the reconciled
transactions' status as "cleared and confirmed", if you want to track
that, by adding the * marker. Eg in the paycheck transaction above,
insert * between 2020-01-15 and paycheck
If you're using version control, this can be another good time to com-
mit:
$ git commit -am 'txns' 2020.journal
Reporting
Here are some basic reports.
Show all transactions:
$ hledger print $ hledger print
2015-09-30 gift received 2020-01-01 * opening balances
assets:cash $20 assets:bank:checking $1000
income:gifts $-20 assets:bank:savings $2000
assets:cash $100
liabilities:creditcard $-50
equity:opening/closing balances $-3050
2015-10-16 farmers market 2020-01-10 * gift received
expenses:food $10 assets:cash $20
assets:cash $-10 income:gifts
2020-01-12 * farmers market
expenses:food $13
assets:cash
2020-01-15 * paycheck
income:salary
assets:bank:checking $1000
2020-01-16 * adjust cash
assets:cash $-2 = $105
expenses:misc
Show account names, and their hierarchy:
$ hledger accounts --tree $ hledger accounts --tree
assets assets
bank
checking
savings
cash cash
equity
opening/closing balances
expenses expenses
food food
misc
income income
gifts gifts
salary
liabilities
creditcard
Show all account totals:
$ hledger balance $ hledger balance
$10 assets:cash $4105 assets
$10 expenses:food $4000 bank
$-20 income:gifts $2000 checking
$2000 savings
$105 cash
$-3050 equity:opening/closing balances
$15 expenses
$13 food
$2 misc
$-1020 income
$-20 gifts
$-1000 salary
$-50 liabilities:creditcard
-------------------- --------------------
0 0
Show only asset and liability balances, as a flat list, limited to
depth 2:
$ hledger bal assets liabilities --flat -2
$4000 assets:bank
$105 assets:cash
$-50 liabilities:creditcard
--------------------
$4055
Show the same thing without negative numbers, formatted as a simple
balance sheet:
$ hledger bs --flat -2
Balance Sheet 2020-01-16
|| 2020-01-16
========================++============
Assets ||
------------------------++------------
assets:bank || $4000
assets:cash || $105
------------------------++------------
|| $4105
========================++============
Liabilities ||
------------------------++------------
liabilities:creditcard || $50
------------------------++------------
|| $50
========================++============
Net: || $4055
The final total is your "net worth" on the end date. (Or use bse for a
full balance sheet with equity.)
Show income and expense totals, formatted as an income statement:
hledger is
Income Statement 2020-01-01-2020-01-16
|| 2020-01-01-2020-01-16
===============++=======================
Revenues ||
---------------++-----------------------
income:gifts || $20
income:salary || $1000
---------------++-----------------------
|| $1020
===============++=======================
Expenses ||
---------------++-----------------------
expenses:food || $13
expenses:misc || $2
---------------++-----------------------
|| $15
===============++=======================
Net: || $1005
The final total is your net income during this period.
Show transactions affecting your wallet, with running total:
$ hledger register cash $ hledger register cash
2015-09-30 gift received assets:cash $20 $20 2020-01-01 opening balances assets:cash $100 $100
2015-10-16 farmers market assets:cash $-10 $10 2020-01-10 gift received assets:cash $20 $120
2020-01-12 farmers market assets:cash $-13 $107
2020-01-16 adjust cash assets:cash $-2 $105
More commands: Show weekly posting counts as a bar chart:
$ hledger # show available commands $ hledger activity -W
$ hledger add # add more transactions to the journal file 2019-12-30 *****
$ hledger balance # all accounts with aggregated balances 2020-01-06 ****
$ hledger balance --help # show detailed help for balance command 2020-01-13 ****
$ hledger balance --depth 1 # only top-level accounts
$ hledger register # show account postings, with running total Starting a New File
$ hledger reg income # show postings to/from income accounts At the end of the year, you may want to continue your journal in a new
$ hledger reg 'assets:some bank:checking' # show postings to/from this checking account file, so that old transactions don't slow down or clutter your reports,
$ hledger print desc:shop # show transactions with shop in the description and to help ensure the integrity of your accounting history. See the
$ hledger activity -W # show transaction counts per week as a bar chart close command.
OPTIONS OPTIONS
General options General options
@ -231,7 +527,6 @@ OPTIONS
Most hledger commands accept arguments after the command name, which Most hledger commands accept arguments after the command name, which
are often a query, filtering the data in some way. are often a query, filtering the data in some way.
Argument files
You can save a set of command line options/arguments in a file, and You can save a set of command line options/arguments in a file, and
then reuse them by writing @FILENAME as a command line argument. Eg: then reuse them by writing @FILENAME as a command line argument. Eg:
hledger bal @foo.args. (To prevent this, eg if you have an argument hledger bal @foo.args. (To prevent this, eg if you have an argument
@ -263,6 +558,113 @@ OPTIONS
See also: Save frequently used options. See also: Save frequently used options.
Queries
One of hledger's strengths is being able to quickly report on precise
subsets of your data. Most commands accept an optional query expres-
sion, 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, prefixes to match specific fields, a not: prefix to negate
the match.
We do not yet support arbitrary boolean combinations of search terms;
instead most commands show transactions/postings/accounts which match
(or negatively match):
o any of the description terms AND
o any of the account terms AND
o any of the status terms AND
o all the other terms.
The print command instead shows transactions which:
o match any of the description terms AND
o have any postings matching any of the positive account terms AND
o have no postings matching any of the negative account terms AND
o match all the other terms.
The following kinds of search terms can be used. Remember these can
also be prefixed with not:, eg to exclude a particular subaccount.
REGEX, acct:REGEX
match account names by this regular expression. (With no pre-
fix, acct: is assumed.) 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 cur-
rency/commodity symbol is fully matched by REGEX. (For a par-
tial 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. PERIODEXPR is a period
expression (with no report interval). Examples: date:2016,
date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
--date2 command line flag is present, this matches secondary
dates instead.
date2:PERIODEXPR
match secondary dates within the specified period.
depth:N
match (or display, depending on command) accounts at or above
this depth
note:REGEX
match transaction notes (part of description right of |, or
whole description when there's no |)
payee:REGEX
match transaction payee/payer names (part of description left of
|, or whole description when there's no |)
real:, real:0
match real or virtual postings respectively
status:, status:!, status:*
match unmarked, pending, or cleared 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.
The following special search term is used automatically in hledger-web,
only:
inacct:ACCTNAME
tells hledger-web to show the transaction register for this ac-
count. Can be filtered further with acct etc.
Some of these can also be expressed as command-line options (eg depth:2
is equivalent to --depth 2). Generally you can mix options and query
arguments, and the resulting query will be their intersection (perhaps
excluding the -p/--period option).
Special characters in arguments and queries Special characters in arguments and queries
In shell command lines, option and argument values which contain "prob- In shell command lines, option and argument values which contain "prob-
lematic" characters, ie spaces, and also characters significant to your lematic" characters, ie spaces, and also characters significant to your
@ -457,6 +859,7 @@ OPTIONS
of 8-digit year of 8-digit year
20181232 8 digits with an invalid 20181232 8 digits with an invalid
day gives an error day gives an error
201801012 9+ digits beginning with a 201801012 9+ digits beginning with a
valid YYYYMMDD gives an valid YYYYMMDD gives an
error error
@ -544,7 +947,6 @@ OPTIONS
1, 2009 1, 2009
-p "from 2009/1" the same -p "from 2009/1" the same
-p "from 2009" the same -p "from 2009" the same
-p "to 2009" everything before january -p "to 2009" everything before january
1, 2009 1, 2009
@ -926,6 +1328,9 @@ OPTIONS
print print
posting cost value at report value at report value at posting cost value at report value at report value at
amounts end or today or journal end DATE/today amounts end or today or journal end DATE/today
balance asser- unchanged unchanged unchanged unchanged balance asser- unchanged unchanged unchanged unchanged
tions / as- tions / as-
signments signments
@ -957,8 +1362,6 @@ OPTIONS
report inter- ends of sums of ends of sums of DATE/today of report inter- ends of sums of ends of sums of DATE/today of
val) postings postings sums of post- val) postings postings sums of post-
ings ings
starting bal- sums of costs sums of post- sums of post- sums of post- starting bal- sums of costs sums of post- sums of post- sums of post-
ances (with of postings ings before re- ings before re- ings before ances (with of postings ings before re- ings before re- ings before
report inter- before report port start port start report start report inter- before report port start port start report start
@ -1071,113 +1474,6 @@ OPTIONS
ing to the shell and so must be escaped at least once more. See Spe- ing to the shell and so must be escaped at least once more. See Spe-
cial characters. cial characters.
QUERIES
One of hledger's strengths is being able to quickly report on precise
subsets of your data. Most commands accept an optional query expres-
sion, 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, prefixes to match specific fields, a not: prefix to negate
the match.
We do not yet support arbitrary boolean combinations of search terms;
instead most commands show transactions/postings/accounts which match
(or negatively match):
o any of the description terms AND
o any of the account terms AND
o any of the status terms AND
o all the other terms.
The print command instead shows transactions which:
o match any of the description terms AND
o have any postings matching any of the positive account terms AND
o have no postings matching any of the negative account terms AND
o match all the other terms.
The following kinds of search terms can be used. Remember these can
also be prefixed with not:, eg to exclude a particular subaccount.
REGEX, acct:REGEX
match account names by this regular expression. (With no pre-
fix, acct: is assumed.) 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 cur-
rency/commodity symbol is fully matched by REGEX. (For a par-
tial 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. PERIODEXPR is a period
expression (with no report interval). Examples: date:2016,
date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
--date2 command line flag is present, this matches secondary
dates instead.
date2:PERIODEXPR
match secondary dates within the specified period.
depth:N
match (or display, depending on command) accounts at or above
this depth
note:REGEX
match transaction notes (part of description right of |, or
whole description when there's no |)
payee:REGEX
match transaction payee/payer names (part of description left of
|, or whole description when there's no |)
real:, real:0
match real or virtual postings respectively
status:, status:!, status:*
match unmarked, pending, or cleared 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.
The following special search term is used automatically in hledger-web,
only:
inacct:ACCTNAME
tells hledger-web to show the transaction register for this ac-
count. Can be filtered further with acct etc.
Some of these can also be expressed as command-line options (eg depth:2
is equivalent to --depth 2). Generally you can mix options and query
arguments, and the resulting query will be their intersection (perhaps
excluding the -p/--period option).
COMMANDS COMMANDS
hledger provides a number of subcommands; hledger with no arguments hledger provides a number of subcommands; hledger with no arguments
shows a list. shows a list.
@ -1601,7 +1897,7 @@ COMMANDS
------------++--------------------------------------------------- ------------++---------------------------------------------------
|| $-1 $1 0 0 0 0 || $-1 $1 0 0 0 0
# Average is rounded to the dollar here since all journal amounts are (Average is rounded to the dollar here since all journal amounts are)
Limitations: Limitations:
@ -2289,7 +2585,7 @@ COMMANDS
files. Eg: files. Eg:
$ hledger -f bank1.csv print --new $ hledger -f bank1.csv print --new
# shows transactions added since last print --new on this file (shows transactions added since last print --new on this file)
This assumes that transactions added to FILE always have same or in- This assumes that transactions added to FILE always have same or in-
creasing dates, and that transactions on the same day do not get re- creasing dates, and that transactions on the same day do not get re-
@ -2662,7 +2958,7 @@ COMMANDS
For help on these, see https://github.com/feuerbach/tasty#options (-- For help on these, see https://github.com/feuerbach/tasty#options (--
--help currently doesn't show them). --help currently doesn't show them).
ADD-ON COMMANDS Add-on Commands
hledger also searches for external add-on commands, and will include hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH these in the commands list. These are programs or scripts in your PATH
whose name starts with hledger- and ends with a recognised file exten- whose name starts with hledger- and ends with a recognised file exten-
@ -2687,10 +2983,8 @@ ADD-ON COMMANDS
haskell) library functions that built-in commands do, for command-line haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc. options, journal parsing, reporting, etc.
Here are some hledger add-ons available: Two important add-ons are the hledger-ui and hledger-web user inter-
faces. These are maintained and released along with hledger:
Official add-ons
These are maintained and released along with hledger.
ui ui
hledger-ui provides an efficient terminal interface. hledger-ui provides an efficient terminal interface.
@ -2698,9 +2992,7 @@ ADD-ON COMMANDS
web web
hledger-web provides a simple web interface. hledger-web provides a simple web interface.
Third party add-ons Third party add-ons, maintained separately from hledger, include:
These are maintained separately, and usually updated shortly after a
hledger release.
iadd iadd
hledger-iadd is a more interactive, terminal UI replacement for the add hledger-iadd is a more interactive, terminal UI replacement for the add
@ -2710,19 +3002,8 @@ ADD-ON COMMANDS
hledger-interest generates interest transactions for an account accord- hledger-interest generates interest transactions for an account accord-
ing to various schemes. ing to various schemes.
Experimental add-ons A few more experimental or old add-ons can be found in hledger's bin/
These are available in source form in the hledger repo's bin/ direc- directory. These are typically prototypes and not guaranteed to work.
tory. They may be less mature and documented than built-in commands.
Reading and tweaking these is a good way to start making your own!
autosync
hledger-autosync is a symbolic link for easily running ledger-autosync,
if installed. ledger-autosync does deduplicating conversion of OFX
data and some CSV formats, and can also download the data if your bank
offers OFX Direct Connect.
chart
hledger-chart.hs is an old very basic pie chart generator.
ENVIRONMENT ENVIRONMENT
COLUMNS The screen width used by the register command. Default: the COLUMNS The screen width used by the register command. Default: the
@ -2732,6 +3013,21 @@ ENVIRONMENT
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal). nal).
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
rent.journal, where current.journal is a symbolic link to YYYY.journal.
On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en-
vironment.plist file containing
{
"LEDGER_FILE" : "~/finance/current.journal"
}
To see the effect you may need to killall Dock, or reboot.
FILES FILES
Reads data from one or more files in hledger journal, timeclock, time- Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or dot, or CSV format specified with -f, or $LEDGER_FILE, or