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

End Tag Table

21
hledger-lib/hledger_journal.txt
View File

@ -211,14 +211,13 @@ FILE FORMAT
Some examples:
# a file comment
; also a file comment
; another file comment
* also a file comment, useful in org/orgstruct mode
comment
This is a multiline file comment,
which continues until a line
where the "end comment" string
appears on its own (or end of file).
A multiline file comment, which continues
until a line containing just "end comment"
(or end of file).
end comment
2012/5/14 something ; a transaction comment
@ -661,9 +660,6 @@ FILE FORMAT
tive rective rec- 2018/06)
tives
------------------------------------------------------------------------------------
account any document account names, de- all entries in all
text clare account types & dis- files, before or
play order after
@ -1304,6 +1300,13 @@ FILE FORMAT
symbol S). The matched posting's amount will be multiplied by 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 data
can potentially affect any transaction, including transactions recorded
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].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\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
.PP
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
'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
@ -504,10 +520,10 @@ Node: Error screen15173
Ref: #error-screen15295
Node: ENVIRONMENT15539
Ref: #environment15653
Node: FILES15880
Ref: #files15979
Node: BUGS16192
Ref: #bugs16269
Node: FILES16460
Ref: #files16559
Node: BUGS16772
Ref: #bugs16849

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-
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
Reads data from one or more files in hledger journal, timeclock, time-
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].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\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
.PP
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
'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
@ -422,10 +438,10 @@ Node: JSON API11063
Ref: #json-api11177
Node: ENVIRONMENT12618
Ref: #environment12734
Node: FILES12887
Ref: #files12987
Node: BUGS13200
Ref: #bugs13278
Node: FILES13467
Ref: #files13567
Node: BUGS13780
Ref: #bugs13858

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-
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
Reads data from one or more files in hledger journal, timeclock, time-
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
# 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:

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:
$ 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
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
\f[C]hledger balance\f[R].
Run \f[C]hledger\f[R] with no arguments for a list of commands.
.SH EXAMPLES
.SH COMMON TASKS
.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
.nf
\f[C]
2015/9/30 gift received
assets:cash $20
income:gifts
2015/10/16 farmers market
expenses:food $10
assets:cash
$ 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
\f[R]
.fi
.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
.nf
\f[C]
$ hledger print
2015-09-30 gift received
assets:cash $20
income:gifts $-20
2020-01-01 * opening balances
assets:bank:checking $1000
assets:bank:savings $2000
assets:cash $100
liabilities:creditcard $-50
equity:opening/closing balances $-3050
2015-10-16 farmers market
expenses:food $10
assets:cash $-10
2020-01-10 * gift received
assets:cash $20
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]
.fi
.PP
Show account names, and their hierarchy:
.IP
.nf
\f[C]
$ hledger accounts --tree
assets
bank
checking
savings
cash
equity
opening/closing balances
expenses
food
misc
income
gifts
salary
liabilities
creditcard
\f[R]
.fi
.PP
Show all account totals:
.IP
.nf
\f[C]
$ hledger balance
$10 assets:cash
$10 expenses:food
$-20 income:gifts
$4105 assets
$4000 bank
$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
\f[R]
.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
.nf
\f[C]
$ hledger register cash
2015-09-30 gift received assets:cash $20 $20
2015-10-16 farmers market assets:cash $-10 $10
2020-01-01 opening balances assets:cash $100 $100
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]
.fi
.PP
More commands:
Show weekly posting counts as a bar chart:
.IP
.nf
\f[C]
$ hledger # show available commands
$ hledger add # add more transactions to the journal file
$ hledger balance # all accounts with aggregated balances
$ hledger balance --help # show detailed help for balance command
$ hledger balance --depth 1 # only top-level accounts
$ hledger register # show account postings, with running total
$ hledger reg income # show postings to/from income accounts
$ hledger reg \[aq]assets:some bank:checking\[aq] # show postings to/from this checking account
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
$ hledger activity -W
2019-12-30 *****
2020-01-06 ****
2020-01-13 ****
\f[R]
.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
.SS General options
.PP
@ -273,7 +628,6 @@ Or, you can run the addon executable directly:
.PP
Most hledger commands accept arguments after the command name, which are
often a query, filtering the data in some way.
.SS Argument files
.PP
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
@ -326,6 +680,120 @@ Good:
.fi
.PP
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
.PP
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
meaning to the shell and so must be escaped at least once more.
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
.PP
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
# 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]
.fi
.PP
@ -3170,7 +3524,7 @@ Eg:
.nf
\f[C]
$ 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]
.fi
.PP
@ -3677,7 +4031,7 @@ $ hledger test -- -pData.Amount --color=never
.PP
For help on these, see https://github.com/feuerbach/tasty#options
(\f[C]-- --help\f[R] currently doesn\[aq]t show them).
.SH ADD-ON COMMANDS
.SS Add-on Commands
.PP
hledger also searches for external add-on commands, and will include
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,
reporting, etc.
.PP
Here are some hledger add-ons available:
.SS Official add-ons
.PP
These are maintained and released along with hledger.
Two important add-ons are the hledger-ui and hledger-web user
interfaces.
These are maintained and released along with hledger:
.SS ui
.PP
hledger-ui provides an efficient terminal interface.
.SS web
.PP
hledger-web provides a simple web interface.
.SS Third party add-ons
.PP
These are maintained separately, and usually updated shortly after a
hledger release.
Third party add-ons, maintained separately from hledger, include:
.SS iadd
.PP
hledger-iadd is a more interactive, terminal UI replacement for the add
@ -3730,22 +4081,10 @@ command.
.PP
hledger-interest generates interest transactions for an account
according to various schemes.
.SS Experimental add-ons
.PP
These are available in source form in the hledger repo\[aq]s bin/
directory.
They may be less mature and documented than built-in commands.
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.
A few more experimental or old add-ons can be found in hledger\[aq]s
bin/ directory.
These are typically prototypes and not guaranteed to work.
.SH ENVIRONMENT
.PP
\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].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\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
.PP
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
with no arguments for a list of commands.
EXAMPLES
Two simple transactions in hledger journal format:
COMMON TASKS
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
income:gifts
2015/10/16 farmers market
expenses:food $10
2020.1.12 * farmers market
expenses:food $13
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
2015-09-30 gift received
assets:cash $20
income:gifts $-20
2020-01-01 * opening balances
assets:bank:checking $1000
assets:bank:savings $2000
assets:cash $100
liabilities:creditcard $-50
equity:opening/closing balances $-3050
2015-10-16 farmers market
expenses:food $10
assets:cash $-10
2020-01-10 * gift received
assets:cash $20
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
assets
bank
checking
savings
cash
equity
opening/closing balances
expenses
food
misc
income
gifts
salary
liabilities
creditcard
Show all account totals:
$ hledger balance
$10 assets:cash
$10 expenses:food
$-20 income:gifts
$4105 assets
$4000 bank
$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
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
2015-09-30 gift received assets:cash $20 $20
2015-10-16 farmers market assets:cash $-10 $10
2020-01-01 opening balances assets:cash $100 $100
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 add # add more transactions to the journal file
$ hledger balance # all accounts with aggregated balances
$ hledger balance --help # show detailed help for balance command
$ hledger balance --depth 1 # only top-level accounts
$ hledger register # show account postings, with running total
$ hledger reg income # show postings to/from income accounts
$ hledger reg 'assets:some bank:checking' # show postings to/from this checking account
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
$ hledger activity -W
2019-12-30 *****
2020-01-06 ****
2020-01-13 ****
Starting a New File
At the end of the year, you may want to continue your journal in a new
file, so that old transactions don't slow down or clutter your reports,
and to help ensure the integrity of your accounting history. See the
close command.
OPTIONS
General options
@ -231,7 +527,6 @@ OPTIONS
Most hledger commands accept arguments after the command name, which
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
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
@ -263,6 +558,113 @@ 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
In shell command lines, option and argument values which contain "prob-
lematic" characters, ie spaces, and also characters significant to your
@ -457,6 +859,7 @@ OPTIONS
of 8-digit year
20181232 8 digits with an invalid
day gives an error
201801012 9+ digits beginning with a
valid YYYYMMDD gives an
error
@ -544,7 +947,6 @@ OPTIONS
1, 2009
-p "from 2009/1" the same
-p "from 2009" the same
-p "to 2009" everything before january
1, 2009
@ -926,6 +1328,9 @@ OPTIONS
print
posting cost value at report value at report value at
amounts end or today or journal end DATE/today
balance asser- unchanged unchanged unchanged unchanged
tions / as-
signments
@ -957,8 +1362,6 @@ OPTIONS
report inter- ends of sums of ends of sums of DATE/today of
val) postings postings sums of post-
ings
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
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-
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
hledger provides a number of subcommands; hledger with no arguments
shows a list.
@ -1601,7 +1897,7 @@ COMMANDS
------------++---------------------------------------------------
|| $-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:
@ -2289,7 +2585,7 @@ COMMANDS
files. Eg:
$ 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-
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 (--
--help currently doesn't show them).
ADD-ON COMMANDS
Add-on Commands
hledger also searches for external add-on commands, and will include
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-
@ -2687,10 +2983,8 @@ ADD-ON COMMANDS
haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Here are some hledger add-ons available:
Official add-ons
These are maintained and released along with hledger.
Two important add-ons are the hledger-ui and hledger-web user inter-
faces. These are maintained and released along with hledger:
ui
hledger-ui provides an efficient terminal interface.
@ -2698,9 +2992,7 @@ ADD-ON COMMANDS
web
hledger-web provides a simple web interface.
Third party add-ons
These are maintained separately, and usually updated shortly after a
hledger release.
Third party add-ons, maintained separately from hledger, include:
iadd
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-
ing to various schemes.
Experimental add-ons
These are available in source form in the hledger repo's bin/ direc-
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.
A few more experimental or old add-ons can be found in hledger's bin/
directory. These are typically prototypes and not guaranteed to work.
ENVIRONMENT
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-
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
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or