diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index aa052a98f..aacfe3289 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -585,9 +585,9 @@ commodity 1 000 000.9455 .PP .SS Commodity display style .PP -For each commodity, hledger chooses a consistent style to use when -displaying amounts. -(Except price amounts, which are always displayed as written). +For the amounts in each commodity, hledger chooses a consistent display +style. +(Excluding price amounts, which are always displayed as written). The display style is chosen as follows: .IP \[bu] 2 If there is a commodity directive (or default commodity directive) for @@ -623,9 +623,19 @@ or, the style of the first posting amount in the journal, with the first-seen digit group style and the maximum-seen number of decimal places. .PP -If reports are showing amounts in a way you don\[aq]t like (eg, with too -many decimal places), use a commodity directive to set your preferred -style. +So if your reports are showing amounts in a way you don\[aq]t like, eg +with too many decimal places, use a commodity directive to set the +commodity\[aq]s display style. +For example: +.IP +.nf +\f[C] +# declare euro, dollar and bitcoin commodities and set their display styles: +commodity EUR 1.000, +commodity $1000.00 +commodity 1000.00000000 BTC +\f[R] +.fi .SS Rounding .PP Amounts are stored internally as decimal numbers with up to 255 decimal diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 75a33e160..518d47656 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -526,9 +526,9 @@ File: hledger_journal.info, Node: Commodity display style, Next: Rounding, Pr 9.2 Commodity display style =========================== -For each commodity, hledger chooses a consistent style to use when -displaying amounts. (Except price amounts, which are always displayed -as written). The display style is chosen as follows: +For the amounts in each commodity, hledger chooses a consistent display +style. (Excluding price amounts, which are always displayed as +written). The display style is chosen as follows: * If there is a commodity directive (or default commodity directive) for the commodity, its style is used (see examples above). @@ -561,9 +561,14 @@ style. first-seen digit group style and the maximum-seen number of decimal places. - If reports are showing amounts in a way you don't like (eg, with too -many decimal places), use a commodity directive to set your preferred -style. + So if your reports are showing amounts in a way you don't like, eg +with too many decimal places, use a commodity directive to set the +commodity's display style. For example: + +# declare euro, dollar and bitcoin commodities and set their display styles: +commodity EUR 1.000, +commodity $1000.00 +commodity 1000.00000000 BTC  File: hledger_journal.info, Node: Rounding, Prev: Commodity display style, Up: AMOUNTS @@ -1996,105 +2001,105 @@ Node: Digit group marks16957 Ref: #digit-group-marks17104 Node: Commodity display style18042 Ref: #commodity-display-style18218 -Node: Rounding19761 -Ref: #rounding19881 -Node: TRANSACTION PRICES20293 -Ref: #transaction-prices20450 -Node: LOT PRICES LOT DATES22881 -Ref: #lot-prices-lot-dates23055 -Node: BALANCE ASSERTIONS23543 -Ref: #balance-assertions23712 -Node: Assertions and ordering24745 -Ref: #assertions-and-ordering24929 -Node: Assertions and included files25629 -Ref: #assertions-and-included-files25868 -Node: Assertions and multiple -f options26201 -Ref: #assertions-and-multiple--f-options26453 -Node: Assertions and commodities26585 -Ref: #assertions-and-commodities26813 -Node: Assertions and prices27970 -Ref: #assertions-and-prices28180 -Node: Assertions and subaccounts28620 -Ref: #assertions-and-subaccounts28845 -Node: Assertions and virtual postings29169 -Ref: #assertions-and-virtual-postings29407 -Node: Assertions and precision29549 -Ref: #assertions-and-precision29738 -Node: BALANCE ASSIGNMENTS30005 -Ref: #balance-assignments30166 -Node: Balance assignments and prices31330 -Ref: #balance-assignments-and-prices31498 -Node: DIRECTIVES31722 -Ref: #directives31868 -Node: Directives and multiple files37366 -Ref: #directives-and-multiple-files37545 -Node: Comment blocks38209 -Ref: #comment-blocks38388 -Node: Including other files38564 -Ref: #including-other-files38740 -Node: Default year39664 -Ref: #default-year39829 -Node: Declaring commodities40236 -Ref: #declaring-commodities40415 -Node: Commodity error checking42259 -Ref: #commodity-error-checking42415 -Node: Default commodity42672 -Ref: #default-commodity42854 -Node: Declaring market prices43743 -Ref: #declaring-market-prices43934 -Node: Declaring accounts44791 -Ref: #declaring-accounts44973 -Node: Account error checking46175 -Ref: #account-error-checking46347 -Node: Account comments47526 -Ref: #account-comments47716 -Node: Account subdirectives48140 -Ref: #account-subdirectives48331 -Node: Account types48644 -Ref: #account-types48824 -Node: Declaring account types49560 -Ref: #declaring-account-types49745 -Node: Auto-detected account types50395 -Ref: #auto-detected-account-types50642 -Node: Interference from auto-detected account types51539 -Ref: #interference-from-auto-detected-account-types51822 -Node: Old account type syntax52305 -Ref: #old-account-type-syntax52508 -Node: Account display order52808 -Ref: #account-display-order52974 -Node: Rewriting accounts54125 -Ref: #rewriting-accounts54306 -Node: Basic aliases55063 -Ref: #basic-aliases55205 -Node: Regex aliases55909 -Ref: #regex-aliases56077 -Node: Combining aliases56796 -Ref: #combining-aliases56985 -Node: Aliases and multiple files58261 -Ref: #aliases-and-multiple-files58466 -Node: end aliases59045 -Ref: #end-aliases59198 -Node: Default parent account59299 -Ref: #default-parent-account59463 -Node: PERIODIC TRANSACTIONS60347 -Ref: #periodic-transactions60509 -Node: Periodic rule syntax62426 -Ref: #periodic-rule-syntax62628 -Node: Two spaces between period expression and description!63332 -Ref: #two-spaces-between-period-expression-and-description63647 -Node: Forecasting with periodic transactions64331 -Ref: #forecasting-with-periodic-transactions64632 -Node: Budgeting with periodic transactions66687 -Ref: #budgeting-with-periodic-transactions66922 -Node: AUTO POSTINGS67331 -Ref: #auto-postings67458 -Node: Auto postings and multiple files69637 -Ref: #auto-postings-and-multiple-files69837 -Node: Auto postings and dates70046 -Ref: #auto-postings-and-dates70316 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions70491 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions70838 -Node: Auto posting tags71180 -Ref: #auto-posting-tags71391 +Node: Rounding19931 +Ref: #rounding20051 +Node: TRANSACTION PRICES20463 +Ref: #transaction-prices20620 +Node: LOT PRICES LOT DATES23051 +Ref: #lot-prices-lot-dates23225 +Node: BALANCE ASSERTIONS23713 +Ref: #balance-assertions23882 +Node: Assertions and ordering24915 +Ref: #assertions-and-ordering25099 +Node: Assertions and included files25799 +Ref: #assertions-and-included-files26038 +Node: Assertions and multiple -f options26371 +Ref: #assertions-and-multiple--f-options26623 +Node: Assertions and commodities26755 +Ref: #assertions-and-commodities26983 +Node: Assertions and prices28140 +Ref: #assertions-and-prices28350 +Node: Assertions and subaccounts28790 +Ref: #assertions-and-subaccounts29015 +Node: Assertions and virtual postings29339 +Ref: #assertions-and-virtual-postings29577 +Node: Assertions and precision29719 +Ref: #assertions-and-precision29908 +Node: BALANCE ASSIGNMENTS30175 +Ref: #balance-assignments30336 +Node: Balance assignments and prices31500 +Ref: #balance-assignments-and-prices31668 +Node: DIRECTIVES31892 +Ref: #directives32038 +Node: Directives and multiple files37536 +Ref: #directives-and-multiple-files37715 +Node: Comment blocks38379 +Ref: #comment-blocks38558 +Node: Including other files38734 +Ref: #including-other-files38910 +Node: Default year39834 +Ref: #default-year39999 +Node: Declaring commodities40406 +Ref: #declaring-commodities40585 +Node: Commodity error checking42429 +Ref: #commodity-error-checking42585 +Node: Default commodity42842 +Ref: #default-commodity43024 +Node: Declaring market prices43913 +Ref: #declaring-market-prices44104 +Node: Declaring accounts44961 +Ref: #declaring-accounts45143 +Node: Account error checking46345 +Ref: #account-error-checking46517 +Node: Account comments47696 +Ref: #account-comments47886 +Node: Account subdirectives48310 +Ref: #account-subdirectives48501 +Node: Account types48814 +Ref: #account-types48994 +Node: Declaring account types49730 +Ref: #declaring-account-types49915 +Node: Auto-detected account types50565 +Ref: #auto-detected-account-types50812 +Node: Interference from auto-detected account types51709 +Ref: #interference-from-auto-detected-account-types51992 +Node: Old account type syntax52475 +Ref: #old-account-type-syntax52678 +Node: Account display order52978 +Ref: #account-display-order53144 +Node: Rewriting accounts54295 +Ref: #rewriting-accounts54476 +Node: Basic aliases55233 +Ref: #basic-aliases55375 +Node: Regex aliases56079 +Ref: #regex-aliases56247 +Node: Combining aliases56966 +Ref: #combining-aliases57155 +Node: Aliases and multiple files58431 +Ref: #aliases-and-multiple-files58636 +Node: end aliases59215 +Ref: #end-aliases59368 +Node: Default parent account59469 +Ref: #default-parent-account59633 +Node: PERIODIC TRANSACTIONS60517 +Ref: #periodic-transactions60679 +Node: Periodic rule syntax62596 +Ref: #periodic-rule-syntax62798 +Node: Two spaces between period expression and description!63502 +Ref: #two-spaces-between-period-expression-and-description63817 +Node: Forecasting with periodic transactions64501 +Ref: #forecasting-with-periodic-transactions64802 +Node: Budgeting with periodic transactions66857 +Ref: #budgeting-with-periodic-transactions67092 +Node: AUTO POSTINGS67501 +Ref: #auto-postings67628 +Node: Auto postings and multiple files69807 +Ref: #auto-postings-and-multiple-files70007 +Node: Auto postings and dates70216 +Ref: #auto-postings-and-dates70486 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions70661 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions71008 +Node: Auto posting tags71350 +Ref: #auto-posting-tags71561  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 21b0d3b7e..0b7925433 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -411,9 +411,9 @@ AMOUNTS commodity 1 000 000.9455 Commodity display style - For each commodity, hledger chooses a consistent style to use when dis- - playing amounts. (Except price amounts, which are always displayed as - written). The display style is chosen as follows: + For the amounts in each commodity, hledger chooses a consistent display + style. (Excluding price amounts, which are always displayed as writ- + ten). The display style is chosen as follows: o If there is a commodity directive (or default commodity directive) for the commodity, its style is used (see examples above). @@ -447,9 +447,14 @@ AMOUNTS first-seen digit group style and the maximum-seen number of decimal places. - If reports are showing amounts in a way you don't like (eg, with too - many decimal places), use a commodity directive to set your preferred - style. + So if your reports are showing amounts in a way you don't like, eg with + too many decimal places, use a commodity directive to set the commod- + ity's display style. For example: + + # declare euro, dollar and bitcoin commodities and set their display styles: + commodity EUR 1.000, + commodity $1000.00 + commodity 1000.00000000 BTC Rounding Amounts are stored internally as decimal numbers with up to 255 decimal @@ -721,6 +726,12 @@ DIRECTIVES ment until end of cur- rent file or end directive + + + + + + commod- format declare a commodity and its number notation: ity number notation & display following entries style in that commodity @@ -740,8 +751,6 @@ DIRECTIVES play style: amounts of that commodity in reports - - include include entries/directives what the included from another file directives affect P declare a market price for a amounts of that diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 2fc0f96e5..17f68ad98 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -65,462 +65,6 @@ 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 COMMON TASKS -.PP -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 Getting help -.IP -.nf -\f[C] -$ 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 -Find more docs, chat, mail list, reddit, issue tracker: -https://hledger.org#help-feedback -.SS Constructing command lines -.PP -hledger has an extensive and powerful command line interface. -We strive to keep it simple and ergonomic, but you may run into one of -the confusing real world details described in OPTIONS, below. -If that happens, here are some tips that may help: -.IP \[bu] 2 -command-specific options must go after the command (it\[aq]s fine to put -all options there) (\f[C]hledger CMD OPTS ARGS\f[R]) -.IP \[bu] 2 -running add-on executables directly simplifies command line parsing -(\f[C]hledger-ui OPTS ARGS\f[R]) -.IP \[bu] 2 -enclose \[dq]problematic\[dq] args in single quotes -.IP \[bu] 2 -if needed, also add a backslash to hide regular expression -metacharacters from the shell -.IP \[bu] 2 -to see how a misbehaving command is being parsed, add -\f[C]--debug=2\f[R]. -.SS Starting a journal file -.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 -m \[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 -m \[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 -2020-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - -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 - $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 -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 -Show weekly posting counts as a bar chart: -.IP -.nf -\f[C] -$ hledger activity -W -2019-12-30 ***** -2020-01-06 **** -2020-01-13 **** -\f[R] -.fi -.SS Migrating to 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. -.PP -If using version control, don\[aq]t forget to \f[C]git add\f[R] the new -file. .SH OPTIONS .SS General options .PP @@ -720,158 +264,79 @@ Good: .fi .PP See also: Save frequently used options. -.SS Queries +.SS Special characters +.SS Single escaping (shell metacharacters) .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\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 -\[dq]problematic\[dq] characters, ie spaces, and also characters -significant to your shell such as \f[C]<\f[R], \f[C]>\f[R], \f[C](\f[R], -\f[C])\f[R], \f[C]|\f[R] and \f[C]$\f[R], should be escaped by enclosing -them in quotes or by writing backslashes before the characters. -Eg: -.PP -\f[C]hledger register -p \[aq]last year\[aq] \[dq]accounts receivable (receivable|payable)\[dq] amt:\[rs]>100\f[R]. -.SS More escaping -.PP -Characters significant both to the shell and in regular expressions may -need one extra level of escaping. -These include parentheses, the pipe symbol and the dollar sign. -Eg, to match the dollar symbol, bash users should do: -.PP -\f[C]hledger balance cur:\[aq]\[rs]$\[aq]\f[R] +In shell command lines, characters significant to your shell - such as +spaces, \f[C]<\f[R], \f[C]>\f[R], \f[C](\f[R], \f[C])\f[R], \f[C]|\f[R], +\f[C]$\f[R] and \f[C]\[rs]\f[R] - should be \[dq]shell-escaped\[dq] if +you want hledger to see them. +This is done by enclosing them in single or double quotes, or by writing +a backslash before them. +Eg to match an account name containing a space: +.IP +.nf +\f[C] +$ hledger register \[aq]credit card\[aq] +\f[R] +.fi .PP or: +.IP +.nf +\f[C] +$ hledger register credit\[rs] card +\f[R] +.fi +.SS Double escaping (regular expression metacharacters) .PP -\f[C]hledger balance cur:\[rs]\[rs]$\f[R] -.SS Even more escaping -.PP -When hledger runs an add-on executable (eg you type -\f[C]hledger ui\f[R], hledger runs \f[C]hledger-ui\f[R]), it de-escapes -command-line options and arguments once, so you might need to -\f[I]triple\f[R]-escape. -Eg in bash, running the ui command and matching the dollar sign, -it\[aq]s: -.PP -\f[C]hledger ui cur:\[aq]\[rs]\[rs]$\[aq]\f[R] +Characters significant in regular expressions (described below) - such +as \f[C].\f[R], \f[C]\[ha]\f[R], \f[C]$\f[R], \f[C][\f[R], \f[C]]\f[R], +\f[C](\f[R], \f[C])\f[R], \f[C]|\f[R], and \f[C]\[rs]\f[R] - may need to +be \[dq]regex-escaped\[dq] if you don\[aq]t want them to be interpreted +by hledger\[aq]s regular expression engine. +This is done by writing backslashes before them, but since backslash is +typically also a shell metacharacter, both shell-escaping and +regex-escaping will be needed. +Eg to match a literal \f[C]$\f[R] sign while using the bash shell: +.IP +.nf +\f[C] +$ hledger balance cur:\[aq]\[rs]$\[aq] +\f[R] +.fi .PP or: +.IP +.nf +\f[C] +$ hledger balance cur:\[rs]\[rs]$ +\f[R] +.fi +.SS Triple escaping (for add-on commands) .PP -\f[C]hledger ui cur:\[rs]\[rs]\[rs]\[rs]$\f[R] +When you use hledger to run an external add-on command (described +below), one level of shell-escaping is lost from any options or +arguments intended for by the add-on command, so those need an extra +level of shell-escaping. +Eg to match a literal \f[C]$\f[R] sign while using the bash shell and +running an add-on command (\f[C]ui\f[R]): +.IP +.nf +\f[C] +$ hledger ui cur:\[aq]\[rs]\[rs]$\[aq] +\f[R] +.fi .PP -If you asked why \f[I]four\f[R] slashes above, this may help: +or: +.IP +.nf +\f[C] +$ hledger ui cur:\[rs]\[rs]\[rs]\[rs]$ +\f[R] +.fi +.PP +If you wondered why \f[I]four\f[R] backslashes, perhaps this helps: .PP .TS tab(@); @@ -898,22 +363,28 @@ T}@T{ T} .TE .PP -(The number of backslashes in fish shell is left as an exercise for the -reader.) -.PP -You can always avoid the extra escaping for add-ons by running the -add-on directly: -.PP -\f[C]hledger-ui cur:\[rs]\[rs]$\f[R] +Or, you can avoid the extra escaping by running the add-on executable +directly: +.IP +.nf +\f[C] +$ hledger-ui cur:\[rs]\[rs]$ +\f[R] +.fi .SS Less escaping .PP -Inside an argument file, or in the search field of hledger-ui or -hledger-web, or at a GHCI prompt, you need one less level of escaping -than at the command line. -And backslashes may work better than quotes. -Eg: -.PP -\f[C]ghci> :main balance cur:\[rs]$\f[R] +Options and arguments are sometimes used in places other than the shell +command line, where shell-escaping is not needed, so there you should +use one less level of escaping. +Those places include: +.IP \[bu] 2 +an \[at]argumentfile +.IP \[bu] 2 +hledger-ui\[aq]s filter field +.IP \[bu] 2 +hledger-web\[aq]s search form +.IP \[bu] 2 +GHCI\[aq]s prompt (used by developers). .SS Unicode characters .PP hledger is expected to handle non-ascii characters correctly: @@ -951,12 +422,64 @@ Eg hledger built in the standard CMD.EXE environment (like the binaries on our download page) might show display problems when run in a cygwin or msys terminal, and vice versa. (See eg #961). -.SS Input files +.SS Regular expressions +.PP +hledger uses regular expressions in a number of places: +.IP \[bu] 2 +query terms, on the command line and in the hledger-web search form: +\f[C]REGEX\f[R], \f[C]desc:REGEX\f[R], \f[C]cur:REGEX\f[R], +\f[C]tag:...=REGEX\f[R] +.IP \[bu] 2 +CSV rules conditional blocks: \f[C]if REGEX ...\f[R] +.IP \[bu] 2 +account alias directives and options: +\f[C]alias /REGEX/ = REPLACEMENT\f[R], +\f[C]--alias /REGEX/=REPLACEMENT\f[R] +.PP +hledger\[aq]s regular expressions come from the regex-tdfa library. +If they\[aq]re not doing what you expect, it\[aq]s important to know +exactly what they support: +.IP "1." 3 +they are case insensitive +.IP "2." 3 +they are infix matching (they do not need to match the entire thing +being matched) +.IP "3." 3 +they are POSIX ERE (extended regular expressions) +.IP "4." 3 +they also support GNU word boundaries (\f[C]\[rs]b\f[R], +\f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R], \f[C]\[rs]>\f[R]) +.IP "5." 3 +they do not support backreferences; if you write \f[C]\[rs]1\f[R], it +will match the digit \f[C]1\f[R]. +Except when doing text replacement, eg in account aliases, where +backreferences can be used in the replacement string to reference +capturing groups in the search regexp. +.IP "6." 3 +they do not support mode modifiers (\f[C](?s)\f[R]), character classes +(\f[C]\[rs]w\f[R], \f[C]\[rs]d\f[R]), or anything else not mentioned +above. +.PP +Some things to note: +.IP \[bu] 2 +In the \f[C]alias\f[R] directive and \f[C]--alias\f[R] option, regular +expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[R]). +Elsewhere in hledger, these are not required. +.IP \[bu] 2 +In queries, to match a regular expression metacharacter like \f[C]$\f[R] +as a literal character, prepend a backslash. +Eg to search for amounts with the dollar sign in hledger-web, write +\f[C]cur:\[rs]$\f[R]. +.IP \[bu] 2 +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 DATA FILES +.PP +hledger reads transactions from one or more data files. +The default data file is \f[C]$HOME/.hledger.journal\f[R] (or on +Windows, something like \f[C]C:/Users/USER/.hledger.journal\f[R]). .PP -hledger reads transactions from a data file (and the add command writes -to it). -By default this file is \f[C]$HOME/.hledger.journal\f[R] (or on Windows, -something like \f[C]C:/Users/USER/.hledger.journal\f[R]). You can override this with the \f[C]$LEDGER_FILE\f[R] environment variable: .IP @@ -967,21 +490,22 @@ $ hledger stats \f[R] .fi .PP -or with the \f[C]-f/--file\f[R] option: +or with one or more \f[C]-f/--file\f[R] options: .IP .nf \f[C] -$ hledger -f /some/file stats +$ hledger -f /some/file -f another_file stats \f[R] .fi .PP -The file name \f[C]-\f[R] (hyphen) means standard input: +The file name \f[C]-\f[R] means standard input: .IP .nf \f[C] $ cat some.journal | hledger -f- \f[R] .fi +.SS Data formats .PP Usually the data file is in hledger\[aq]s journal format, but it can be in any of the supported file formats, which currently are: @@ -1035,9 +559,8 @@ So for non-journal files, it\[aq]s important to use a recognised file extension, so as to either read successfully or to show relevant error messages. .PP -When you can\[aq]t ensure the right file extension, not to worry: you -can force a specific reader/format by prefixing the file path with the -format and a colon. +You can also force a specific reader/format by prefixing the file path +with the format and a colon. Eg to read a .dat file as csv: .IP .nf @@ -1046,12 +569,13 @@ $ hledger -f csv:/some/csv-file.dat stats $ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print -ftimeclock:- \f[R] .fi +.SS Multiple files .PP You can specify multiple \f[C]-f\f[R] options, to read multiple files as one big journal. There are some limitations with this: .IP \[bu] 2 -directives in one file will not affect the other files +most directives do not affect sibling files .IP \[bu] 2 balance assertions will not see any account balances from previous files .PP @@ -1086,154 +610,11 @@ Are all commodities declared with a \f[C]commodity\f[R] directive ? See also: https://hledger.org/checking-for-errors.html .PP \f[I]experimental.\f[R] -.SS Output destination -.PP -hledger commands send their output to the terminal by default. -You can of course redirect this, eg into a file, using standard shell -syntax: -.IP -.nf -\f[C] -$ hledger print > foo.txt -\f[R] -.fi -.PP -Some commands (print, register, stats, the balance commands) also -provide the \f[C]-o/--output-file\f[R] option, which does the same thing -without needing the shell. -Eg: -.IP -.nf -\f[C] -$ hledger print -o foo.txt -$ hledger print -o - # write to stdout (the default) -\f[R] -.fi -.SS Output format -.PP -Some commands (print, register, the balance commands) offer a choice of -output format. -In addition to the usual plain text format (\f[C]txt\f[R]), there are -CSV (\f[C]csv\f[R]), HTML (\f[C]html\f[R]), JSON (\f[C]json\f[R]) and -SQL (\f[C]sql\f[R]). -This is controlled by the \f[C]-O/--output-format\f[R] option: -.IP -.nf -\f[C] -$ hledger print -O csv -\f[R] -.fi -.PP -or, by a file extension specified with \f[C]-o/--output-file\f[R]: -.IP -.nf -\f[C] -$ hledger balancesheet -o foo.html # write HTML to foo.html -\f[R] -.fi -.PP -The \f[C]-O\f[R] option can be used to override the file extension if -needed: -.IP -.nf -\f[C] -$ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt -\f[R] -.fi -.PP -Some notes about JSON output: -.IP \[bu] 2 -This feature is marked experimental, and not yet much used; you should -expect our JSON to evolve. -Real-world feedback is welcome. -.IP \[bu] 2 -Our JSON is rather large and verbose, as it is quite a faithful -representation of hledger\[aq]s internal data types. -To understand the JSON, read the Haskell type definitions, which are -mostly in -https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. -.IP \[bu] 2 -hledger represents quantities as Decimal values storing up to 255 -significant digits, eg for repeating decimals. -Such numbers can arise in practice (from automatically-calculated -transaction prices), and would break most JSON consumers. -So in JSON, we show quantities as simple Numbers with at most 10 decimal -places. -We don\[aq]t limit the number of integer digits, but that part is under -your control. -We hope this approach will not cause problems in practice; if you find -otherwise, please let us know. -(Cf #1195) -.PP -Notes about SQL output: -.IP \[bu] 2 -SQL output is also marked experimental, and much like JSON could use -real-world feedback. -.IP \[bu] 2 -SQL output is expected to work with sqlite, MySQL and PostgreSQL -.IP \[bu] 2 -SQL output is structured with the expectations that statements will be -executed in the empty database. -If you already have tables created via SQL output of hledger, you would -probably want to either clear tables of existing data (via -\f[C]delete\f[R] or \f[C]truncate\f[R] SQL statements) or drop tables -completely as otherwise your postings will be duped. -.SS Regular expressions -.PP -hledger uses regular expressions in a number of places: -.IP \[bu] 2 -query terms, on the command line and in the hledger-web search form: -\f[C]REGEX\f[R], \f[C]desc:REGEX\f[R], \f[C]cur:REGEX\f[R], -\f[C]tag:...=REGEX\f[R] -.IP \[bu] 2 -CSV rules conditional blocks: \f[C]if REGEX ...\f[R] -.IP \[bu] 2 -account alias directives and options: -\f[C]alias /REGEX/ = REPLACEMENT\f[R], -\f[C]--alias /REGEX/=REPLACEMENT\f[R] -.PP -hledger\[aq]s regular expressions come from the regex-tdfa library. -If they\[aq]re not doing what you expect, it\[aq]s important to know -exactly what they support: -.IP "1." 3 -they are case insensitive -.IP "2." 3 -they are infix matching (they do not need to match the entire thing -being matched) -.IP "3." 3 -they are POSIX ERE (extended regular expressions) -.IP "4." 3 -they also support GNU word boundaries (\f[C]\[rs]b\f[R], -\f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R], \f[C]\[rs]>\f[R]) -.IP "5." 3 -they do not support backreferences; if you write \f[C]\[rs]1\f[R], it -will match the digit \f[C]1\f[R]. -Except when doing text replacement, eg in account aliases, where -backreferences can be used in the replacement string to reference -capturing groups in the search regexp. -.IP "6." 3 -they do not support mode modifiers (\f[C](?s)\f[R]), character classes -(\f[C]\[rs]w\f[R], \f[C]\[rs]d\f[R]), or anything else not mentioned -above. -.PP -Some things to note: -.IP \[bu] 2 -In the \f[C]alias\f[R] directive and \f[C]--alias\f[R] option, regular -expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[R]). -Elsewhere in hledger, these are not required. -.IP \[bu] 2 -In queries, to match a regular expression metacharacter like \f[C]$\f[R] -as a literal character, prepend a backslash. -Eg to search for amounts with the dollar sign in hledger-web, write -\f[C]cur:\[rs]$\f[R]. -.IP \[bu] 2 -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 TIME PERIODS .SS Smart dates .PP hledger\[aq]s user interfaces accept a flexible \[dq]smart date\[dq] -syntax (unlike dates in the journal file). +syntax. Smart dates allow some english words, can be relative to today\[aq]s date, and can have less-significant date parts omitted (defaulting to 1). @@ -1673,7 +1054,7 @@ Group postings from start of wednesday to end of next tuesday (N is start date and exclusive end date): .PP \f[C]hledger register checking -p \[dq]every 3rd day of week\[dq]\f[R] -.SS Depth limiting +.SH DEPTH .PP With the \f[C]--depth N\f[R] option (short form: \f[C]-N\f[R]), commands like account, balance and register will show only the uppermost accounts @@ -1681,81 +1062,121 @@ in the account tree, down to level N. Use this when you want a summary with less detail. This flag has the same effect as a \f[C]depth:\f[R] query argument (so \f[C]-2\f[R], \f[C]--depth=2\f[R] or \f[C]depth:2\f[R] are equivalent). -.SS Pivoting +.SH QUERIES .PP -Normally hledger sums amounts, and organizes them in a hierarchy, based -on account name. -The \f[C]--pivot FIELD\f[R] option causes it to sum and organize -hierarchy based on the value of some other field instead. -FIELD can be: \f[C]code\f[R], \f[C]description\f[R], \f[C]payee\f[R], -\f[C]note\f[R], or the full name (case insensitive) of any tag. -As with account names, values containing \f[C]colon:separated:parts\f[R] -will be displayed hierarchically in reports. +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 -\f[C]--pivot\f[R] is a general option affecting all reports; you can -think of hledger transforming the journal before any other processing, -replacing every posting\[aq]s account name with the value of the -specified field on that posting, inheriting it from the transaction or -using a blank value if it\[aq]s not present. +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 -An example: -.IP -.nf -\f[C] -2016/02/16 Member Fee Payment - assets:bank account 2 EUR - income:member fees -2 EUR ; member: John Doe -\f[R] -.fi +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 -Normal balance report showing account names: -.IP -.nf -\f[C] -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:member fees --------------------- - 0 -\f[R] -.fi +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\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 -Pivoted balance report, using member: tag values instead: -.IP -.nf -\f[C] -$ hledger balance --pivot member - 2 EUR - -2 EUR John Doe --------------------- - 0 -\f[R] -.fi +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 -One way to show only amounts with a member: value (using a query, -described below): -.IP -.nf -\f[C] -$ hledger balance --pivot member tag:member=. - -2 EUR John Doe --------------------- - -2 EUR -\f[R] -.fi -.PP -Another way (the acct: query matches against the pivoted \[dq]account -name\[dq]): -.IP -.nf -\f[C] -$ hledger balance --pivot member acct:. - -2 EUR John Doe --------------------- - -2 EUR -\f[R] -.fi -.SS Valuation +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 VALUATION .PP Instead of reporting amounts in their original commodity, hledger can convert them to cost/sale amount (using the conversion rate recorded in @@ -1793,8 +1214,6 @@ For multiperiod reports, each column/period is valued on the last day of the period, by default. .SS Market prices .PP -\f[I](experimental)\f[R] -.PP To convert a commodity A to its market value in another commodity B, hledger looks for a suitable market price (exchange rate) as follows, in this order of preference : @@ -1819,8 +1238,6 @@ Amounts for which no applicable market price can be found, are not converted. .SS --infer-value: market prices from transactions .PP -\f[I](experimental)\f[R] -.PP Normally, market value in hledger is fully controlled by, and requires, P directives in your journal. Since adding and updating those can be a chore, and since transactions @@ -1852,8 +1269,6 @@ but not, currently, from \[dq]more correct\[dq] multicommodity transactions (no \f[C]\[at]\f[R], multiple commodities, balanced). .SS Valuation commodity .PP -\f[I](experimental)\f[R] -.PP \f[B]When you specify a valuation commodity (\f[CB]-X COMM\f[B] or \f[CB]--value TYPE,COMM\f[B]):\f[R] .PD 0 @@ -2462,26 +1877,195 @@ otherwise the latest transaction date in the journal, otherwise today. \f[I]report interval\f[R] a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report\[aq]s multi-period mode (whether showing one or many subperiods). +.SH PIVOTING +.PP +Normally hledger sums amounts, and organizes them in a hierarchy, based +on account name. +The \f[C]--pivot FIELD\f[R] option causes it to sum and organize +hierarchy based on the value of some other field instead. +FIELD can be: \f[C]code\f[R], \f[C]description\f[R], \f[C]payee\f[R], +\f[C]note\f[R], or the full name (case insensitive) of any tag. +As with account names, values containing \f[C]colon:separated:parts\f[R] +will be displayed hierarchically in reports. +.PP +\f[C]--pivot\f[R] is a general option affecting all reports; you can +think of hledger transforming the journal before any other processing, +replacing every posting\[aq]s account name with the value of the +specified field on that posting, inheriting it from the transaction or +using a blank value if it\[aq]s not present. +.PP +An example: +.IP +.nf +\f[C] +2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe +\f[R] +.fi +.PP +Normal balance report showing account names: +.IP +.nf +\f[C] +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees +-------------------- + 0 +\f[R] +.fi +.PP +Pivoted balance report, using member: tag values instead: +.IP +.nf +\f[C] +$ hledger balance --pivot member + 2 EUR + -2 EUR John Doe +-------------------- + 0 +\f[R] +.fi +.PP +One way to show only amounts with a member: value (using a query, +described below): +.IP +.nf +\f[C] +$ hledger balance --pivot member tag:member=. + -2 EUR John Doe +-------------------- + -2 EUR +\f[R] +.fi +.PP +Another way (the acct: query matches against the pivoted \[dq]account +name\[dq]): +.IP +.nf +\f[C] +$ hledger balance --pivot member acct:. + -2 EUR John Doe +-------------------- + -2 EUR +\f[R] +.fi +.SH OUTPUT +.SS Output destination +.PP +hledger commands send their output to the terminal by default. +You can of course redirect this, eg into a file, using standard shell +syntax: +.IP +.nf +\f[C] +$ hledger print > foo.txt +\f[R] +.fi +.PP +Some commands (print, register, stats, the balance commands) also +provide the \f[C]-o/--output-file\f[R] option, which does the same thing +without needing the shell. +Eg: +.IP +.nf +\f[C] +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default) +\f[R] +.fi +.SS Output format +.PP +Some commands (print, register, the balance commands) offer a choice of +output format. +In addition to the usual plain text format (\f[C]txt\f[R]), there are +CSV (\f[C]csv\f[R]), HTML (\f[C]html\f[R]), JSON (\f[C]json\f[R]) and +SQL (\f[C]sql\f[R]). +This is controlled by the \f[C]-O/--output-format\f[R] option: +.IP +.nf +\f[C] +$ hledger print -O csv +\f[R] +.fi +.PP +or, by a file extension specified with \f[C]-o/--output-file\f[R]: +.IP +.nf +\f[C] +$ hledger balancesheet -o foo.html # write HTML to foo.html +\f[R] +.fi +.PP +The \f[C]-O\f[R] option can be used to override the file extension if +needed: +.IP +.nf +\f[C] +$ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt +\f[R] +.fi +.PP +Some notes about JSON output: +.IP \[bu] 2 +This feature is marked experimental, and not yet much used; you should +expect our JSON to evolve. +Real-world feedback is welcome. +.IP \[bu] 2 +Our JSON is rather large and verbose, as it is quite a faithful +representation of hledger\[aq]s internal data types. +To understand the JSON, read the Haskell type definitions, which are +mostly in +https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. +.IP \[bu] 2 +hledger represents quantities as Decimal values storing up to 255 +significant digits, eg for repeating decimals. +Such numbers can arise in practice (from automatically-calculated +transaction prices), and would break most JSON consumers. +So in JSON, we show quantities as simple Numbers with at most 10 decimal +places. +We don\[aq]t limit the number of integer digits, but that part is under +your control. +We hope this approach will not cause problems in practice; if you find +otherwise, please let us know. +(Cf #1195) +.PP +Notes about SQL output: +.IP \[bu] 2 +SQL output is also marked experimental, and much like JSON could use +real-world feedback. +.IP \[bu] 2 +SQL output is expected to work with sqlite, MySQL and PostgreSQL +.IP \[bu] 2 +SQL output is structured with the expectations that statements will be +executed in the empty database. +If you already have tables created via SQL output of hledger, you would +probably want to either clear tables of existing data (via +\f[C]delete\f[R] or \f[C]truncate\f[R] SQL statements) or drop tables +completely as otherwise your postings will be duped. .SH COMMANDS .PP hledger provides a number of commands for producing reports and managing your data. -Run \f[C]hledger\f[R] with no arguments to list the commands available. +Run \f[C]hledger\f[R] with no arguments to list the commands available, +and \f[C]hledger CMD\f[R] to run a command. +CMD can be the full command name, or its standard abbreviation shown in +the commands list, or any unambiguous prefix of the name. +Eg: \f[C]hledger bal\f[R]. .PP -To run a command, write its name (or its abbreviation shown in the -commands list, or any unambiguous prefix of the name) as hledger\[aq]s -first argument. -Eg: \f[C]hledger balance\f[R] or \f[C]hledger bal\f[R]. +Here are the built-in commands, with the most often-used in bold: .PP -Here are the built-in commands: +\f[B]Data entry:\f[R] .PP -\f[B]Data entry (these modify the journal file):\f[R] +These data entry commands are the only ones which can modify your +journal file. .IP \[bu] 2 -add - add transactions using guided prompts +\f[B]add\f[R] - add transactions using guided prompts .IP \[bu] 2 -import - add any new transactions from other files (eg csv) +\f[B]import\f[R] - add any new transactions from other files (eg csv) .PP -\f[B]Data management\f[R]: +\f[B]Data management:\f[R] .IP \[bu] 2 check - check for various kinds of issue in the data .IP \[bu] 2 @@ -2493,15 +2077,15 @@ rewrite - generate extra postings, similar to print --auto .PP \f[B]Financial statements:\f[R] .IP \[bu] 2 -aregister (areg) - show transactions in a particular account +\f[B]aregister (areg)\f[R] - show transactions in a particular account .IP \[bu] 2 -balancesheet (bs) - show assets, liabilities and net worth +\f[B]balancesheet (bs)\f[R] - show assets, liabilities and net worth .IP \[bu] 2 balancesheetequity (bse) - show assets, liabilities and equity .IP \[bu] 2 cashflow (cf) - show changes in liquid assets .IP \[bu] 2 -incomestatement (is) - show revenues and expenses +\f[B]incomestatement (is)\f[R] - show revenues and expenses .IP \[bu] 2 roi - show return on investments .PP @@ -2511,7 +2095,8 @@ accounts (a) - show account names .IP \[bu] 2 activity - show postings-per-interval bar charts .IP \[bu] 2 -balance (b, bal) - show balance changes/end balances/budgets in accounts +\f[B]balance (b, bal)\f[R] - show balance changes/end balances/budgets +in any accounts .IP \[bu] 2 codes - show transaction codes .IP \[bu] 2 @@ -2521,18 +2106,20 @@ descriptions - show unique transaction descriptions .IP \[bu] 2 files - show input file paths .IP \[bu] 2 +help - show hledger user manuals in several formats +.IP \[bu] 2 notes - show unique note segments of transaction descriptions .IP \[bu] 2 payees - show unique payee segments of transaction descriptions .IP \[bu] 2 prices - show market price records .IP \[bu] 2 -print (p, txns) - show transactions (journal entries) +\f[B]print (p, txns)\f[R] - show transactions (journal entries) .IP \[bu] 2 print-unique - show only transactions with unique descriptions .IP \[bu] 2 -register (r, reg) - show postings in one or more accounts & running -total +\f[B]register (r, reg)\f[R] - show postings in one or more accounts & +running total .IP \[bu] 2 register-match - show a recent posting that best matches a description .IP \[bu] 2 @@ -2542,6 +2129,26 @@ tags - show tag names .IP \[bu] 2 test - run self tests .PP +\f[B]Add-on commands:\f[R] +.PP +Programs or scripts named \f[C]hledger-SOMETHING\f[R] in your PATH are +add-on commands; these appear in the commands list with a \f[C]+\f[R] +mark. +Two of these are maintained and released with hledger: +.IP \[bu] 2 +\f[B]ui\f[R] - an efficient terminal interface (TUI) for hledger +.IP \[bu] 2 +\f[B]web\f[R] - a simple web interface (WUI) for hledger +.PP +And these add-ons are maintained separately: +.IP \[bu] 2 +iadd - a more interactive alternative for the add command +.IP \[bu] 2 +interest - generates interest transactions according to various schemes +.IP \[bu] 2 +stockquotes - downloads market prices for your commodities from +AlphaVantage \f[I](experimental)\f[R] +.PP Next, the detailed command docs, in alphabetical order. .SS accounts .PP @@ -3459,6 +3066,9 @@ the \f[C]Asset\f[R] or \f[C]Cash\f[R] or \f[C]Liability\f[R] type, or otherwise all accounts under a top-level \f[C]asset\f[R] or \f[C]liability\f[R] account (case insensitive, plurals allowed). .PP +(This report is essentially similar to \[dq]hledger balance --historical +assets liabilities\[dq], with liabilities sign-flipped.) +.PP Example: .IP .nf @@ -3515,6 +3125,10 @@ or \f[C]Equity\f[R] type, or otherwise all accounts under a top-level \f[C]asset\f[R], \f[C]liability\f[R] or \f[C]equity\f[R] account (case insensitive, plurals allowed). .PP +(This report is essentially similar to \[dq]hledger balance --historical +assets liabilities equity\[dq], with liabilities and equity +sign-flipped.) +.PP Example: .IP .nf @@ -3565,6 +3179,9 @@ The \[dq]cash\[dq] accounts shown are those accounts declared with the have \f[C]fixed\f[R], \f[C]investment\f[R], \f[C]receivable\f[R] or \f[C]A/R\f[R] in their name. .PP +(This report is essentially similar to \[dq]hledger balance --change +assets not:fixed not:investment not:receivable\[dq].) +.PP Example: .IP .nf @@ -4045,6 +3662,9 @@ the \f[C]Revenue\f[R] or \f[C]Expense\f[R] type, or otherwise all accounts under a top-level \f[C]revenue\f[R] or \f[C]income\f[R] or \f[C]expense\f[R] account (case insensitive, plurals allowed). .PP +(This report is essentially similar to \[dq]hledger balance --change +revenues expenses\[dq], with revenues sign-flipped.) +.PP Example: .IP .nf @@ -4106,6 +3726,371 @@ Petrol Snacks \f[R] .fi +.SS payees +.PP +payees +.PD 0 +.P +.PD +List the unique payee/payer names that appear in transactions. +.PP +This command lists the unique payee/payer names that appear in +transactions, in alphabetic order. +You can add a query to select a subset of transactions. +The payee/payer is the part of the transaction description before a | +character (or if there is no |, the whole description). +.PP +Example: +.IP +.nf +\f[C] +$ hledger payees +Store Name +Gas Station +Person A +\f[R] +.fi +.SS prices +.PP +prices +.PD 0 +.P +.PD +Print market price directives from the journal. +With --costs, also print synthetic market prices based on transaction +prices. +With --inverted-costs, also print inverse prices based on transaction +prices. +Prices (and postings providing prices) can be filtered by a query. +Price amounts are always displayed with their full precision. +.SS print +.PP +print, txns, p +.PD 0 +.P +.PD +Show transaction journal entries, sorted by date. +.PP +The print command displays full journal entries (transactions) from the +journal file in date order, tidily formatted. +With --date2, transactions are sorted by secondary date instead. +.PP +print\[aq]s output is always a valid hledger journal. +.PD 0 +.P +.PD +It preserves all transaction information, but it does not preserve +directives or inter-transaction comments +.IP +.nf +\f[C] +$ hledger print +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + +2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + +2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + +2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + +2008/12/31 * pay off + liabilities:debts $1 + assets:bank:checking $-1 +\f[R] +.fi +.PP +Normally, the journal entry\[aq]s explicit or implicit amount style is +preserved. +For example, when an amount is omitted in the journal, it will not +appear in the output. +Similarly, when a transaction price is implied but not written, it will +not appear in the output. +You can use the \f[C]-x\f[R]/\f[C]--explicit\f[R] flag to make all +amounts and transaction prices explicit, which can be useful for +troubleshooting or for making your journal more readable and robust +against data entry errors. +\f[C]-x\f[R] is also implied by using any of +\f[C]-B\f[R],\f[C]-V\f[R],\f[C]-X\f[R],\f[C]--value\f[R]. +.PP +Note, \f[C]-x\f[R]/\f[C]--explicit\f[R] will cause postings with a +multi-commodity amount (these can arise when a multi-commodity +transaction has an implicit amount) to be split into multiple +single-commodity postings, keeping the output parseable. +.PP +With \f[C]-B\f[R]/\f[C]--cost\f[R], amounts with transaction prices are +converted to cost using that price. +This can be used for troubleshooting. +.PP +With \f[C]-m\f[R]/\f[C]--match\f[R] and a STR argument, print will show +at most one transaction: the one one whose description is most similar +to STR, and is most recent. +STR should contain at least two characters. +If there is no similar-enough match, no transaction will be shown. +.PP +With \f[C]--new\f[R], for each FILE being read, hledger reads (and +writes) a special state file (\f[C].latest.FILE\f[R] in the same +directory), containing the latest transaction date(s) that were seen +last time FILE was read. +When this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. +This is useful for ignoring already-seen entries in import data, such as +downloaded CSV files. +Eg: +.IP +.nf +\f[C] +$ hledger -f bank1.csv print --new +(shows transactions added since last print --new on this file) +\f[R] +.fi +.PP +This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. +See also the import command. +.PP +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +and (experimental) \f[C]json\f[R] and \f[C]sql\f[R]. +.PP +Here\[aq]s an example of print\[aq]s CSV output: +.IP +.nf +\f[C] +$ hledger print -Ocsv +\[dq]txnidx\[dq],\[dq]date\[dq],\[dq]date2\[dq],\[dq]status\[dq],\[dq]code\[dq],\[dq]description\[dq],\[dq]comment\[dq],\[dq]account\[dq],\[dq]amount\[dq],\[dq]commodity\[dq],\[dq]credit\[dq],\[dq]debit\[dq],\[dq]posting-status\[dq],\[dq]posting-comment\[dq] +\[dq]1\[dq],\[dq]2008/01/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]income\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]1\[dq],\[dq]2008/01/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]income\[dq],\[dq]\[dq],\[dq]income:salary\[dq],\[dq]-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]2\[dq],\[dq]2008/06/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]gift\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]2\[dq],\[dq]2008/06/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]gift\[dq],\[dq]\[dq],\[dq]income:gifts\[dq],\[dq]-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]3\[dq],\[dq]2008/06/02\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]save\[dq],\[dq]\[dq],\[dq]assets:bank:saving\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]3\[dq],\[dq]2008/06/02\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]save\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]expenses:food\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]expenses:supplies\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]assets:cash\[dq],\[dq]-2\[dq],\[dq]$\[dq],\[dq]2\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]5\[dq],\[dq]2008/12/31\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]pay off\[dq],\[dq]\[dq],\[dq]liabilities:debts\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq] +\[dq]5\[dq],\[dq]2008/12/31\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]pay off\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq] +\f[R] +.fi +.IP \[bu] 2 +There is one CSV record per posting, with the parent transaction\[aq]s +fields repeated. +.IP \[bu] 2 +The \[dq]txnidx\[dq] (transaction index) field shows which postings +belong to the same transaction. +(This number might change if transactions are reordered within the file, +files are parsed/included in a different order, etc.) +.IP \[bu] 2 +The amount is separated into \[dq]commodity\[dq] (the symbol) and +\[dq]amount\[dq] (numeric quantity) fields. +.IP \[bu] 2 +The numeric amount is repeated in either the \[dq]credit\[dq] or +\[dq]debit\[dq] column, for convenience. +(Those names are not accurate in the accounting sense; it just puts +negative amounts under credit and zero or greater amounts under debit.) +.SS print-unique +.PP +print-unique +.PD 0 +.P +.PD +Print transactions which do not reuse an already-seen description. +.PP +Example: +.IP +.nf +\f[C] +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 +\f[R] +.fi +.SS register +.PP +register, reg, r +.PD 0 +.P +.PD +Show postings and their running total. +.PP +The register command displays matched postings, across all accounts, in +date order, with their running total or running historical balance. +(See also the \f[C]aregister\f[R] command, which shows matched +transactions in a specific account.) +.PP +register normally shows line per posting, but note that multi-commodity +amounts will occupy multiple lines (one line per commodity). +.PP +It is typically used with a query selecting a particular account, to see +that account\[aq]s activity: +.IP +.nf +\f[C] +$ hledger register checking +2008/01/01 income assets:bank:checking $1 $1 +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 +\f[R] +.fi +.PP +With --date2, it shows and sorts by secondary date instead. +.PP +The \f[C]--historical\f[R]/\f[C]-H\f[R] flag adds the balance from any +undisplayed prior postings to the running total. +This is useful when you want to see only recent activity, with a +historically accurate running balance: +.IP +.nf +\f[C] +$ hledger register checking -b 2008/6 --historical +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 +\f[R] +.fi +.PP +The \f[C]--depth\f[R] option limits the amount of sub-account detail +displayed. +.PP +The \f[C]--average\f[R]/\f[C]-A\f[R] flag shows the running average +posting amount instead of the running total (so, the final number +displayed is the average for the whole report period). +This flag implies \f[C]--empty\f[R] (see below). +It is affected by \f[C]--historical\f[R]. +It works best when showing just one account and one commodity. +.PP +The \f[C]--related\f[R]/\f[C]-r\f[R] flag shows the \f[I]other\f[R] +postings in the transactions of the postings which would normally be +shown. +.PP +The \f[C]--invert\f[R] flag negates all amounts. +For example, it can be used on an income account where amounts are +normally displayed as negative numbers. +It\[aq]s also useful to show postings on the checking account together +with the related account: +.IP +.nf +\f[C] +$ hledger register --related --invert assets:checking +\f[R] +.fi +.PP +With a reporting interval, register shows summary postings, one per +interval, aggregating the postings to each account: +.IP +.nf +\f[C] +$ hledger register --monthly income +2008/01 income:salary $-1 $-1 +2008/06 income:gifts $-1 $-2 +\f[R] +.fi +.PP +Periods with no activity, and summary postings with a zero amount, are +not shown by default; use the \f[C]--empty\f[R]/\f[C]-E\f[R] flag to see +them: +.IP +.nf +\f[C] +$ hledger register --monthly income -E +2008/01 income:salary $-1 $-1 +2008/02 0 $-1 +2008/03 0 $-1 +2008/04 0 $-1 +2008/05 0 $-1 +2008/06 income:gifts $-1 $-2 +2008/07 0 $-2 +2008/08 0 $-2 +2008/09 0 $-2 +2008/10 0 $-2 +2008/11 0 $-2 +2008/12 0 $-2 +\f[R] +.fi +.PP +Often, you\[aq]ll want to see just one line per interval. +The \f[C]--depth\f[R] option helps with this, causing subaccounts to be +aggregated: +.IP +.nf +\f[C] +$ hledger register --monthly assets --depth 1h +2008/01 assets $1 $1 +2008/06 assets $-1 0 +2008/12 assets $-1 $-1 +\f[R] +.fi +.PP +Note when using report intervals, if you specify start/end dates these +will be adjusted outward if necessary to contain a whole number of +intervals. +This ensures that the first and last intervals are full length and +comparable to the others in the report. +.SS Custom register output +.PP +register uses the full terminal width by default, except on windows. +You can override this by setting the \f[C]COLUMNS\f[R] environment +variable (not a bash shell variable) or by using the +\f[C]--width\f[R]/\f[C]-w\f[R] option. +.PP +The description and account columns normally share the space equally +(about half of (width - 40) each). +You can adjust this by adding a description width as part of +--width\[aq]s argument, comma-separated: \f[C]--width W,D\f[R] . +Here\[aq]s a diagram (won\[aq]t display correctly in --help): +.IP +.nf +\f[C] +<--------------------------------- width (W) ----------------------------------> +date (10) description (D) account (W-41-D) amount (12) balance (12) +DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA +\f[R] +.fi +.PP +and some examples: +.IP +.nf +\f[C] +$ hledger reg # use terminal width (or 80 on windows) +$ hledger reg -w 100 # use width 100 +$ COLUMNS=100 hledger reg # set with one-time environment variable +$ export COLUMNS=100; hledger reg # set till session end (or window resize) +$ hledger reg -w 100,40 # set overall width 100, description width 40 +$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 +\f[R] +.fi +.PP +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +and (experimental) \f[C]json\f[R]. +.SS register-match +.PP +register-match +.PD 0 +.P +.PD +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. +If there are multiple equally good matches, it shows the most recent. +Query options (options, not arguments) can be used to restrict the +search space. +Helps ledger-autosync detect already-seen transactions when importing. .SS rewrite .PP rewrite @@ -4671,34 +4656,29 @@ $ 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). -.SS Add-on commands +.SS About add-on commands .PP -Any programs or scripts in your PATH named named -\f[C]hledger-SOMETHING\f[R] will also appear in the commands list (with -a \f[C]+\f[R] mark). -These are called add-on commands. +Add-on commands are programs or scripts in your PATH +.IP \[bu] 2 +whose name starts with \f[C]hledger-\f[R] +.IP \[bu] 2 +whose name ends with a recognised file extension: +\f[C].bat\f[R],\f[C].com\f[R],\f[C].exe\f[R], +\f[C].hs\f[R],\f[C].lhs\f[R],\f[C].pl\f[R],\f[C].py\f[R],\f[C].rb\f[R],\f[C].rkt\f[R],\f[C].sh\f[R] +or none +.IP \[bu] 2 +and (on unix, mac) which are executable by the current user. .PP -These offical add-ons are maintained and released along with hledger: -.IP \[bu] 2 -ui an efficient terminal interface for hledger (TUI) -.IP \[bu] 2 -web a simple web interface for hledger (WUI) +Add-ons are a relatively easy way to add local features or experiment +with new ideas. +They can be written in any language, but haskell scripts have a big +advantage: they can use the same hledger library functions that built-in +commands use for command-line options, parsing and reporting. +Some experimental/example add-on scripts can be found in the hledger +repo\[aq]s bin/ directory. .PP -These add-ons are maintained separately: -.IP \[bu] 2 -iadd a more interactive alternative for the add command -.IP \[bu] 2 -interest generates interest transactions according to various schemes -.IP \[bu] 2 -stockquotes downloads market prices for your commodities from -AlphaVantage \f[I](experimental)\f[R] -.PP -Additional experimental add-ons, which may not be in a working state, -can be found in the bin/ directory in the hledger repo. -.SS Add-on command flags -.PP -In a hledger command line, add-on command flags must have a double dash -(\f[C]--\f[R]) preceding them. +Note in a hledger command line, add-on command flags must have a double +dash (\f[C]--\f[R]) preceding them. Eg you must write: .IP .nf @@ -4731,24 +4711,462 @@ add-on program directly, eg: $ hledger-web --serve \f[R] .fi -.SS Making add-on commands +.SH COMMON TASKS .PP -Add-on commands are programs or scripts in your PATH -.IP \[bu] 2 -whose name starts with \f[C]hledger-\f[R] -.IP \[bu] 2 -whose name ends with a recognised file extension: -\f[C].bat\f[R],\f[C].com\f[R],\f[C].exe\f[R], -\f[C].hs\f[R],\f[C].lhs\f[R],\f[C].pl\f[R],\f[C].py\f[R],\f[C].rb\f[R],\f[C].rkt\f[R],\f[C].sh\f[R] -or none -.IP \[bu] 2 -and (on unix, mac) which are executable by the current user. +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 Getting help +.IP +.nf +\f[C] +$ 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 -Add-ons are a relatively easy way to add local features or experiment -with new ideas. -They can be written in any language, but haskell scripts have a big -advantage: they can use the same hledger library functions that built-in -commands use for command-line options, parsing and reporting. +Find more docs, chat, mail list, reddit, issue tracker: +https://hledger.org#help-feedback +.SS Constructing command lines +.PP +hledger has an extensive and powerful command line interface. +We strive to keep it simple and ergonomic, but you may run into one of +the confusing real world details described in OPTIONS, below. +If that happens, here are some tips that may help: +.IP \[bu] 2 +command-specific options must go after the command (it\[aq]s fine to put +all options there) (\f[C]hledger CMD OPTS ARGS\f[R]) +.IP \[bu] 2 +running add-on executables directly simplifies command line parsing +(\f[C]hledger-ui OPTS ARGS\f[R]) +.IP \[bu] 2 +enclose \[dq]problematic\[dq] args in single quotes +.IP \[bu] 2 +if needed, also add a backslash to hide regular expression +metacharacters from the shell +.IP \[bu] 2 +to see how a misbehaving command is being parsed, add +\f[C]--debug=2\f[R]. +.SS Starting a journal file +.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 -m \[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 -m \[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 +2020-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + +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 + $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 +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 +Show weekly posting counts as a bar chart: +.IP +.nf +\f[C] +$ hledger activity -W +2019-12-30 ***** +2020-01-06 **** +2020-01-13 **** +\f[R] +.fi +.SS Migrating to 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. +.PP +If using version control, don\[aq]t forget to \f[C]git add\f[R] the new +file. .SH ENVIRONMENT .PP \f[B]LEDGER_FILE\f[R] The journal file path when not specified with @@ -4783,12 +5201,6 @@ Default: the full terminal width. \f[B]NO_COLOR\f[R] If this variable exists with any value, hledger will not use ANSI color codes in terminal output. This overrides the --color/--colour option. -.SH FILES -.PP -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with \f[C]-f\f[R], or -\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]). .SH LIMITATIONS .PP The need to precede add-on command options with \f[C]--\f[R] when diff --git a/hledger/hledger.info b/hledger/hledger.info index 8f5850388..e7a4299c3 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1,7 +1,7 @@ This is hledger.info, produced by makeinfo version 6.7 from stdin.  -File: hledger.info, Node: Top, Next: COMMON TASKS, Up: (dir) +File: hledger.info, Node: Top, Next: OPTIONS, Up: (dir) hledger(1) ********** @@ -57,441 +57,24 @@ try some commands like 'hledger print' or 'hledger balance'. Run * Menu: -* COMMON TASKS:: * OPTIONS:: +* DATA FILES:: +* TIME PERIODS:: +* DEPTH:: +* QUERIES:: +* VALUATION:: +* PIVOTING:: +* OUTPUT:: * COMMANDS:: +* COMMON TASKS:: * ENVIRONMENT:: -* FILES:: * LIMITATIONS:: * TROUBLESHOOTING::  -File: hledger.info, Node: COMMON TASKS, Next: OPTIONS, Prev: Top, Up: Top +File: hledger.info, Node: OPTIONS, Next: DATA FILES, Prev: Top, Up: Top -1 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. - -* Menu: - -* Getting help:: -* Constructing command lines:: -* Starting a journal file:: -* Setting opening balances:: -* Recording transactions:: -* Reconciling:: -* Reporting:: -* Migrating to a new file:: - - -File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: COMMON TASKS - -1.1 Getting 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 - - -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: COMMON TASKS - -1.2 Constructing command lines -============================== - -hledger has an extensive and powerful command line interface. We strive -to keep it simple and ergonomic, but you may run into one of the -confusing real world details described in OPTIONS, below. If that -happens, here are some tips that may help: - - * command-specific options must go after the command (it's fine to - put all options there) ('hledger CMD OPTS ARGS') - * running add-on executables directly simplifies command line parsing - ('hledger-ui OPTS ARGS') - * enclose "problematic" args in single quotes - * if needed, also add a backslash to hide regular expression - metacharacters from the shell - * to see how a misbehaving command is being parsed, add '--debug=2'. - - -File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: COMMON TASKS - -1.3 Starting a journal file -=========================== - -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 () - - -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: COMMON TASKS - -1.4 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 -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. - - Add an opening balances transaction to the journal, declaring the -balances on this date. Here are two ways to do it: - - * 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. - - * 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 -m 'initial balances' 2020.journal - - -File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: COMMON TASKS - -1.5 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 - -2020.1.12 * farmers market - expenses:food $13 - assets:cash - -2020-01-15 paycheck - income:salary - assets:bank:checking $1000 - - -File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: COMMON TASKS - -1.6 Reconciling -=============== - -Periodically you should reconcile - compare your hledger-reported -balances 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 -discrepancies. - - 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 - already-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 checking -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 transaction history and running balance from your bank - with the one reported by 'hledger reg checking -C'. This will be - easier if you generally record transaction dates quite similar to - your bank's clearing dates. - - 3. Repeat for other asset/liability accounts. - - Tip: instead of the register command, use hledger-ui to see a -live-updating register while you edit the journal: 'hledger-ui --watch ---register 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 -commit: - -$ git commit -m 'txns' 2020.journal - - -File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: COMMON TASKS - -1.7 Reporting -============= - -Here are some basic reports. - - Show all transactions: - -$ hledger print -2020-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - -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 - $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 -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 - - Show weekly posting counts as a bar chart: - -$ hledger activity -W -2019-12-30 ***** -2020-01-06 **** -2020-01-13 **** - - -File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: COMMON TASKS - -1.8 Migrating to 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. - - If using version control, don't forget to 'git add' the new file. - - -File: hledger.info, Node: OPTIONS, Next: COMMANDS, Prev: COMMON TASKS, Up: Top - -2 OPTIONS +1 OPTIONS ********* * Menu: @@ -499,26 +82,14 @@ File: hledger.info, Node: OPTIONS, Next: COMMANDS, Prev: COMMON TASKS, Up: T * General options:: * Command options:: * Command arguments:: -* Queries:: -* Special characters in arguments and queries:: +* Special characters:: * Unicode characters:: -* Input files:: -* Strict mode:: -* Output destination:: -* Output format:: * Regular expressions:: -* Smart dates:: -* Report start & end date:: -* Report intervals:: -* Period expressions:: -* Depth limiting:: -* Pivoting:: -* Valuation::  File: hledger.info, Node: General options, Next: Command options, Up: OPTIONS -2.1 General options +1.1 General options =================== To see general usage help, including general options which are supported @@ -657,7 +228,7 @@ the last one takes precedence.  File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS -2.2 Command options +1.2 Command options =================== To see options for a particular command, including command-specific @@ -671,9 +242,9 @@ options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can run the add-on executable directly: 'hledger-ui --watch'.  -File: hledger.info, Node: Command arguments, Next: Queries, Prev: Command options, Up: OPTIONS +File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: OPTIONS -2.3 Command arguments +1.3 Command arguments ===================== Most hledger commands accept arguments after the command name, which are @@ -711,201 +282,105 @@ than you would at the command prompt. Bad: See also: Save frequently used options.  -File: hledger.info, Node: Queries, Next: Special characters in arguments and queries, Prev: Command arguments, Up: OPTIONS +File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: OPTIONS -2.4 Queries -=========== - -One of hledger'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. - - We do not yet support arbitrary boolean combinations of search terms; -instead most commands show transactions/postings/accounts which match -(or negatively match): - - * any of the description terms AND - * any of the account terms AND - * any of the status terms AND - * all the other terms. - - The print command instead shows transactions which: - - * match any of the description terms AND - * have any postings matching any of the positive account terms AND - * have no postings matching any of the negative account terms AND - * match all the other terms. - - The following kinds of search terms can be used. 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 prefix, - 'acct:' is assumed.) same as above - -*'amt:N, amt:N, amt:>=N'* - - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not - tested, and will always match.) The comparison has two modes: if N - is preceded by a + or - sign (or is 0), the two signed numbers are - compared. Otherwise, the absolute magnitudes are compared, - ignoring sign. -*'code:REGEX'* - - match by transaction code (eg check number) -*'cur:REGEX'* - - match postings or transactions including any amounts whose - currency/commodity symbol is fully matched by REGEX. (For a partial - match, use '.*REGEX.*'). Note, to match characters which are - regex-significant, like the dollar sign ('$'), you need to prepend - '\'. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: 'hledger - print cur:'\$'' or 'hledger print cur:\\$'. -*'desc:REGEX'* - - match transaction descriptions. -*'date:PERIODEXPR'* - - match dates within the specified period. 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 - account. 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). - - -File: hledger.info, Node: Special characters in arguments and queries, Next: Unicode characters, Prev: Queries, Up: OPTIONS - -2.5 Special characters in arguments and queries -=============================================== - -In shell command lines, option and argument values which contain -"problematic" characters, ie spaces, and also characters significant to -your shell such as '<', '>', '(', ')', '|' and '$', should be escaped by -enclosing them in quotes or by writing backslashes before the -characters. Eg: - - 'hledger register -p 'last year' "accounts receivable -(receivable|payable)" amt:\>100'. +1.4 Special characters +====================== * Menu: -* More escaping:: -* Even more escaping:: +* Single escaping shell metacharacters:: +* Double escaping regular expression metacharacters:: +* Triple escaping for add-on commands:: * Less escaping::  -File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries +File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters -2.5.1 More escaping -------------------- +1.4.1 Single escaping (shell metacharacters) +-------------------------------------------- -Characters significant both to the shell and in regular expressions may -need one extra level of escaping. These include parentheses, the pipe -symbol and the dollar sign. Eg, to match the dollar symbol, bash users -should do: +In shell command lines, characters significant to your shell - such as +spaces, '<', '>', '(', ')', '|', '$' and '\' - should be "shell-escaped" +if you want hledger to see them. This is done by enclosing them in +single or double quotes, or by writing a backslash before them. Eg to +match an account name containing a space: - 'hledger balance cur:'\$'' +$ hledger register 'credit card' or: - 'hledger balance cur:\\$' +$ hledger register credit\ card  -File: hledger.info, Node: Even more escaping, Next: Less escaping, Prev: More escaping, Up: Special characters in arguments and queries +File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters -2.5.2 Even more escaping ------------------------- +1.4.2 Double escaping (regular expression metacharacters) +--------------------------------------------------------- -When hledger runs an add-on executable (eg you type 'hledger ui', -hledger runs 'hledger-ui'), it de-escapes command-line options and -arguments once, so you might need to _triple_-escape. Eg in bash, -running the ui command and matching the dollar sign, it's: +Characters significant in regular expressions (described below) - such +as '.', '^', '$', '[', ']', '(', ')', '|', and '\' - may need to be +"regex-escaped" if you don't want them to be interpreted by hledger's +regular expression engine. This is done by writing backslashes before +them, but since backslash is typically also a shell metacharacter, both +shell-escaping and regex-escaping will be needed. Eg to match a literal +'$' sign while using the bash shell: - 'hledger ui cur:'\\$'' +$ hledger balance cur:'\$' or: - 'hledger ui cur:\\\\$' +$ hledger balance cur:\\$ - If you asked why _four_ slashes above, this may help: + +File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters + +1.4.3 Triple escaping (for add-on commands) +------------------------------------------- + +When you use hledger to run an external add-on command (described +below), one level of shell-escaping is lost from any options or +arguments intended for by the add-on command, so those need an extra +level of shell-escaping. Eg to match a literal '$' sign while using the +bash shell and running an add-on command ('ui'): + +$ hledger ui cur:'\\$' + + or: + +$ hledger ui cur:\\\\$ + + If you wondered why _four_ backslashes, perhaps this helps: unescaped: '$' escaped: '\$' double-escaped: '\\$' triple-escaped: '\\\\$' - (The number of backslashes in fish shell is left as an exercise for -the reader.) + Or, you can avoid the extra escaping by running the add-on executable +directly: - You can always avoid the extra escaping for add-ons by running the -add-on directly: - - 'hledger-ui cur:\\$' +$ hledger-ui cur:\\$  -File: hledger.info, Node: Less escaping, Prev: Even more escaping, Up: Special characters in arguments and queries +File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters -2.5.3 Less escaping +1.4.4 Less escaping ------------------- -Inside an argument file, or in the search field of hledger-ui or -hledger-web, or at a GHCI prompt, you need one less level of escaping -than at the command line. And backslashes may work better than quotes. -Eg: +Options and arguments are sometimes used in places other than the shell +command line, where shell-escaping is not needed, so there you should +use one less level of escaping. Those places include: - 'ghci> :main balance cur:\$' + * an @argumentfile + * hledger-ui's filter field + * hledger-web's search form + * GHCI's prompt (used by developers).  -File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Special characters in arguments and queries, Up: OPTIONS +File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: OPTIONS -2.6 Unicode characters +1.5 Unicode characters ====================== hledger is expected to handle non-ascii characters correctly: @@ -942,170 +417,10 @@ hledger is expected to handle non-ascii characters correctly: terminal, and vice versa. (See eg #961).  -File: hledger.info, Node: Input files, Next: Strict mode, Prev: Unicode characters, Up: OPTIONS +File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: OPTIONS -2.7 Input files -=============== - -hledger reads transactions from a data file (and the add command writes -to it). By default this file is '$HOME/.hledger.journal' (or on -Windows, something like 'C:/Users/USER/.hledger.journal'). You can -override this with the '$LEDGER_FILE' environment variable: - -$ setenv LEDGER_FILE ~/finance/2016.journal -$ hledger stats - - or with the '-f/--file' option: - -$ hledger -f /some/file stats - - The file name '-' (hyphen) means standard input: - -$ cat some.journal | hledger -f- - - Usually the data file is in hledger's journal format, but it can be -in any of the supported file formats, which currently are: - -Reader: Reads: Used for file - extensions: --------------------------------------------------------------------------- -'journal'hledger journal files and some Ledger '.journal' '.j' - journals, for transactions '.hledger' '.ledger' -'timeclock'timeclock files, for precise time '.timeclock' - logging -'timedot'timedot files, for approximate time '.timedot' - logging -'csv' comma/semicolon/tab/other-separated '.csv' '.ssv' '.tsv' - values, for data import - - hledger detects the format automatically based on the file extensions -shown above. If it can't recognise the file extension, it assumes -'journal' format. So for non-journal files, it's important to use a -recognised file extension, so as to either read successfully or to show -relevant error messages. - - When you can't ensure the right file extension, not to worry: you can -force a specific reader/format by prefixing the file path with the -format and a colon. Eg to read a .dat file as csv: - -$ hledger -f csv:/some/csv-file.dat stats -$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- - - You can specify multiple '-f' options, to read multiple files as one -big journal. There are some limitations with this: - - * directives in one file will not affect the other files - * balance assertions will not see any account balances from previous - files - - If you need either of those things, you can - - * use a single parent file which includes the others - * or concatenate the files into one before reading, eg: 'cat - a.journal b.journal | hledger -f- CMD'. - - -File: hledger.info, Node: Strict mode, Next: Output destination, Prev: Input files, Up: OPTIONS - -2.8 Strict mode -=============== - -hledger checks input files for valid data. By default, the most -important errors are detected, while still accepting easy journal files -without a lot of declarations: - - * Are the input files parseable, with valid syntax ? - * Are all transactions balanced ? - * Do all balance assertions pass ? - - With the '-s'/'--strict' flag, additional checks are performed: - - * Are all accounts posted to, declared with an 'account' directive ? - (Account error checking) - * Are all commodities declared with a 'commodity' directive ? - (Commodity error checking) - - See also: https://hledger.org/checking-for-errors.html - - _experimental._ - - -File: hledger.info, Node: Output destination, Next: Output format, Prev: Strict mode, Up: OPTIONS - -2.9 Output destination -====================== - -hledger commands send their output to the terminal by default. You can -of course redirect this, eg into a file, using standard shell syntax: - -$ hledger print > foo.txt - - Some commands (print, register, stats, the balance commands) also -provide the '-o/--output-file' option, which does the same thing without -needing the shell. Eg: - -$ hledger print -o foo.txt -$ hledger print -o - # write to stdout (the default) - - -File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS - -2.10 Output format -================== - -Some commands (print, register, the balance commands) offer a choice of -output format. In addition to the usual plain text format ('txt'), -there are CSV ('csv'), HTML ('html'), JSON ('json') and SQL ('sql'). -This is controlled by the '-O/--output-format' option: - -$ hledger print -O csv - - or, by a file extension specified with '-o/--output-file': - -$ hledger balancesheet -o foo.html # write HTML to foo.html - - The '-O' option can be used to override the file extension if needed: - -$ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt - - Some notes about JSON output: - - * This feature is marked experimental, and not yet much used; you - should expect our JSON to evolve. Real-world feedback is welcome. - - * Our JSON is rather large and verbose, as it is quite a faithful - representation of hledger's internal data types. To understand the - JSON, read the Haskell type definitions, which are mostly in - https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. - - * hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can - arise in practice (from automatically-calculated transaction - prices), and would break most JSON consumers. So in JSON, we show - quantities as simple Numbers with at most 10 decimal places. We - don't limit the number of integer digits, but that part is under - your control. We hope this approach will not cause problems in - practice; if you find otherwise, please let us know. (Cf #1195) - - Notes about SQL output: - - * SQL output is also marked experimental, and much like JSON could - use real-world feedback. - - * SQL output is expected to work with sqlite, MySQL and PostgreSQL - - * SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables - created via SQL output of hledger, you would probably want to - either clear tables of existing data (via 'delete' or 'truncate' - SQL statements) or drop tables completely as otherwise your - postings will be duped. - - -File: hledger.info, Node: Regular expressions, Next: Smart dates, Prev: Output format, Up: OPTIONS - -2.11 Regular expressions -======================== +1.6 Regular expressions +======================= hledger uses regular expressions in a number of places: @@ -1147,15 +462,133 @@ they support: See Special characters.  -File: hledger.info, Node: Smart dates, Next: Report start & end date, Prev: Regular expressions, Up: OPTIONS +File: hledger.info, Node: DATA FILES, Next: TIME PERIODS, Prev: OPTIONS, Up: Top -2.12 Smart dates +2 DATA FILES +************ + +hledger reads transactions from one or more data files. The default +data file is '$HOME/.hledger.journal' (or on Windows, something like +'C:/Users/USER/.hledger.journal'). + + You can override this with the '$LEDGER_FILE' environment variable: + +$ setenv LEDGER_FILE ~/finance/2016.journal +$ hledger stats + + or with one or more '-f/--file' options: + +$ hledger -f /some/file -f another_file stats + + The file name '-' means standard input: + +$ cat some.journal | hledger -f- + +* Menu: + +* Data formats:: +* Multiple files:: +* Strict mode:: + + +File: hledger.info, Node: Data formats, Next: Multiple files, Up: DATA FILES + +2.1 Data formats ================ -hledger's user interfaces accept a flexible "smart date" syntax (unlike -dates in the journal file). Smart dates allow some english words, can -be relative to today's date, and can have less-significant date parts -omitted (defaulting to 1). +Usually the data file is in hledger's journal format, but it can be in +any of the supported file formats, which currently are: + +Reader: Reads: Used for file + extensions: +-------------------------------------------------------------------------- +'journal'hledger journal files and some Ledger '.journal' '.j' + journals, for transactions '.hledger' '.ledger' +'timeclock'timeclock files, for precise time '.timeclock' + logging +'timedot'timedot files, for approximate time '.timedot' + logging +'csv' comma/semicolon/tab/other-separated '.csv' '.ssv' '.tsv' + values, for data import + + hledger detects the format automatically based on the file extensions +shown above. If it can't recognise the file extension, it assumes +'journal' format. So for non-journal files, it's important to use a +recognised file extension, so as to either read successfully or to show +relevant error messages. + + You can also force a specific reader/format by prefixing the file +path with the format and a colon. Eg to read a .dat file as csv: + +$ hledger -f csv:/some/csv-file.dat stats +$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- + + +File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: DATA FILES + +2.2 Multiple files +================== + +You can specify multiple '-f' options, to read multiple files as one big +journal. There are some limitations with this: + + * most directives do not affect sibling files + * balance assertions will not see any account balances from previous + files + + If you need either of those things, you can + + * use a single parent file which includes the others + * or concatenate the files into one before reading, eg: 'cat + a.journal b.journal | hledger -f- CMD'. + + +File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: DATA FILES + +2.3 Strict mode +=============== + +hledger checks input files for valid data. By default, the most +important errors are detected, while still accepting easy journal files +without a lot of declarations: + + * Are the input files parseable, with valid syntax ? + * Are all transactions balanced ? + * Do all balance assertions pass ? + + With the '-s'/'--strict' flag, additional checks are performed: + + * Are all accounts posted to, declared with an 'account' directive ? + (Account error checking) + * Are all commodities declared with a 'commodity' directive ? + (Commodity error checking) + + See also: https://hledger.org/checking-for-errors.html + + _experimental._ + + +File: hledger.info, Node: TIME PERIODS, Next: DEPTH, Prev: DATA FILES, Up: Top + +3 TIME PERIODS +************** + +* Menu: + +* Smart dates:: +* Report start & end date:: +* Report intervals:: +* Period expressions:: + + +File: hledger.info, Node: Smart dates, Next: Report start & end date, Up: TIME PERIODS + +3.1 Smart dates +=============== + +hledger's user interfaces accept a flexible "smart date" syntax. Smart +dates allow some english words, can be relative to today's date, and can +have less-significant date parts omitted (defaulting to 1). Examples: @@ -1186,10 +619,10 @@ results: '201801012' 9+ digits beginning with a valid YYYYMMDD gives an error  -File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS +File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: TIME PERIODS -2.13 Report start & end date -============================ +3.2 Report start & end date +=========================== By default, most hledger reports will show the full span of time represented by the journal data. The report start date will be the @@ -1229,10 +662,10 @@ thismonth' 'date:thismonth'  -File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS +File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: TIME PERIODS -2.14 Report intervals -===================== +3.3 Report intervals +==================== A report interval can be specified so that commands like register, balance and activity will divide their reports into multiple subperiods. @@ -1242,10 +675,10 @@ complex intervals may be specified with a period expression. Report intervals can not be specified with a query.  -File: hledger.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS +File: hledger.info, Node: Period expressions, Prev: Report intervals, Up: TIME PERIODS -2.15 Period expressions -======================= +3.4 Period expressions +====================== The '-p/--period' option accepts period expressions, a shorthand way of expressing a start date, end date, and/or report interval all at once. @@ -1371,10 +804,10 @@ start date and exclusive end date): 'hledger register checking -p "every 3rd day of week"'  -File: hledger.info, Node: Depth limiting, Next: Pivoting, Prev: Period expressions, Up: OPTIONS +File: hledger.info, Node: DEPTH, Next: QUERIES, Prev: TIME PERIODS, Up: Top -2.16 Depth limiting -=================== +4 DEPTH +******* With the '--depth N' option (short form: '-N'), commands like account, balance and register will show only the uppermost accounts in the @@ -1383,67 +816,119 @@ less detail. This flag has the same effect as a 'depth:' query argument (so '-2', '--depth=2' or 'depth:2' are equivalent).  -File: hledger.info, Node: Pivoting, Next: Valuation, Prev: Depth limiting, Up: OPTIONS +File: hledger.info, Node: QUERIES, Next: VALUATION, Prev: DEPTH, Up: Top -2.17 Pivoting -============= +5 QUERIES +********* -Normally hledger sums amounts, and organizes them in a hierarchy, based -on account name. The '--pivot FIELD' option causes it to sum and -organize hierarchy based on the value of some other field instead. -FIELD can be: 'code', 'description', 'payee', 'note', or the full name -(case insensitive) of any tag. As with account names, values containing -'colon:separated:parts' will be displayed hierarchically in reports. +One of hledger'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. - '--pivot' is a general option affecting all reports; you can think of -hledger transforming the journal before any other processing, replacing -every posting's account name with the value of the specified field on -that posting, inheriting it from the transaction or using a blank value -if it's not present. + We do not yet support arbitrary boolean combinations of search terms; +instead most commands show transactions/postings/accounts which match +(or negatively match): - An example: + * any of the description terms AND + * any of the account terms AND + * any of the status terms AND + * all the other terms. -2016/02/16 Member Fee Payment - assets:bank account 2 EUR - income:member fees -2 EUR ; member: John Doe + The print command instead shows transactions which: - Normal balance report showing account names: + * match any of the description terms AND + * have any postings matching any of the positive account terms AND + * have no postings matching any of the negative account terms AND + * match all the other terms. -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:member fees --------------------- - 0 + The following kinds of search terms can be used. Remember these can +also be prefixed with *'not:'*, eg to exclude a particular subaccount. - Pivoted balance report, using member: tag values instead: +*'REGEX', 'acct:REGEX'* -$ hledger balance --pivot member - 2 EUR - -2 EUR John Doe --------------------- - 0 + match account names by this regular expression. (With no prefix, + 'acct:' is assumed.) same as above - One way to show only amounts with a member: value (using a query, -described below): +*'amt:N, amt:N, amt:>=N'* -$ hledger balance --pivot member tag:member=. - -2 EUR John Doe --------------------- - -2 EUR + 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'* - Another way (the acct: query matches against the pivoted "account -name"): + match by transaction code (eg check number) +*'cur:REGEX'* -$ hledger balance --pivot member acct:. - -2 EUR John Doe --------------------- - -2 EUR + match postings or transactions including any amounts whose + currency/commodity symbol is fully matched by REGEX. (For a partial + match, use '.*REGEX.*'). Note, to match characters which are + regex-significant, like the dollar sign ('$'), you need to prepend + '\'. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: 'hledger + print cur:'\$'' or 'hledger print cur:\\$'. +*'desc:REGEX'* + + match transaction descriptions. +*'date:PERIODEXPR'* + + match dates within the specified period. 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 + account. 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).  -File: hledger.info, Node: Valuation, Prev: Pivoting, Up: OPTIONS +File: hledger.info, Node: VALUATION, Next: PIVOTING, Prev: QUERIES, Up: Top -2.18 Valuation -============== +6 VALUATION +*********** Instead of reporting amounts in their original commodity, hledger can convert them to cost/sale amount (using the conversion rate recorded in @@ -1467,39 +952,39 @@ usually one of those is all you need. * Effect of valuation on reports::  -File: hledger.info, Node: -B Cost, Next: -V Value, Up: Valuation +File: hledger.info, Node: -B Cost, Next: -V Value, Up: VALUATION -2.18.1 -B: Cost ---------------- +6.1 -B: Cost +============ The '-B/--cost' flag converts amounts to their cost or sale amount at transaction time, if they have a transaction price specified.  -File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Prev: -B Cost, Up: Valuation +File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Prev: -B Cost, Up: VALUATION -2.18.2 -V: Value ----------------- +6.2 -V: Value +============= The '-V/--market' flag converts amounts to market value in their default _valuation commodity_, using the market prices in effect on the _valuation date(s)_, if any. More on these in a minute.  -File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation +File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: VALUATION -2.18.3 -X: Value in specified commodity ---------------------------------------- +6.3 -X: Value in specified commodity +==================================== The '-X/--exchange=COMM' option is like '-V', except you tell it which currency you want to convert to, and it tries to convert everything to that.  -File: hledger.info, Node: Valuation date, Next: Market prices, Prev: -X Value in specified commodity, Up: Valuation +File: hledger.info, Node: Valuation date, Next: Market prices, Prev: -X Value in specified commodity, Up: VALUATION -2.18.4 Valuation date ---------------------- +6.4 Valuation date +================== Since market prices can change from day to day, market value reports have a valuation date (or more than one), which determines which market @@ -1513,14 +998,12 @@ valuation date is the journal's end date. of the period, by default.  -File: hledger.info, Node: Market prices, Next: --infer-value market prices from transactions, Prev: Valuation date, Up: Valuation +File: hledger.info, Node: Market prices, Next: --infer-value market prices from transactions, Prev: Valuation date, Up: VALUATION -2.18.5 Market prices --------------------- +6.5 Market prices +================= -_(experimental)_ - - To convert a commodity A to its market value in another commodity B, +To convert a commodity A to its market value in another commodity B, hledger looks for a suitable market price (exchange rate) as follows, in this order of preference : @@ -1544,18 +1027,16 @@ this order of preference : converted.  -File: hledger.info, Node: --infer-value market prices from transactions, Next: Valuation commodity, Prev: Market prices, Up: Valuation +File: hledger.info, Node: --infer-value market prices from transactions, Next: Valuation commodity, Prev: Market prices, Up: VALUATION -2.18.6 -infer-value: market prices from transactions ----------------------------------------------------- +6.6 -infer-value: market prices from transactions +================================================= -_(experimental)_ - - Normally, market value in hledger is fully controlled by, and -requires, P directives in your journal. Since adding and updating those -can be a chore, and since transactions usually take place at close to -market value, why not use the recorded transaction prices as additional -market prices (as Ledger does) ? We could produce value reports without +Normally, market value in hledger is fully controlled by, and requires, +P directives in your journal. Since adding and updating those can be a +chore, and since transactions usually take place at close to market +value, why not use the recorded transaction prices as additional market +prices (as Ledger does) ? We could produce value reports without needing P directives at all. Adding the '--infer-value' flag to '-V', '-X' or '--value' enables @@ -1579,14 +1060,12 @@ you, read all of this Valuation section carefully, and try adding (no '@', multiple commodities, balanced).  -File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-value market prices from transactions, Up: Valuation +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-value market prices from transactions, Up: VALUATION -2.18.7 Valuation commodity --------------------------- +6.7 Valuation commodity +======================= -_(experimental)_ - - *When you specify a valuation commodity ('-X COMM' or '--value +*When you specify a valuation commodity ('-X COMM' or '--value TYPE,COMM'):* hledger will convert all amounts to COMM, wherever it can find a suitable market price (including by reversing or chaining prices). @@ -1619,10 +1098,10 @@ follows, in this order of preference: converted.  -File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation +File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: VALUATION -2.18.8 Simple valuation examples --------------------------------- +6.8 Simple valuation examples +============================= Here are some quick examples of '-V': @@ -1654,10 +1133,10 @@ $ hledger -f t.j bal -N euros -V $103.00 assets:euros  -File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation +File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: VALUATION -2.18.9 -value: Flexible valuation ---------------------------------- +6.9 -value: Flexible valuation +============================== '-B', '-V' and '-X' are special cases of the more general '--value' option: @@ -1702,10 +1181,10 @@ part: a comma, then the target commodity's symbol. Eg: this commodity, deducing market prices as described above.  -File: hledger.info, Node: More valuation examples, Next: Effect of valuation on reports, Prev: --value Flexible valuation, Up: Valuation +File: hledger.info, Node: More valuation examples, Next: Effect of valuation on reports, Prev: --value Flexible valuation, Up: VALUATION -2.18.10 More valuation examples -------------------------------- +6.10 More valuation examples +============================ Here are some examples showing the effect of '--value', as seen with 'print': @@ -1816,10 +1295,10 @@ $ hledger print -X A b -0.50A  -File: hledger.info, Node: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation +File: hledger.info, Node: Effect of valuation on reports, Prev: More valuation examples, Up: VALUATION -2.18.11 Effect of valuation on reports --------------------------------------- +6.11 Effect of valuation on reports +=================================== Here is a reference for how valuation is supposed to affect each part of hledger's reports (and a glossary). (It's wide, you'll have to scroll @@ -1952,27 +1431,168 @@ _report interval_ subperiods).  -File: hledger.info, Node: COMMANDS, Next: ENVIRONMENT, Prev: OPTIONS, Up: Top +File: hledger.info, Node: PIVOTING, Next: OUTPUT, Prev: VALUATION, Up: Top -3 COMMANDS +7 PIVOTING +********** + +Normally hledger sums amounts, and organizes them in a hierarchy, based +on account name. The '--pivot FIELD' option causes it to sum and +organize hierarchy based on the value of some other field instead. +FIELD can be: 'code', 'description', 'payee', 'note', or the full name +(case insensitive) of any tag. As with account names, values containing +'colon:separated:parts' will be displayed hierarchically in reports. + + '--pivot' is a general option affecting all reports; you can think of +hledger transforming the journal before any other processing, replacing +every posting's account name with the value of the specified field on +that posting, inheriting it from the transaction or using a blank value +if it's not present. + + An example: + +2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees +-------------------- + 0 + + Pivoted balance report, using member: tag values instead: + +$ hledger balance --pivot member + 2 EUR + -2 EUR John Doe +-------------------- + 0 + + One way to show only amounts with a member: value (using a query, +described below): + +$ hledger balance --pivot member tag:member=. + -2 EUR John Doe +-------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account +name"): + +$ hledger balance --pivot member acct:. + -2 EUR John Doe +-------------------- + -2 EUR + + +File: hledger.info, Node: OUTPUT, Next: COMMANDS, Prev: PIVOTING, Up: Top + +8 OUTPUT +******** + +* Menu: + +* Output destination:: +* Output format:: + + +File: hledger.info, Node: Output destination, Next: Output format, Up: OUTPUT + +8.1 Output destination +====================== + +hledger commands send their output to the terminal by default. You can +of course redirect this, eg into a file, using standard shell syntax: + +$ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also +provide the '-o/--output-file' option, which does the same thing without +needing the shell. Eg: + +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default) + + +File: hledger.info, Node: Output format, Prev: Output destination, Up: OUTPUT + +8.2 Output format +================= + +Some commands (print, register, the balance commands) offer a choice of +output format. In addition to the usual plain text format ('txt'), +there are CSV ('csv'), HTML ('html'), JSON ('json') and SQL ('sql'). +This is controlled by the '-O/--output-format' option: + +$ hledger print -O csv + + or, by a file extension specified with '-o/--output-file': + +$ hledger balancesheet -o foo.html # write HTML to foo.html + + The '-O' option can be used to override the file extension if needed: + +$ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt + + Some notes about JSON output: + + * This feature is marked experimental, and not yet much used; you + should expect our JSON to evolve. Real-world feedback is welcome. + + * Our JSON is rather large and verbose, as it is quite a faithful + representation of hledger's internal data types. To understand the + JSON, read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. + + * hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can + arise in practice (from automatically-calculated transaction + prices), and would break most JSON consumers. So in JSON, we show + quantities as simple Numbers with at most 10 decimal places. We + don't limit the number of integer digits, but that part is under + your control. We hope this approach will not cause problems in + practice; if you find otherwise, please let us know. (Cf #1195) + + Notes about SQL output: + + * SQL output is also marked experimental, and much like JSON could + use real-world feedback. + + * SQL output is expected to work with sqlite, MySQL and PostgreSQL + + * SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables + created via SQL output of hledger, you would probably want to + either clear tables of existing data (via 'delete' or 'truncate' + SQL statements) or drop tables completely as otherwise your + postings will be duped. + + +File: hledger.info, Node: COMMANDS, Next: COMMON TASKS, Prev: OUTPUT, Up: Top + +9 COMMANDS ********** hledger provides a number of commands for producing reports and managing your data. Run 'hledger' with no arguments to list the commands -available. +available, and 'hledger CMD' to run a command. CMD can be the full +command name, or its standard abbreviation shown in the commands list, +or any unambiguous prefix of the name. Eg: 'hledger bal'. - To run a command, write its name (or its abbreviation shown in the -commands list, or any unambiguous prefix of the name) as hledger's first -argument. Eg: 'hledger balance' or 'hledger bal'. + Here are the built-in commands, with the most often-used in bold: - Here are the built-in commands: + *Data entry:* - *Data entry (these modify the journal file):* + These data entry commands are the only ones which can modify your +journal file. - * add - add transactions using guided prompts - * import - add any new transactions from other files (eg csv) + * *add* - add transactions using guided prompts + * *import* - add any new transactions from other files (eg csv) - *Data management*: + *Data management:* * check - check for various kinds of issue in the data * close (equity) - generate balance-resetting transactions @@ -1981,36 +1601,54 @@ argument. Eg: 'hledger balance' or 'hledger bal'. *Financial statements:* - * aregister (areg) - show transactions in a particular account - * balancesheet (bs) - show assets, liabilities and net worth + * *aregister (areg)* - show transactions in a particular account + * *balancesheet (bs)* - show assets, liabilities and net worth * balancesheetequity (bse) - show assets, liabilities and equity * cashflow (cf) - show changes in liquid assets - * incomestatement (is) - show revenues and expenses + * *incomestatement (is)* - show revenues and expenses * roi - show return on investments *Miscellaneous reports:* * accounts (a) - show account names * activity - show postings-per-interval bar charts - * balance (b, bal) - show balance changes/end balances/budgets in - accounts + * *balance (b, bal)* - show balance changes/end balances/budgets in + any accounts * codes - show transaction codes * commodities - show commodity/currency symbols * descriptions - show unique transaction descriptions * files - show input file paths + * help - show hledger user manuals in several formats * notes - show unique note segments of transaction descriptions * payees - show unique payee segments of transaction descriptions * prices - show market price records - * print (p, txns) - show transactions (journal entries) + * *print (p, txns)* - show transactions (journal entries) * print-unique - show only transactions with unique descriptions - * register (r, reg) - show postings in one or more accounts & running - total + * *register (r, reg)* - show postings in one or more accounts & + running total * register-match - show a recent posting that best matches a description * stats - show journal statistics * tags - show tag names * test - run self tests + *Add-on commands:* + + Programs or scripts named 'hledger-SOMETHING' in your PATH are add-on +commands; these appear in the commands list with a '+' mark. Two of +these are maintained and released with hledger: + + * *ui* - an efficient terminal interface (TUI) for hledger + * *web* - a simple web interface (WUI) for hledger + + And these add-ons are maintained separately: + + * iadd - a more interactive alternative for the add command + * interest - generates interest transactions according to various + schemes + * stockquotes - downloads market prices for your commodities from + AlphaVantage _(experimental)_ + Next, the detailed command docs, in alphabetical order. * Menu: @@ -2034,19 +1672,23 @@ argument. Eg: 'hledger balance' or 'hledger bal'. * import:: * incomestatement:: * notes:: +* payees:: +* prices:: +* print:: +* print-unique:: +* register:: +* register-match:: * rewrite:: * roi:: * stats:: * tags:: * test:: -* Add-on commands:: -* Add-on command flags:: -* Making add-on commands:: +* About add-on commands::  File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS -3.1 accounts +9.1 accounts ============ accounts, a @@ -2076,7 +1718,7 @@ liabilities:debts  File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS -3.2 activity +9.2 activity ============ activity @@ -2097,7 +1739,7 @@ $ hledger activity --quarterly  File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: COMMANDS -3.3 add +9.3 add ======= add @@ -2168,7 +1810,7 @@ file path ends with a period, as that would cause problems (#1056).  File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: COMMANDS -3.4 aregister +9.4 aregister ============= aregister, areg @@ -2212,7 +1854,7 @@ options The output formats supported are 'txt', 'csv', and 'json'.  File: hledger.info, Node: aregister and custom posting dates, Up: aregister -3.4.1 aregister and custom posting dates +9.4.1 aregister and custom posting dates ---------------------------------------- Transactions whose date is outside the report period can still be shown, @@ -2240,7 +1882,7 @@ $ hledger areg assets date:jul  File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: COMMANDS -3.5 balance +9.5 balance =========== balance, bal, b @@ -2287,7 +1929,7 @@ options The output formats supported are (in most modes): 'txt', 'csv',  File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance -3.5.1 Classic balance report +9.5.1 Classic balance report ---------------------------- This is the original balance report, as found in Ledger. It usually @@ -2333,7 +1975,7 @@ $ hledger balance -p 2008/6 expenses --no-total  File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance -3.5.2 Customising the classic balance report +9.5.2 Customising the classic balance report -------------------------------------------- You can customise the layout of classic balance reports with '--format @@ -2395,7 +2037,7 @@ may be needed to get pleasing results.  File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance -3.5.3 Colour support +9.5.3 Colour support -------------------- In terminal output, when colour is enabled, the balance command shows @@ -2404,7 +2046,7 @@ negative amounts in red.  File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance -3.5.4 Flat mode +9.5.4 Flat mode --------------- To see a flat list instead of the default hierarchical display, use @@ -2420,7 +2062,7 @@ $ hledger balance -p 2008/6 expenses -N --flat --drop 1  File: hledger.info, Node: Depth limited balance reports, Next: Percentages, Prev: Flat mode, Up: balance -3.5.5 Depth limited balance reports +9.5.5 Depth limited balance reports ----------------------------------- With '--depth N' or 'depth:N' or just '-N', balance reports show @@ -2439,7 +2081,7 @@ show inclusive balances at the depth limit.  File: hledger.info, Node: Percentages, Next: Sorting by amount, Prev: Depth limited balance reports, Up: balance -3.5.6 Percentages +9.5.6 Percentages ----------------- With '-%' or '--percent', balance reports show each account's value @@ -2471,7 +2113,7 @@ to use '-V' or '-B' to coerce the report into using a single commodity.  File: hledger.info, Node: Sorting by amount, Next: Multicolumn balance report, Prev: Percentages, Up: balance -3.5.7 Sorting by amount +9.5.7 Sorting by amount ----------------------- With '-S'/'--sort-amount', accounts with the largest (most positive) @@ -2487,7 +2129,7 @@ like 'balancesheet' or 'incomestatement', which also support '-S'. Eg:  File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Sorting by amount, Up: balance -3.5.8 Multicolumn balance report +9.5.8 Multicolumn balance report -------------------------------- Multicolumn or tabular balance reports are a very useful hledger @@ -2608,7 +2250,7 @@ bal -D --color=yes | less -RS'.  File: hledger.info, Node: Budget report, Prev: Multicolumn balance report, Up: balance -3.5.9 Budget report +9.5.9 Budget report ------------------- With '--budget', extra columns are displayed showing budget goals for @@ -2732,7 +2374,7 @@ Budget performance in 2017/11/01-2017/12/31:  File: hledger.info, Node: Budget report start date, Next: Nested budgets, Up: Budget report -3.5.9.1 Budget report start date +9.5.9.1 Budget report start date ................................ This might be a bug, but for now: when making budget reports, it's a @@ -2776,7 +2418,7 @@ Budget performance in 2020-01-01..2020-01-15:  File: hledger.info, Node: Nested budgets, Prev: Budget report start date, Up: Budget report -3.5.9.2 Nested budgets +9.5.9.2 Nested budgets ...................... You can add budgets to any account in your account hierarchy. If you @@ -2864,7 +2506,7 @@ Budget performance in 2019/01:  File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS -3.6 balancesheet +9.6 balancesheet ================ balancesheet, bs @@ -2878,6 +2520,9 @@ with the 'Asset' or 'Cash' or 'Liability' type, or otherwise all accounts under a top-level 'asset' or 'liability' account (case insensitive, plurals allowed). + (This report is essentially similar to "hledger balance -historical +assets liabilities", with liabilities sign-flipped.) + Example: $ hledger balancesheet @@ -2915,7 +2560,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS -3.7 balancesheetequity +9.7 balancesheetequity ====================== balancesheetequity, bse @@ -2928,6 +2573,9 @@ declared with the 'Asset', 'Cash', 'Liability' or 'Equity' type, or otherwise all accounts under a top-level 'asset', 'liability' or 'equity' account (case insensitive, plurals allowed). + (This report is essentially similar to "hledger balance -historical +assets liabilities equity", with liabilities and equity sign-flipped.) + Example: $ hledger balancesheetequity @@ -2961,7 +2609,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: COMMANDS -3.8 cashflow +9.8 cashflow ============ cashflow, cf @@ -2974,6 +2622,9 @@ type, or otherwise all accounts under a top-level 'asset' account (case insensitive, plural allowed) which do not have 'fixed', 'investment', 'receivable' or 'A/R' in their name. + (This report is essentially similar to "hledger balance -change +assets not:fixed not:investment not:receivable".) + Example: $ hledger cashflow @@ -3003,7 +2654,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: COMMANDS -3.9 check +9.9 check ========= check @@ -3030,7 +2681,7 @@ hledger check ordereddates uniqueleafnames # basic + specified checks  File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check -3.9.1 Basic checks +9.9.1 Basic checks ------------------ These are always run by this command and other commands: @@ -3048,7 +2699,7 @@ These are always run by this command and other commands:  File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check -3.9.2 Strict checks +9.9.2 Strict checks ------------------- These are always run by this and other commands when '-s'/'--strict' is @@ -3062,7 +2713,7 @@ used (strict mode):  File: hledger.info, Node: Other checks, Next: Add-on checks, Prev: Strict checks, Up: check -3.9.3 Other checks +9.9.3 Other checks ------------------ These checks can be run by specifying their names as arguments to the @@ -3077,7 +2728,7 @@ check command:  File: hledger.info, Node: Add-on checks, Prev: Other checks, Up: check -3.9.4 Add-on checks +9.9.4 Add-on checks ------------------- Some checks are not yet integrated with this command, but are available @@ -3096,7 +2747,7 @@ Cookbook -> Scripting may be helpful.  File: hledger.info, Node: close, Next: codes, Prev: check, Up: COMMANDS -3.10 close +9.10 close ========== close, equity @@ -3136,7 +2787,7 @@ you have many foreign currency or investment transactions.  File: hledger.info, Node: close usage, Up: close -3.10.1 close usage +9.10.1 close usage ------------------ If you split your journal files by time (eg yearly), you will typically @@ -3207,7 +2858,7 @@ breaking balance assertions:  File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS -3.11 codes +9.11 codes ========== codes @@ -3253,7 +2904,7 @@ $ hledger codes -E  File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS -3.12 commodities +9.12 commodities ================ commodities @@ -3262,7 +2913,7 @@ List all commodity/currency symbols used or declared in the journal.  File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS -3.13 descriptions +9.13 descriptions ================= descriptions @@ -3282,7 +2933,7 @@ Person A  File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS -3.14 diff +9.14 diff ========= diff @@ -3317,7 +2968,7 @@ These transactions are in the second file only:  File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS -3.15 files +9.15 files ========== files @@ -3327,7 +2978,7 @@ file names matching the regular expression (case sensitive) are shown.  File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS -3.16 help +9.16 help ========= help @@ -3367,7 +3018,7 @@ DESCRIPTION  File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS -3.17 import +9.17 import =========== import @@ -3397,7 +3048,7 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions  File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Up: import -3.17.1 Importing balance assignments +9.17.1 Importing balance assignments ------------------------------------ Entries added by import will have their posting amounts made explicit @@ -3416,7 +3067,7 @@ please test it and send a pull request.)  File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import -3.17.2 Commodity display styles +9.17.2 Commodity display styles ------------------------------- Imported amounts will be formatted according to the canonical commodity @@ -3425,7 +3076,7 @@ styles (declared or inferred) in the main journal file.  File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS -3.18 incomestatement +9.18 incomestatement ==================== incomestatement, is @@ -3439,6 +3090,9 @@ with the 'Revenue' or 'Expense' type, or otherwise all accounts under a top-level 'revenue' or 'income' or 'expense' account (case insensitive, plurals allowed). + (This report is essentially similar to "hledger balance -change +revenues expenses", with revenues sign-flipped.) + Example: $ hledger incomestatement @@ -3473,9 +3127,9 @@ options The output formats supported are 'txt', 'csv', 'html', and (experimental) 'json'.  -File: hledger.info, Node: notes, Next: rewrite, Prev: incomestatement, Up: COMMANDS +File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS -3.19 notes +9.19 notes ========== notes @@ -3493,9 +3147,317 @@ Petrol Snacks  -File: hledger.info, Node: rewrite, Next: roi, Prev: notes, Up: COMMANDS +File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS -3.20 rewrite +9.20 payees +=========== + +payees +List the unique payee/payer names that appear in transactions. + + This command lists the unique payee/payer names that appear in +transactions, in alphabetic order. You can add a query to select a +subset of transactions. The payee/payer is the part of the transaction +description before a | character (or if there is no |, the whole +description). + + Example: + +$ hledger payees +Store Name +Gas Station +Person A + + +File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS + +9.21 prices +=========== + +prices +Print market price directives from the journal. With -costs, also print +synthetic market prices based on transaction prices. With +-inverted-costs, also print inverse prices based on transaction prices. +Prices (and postings providing prices) can be filtered by a query. +Price amounts are always displayed with their full precision. + + +File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS + +9.22 print +========== + +print, txns, p +Show transaction journal entries, sorted by date. + + The print command displays full journal entries (transactions) from +the journal file in date order, tidily formatted. With -date2, +transactions are sorted by secondary date instead. + + print's output is always a valid hledger journal. +It preserves all transaction information, but it does not preserve +directives or inter-transaction comments + +$ hledger print +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + +2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + +2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + +2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + +2008/12/31 * pay off + liabilities:debts $1 + assets:bank:checking $-1 + + Normally, the journal entry's explicit or implicit amount style is +preserved. For example, when an amount is omitted in the journal, it +will not appear in the output. Similarly, when a transaction price is +implied but not written, it will not appear in the output. You can use +the '-x'/'--explicit' flag to make all amounts and transaction prices +explicit, which can be useful for troubleshooting or for making your +journal more readable and robust against data entry errors. '-x' is +also implied by using any of '-B','-V','-X','--value'. + + Note, '-x'/'--explicit' will cause postings with a multi-commodity +amount (these can arise when a multi-commodity transaction has an +implicit amount) to be split into multiple single-commodity postings, +keeping the output parseable. + + With '-B'/'--cost', amounts with transaction prices are converted to +cost using that price. This can be used for troubleshooting. + + With '-m'/'--match' and a STR argument, print will show at most one +transaction: the one one whose description is most similar to STR, and +is most recent. STR should contain at least two characters. If there +is no similar-enough match, no transaction will be shown. + + With '--new', for each FILE being read, hledger reads (and writes) a +special state file ('.latest.FILE' in the same directory), containing +the latest transaction date(s) that were seen last time FILE was read. +When this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. This is useful for +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) + + This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. See also the import command. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', and +(experimental) 'json' and 'sql'. + + Here's an example of print's CSV output: + +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + * There is one CSV record per posting, with the parent transaction's + fields repeated. + * The "txnidx" (transaction index) field shows which postings belong + to the same transaction. (This number might change if transactions + are reordered within the file, files are parsed/included in a + different order, etc.) + * The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + * The numeric amount is repeated in either the "credit" or "debit" + column, for convenience. (Those names are not accurate in the + accounting sense; it just puts negative amounts under credit and + zero or greater amounts under debit.) + + +File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS + +9.23 print-unique +================= + +print-unique +Print transactions which do not reuse an already-seen description. + + Example: + +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 + + +File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS + +9.24 register +============= + +register, reg, r +Show postings and their running total. + + The register command displays matched postings, across all accounts, +in date order, with their running total or running historical balance. +(See also the 'aregister' command, which shows matched transactions in a +specific account.) + + register normally shows line per posting, but note that +multi-commodity amounts will occupy multiple lines (one line per +commodity). + + It is typically used with a query selecting a particular account, to +see that account's activity: + +$ hledger register checking +2008/01/01 income assets:bank:checking $1 $1 +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + With -date2, it shows and sorts by secondary date instead. + + The '--historical'/'-H' flag adds the balance from any undisplayed +prior postings to the running total. This is useful when you want to +see only recent activity, with a historically accurate running balance: + +$ hledger register checking -b 2008/6 --historical +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + The '--depth' option limits the amount of sub-account detail +displayed. + + The '--average'/'-A' flag shows the running average posting amount +instead of the running total (so, the final number displayed is the +average for the whole report period). This flag implies '--empty' (see +below). It is affected by '--historical'. It works best when showing +just one account and one commodity. + + The '--related'/'-r' flag shows the _other_ postings in the +transactions of the postings which would normally be shown. + + The '--invert' flag negates all amounts. For example, it can be used +on an income account where amounts are normally displayed as negative +numbers. It's also useful to show postings on the checking account +together with the related account: + +$ hledger register --related --invert assets:checking + + With a reporting interval, register shows summary postings, one per +interval, aggregating the postings to each account: + +$ hledger register --monthly income +2008/01 income:salary $-1 $-1 +2008/06 income:gifts $-1 $-2 + + Periods with no activity, and summary postings with a zero amount, +are not shown by default; use the '--empty'/'-E' flag to see them: + +$ hledger register --monthly income -E +2008/01 income:salary $-1 $-1 +2008/02 0 $-1 +2008/03 0 $-1 +2008/04 0 $-1 +2008/05 0 $-1 +2008/06 income:gifts $-1 $-2 +2008/07 0 $-2 +2008/08 0 $-2 +2008/09 0 $-2 +2008/10 0 $-2 +2008/11 0 $-2 +2008/12 0 $-2 + + Often, you'll want to see just one line per interval. The '--depth' +option helps with this, causing subaccounts to be aggregated: + +$ hledger register --monthly assets --depth 1h +2008/01 assets $1 $1 +2008/06 assets $-1 0 +2008/12 assets $-1 $-1 + + Note when using report intervals, if you specify start/end dates +these will be adjusted outward if necessary to contain a whole number of +intervals. This ensures that the first and last intervals are full +length and comparable to the others in the report. + +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +9.24.1 Custom register output +----------------------------- + +register uses the full terminal width by default, except on windows. +You can override this by setting the 'COLUMNS' environment variable (not +a bash shell variable) or by using the '--width'/'-w' option. + + The description and account columns normally share the space equally +(about half of (width - 40) each). You can adjust this by adding a +description width as part of -width's argument, comma-separated: +'--width W,D' . Here's a diagram (won't display correctly in -help): + +<--------------------------------- width (W) ----------------------------------> +date (10) description (D) account (W-41-D) amount (12) balance (12) +DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA + + and some examples: + +$ hledger reg # use terminal width (or 80 on windows) +$ hledger reg -w 100 # use width 100 +$ COLUMNS=100 hledger reg # set with one-time environment variable +$ export COLUMNS=100; hledger reg # set till session end (or window resize) +$ hledger reg -w 100,40 # set overall width 100, description width 40 +$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', and +(experimental) 'json'. + + +File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS + +9.25 register-match +=================== + +register-match +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. If there are multiple equally +good matches, it shows the most recent. Query options (options, not +arguments) can be used to restrict the search space. Helps +ledger-autosync detect already-seen transactions when importing. + + +File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS + +9.26 rewrite ============ rewrite @@ -3549,7 +3511,7 @@ commodity.  File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite -3.20.1 Re-write rules in a file +9.26.1 Re-write rules in a file ------------------------------- During the run this tool will execute so called "Automated Transactions" @@ -3587,7 +3549,7 @@ postings.  File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite -3.20.2 Diff output format +9.26.2 Diff output format ------------------------- To use this tool for batch modification of your journal files you may @@ -3628,7 +3590,7 @@ output from 'hledger print'.  File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite -3.20.3 rewrite vs. print -auto +9.26.3 rewrite vs. print -auto ------------------------------ This command predates print -auto, and currently does much the same @@ -3648,7 +3610,7 @@ thing, but with these differences:  File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS -3.21 roi +9.27 roi ======== roi @@ -3904,7 +3866,7 @@ $ hledger roi -Y --inv investment --pnl "unrealized"  File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS -3.22 stats +9.28 stats ========== stats @@ -3935,7 +3897,7 @@ selection.  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS -3.23 tags +9.29 tags ========= tags @@ -3953,9 +3915,9 @@ parsed from the input data, including duplicates. they are omitted.  -File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: COMMANDS +File: hledger.info, Node: test, Next: About add-on commands, Prev: tags, Up: COMMANDS -3.24 test +9.30 test ========= test @@ -3980,39 +3942,28 @@ $ hledger test -- -pData.Amount --color=never ('-- --help' currently doesn't show them).  -File: hledger.info, Node: Add-on commands, Next: Add-on command flags, Prev: test, Up: COMMANDS +File: hledger.info, Node: About add-on commands, Prev: test, Up: COMMANDS -3.25 Add-on commands -==================== +9.31 About add-on commands +========================== -Any programs or scripts in your PATH named named 'hledger-SOMETHING' -will also appear in the commands list (with a '+' mark). These are -called add-on commands. +Add-on commands are programs or scripts in your PATH - These offical add-ons are maintained and released along with hledger: + * whose name starts with 'hledger-' + * whose name ends with a recognised file extension: + '.bat','.com','.exe', '.hs','.lhs','.pl','.py','.rb','.rkt','.sh' + or none + * and (on unix, mac) which are executable by the current user. - * ui an efficient terminal interface for hledger (TUI) - * web a simple web interface for hledger (WUI) + Add-ons are a relatively easy way to add local features or experiment +with new ideas. They can be written in any language, but haskell +scripts have a big advantage: they can use the same hledger library +functions that built-in commands use for command-line options, parsing +and reporting. Some experimental/example add-on scripts can be found in +the hledger repo's bin/ directory. - These add-ons are maintained separately: - - * iadd a more interactive alternative for the add command - * interest generates interest transactions according to various - schemes - * stockquotes downloads market prices for your commodities from - AlphaVantage _(experimental)_ - - Additional experimental add-ons, which may not be in a working state, -can be found in the bin/ directory in the hledger repo. - - -File: hledger.info, Node: Add-on command flags, Next: Making add-on commands, Prev: Add-on commands, Up: COMMANDS - -3.26 Add-on command flags -========================= - -In a hledger command line, add-on command flags must have a double dash -('--') preceding them. Eg you must write: + Note in a hledger command line, add-on command flags must have a +double dash ('--') preceding them. Eg you must write: $ hledger web -- --serve @@ -4032,30 +3983,433 @@ add-on program directly, eg: $ hledger-web --serve  -File: hledger.info, Node: Making add-on commands, Prev: Add-on command flags, Up: COMMANDS +File: hledger.info, Node: COMMON TASKS, Next: ENVIRONMENT, Prev: COMMANDS, Up: Top -3.27 Making add-on commands -=========================== +10 COMMON TASKS +*************** -Add-on commands are programs or scripts in your PATH +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. - * whose name starts with 'hledger-' - * whose name ends with a recognised file extension: - '.bat','.com','.exe', '.hs','.lhs','.pl','.py','.rb','.rkt','.sh' - or none - * and (on unix, mac) which are executable by the current user. +* Menu: - Add-ons are a relatively easy way to add local features or experiment -with new ideas. They can be written in any language, but haskell -scripts have a big advantage: they can use the same hledger library -functions that built-in commands use for command-line options, parsing -and reporting. +* Getting help:: +* Constructing command lines:: +* Starting a journal file:: +* Setting opening balances:: +* Recording transactions:: +* Reconciling:: +* Reporting:: +* Migrating to a new file::  -File: hledger.info, Node: ENVIRONMENT, Next: FILES, Prev: COMMANDS, Up: Top +File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: COMMON TASKS -4 ENVIRONMENT -************* +10.1 Getting 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 + + +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: COMMON TASKS + +10.2 Constructing command lines +=============================== + +hledger has an extensive and powerful command line interface. We strive +to keep it simple and ergonomic, but you may run into one of the +confusing real world details described in OPTIONS, below. If that +happens, here are some tips that may help: + + * command-specific options must go after the command (it's fine to + put all options there) ('hledger CMD OPTS ARGS') + * running add-on executables directly simplifies command line parsing + ('hledger-ui OPTS ARGS') + * enclose "problematic" args in single quotes + * if needed, also add a backslash to hide regular expression + metacharacters from the shell + * to see how a misbehaving command is being parsed, add '--debug=2'. + + +File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: COMMON TASKS + +10.3 Starting a journal file +============================ + +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 () + + +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: COMMON TASKS + +10.4 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 +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. + + Add an opening balances transaction to the journal, declaring the +balances on this date. Here are two ways to do it: + + * 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. + + * 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 -m 'initial balances' 2020.journal + + +File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: COMMON TASKS + +10.5 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 + +2020.1.12 * farmers market + expenses:food $13 + assets:cash + +2020-01-15 paycheck + income:salary + assets:bank:checking $1000 + + +File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: COMMON TASKS + +10.6 Reconciling +================ + +Periodically you should reconcile - compare your hledger-reported +balances 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 +discrepancies. + + 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 + already-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 checking -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 transaction history and running balance from your bank + with the one reported by 'hledger reg checking -C'. This will be + easier if you generally record transaction dates quite similar to + your bank's clearing dates. + + 3. Repeat for other asset/liability accounts. + + Tip: instead of the register command, use hledger-ui to see a +live-updating register while you edit the journal: 'hledger-ui --watch +--register 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 +commit: + +$ git commit -m 'txns' 2020.journal + + +File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: COMMON TASKS + +10.7 Reporting +============== + +Here are some basic reports. + + Show all transactions: + +$ hledger print +2020-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + +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 + $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 +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 + + Show weekly posting counts as a bar chart: + +$ hledger activity -W +2019-12-30 ***** +2020-01-06 **** +2020-01-13 **** + + +File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: COMMON TASKS + +10.8 Migrating to 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. + + If using version control, don't forget to 'git add' the new file. + + +File: hledger.info, Node: ENVIRONMENT, Next: LIMITATIONS, Prev: COMMON TASKS, Up: Top + +11 ENVIRONMENT +************** *LEDGER_FILE* The journal file path when not specified with '-f'. Default: '~/.hledger.journal' (on windows, perhaps @@ -4085,21 +4439,10 @@ use ANSI color codes in terminal output. This overrides the -color/-colour option.  -File: hledger.info, Node: FILES, Next: LIMITATIONS, Prev: ENVIRONMENT, Up: Top +File: hledger.info, Node: LIMITATIONS, Next: TROUBLESHOOTING, Prev: ENVIRONMENT, Up: Top -5 FILES -******* - -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or -'$HOME/.hledger.journal' (on windows, perhaps -'C:/Users/USER/.hledger.journal'). - - -File: hledger.info, Node: LIMITATIONS, Next: TROUBLESHOOTING, Prev: FILES, Up: Top - -6 LIMITATIONS -************* +12 LIMITATIONS +************** The need to precede add-on command options with '--' when invoked from hledger is awkward. @@ -4126,8 +4469,8 @@ Ledger.  File: hledger.info, Node: TROUBLESHOOTING, Prev: LIMITATIONS, Up: Top -7 TROUBLESHOOTING -***************** +13 TROUBLESHOOTING +****************** Here are some issues you might encounter when you run hledger (and remember you can also seek help from the IRC channel, mail list or bug @@ -4199,197 +4542,215 @@ $ LANG=en_US.UTF-8 hledger -f my.journal print  Tag Table: Node: Top68 -Node: COMMON TASKS2337 -Ref: #common-tasks2449 -Node: Getting help2856 -Ref: #getting-help2988 -Node: Constructing command lines3541 -Ref: #constructing-command-lines3733 -Node: Starting a journal file4430 -Ref: #starting-a-journal-file4628 -Node: Setting opening balances5816 -Ref: #setting-opening-balances6012 -Node: Recording transactions9153 -Ref: #recording-transactions9333 -Node: Reconciling9889 -Ref: #reconciling10032 -Node: Reporting12289 -Ref: #reporting12429 -Node: Migrating to a new file16428 -Ref: #migrating-to-a-new-file16576 -Node: OPTIONS16875 -Ref: #options16982 -Node: General options17368 -Ref: #general-options17493 -Node: Command options20894 -Ref: #command-options21045 -Node: Command arguments21445 -Ref: #command-arguments21592 -Node: Queries22472 -Ref: #queries22627 -Node: Special characters in arguments and queries26589 -Ref: #special-characters-in-arguments-and-queries26817 -Node: More escaping27268 -Ref: #more-escaping27430 -Node: Even more escaping27726 -Ref: #even-more-escaping27920 -Node: Less escaping28594 -Ref: #less-escaping28756 -Node: Unicode characters29001 -Ref: #unicode-characters29183 -Node: Input files30595 -Ref: #input-files30731 -Node: Strict mode33030 -Ref: #strict-mode33166 -Node: Output destination33814 -Ref: #output-destination33966 -Node: Output format34391 -Ref: #output-format34543 -Node: Regular expressions36710 -Ref: #regular-expressions36867 -Node: Smart dates38603 -Ref: #smart-dates38754 -Node: Report start & end date40115 -Ref: #report-start-end-date40287 -Node: Report intervals41820 -Ref: #report-intervals41985 -Node: Period expressions42375 -Ref: #period-expressions42535 -Node: Depth limiting46978 -Ref: #depth-limiting47122 -Node: Pivoting47454 -Ref: #pivoting47577 -Node: Valuation49253 -Ref: #valuation49355 -Node: -B Cost50044 -Ref: #b-cost50148 -Node: -V Value50281 -Ref: #v-value50427 -Node: -X Value in specified commodity50622 -Ref: #x-value-in-specified-commodity50821 -Node: Valuation date50970 -Ref: #valuation-date51138 -Node: Market prices51575 -Ref: #market-prices51755 -Node: --infer-value market prices from transactions52697 -Ref: #infer-value-market-prices-from-transactions52946 -Node: Valuation commodity54228 -Ref: #valuation-commodity54437 -Node: Simple valuation examples55663 -Ref: #simple-valuation-examples55865 -Node: --value Flexible valuation56524 -Ref: #value-flexible-valuation56732 -Node: More valuation examples58679 -Ref: #more-valuation-examples58888 -Node: Effect of valuation on reports60893 -Ref: #effect-of-valuation-on-reports61081 -Node: COMMANDS68100 -Ref: #commands68208 -Node: accounts70773 -Ref: #accounts70871 -Node: activity71570 -Ref: #activity71680 -Node: add72063 -Ref: #add72164 -Node: aregister74957 -Ref: #aregister75069 -Node: aregister and custom posting dates76563 -Ref: #aregister-and-custom-posting-dates76727 -Node: balance77548 -Ref: #balance77665 -Node: Classic balance report79291 -Ref: #classic-balance-report79464 -Node: Customising the classic balance report80788 -Ref: #customising-the-classic-balance-report81016 -Node: Colour support83092 -Ref: #colour-support83259 -Node: Flat mode83355 -Ref: #flat-mode83503 -Node: Depth limited balance reports83916 -Ref: #depth-limited-balance-reports84101 -Node: Percentages84557 -Ref: #percentages84714 -Node: Sorting by amount85851 -Ref: #sorting-by-amount86017 -Node: Multicolumn balance report86511 -Ref: #multicolumn-balance-report86697 -Node: Budget report92294 -Ref: #budget-report92428 -Node: Budget report start date97717 -Ref: #budget-report-start-date97882 -Node: Nested budgets99214 -Ref: #nested-budgets99359 -Node: balancesheet102799 -Ref: #balancesheet102935 -Node: balancesheetequity104447 -Ref: #balancesheetequity104596 -Node: cashflow105672 -Ref: #cashflow105794 -Node: check107010 -Ref: #check107113 -Node: Basic checks107718 -Ref: #basic-checks107834 -Node: Strict checks108327 -Ref: #strict-checks108466 -Node: Other checks108709 -Ref: #other-checks108847 -Node: Add-on checks109145 -Ref: #add-on-checks109263 -Node: close109716 -Ref: #close109818 -Node: close usage111340 -Ref: #close-usage111433 -Node: codes114246 -Ref: #codes114354 -Node: commodities115066 -Ref: #commodities115193 -Node: descriptions115275 -Ref: #descriptions115403 -Node: diff115707 -Ref: #diff115813 -Node: files116860 -Ref: #files116960 -Node: help117107 -Ref: #help117207 -Node: import118288 -Ref: #import118402 -Node: Importing balance assignments119324 -Ref: #importing-balance-assignments119505 -Node: Commodity display styles120154 -Ref: #commodity-display-styles120325 -Node: incomestatement120454 -Ref: #incomestatement120587 -Node: notes121932 -Ref: #notes122046 -Node: rewrite122414 -Ref: #rewrite122520 -Node: Re-write rules in a file124426 -Ref: #re-write-rules-in-a-file124587 -Node: Diff output format125736 -Ref: #diff-output-format125917 -Node: rewrite vs print --auto127009 -Ref: #rewrite-vs.-print---auto127167 -Node: roi127723 -Ref: #roi127821 -Node: stats140031 -Ref: #stats140130 -Node: tags140918 -Ref: #tags141016 -Node: test141535 -Ref: #test141643 -Node: Add-on commands142390 -Ref: #add-on-commands142536 -Node: Add-on command flags143300 -Ref: #add-on-command-flags143474 -Node: Making add-on commands144054 -Ref: #making-add-on-commands144208 -Node: ENVIRONMENT144801 -Ref: #environment144913 -Node: FILES145898 -Ref: #files-1146001 -Node: LIMITATIONS146214 -Ref: #limitations146333 -Node: TROUBLESHOOTING147076 -Ref: #troubleshooting147189 +Node: OPTIONS2414 +Ref: #options2514 +Node: General options2656 +Ref: #general-options2781 +Node: Command options6182 +Ref: #command-options6333 +Node: Command arguments6733 +Ref: #command-arguments6891 +Node: Special characters7771 +Ref: #special-characters7934 +Node: Single escaping shell metacharacters8097 +Ref: #single-escaping-shell-metacharacters8338 +Node: Double escaping regular expression metacharacters8739 +Ref: #double-escaping-regular-expression-metacharacters9050 +Node: Triple escaping for add-on commands9576 +Ref: #triple-escaping-for-add-on-commands9836 +Node: Less escaping10480 +Ref: #less-escaping10634 +Node: Unicode characters10958 +Ref: #unicode-characters11123 +Node: Regular expressions12535 +Ref: #regular-expressions12675 +Node: DATA FILES14411 +Ref: #data-files14526 +Node: Data formats15065 +Ref: #data-formats15183 +Node: Multiple files16458 +Ref: #multiple-files16600 +Node: Strict mode17069 +Ref: #strict-mode17184 +Node: TIME PERIODS17832 +Ref: #time-periods17949 +Node: Smart dates18047 +Ref: #smart-dates18173 +Node: Report start & end date19499 +Ref: #report-start-end-date19674 +Node: Report intervals21207 +Ref: #report-intervals21375 +Node: Period expressions21765 +Ref: #period-expressions21905 +Node: DEPTH26348 +Ref: #depth26448 +Node: QUERIES26780 +Ref: #queries26881 +Node: VALUATION30843 +Ref: #valuation30951 +Node: -B Cost31640 +Ref: #b-cost31738 +Node: -V Value31871 +Ref: #v-value32011 +Node: -X Value in specified commodity32206 +Ref: #x-value-in-specified-commodity32399 +Node: Valuation date32548 +Ref: #valuation-date32710 +Node: Market prices33147 +Ref: #market-prices33321 +Node: --infer-value market prices from transactions34242 +Ref: #infer-value-market-prices-from-transactions34485 +Node: Valuation commodity35746 +Ref: #valuation-commodity35949 +Node: Simple valuation examples37154 +Ref: #simple-valuation-examples37350 +Node: --value Flexible valuation38009 +Ref: #value-flexible-valuation38211 +Node: More valuation examples40158 +Ref: #more-valuation-examples40361 +Node: Effect of valuation on reports42366 +Ref: #effect-of-valuation-on-reports42548 +Node: PIVOTING49567 +Ref: #pivoting49672 +Node: OUTPUT51348 +Ref: #output51448 +Node: Output destination51499 +Ref: #output-destination51630 +Node: Output format52055 +Ref: #output-format52176 +Node: COMMANDS54343 +Ref: #commands54451 +Node: accounts57836 +Ref: #accounts57934 +Node: activity58633 +Ref: #activity58743 +Node: add59126 +Ref: #add59227 +Node: aregister62020 +Ref: #aregister62132 +Node: aregister and custom posting dates63626 +Ref: #aregister-and-custom-posting-dates63790 +Node: balance64611 +Ref: #balance64728 +Node: Classic balance report66354 +Ref: #classic-balance-report66527 +Node: Customising the classic balance report67851 +Ref: #customising-the-classic-balance-report68079 +Node: Colour support70155 +Ref: #colour-support70322 +Node: Flat mode70418 +Ref: #flat-mode70566 +Node: Depth limited balance reports70979 +Ref: #depth-limited-balance-reports71164 +Node: Percentages71620 +Ref: #percentages71777 +Node: Sorting by amount72914 +Ref: #sorting-by-amount73080 +Node: Multicolumn balance report73574 +Ref: #multicolumn-balance-report73760 +Node: Budget report79357 +Ref: #budget-report79491 +Node: Budget report start date84780 +Ref: #budget-report-start-date84945 +Node: Nested budgets86277 +Ref: #nested-budgets86422 +Node: balancesheet89862 +Ref: #balancesheet89998 +Node: balancesheetequity91635 +Ref: #balancesheetequity91784 +Node: cashflow93003 +Ref: #cashflow93125 +Node: check94459 +Ref: #check94562 +Node: Basic checks95167 +Ref: #basic-checks95283 +Node: Strict checks95776 +Ref: #strict-checks95915 +Node: Other checks96158 +Ref: #other-checks96296 +Node: Add-on checks96594 +Ref: #add-on-checks96712 +Node: close97165 +Ref: #close97267 +Node: close usage98789 +Ref: #close-usage98882 +Node: codes101695 +Ref: #codes101803 +Node: commodities102515 +Ref: #commodities102642 +Node: descriptions102724 +Ref: #descriptions102852 +Node: diff103156 +Ref: #diff103262 +Node: files104309 +Ref: #files104409 +Node: help104556 +Ref: #help104656 +Node: import105737 +Ref: #import105851 +Node: Importing balance assignments106773 +Ref: #importing-balance-assignments106954 +Node: Commodity display styles107603 +Ref: #commodity-display-styles107774 +Node: incomestatement107903 +Ref: #incomestatement108036 +Node: notes109498 +Ref: #notes109611 +Node: payees109979 +Ref: #payees110085 +Node: prices110505 +Ref: #prices110611 +Node: print110952 +Ref: #print111062 +Node: print-unique115858 +Ref: #print-unique115984 +Node: register116269 +Ref: #register116396 +Node: Custom register output120845 +Ref: #custom-register-output120974 +Node: register-match122311 +Ref: #register-match122445 +Node: rewrite122796 +Ref: #rewrite122911 +Node: Re-write rules in a file124817 +Ref: #re-write-rules-in-a-file124978 +Node: Diff output format126127 +Ref: #diff-output-format126308 +Node: rewrite vs print --auto127400 +Ref: #rewrite-vs.-print---auto127558 +Node: roi128114 +Ref: #roi128212 +Node: stats140422 +Ref: #stats140521 +Node: tags141309 +Ref: #tags141407 +Node: test141926 +Ref: #test142040 +Node: About add-on commands142787 +Ref: #about-add-on-commands142922 +Node: COMMON TASKS144196 +Ref: #common-tasks144319 +Node: Getting help144726 +Ref: #getting-help144860 +Node: Constructing command lines145413 +Ref: #constructing-command-lines145607 +Node: Starting a journal file146304 +Ref: #starting-a-journal-file146504 +Node: Setting opening balances147692 +Ref: #setting-opening-balances147890 +Node: Recording transactions151031 +Ref: #recording-transactions151213 +Node: Reconciling151769 +Ref: #reconciling151914 +Node: Reporting154171 +Ref: #reporting154313 +Node: Migrating to a new file158312 +Ref: #migrating-to-a-new-file158462 +Node: ENVIRONMENT158761 +Ref: #environment158885 +Node: LIMITATIONS159870 +Ref: #limitations159997 +Node: TROUBLESHOOTING160740 +Ref: #troubleshooting160855  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 2c9bcb362..ac6080ab6 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -55,380 +55,9 @@ DESCRIPTION try some commands like hledger print or hledger balance. Run hledger with no arguments for a list of commands. -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. - - Getting 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 - - Constructing command lines - hledger has an extensive and powerful command line interface. We - strive to keep it simple and ergonomic, but you may run into one of the - confusing real world details described in OPTIONS, below. If that hap- - pens, here are some tips that may help: - - o command-specific options must go after the command (it's fine to put - all options there) (hledger CMD OPTS ARGS) - - o running add-on executables directly simplifies command line parsing - (hledger-ui OPTS ARGS) - - o enclose "problematic" args in single quotes - - o if needed, also add a backslash to hide regular expression metachar- - acters from the shell - - o to see how a misbehaving command is being parsed, add --debug=2. - - Starting a journal file - 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 -m '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 - - 2020.1.12 * farmers market - expenses:food $13 - assets:cash - - 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 -m 'txns' 2020.journal - - Reporting - Here are some basic reports. - - Show all transactions: - - $ hledger print - 2020-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - - 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 - $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 - 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 - - Show weekly posting counts as a bar chart: - - $ hledger activity -W - 2019-12-30 ***** - 2020-01-06 **** - 2020-01-13 **** - - Migrating to 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. - - If using version control, don't forget to git add the new file. - OPTIONS General options - To see general usage help, including general options which are sup- + To see general usage help, including general options which are sup- ported by most hledger commands, run hledger -h. General help options: @@ -449,7 +78,7 @@ OPTIONS $LEDGER_FILE or $HOME/.hledger.journal) --rules-file=RULESFILE - Conversion rules file to use when reading CSV (default: + Conversion rules file to use when reading CSV (default: FILE.rules) --separator=CHAR @@ -468,7 +97,7 @@ OPTIONS assignments) -s --strict - do extra error checking (check that all posted accounts are de- + do extra error checking (check that all posted accounts are de- clared) General reporting options: @@ -495,7 +124,7 @@ OPTIONS multiperiod/multicolumn report by year -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once + set start date, end date, and/or reporting interval all at once using period expressions syntax --date2 @@ -518,21 +147,21 @@ OPTIONS hide/aggregate accounts or postings more than NUM levels deep -E --empty - show items with zero amount, normally hidden (and vice-versa in + show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) -B --cost convert amounts to their cost/selling amount at transaction time -V --market - convert amounts to their market value in default valuation com- + convert amounts to their market value in default valuation com- modities -X --exchange=COMM convert amounts to their market value in commodity COMM --value - convert amounts to cost or market value, more flexibly than + convert amounts to cost or market value, more flexibly than -B/-V/-X --infer-value @@ -541,15 +170,15 @@ OPTIONS --auto apply automated posting rules to modify transactions. --forecast - generate future transactions from periodic transaction rules, - for the next 6 months or till report end date. In hledger-ui, + generate future transactions from periodic transaction rules, + for the next 6 months or till report end date. In hledger-ui, also make ordinary future transactions visible. --color=WHEN (or --colour=WHEN) - Should color-supporting commands use ANSI color codes in text - output. 'auto' (default): whenever stdout seems to be a color- - supporting terminal. 'always' or 'yes': always, useful eg when - piping output into 'less -R'. 'never' or 'no': never. A + Should color-supporting commands use ANSI color codes in text + output. 'auto' (default): whenever stdout seems to be a color- + supporting terminal. 'always' or 'yes': always, useful eg when + piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. When a reporting option appears more than once in the command line, the @@ -561,26 +190,26 @@ OPTIONS To see options for a particular command, including command-specific op- tions, run: hledger COMMAND -h. - Command-specific options must be written after the command name, eg: + Command-specific options must be written after the command name, eg: hledger print -x. - Additionally, if the command is an add-on, you may need to put its op- - tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can + Additionally, if the command is an add-on, you may need to put its op- + tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can run the add-on executable directly: hledger-ui --watch. Command arguments - 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. - 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 - that begins with a literal @, precede it with --, eg: hledger bal -- + 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 + that begins with a literal @, precede it with --, eg: hledger bal -- @ARG). - Inside the argument file, each line should contain just one option or + Inside the argument file, each line should contain just one option or argument. Avoid the use of spaces, except inside quotes (or you'll see - a confusing error). Between a flag and its argument, use = (or noth- + a confusing error). Between a flag and its argument, use = (or noth- ing). Bad: assets depth:2 @@ -592,7 +221,7 @@ OPTIONS depth:2 -X=USD - For special characters (see below), use one less level of quoting than + For special characters (see below), use one less level of quoting than you would at the command prompt. Bad: -X"$" @@ -603,7 +232,453 @@ OPTIONS See also: Save frequently used options. - Queries + Special characters + Single escaping (shell metacharacters) + In shell command lines, characters significant to your shell - such as + spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want + hledger to see them. This is done by enclosing them in single or dou- + ble quotes, or by writing a backslash before them. Eg to match an ac- + count name containing a space: + + $ hledger register 'credit card' + + or: + + $ hledger register credit\ card + + Double escaping (regular expression metacharacters) + Characters significant in regular expressions (described below) - such + as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if + you don't want them to be interpreted by hledger's regular expression + engine. This is done by writing backslashes before them, but since + backslash is typically also a shell metacharacter, both shell-escaping + and regex-escaping will be needed. Eg to match a literal $ sign while + using the bash shell: + + $ hledger balance cur:'\$' + + or: + + $ hledger balance cur:\\$ + + Triple escaping (for add-on commands) + When you use hledger to run an external add-on command (described be- + low), one level of shell-escaping is lost from any options or arguments + intended for by the add-on command, so those need an extra level of + shell-escaping. Eg to match a literal $ sign while using the bash + shell and running an add-on command (ui): + + $ hledger ui cur:'\\$' + + or: + + $ hledger ui cur:\\\\$ + + If you wondered why four backslashes, perhaps this helps: + + unescaped: $ + escaped: \$ + double-escaped: \\$ + triple-escaped: \\\\$ + + Or, you can avoid the extra escaping by running the add-on executable + directly: + + $ hledger-ui cur:\\$ + + Less escaping + Options and arguments are sometimes used in places other than the shell + command line, where shell-escaping is not needed, so there you should + use one less level of escaping. Those places include: + + o an @argumentfile + + o hledger-ui's filter field + + o hledger-web's search form + + o GHCI's prompt (used by developers). + + Unicode characters + hledger is expected to handle non-ascii characters correctly: + + o they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's search/add/edit + forms, etc.) + + o they should be displayed correctly by all hledger tools, and on- + screen alignment should be preserved. + + This requires a well-configured environment. Here are some tips: + + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like + this: export LANG=en_US.UTF-8. There are some more details in Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- + grams). + + o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + must support unicode + + o the terminal must be using a font which includes the required unicode + glyphs + + o the terminal should be configured to display wide characters as dou- + ble width (for report alignment) + + o on Windows, for best results you should run hledger in the same kind + of environment in which it was built. Eg hledger built in the stan- + dard CMD.EXE environment (like the binaries on our download page) + might show display problems when run in a cygwin or msys terminal, + and vice versa. (See eg #961). + + Regular expressions + hledger uses regular expressions in a number of places: + + o query terms, on the command line and in the hledger-web search form: + REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX + + o CSV rules conditional blocks: if REGEX ... + + o account alias directives and options: alias /REGEX/ = REPLACEMENT, + --alias /REGEX/=REPLACEMENT + + hledger's regular expressions come from the regex-tdfa library. If + they're not doing what you expect, it's important to know exactly what + they support: + + 1. they are case insensitive + + 2. they are infix matching (they do not need to match the entire thing + being matched) + + 3. they are POSIX ERE (extended regular expressions) + + 4. they also support GNU word boundaries (\b, \B, \<, \>) + + 5. they do not support backreferences; if you write \1, it will match + the digit 1. Except when doing text replacement, eg in account + aliases, where backreferences can be used in the replacement string + to reference capturing groups in the search regexp. + + 6. they do not support mode modifiers ((?s)), character classes (\w, + \d), or anything else not mentioned above. + + Some things to note: + + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + these are not required. + + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts + with the dollar sign in hledger-web, write cur:\$. + + o On the command line, some metacharacters like $ have a special mean- + ing to the shell and so must be escaped at least once more. See Spe- + cial characters. + +DATA FILES + hledger reads transactions from one or more data files. The default + data file is $HOME/.hledger.journal (or on Windows, something like + C:/Users/USER/.hledger.journal). + + You can override this with the $LEDGER_FILE environment variable: + + $ setenv LEDGER_FILE ~/finance/2016.journal + $ hledger stats + + or with one or more -f/--file options: + + $ hledger -f /some/file -f another_file stats + + The file name - means standard input: + + $ cat some.journal | hledger -f- + + Data formats + Usually the data file is in hledger's journal format, but it can be in + any of the supported file formats, which currently are: + + Reader: Reads: Used for file exten- + sions: + ----------------------------------------------------------------------------- + journal hledger journal files and some Ledger .journal .j .hledger + journals, for transactions .ledger + time- timeclock files, for precise time log- .timeclock + clock ging + + + timedot timedot files, for approximate time .timedot + logging + csv comma/semicolon/tab/other-separated .csv .ssv .tsv + values, for data import + + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a + recognised file extension, so as to either read successfully or to show + relevant error messages. + + You can also force a specific reader/format by prefixing the file path + with the format and a colon. Eg to read a .dat file as csv: + + $ hledger -f csv:/some/csv-file.dat stats + $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- + + Multiple files + You can specify multiple -f options, to read multiple files as one big + journal. There are some limitations with this: + + o most directives do not affect sibling files + + o balance assertions will not see any account balances from previous + files + + If you need either of those things, you can + + o use a single parent file which includes the others + + o or concatenate the files into one before reading, eg: cat a.journal + b.journal | hledger -f- CMD. + + Strict mode + hledger checks input files for valid data. By default, the most impor- + tant errors are detected, while still accepting easy journal files + without a lot of declarations: + + o Are the input files parseable, with valid syntax ? + + o Are all transactions balanced ? + + o Do all balance assertions pass ? + + With the -s/--strict flag, additional checks are performed: + + o Are all accounts posted to, declared with an account directive ? + (Account error checking) + + o Are all commodities declared with a commodity directive ? (Commodity + error checking) + + See also: https://hledger.org/checking-for-errors.html + + experimental. + +TIME PERIODS + Smart dates + hledger's user interfaces accept a flexible "smart date" syntax. Smart + dates allow some english words, can be relative to today's date, and + can have less-significant date parts omitted (defaulting to 1). + + Examples: + + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 + 2004 start of year + 2004/10 start of month + + 10/1 month and day in current year + 21 day in current month + october, oct start of month in current year + yesterday, today, tomor- -1, 0, 1 days from today + row + last/this/next -1, 0, 1 periods from the current period + day/week/month/quar- + ter/year + 20181201 8 digit YYYYMMDD with valid year month and day + 201812 6 digit YYYYMM with valid year and month + + Counterexamples - malformed digit sequences might give surprising re- + sults: + + 201813 6 digits with an invalid month is parsed as start of + 6-digit year + 20181301 8 digits with an invalid month is parsed as start 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 + + Report start & end date + By default, most hledger reports will show the full span of time repre- + sented by the journal data. The report start date will be the earliest + transaction or posting date, and the report end date will be the latest + transaction, posting, or market price date. + + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, + -e/--end, -p/--period or a date: query (described below). All of these + accept the smart date syntax. + + Some notes: + + o As in Ledger, end dates are exclusive, so you need to write the date + after the last day you want to include. + + o As noted in reporting options: among start/end dates specified with + options, the last (i.e. right-most) option takes precedence. + + o The effective report start and end dates are the intersection of the + start/end dates from options and that from date: queries. That is, + date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the + smallest common time span. + + Examples: + + -b 2016/3/17 begin on St. Patrick's day 2016 + -e 12/1 end at the start of december 1st of the current year + (11/30 will be the last date included) + -b thismonth all transactions on or after the 1st of the current month + -p thismonth all transactions in the current month + date:2016/3/17.. the above written as queries instead (.. can also be re- + placed with -) + date:..12/1 + date:thismonth.. + date:thismonth + + Report intervals + A report interval can be specified so that commands like register, bal- + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report in- + tervals can not be specified with a query. + + Period expressions + The -p/--period option accepts period expressions, a shorthand way of + expressing a start date, end date, and/or report interval all at once. + + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as + exclusive: + + -p "from 2009/1/1 to 2009/4/1" + + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as + ".." or "-". These are equivalent to the above: + + -p "2009/1/1 2009/4/1" + -p2009/1/1to2009/4/1 + -p2009/1/1..2009/4/1 + + Dates are smart dates, so if the current year is 2009, the above can + also be written as: + + -p "1/1 4/1" + -p "january-apr" + -p "this year to 4/1" + + If you specify only one date, the missing start or end date will be the + earliest or latest transaction in your journal: + + -p "from 2009/1/1" everything after january + 1, 2009 + -p "from 2009/1" the same + -p "from 2009" the same + -p "to 2009" everything before january + 1, 2009 + + A single date with no "from" or "to" defines both the start and end + date like so: + + -p "2009" the year 2009; equivalent + to "2009/1/1 to 2010/1/1" + -p "2009/1" the month of jan; equiva- + lent to "2009/1/1 to + 2009/2/1" + -p "2009/1/1" just that day; equivalent + to "2009/1/1 to 2009/1/2" + + Or you can specify a single quarter like so: + + -p "2009Q1" first quarter of 2009, + equivalent to "2009/1/1 to + 2009/4/1" + -p "q4" fourth quarter of the cur- + rent year + + The argument of -p can also begin with, or be, a report interval ex- + pression. The basic report intervals are daily, weekly, monthly, quar- + terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y + flags. Between report interval and start/end dates (if any), the word + in is optional. Examples: + + -p "weekly from 2009/1/1 to 2009/4/1" + -p "monthly in 2008" + -p "quarterly" + + Note that weekly, monthly, quarterly and yearly intervals will always + start on the first day on week, month, quarter or year accordingly, and + will end on the last day of same period, even if associated period ex- + pression specifies different explicit start and end date. + + For example: + + -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- + to 2009/4/1" day + -p "monthly in starts on 2018/11/01 + 2008/11/25" + -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, + 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 + -p "yearly from starts on 2009/01/01, first day of 2009 + 2009-12-29" + + The following more complex report intervals are also supported: bi- + weekly, fortnightly, bimonthly, every day|week|month|quarter|year, ev- + ery N days|weeks|months|quarters|years. + + All of these will start on the first day of the requested period and + end on the last one, as described above. + + Examples: + + -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, + 2008/03/01, ... + -p "every 2 weeks" starts on closest preceding Monday + -p "every 5 month from periods will have boundaries on 2009/03/01, + 2009/03" 2009/08/01, ... + + If you want intervals that start on arbitrary day of your choosing and + span a week, month or year, you need to use any of the following: + + every Nth day of week, every WEEKDAYNAME (eg + mon|tue|wed|thu|fri|sat|sun), every Nth day [of month], every Nth WEEK- + DAYNAME [of month], every MM/DD [of year], every Nth MMM [of year], ev- + ery MMM Nth [of year]. + + Examples: + + -p "every 2nd day of periods will go from Tue to Tue + week" + -p "every Tue" same + -p "every 15th day" period boundaries will be on 15th of each + month + -p "every 2nd Monday" period boundaries will be on second Monday of + each month + -p "every 11/05" yearly periods with boundaries on 5th of Nov + -p "every 5th Nov" same + -p "every Nov 5th" same + + Show historical balances at end of 15th each month (N is exclusive end + date): + + hledger balance -H -p "every 16th day" + + Group postings from start of wednesday to end of next tuesday (N is + start date and exclusive end date): + + hledger register checking -p "every 3rd day of week" + +DEPTH + With the --depth N option (short form: -N), commands like account, bal- + ance and register will show only the uppermost accounts in the account + tree, down to level N. Use this when you want a summary with less de- + tail. This flag has the same effect as a depth: query argument (so -2, + --depth=2 or depth:2 are equivalent). + +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 @@ -710,551 +785,7 @@ OPTIONS 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 - shell such as <, >, (, ), | and $, should be escaped by enclosing them - in quotes or by writing backslashes before the characters. Eg: - - hledger register -p 'last year' "accounts receivable (receiv- - able|payable)" amt:\>100. - - More escaping - Characters significant both to the shell and in regular expressions may - need one extra level of escaping. These include parentheses, the pipe - symbol and the dollar sign. Eg, to match the dollar symbol, bash users - should do: - - hledger balance cur:'\$' - - or: - - hledger balance cur:\\$ - - Even more escaping - When hledger runs an add-on executable (eg you type hledger ui, hledger - runs hledger-ui), it de-escapes command-line options and arguments - once, so you might need to triple-escape. Eg in bash, running the ui - command and matching the dollar sign, it's: - - hledger ui cur:'\\$' - - or: - - hledger ui cur:\\\\$ - - If you asked why four slashes above, this may help: - - unescaped: $ - escaped: \$ - double-escaped: \\$ - triple-escaped: \\\\$ - - (The number of backslashes in fish shell is left as an exercise for the - reader.) - - You can always avoid the extra escaping for add-ons by running the add- - on directly: - - hledger-ui cur:\\$ - - Less escaping - Inside an argument file, or in the search field of hledger-ui or - hledger-web, or at a GHCI prompt, you need one less level of escaping - than at the command line. And backslashes may work better than quotes. - Eg: - - ghci> :main balance cur:\$ - - Unicode characters - hledger is expected to handle non-ascii characters correctly: - - o they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's search/add/edit - forms, etc.) - - o they should be displayed correctly by all hledger tools, and on- - screen alignment should be preserved. - - This requires a well-configured environment. Here are some tips: - - o A system locale must be configured, and it must be one that can de- - code the characters being used. In bash, you can set a locale like - this: export LANG=en_US.UTF-8. There are some more details in Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- - grams). - - o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) - must support unicode - - o the terminal must be using a font which includes the required unicode - glyphs - - o the terminal should be configured to display wide characters as dou- - ble width (for report alignment) - - o on Windows, for best results you should run hledger in the same kind - of environment in which it was built. Eg hledger built in the stan- - dard CMD.EXE environment (like the binaries on our download page) - might show display problems when run in a cygwin or msys terminal, - and vice versa. (See eg #961). - - Input files - hledger reads transactions from a data file (and the add command writes - to it). By default this file is $HOME/.hledger.journal (or on Windows, - something like C:/Users/USER/.hledger.journal). You can override this - with the $LEDGER_FILE environment variable: - - $ setenv LEDGER_FILE ~/finance/2016.journal - $ hledger stats - - or with the -f/--file option: - - $ hledger -f /some/file stats - - The file name - (hyphen) means standard input: - - $ cat some.journal | hledger -f- - - Usually the data file is in hledger's journal format, but it can be in - any of the supported file formats, which currently are: - - Reader: Reads: Used for file exten- - sions: - ----------------------------------------------------------------------------- - journal hledger journal files and some Ledger .journal .j .hledger - journals, for transactions .ledger - time- timeclock files, for precise time log- .timeclock - clock ging - timedot timedot files, for approximate time .timedot - logging - csv comma/semicolon/tab/other-separated .csv .ssv .tsv - values, for data import - - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a - recognised file extension, so as to either read successfully or to show - relevant error messages. - - When you can't ensure the right file extension, not to worry: you can - force a specific reader/format by prefixing the file path with the for- - mat and a colon. Eg to read a .dat file as csv: - - $ hledger -f csv:/some/csv-file.dat stats - $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- - - You can specify multiple -f options, to read multiple files as one big - journal. There are some limitations with this: - - o directives in one file will not affect the other files - - o balance assertions will not see any account balances from previous - files - - If you need either of those things, you can - - o use a single parent file which includes the others - - o or concatenate the files into one before reading, eg: cat a.journal - b.journal | hledger -f- CMD. - - Strict mode - hledger checks input files for valid data. By default, the most impor- - tant errors are detected, while still accepting easy journal files - without a lot of declarations: - - o Are the input files parseable, with valid syntax ? - - o Are all transactions balanced ? - - o Do all balance assertions pass ? - - With the -s/--strict flag, additional checks are performed: - - o Are all accounts posted to, declared with an account directive ? - (Account error checking) - - o Are all commodities declared with a commodity directive ? (Commodity - error checking) - - See also: https://hledger.org/checking-for-errors.html - - experimental. - - Output destination - hledger commands send their output to the terminal by default. You can - of course redirect this, eg into a file, using standard shell syntax: - - $ hledger print > foo.txt - - Some commands (print, register, stats, the balance commands) also pro- - vide the -o/--output-file option, which does the same thing without - needing the shell. Eg: - - $ hledger print -o foo.txt - $ hledger print -o - # write to stdout (the default) - - Output format - Some commands (print, register, the balance commands) offer a choice of - output format. In addition to the usual plain text format (txt), there - are CSV (csv), HTML (html), JSON (json) and SQL (sql). This is con- - trolled by the -O/--output-format option: - - $ hledger print -O csv - - or, by a file extension specified with -o/--output-file: - - $ hledger balancesheet -o foo.html # write HTML to foo.html - - The -O option can be used to override the file extension if needed: - - $ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt - - Some notes about JSON output: - - o This feature is marked experimental, and not yet much used; you - should expect our JSON to evolve. Real-world feedback is welcome. - - o Our JSON is rather large and verbose, as it is quite a faithful rep- - resentation of hledger's internal data types. To understand the - JSON, read the Haskell type definitions, which are mostly in - https://github.com/simonmichael/hledger/blob/master/hledger- - lib/Hledger/Data/Types.hs. - - o hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can - arise in practice (from automatically-calculated transaction prices), - and would break most JSON consumers. So in JSON, we show quantities - as simple Numbers with at most 10 decimal places. We don't limit the - number of integer digits, but that part is under your control. We - hope this approach will not cause problems in practice; if you find - otherwise, please let us know. (Cf #1195) - - Notes about SQL output: - - o SQL output is also marked experimental, and much like JSON could use - real-world feedback. - - o SQL output is expected to work with sqlite, MySQL and PostgreSQL - - o SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables cre- - ated via SQL output of hledger, you would probably want to either - clear tables of existing data (via delete or truncate SQL statements) - or drop tables completely as otherwise your postings will be duped. - - Regular expressions - hledger uses regular expressions in a number of places: - - o query terms, on the command line and in the hledger-web search form: - REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX - - o CSV rules conditional blocks: if REGEX ... - - o account alias directives and options: alias /REGEX/ = REPLACEMENT, - --alias /REGEX/=REPLACEMENT - - hledger's regular expressions come from the regex-tdfa library. If - they're not doing what you expect, it's important to know exactly what - they support: - - 1. they are case insensitive - - 2. they are infix matching (they do not need to match the entire thing - being matched) - - 3. they are POSIX ERE (extended regular expressions) - - 4. they also support GNU word boundaries (\b, \B, \<, \>) - - 5. they do not support backreferences; if you write \1, it will match - the digit 1. Except when doing text replacement, eg in account - aliases, where backreferences can be used in the replacement string - to reference capturing groups in the search regexp. - - 6. they do not support mode modifiers ((?s)), character classes (\w, - \d), or anything else not mentioned above. - - Some things to note: - - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, - these are not required. - - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts - with the dollar sign in hledger-web, write cur:\$. - - o On the command line, some metacharacters like $ have a special mean- - ing to the shell and so must be escaped at least once more. See Spe- - cial characters. - - Smart dates - hledger's user interfaces accept a flexible "smart date" syntax (unlike - dates in the journal file). Smart dates allow some english words, can - be relative to today's date, and can have less-significant date parts - omitted (defaulting to 1). - - Examples: - - 2004/10/1, 2004-01-01, exact date, several separators allowed. Year - 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 - 2004 start of year - 2004/10 start of month - 10/1 month and day in current year - 21 day in current month - october, oct start of month in current year - yesterday, today, tomor- -1, 0, 1 days from today - row - last/this/next -1, 0, 1 periods from the current period - day/week/month/quar- - ter/year - 20181201 8 digit YYYYMMDD with valid year month and day - 201812 6 digit YYYYMM with valid year and month - - Counterexamples - malformed digit sequences might give surprising re- - sults: - - 201813 6 digits with an invalid month is parsed as start of - 6-digit year - 20181301 8 digits with an invalid month is parsed as start 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 - - Report start & end date - By default, most hledger reports will show the full span of time repre- - sented by the journal data. The report start date will be the earliest - transaction or posting date, and the report end date will be the latest - transaction, posting, or market price date. - - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, - -e/--end, -p/--period or a date: query (described below). All of these - accept the smart date syntax. - - Some notes: - - o As in Ledger, end dates are exclusive, so you need to write the date - after the last day you want to include. - - o As noted in reporting options: among start/end dates specified with - options, the last (i.e. right-most) option takes precedence. - - o The effective report start and end dates are the intersection of the - start/end dates from options and that from date: queries. That is, - date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the - smallest common time span. - - Examples: - - -b 2016/3/17 begin on St. Patrick's day 2016 - -e 12/1 end at the start of december 1st of the current year - (11/30 will be the last date included) - -b thismonth all transactions on or after the 1st of the current month - -p thismonth all transactions in the current month - date:2016/3/17.. the above written as queries instead (.. can also be re- - placed with -) - date:..12/1 - date:thismonth.. - date:thismonth - - Report intervals - A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report in- - tervals can not be specified with a query. - - Period expressions - The -p/--period option accepts period expressions, a shorthand way of - expressing a start date, end date, and/or report interval all at once. - - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as - exclusive: - - -p "from 2009/1/1 to 2009/4/1" - - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as - ".." or "-". These are equivalent to the above: - - -p "2009/1/1 2009/4/1" - -p2009/1/1to2009/4/1 - -p2009/1/1..2009/4/1 - - Dates are smart dates, so if the current year is 2009, the above can - also be written as: - - -p "1/1 4/1" - -p "january-apr" - -p "this year to 4/1" - - If you specify only one date, the missing start or end date will be the - earliest or latest transaction in your journal: - - -p "from 2009/1/1" everything after january - 1, 2009 - -p "from 2009/1" the same - -p "from 2009" the same - -p "to 2009" everything before january - 1, 2009 - - A single date with no "from" or "to" defines both the start and end - date like so: - - -p "2009" the year 2009; equivalent - to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- - lent to "2009/1/1 to - 2009/2/1" - -p "2009/1/1" just that day; equivalent - to "2009/1/1 to 2009/1/2" - - Or you can specify a single quarter like so: - - -p "2009Q1" first quarter of 2009, - equivalent to "2009/1/1 to - 2009/4/1" - -p "q4" fourth quarter of the cur- - rent year - - The argument of -p can also begin with, or be, a report interval ex- - pression. The basic report intervals are daily, weekly, monthly, quar- - terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y - flags. Between report interval and start/end dates (if any), the word - in is optional. Examples: - - -p "weekly from 2009/1/1 to 2009/4/1" - -p "monthly in 2008" - -p "quarterly" - - Note that weekly, monthly, quarterly and yearly intervals will always - start on the first day on week, month, quarter or year accordingly, and - will end on the last day of same period, even if associated period ex- - pression specifies different explicit start and end date. - - For example: - - -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- - to 2009/4/1" day - -p "monthly in starts on 2018/11/01 - 2008/11/25" - -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, - 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 - -p "yearly from starts on 2009/01/01, first day of 2009 - 2009-12-29" - - The following more complex report intervals are also supported: bi- - weekly, fortnightly, bimonthly, every day|week|month|quarter|year, ev- - ery N days|weeks|months|quarters|years. - - All of these will start on the first day of the requested period and - end on the last one, as described above. - - Examples: - - -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, - 2008/03/01, ... - -p "every 2 weeks" starts on closest preceding Monday - -p "every 5 month from periods will have boundaries on 2009/03/01, - 2009/03" 2009/08/01, ... - - If you want intervals that start on arbitrary day of your choosing and - span a week, month or year, you need to use any of the following: - - every Nth day of week, every WEEKDAYNAME (eg - mon|tue|wed|thu|fri|sat|sun), every Nth day [of month], every Nth WEEK- - DAYNAME [of month], every MM/DD [of year], every Nth MMM [of year], ev- - ery MMM Nth [of year]. - - Examples: - - -p "every 2nd day of periods will go from Tue to Tue - week" - -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each - month - -p "every 2nd Monday" period boundaries will be on second Monday of - each month - -p "every 11/05" yearly periods with boundaries on 5th of Nov - -p "every 5th Nov" same - -p "every Nov 5th" same - - Show historical balances at end of 15th each month (N is exclusive end - date): - - hledger balance -H -p "every 16th day" - - Group postings from start of wednesday to end of next tuesday (N is - start date and exclusive end date): - - hledger register checking -p "every 3rd day of week" - - Depth limiting - With the --depth N option (short form: -N), commands like account, bal- - ance and register will show only the uppermost accounts in the account - tree, down to level N. Use this when you want a summary with less de- - tail. This flag has the same effect as a depth: query argument (so -2, - --depth=2 or depth:2 are equivalent). - - Pivoting - Normally hledger sums amounts, and organizes them in a hierarchy, based - on account name. The --pivot FIELD option causes it to sum and orga- - nize hierarchy based on the value of some other field instead. FIELD - can be: code, description, payee, note, or the full name (case insensi- - tive) of any tag. As with account names, values containing colon:sepa- - rated:parts will be displayed hierarchically in reports. - - --pivot is a general option affecting all reports; you can think of - hledger transforming the journal before any other processing, replacing - every posting's account name with the value of the specified field on - that posting, inheriting it from the transaction or using a blank value - if it's not present. - - An example: - - 2016/02/16 Member Fee Payment - assets:bank account 2 EUR - income:member fees -2 EUR ; member: John Doe - - Normal balance report showing account names: - - $ hledger balance - 2 EUR assets:bank account - -2 EUR income:member fees - -------------------- - 0 - - Pivoted balance report, using member: tag values instead: - - $ hledger balance --pivot member - 2 EUR - -2 EUR John Doe - -------------------- - 0 - - One way to show only amounts with a member: value (using a query, de- - scribed below): - - $ hledger balance --pivot member tag:member=. - -2 EUR John Doe - -------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account - name"): - - $ hledger balance --pivot member acct:. - -2 EUR John Doe - -------------------- - -2 EUR - - Valuation +VALUATION Instead of reporting amounts in their original commodity, hledger can convert them to cost/sale amount (using the conversion rate recorded in the transaction), or to market value (using some market price on a cer- @@ -1289,8 +820,6 @@ OPTIONS of the period, by default. Market prices - (experimental) - To convert a commodity A to its market value in another commodity B, hledger looks for a suitable market price (exchange rate) as follows, in this order of preference : @@ -1315,8 +844,6 @@ OPTIONS verted. --infer-value: market prices from transactions - (experimental) - Normally, market value in hledger is fully controlled by, and requires, P directives in your journal. Since adding and updating those can be a chore, and since transactions usually take place at close to market @@ -1345,8 +872,6 @@ OPTIONS (no @, multiple commodities, balanced). Valuation commodity - (experimental) - When you specify a valuation commodity (-X COMM or --value TYPE,COMM): hledger will convert all amounts to COMM, wherever it can find a suit- able market price (including by reversing or chaining prices). @@ -1579,6 +1104,8 @@ OPTIONS signments register + + starting cost value at day not sup- value at day value at balance before report ported before report DATE/today (-H) or journal or journal @@ -1620,9 +1147,6 @@ OPTIONS start postings be- postings be- fore report fore report start start - - - balance sums of costs same as not sup- balance value at changes of postings --value=end ported change in DATE/today of (bal, is, in period each period, sums of post- @@ -1682,18 +1206,134 @@ OPTIONS report's multi-period mode (whether showing one or many subperi- ods). +PIVOTING + Normally hledger sums amounts, and organizes them in a hierarchy, based + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD + can be: code, description, payee, note, or the full name (case insensi- + tive) of any tag. As with account names, values containing colon:sepa- + rated:parts will be displayed hierarchically in reports. + + --pivot is a general option affecting all reports; you can think of + hledger transforming the journal before any other processing, replacing + every posting's account name with the value of the specified field on + that posting, inheriting it from the transaction or using a blank value + if it's not present. + + An example: + + 2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe + + Normal balance report showing account names: + + $ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees + -------------------- + 0 + + Pivoted balance report, using member: tag values instead: + + $ hledger balance --pivot member + 2 EUR + -2 EUR John Doe + -------------------- + 0 + + One way to show only amounts with a member: value (using a query, de- + scribed below): + + $ hledger balance --pivot member tag:member=. + -2 EUR John Doe + -------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account + name"): + + $ hledger balance --pivot member acct:. + -2 EUR John Doe + -------------------- + -2 EUR + +OUTPUT + Output destination + hledger commands send their output to the terminal by default. You can + of course redirect this, eg into a file, using standard shell syntax: + + $ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also pro- + vide the -o/--output-file option, which does the same thing without + needing the shell. Eg: + + $ hledger print -o foo.txt + $ hledger print -o - # write to stdout (the default) + + Output format + Some commands (print, register, the balance commands) offer a choice of + output format. In addition to the usual plain text format (txt), there + are CSV (csv), HTML (html), JSON (json) and SQL (sql). This is con- + trolled by the -O/--output-format option: + + $ hledger print -O csv + + or, by a file extension specified with -o/--output-file: + + $ hledger balancesheet -o foo.html # write HTML to foo.html + + The -O option can be used to override the file extension if needed: + + $ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt + + Some notes about JSON output: + + o This feature is marked experimental, and not yet much used; you + should expect our JSON to evolve. Real-world feedback is welcome. + + o Our JSON is rather large and verbose, as it is quite a faithful rep- + resentation of hledger's internal data types. To understand the + JSON, read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/master/hledger- + lib/Hledger/Data/Types.hs. + + o hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can + arise in practice (from automatically-calculated transaction prices), + and would break most JSON consumers. So in JSON, we show quantities + as simple Numbers with at most 10 decimal places. We don't limit the + number of integer digits, but that part is under your control. We + hope this approach will not cause problems in practice; if you find + otherwise, please let us know. (Cf #1195) + + Notes about SQL output: + + o SQL output is also marked experimental, and much like JSON could use + real-world feedback. + + o SQL output is expected to work with sqlite, MySQL and PostgreSQL + + o SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables cre- + ated via SQL output of hledger, you would probably want to either + clear tables of existing data (via delete or truncate SQL statements) + or drop tables completely as otherwise your postings will be duped. + COMMANDS hledger provides a number of commands for producing reports and manag- ing your data. Run hledger with no arguments to list the commands - available. + available, and hledger CMD to run a command. CMD can be the full com- + mand name, or its standard abbreviation shown in the commands list, or + any unambiguous prefix of the name. Eg: hledger bal. - To run a command, write its name (or its abbreviation shown in the com- - mands list, or any unambiguous prefix of the name) as hledger's first - argument. Eg: hledger balance or hledger bal. + Here are the built-in commands, with the most often-used in bold: - Here are the built-in commands: + Data entry: - Data entry (these modify the journal file): + These data entry commands are the only ones which can modify your jour- + nal file. o add - add transactions using guided prompts @@ -1729,8 +1369,8 @@ COMMANDS o activity - show postings-per-interval bar charts - o balance (b, bal) - show balance changes/end balances/budgets in ac- - counts + o balance (b, bal) - show balance changes/end balances/budgets in any + accounts o codes - show transaction codes @@ -1740,6 +1380,8 @@ COMMANDS o files - show input file paths + o help - show hledger user manuals in several formats + o notes - show unique note segments of transaction descriptions o payees - show unique payee segments of transaction descriptions @@ -1750,10 +1392,10 @@ COMMANDS o print-unique - show only transactions with unique descriptions - o register (r, reg) - show postings in one or more accounts & running + o register (r, reg) - show postings in one or more accounts & running total - o register-match - show a recent posting that best matches a descrip- + o register-match - show a recent posting that best matches a descrip- tion o stats - show journal statistics @@ -1762,19 +1404,39 @@ COMMANDS o test - run self tests + Add-on commands: + + Programs or scripts named hledger-SOMETHING in your PATH are add-on + commands; these appear in the commands list with a + mark. Two of + these are maintained and released with hledger: + + o ui - an efficient terminal interface (TUI) for hledger + + o web - a simple web interface (WUI) for hledger + + And these add-ons are maintained separately: + + o iadd - a more interactive alternative for the add command + + o interest - generates interest transactions according to various + schemes + + o stockquotes - downloads market prices for your commodities from Al- + phaVantage (experimental) + Next, the detailed command docs, in alphabetical order. accounts accounts, a Show account names. - This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (the default). With - query arguments, only matched account names and account names refer- - enced by matched postings are shown. It shows a flat list by default. - With --tree, it uses indentation to show the account hierarchy. In - flat mode you can add --drop N to omit the first few account name com- - ponents. Account names can be depth-clipped with depth:N or --depth N + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N or -N. Examples: @@ -1793,8 +1455,8 @@ COMMANDS activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. Examples: @@ -1807,25 +1469,25 @@ COMMANDS add add - Prompt for transactions and add them to the journal. Any arguments + Prompt for transactions and add them to the journal. Any arguments will be used as default inputs for the first N prompts. - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- actions, and appends them to the journal file (if there are multiple -f - FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + FILE options, the first file is used.) Existing transactions are not + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by de- - scription) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. @@ -1833,10 +1495,10 @@ COMMANDS o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. @@ -1845,7 +1507,7 @@ COMMANDS o If you make a mistake, enter < at any prompt to go one step backward. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -1875,16 +1537,16 @@ COMMANDS Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2015/05/22]: $ - On Microsoft Windows, the add command makes sure that no part of the + On Microsoft Windows, the add command makes sure that no part of the file path ends with a period, as that would cause problems (#1056). aregister aregister, areg - Show transactions affecting a particular account, and the account's + Show transactions affecting a particular account, and the account's running balance. - aregister shows the transactions affecting a particular account (and - its subaccounts), from the point of view of that account. Each line + aregister shows the transactions affecting a particular account (and + its subaccounts), from the point of view of that account. Each line shows: o the transaction's (or posting's, see below) date @@ -1893,48 +1555,48 @@ COMMANDS o the net change to this account's balance - o the account's historical running balance (including balance from + o the account's historical running balance (including balance from transactions before the report start date). - With aregister, each line represents a whole transaction - as in - hledger-ui, hledger-web, and your bank statement. By contrast, the - register command shows individual postings, across all accounts. You - might prefer aregister for reconciling with real-world asset/liability + With aregister, each line represents a whole transaction - as in + hledger-ui, hledger-web, and your bank statement. By contrast, the + register command shows individual postings, across all accounts. You + might prefer aregister for reconciling with real-world asset/liability accounts, and register for reviewing detailed revenues/expenses. An account must be specified as the first argument, which should be the - full account name or an account pattern (regular expression). aregis- - ter will show transactions in this account (the first one matched) and + full account name or an account pattern (regular expression). aregis- + ter will show transactions in this account (the first one matched) and any of its subaccounts. - Any additional arguments form a query which will filter the transac- + Any additional arguments form a query which will filter the transac- tions shown. - Transactions making a net change of zero are not shown by default; add + Transactions making a net change of zero are not shown by default; add the -E/--empty flag to show them. This command also supports the output destination and output format op- tions The output formats supported are txt, csv, and json. aregister and custom posting dates - Transactions whose date is outside the report period can still be - shown, if they have a posting to this account dated inside the report - period. (And in this case it's the posting date that is shown.) This + Transactions whose date is outside the report period can still be + shown, if they have a posting to this account dated inside the report + period. (And in this case it's the posting date that is shown.) This ensures that aregister can show an accurate historical running balance, matching the one shown by register -H with the same arguments. - To filter strictly by transaction date instead, add the --txn-dates - flag. If you use this flag and some of your postings have custom + To filter strictly by transaction date instead, add the --txn-dates + flag. If you use this flag and some of your postings have custom dates, it's probably best to assume the running balance is wrong. Examples: - Show all transactions and historical running balance in the first ac- + Show all transactions and historical running balance in the first ac- count whose name contains "checking": $ hledger areg checking - Show transactions and historical running balance in all asset accounts + Show transactions and historical running balance in all asset accounts during july: $ hledger areg assets date:jul @@ -1944,22 +1606,22 @@ COMMANDS Show accounts and their balances. The balance command is hledger's most versatile command. Note, despite - the name, it is not always used for showing real-world account bal- - ances; the more accounting-aware balancesheet and incomestatement may + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may be more convenient for that. By default, it displays all accounts, and each account's change in bal- ance during the entire period of the journal. Balance changes are cal- - culated by adding up the postings in each account. You can limit the - postings matched, by a query, to see fewer accounts, changes over a + culated by adding up the postings in each account. You can limit the + postings matched, by a query, to see fewer accounts, changes over a different time period, changes from only cleared transactions, etc. If you include an account's complete history of postings in the report, - the balance change is equivalent to the account's current ending bal- - ance. For a real-world account, typically you won't have all transac- + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- tions in the journal; instead you'll have all transactions after a cer- - tain date, and an "opening balances" transaction setting the correct - starting balance on that date. Then the balance command will show + tain date, and an "opening balances" transaction setting the correct + starting balance on that date. Then the balance command will show real-world account balances. In some cases the -H/--historical flag is used to ensure this (more below). @@ -1970,7 +1632,7 @@ COMMANDS The balance command can produce several styles of report: Classic balance report - This is the original balance report, as found in Ledger. It usually + This is the original balance report, as found in Ledger. It usually looks like this: $ hledger balance @@ -1988,21 +1650,21 @@ COMMANDS 0 By default, accounts are displayed hierarchically, with subaccounts in- - dented below their parent, with accounts at each level of the tree + dented below their parent, with accounts at each level of the tree sorted by declaration order if declared, then by account name. "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to + balance of their own, are elided into the following line for more com- + pact output. (Eg above, the "liabilities" account.) Use --no-elide to prevent this. - Account balances are "inclusive" - they include the balances of any + Account balances are "inclusive" - they include the balances of any subaccounts. - Accounts which have zero balance (and no non-zero subaccounts) are + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use -E/--empty to show them. - A final total is displayed by default; use -N/--no-total to suppress + A final total is displayed by default; use -N/--no-total to suppress it, eg: $ hledger balance -p 2008/6 expenses --no-total @@ -2011,7 +1673,7 @@ COMMANDS $1 supplies Customising the classic balance report - You can customise the layout of classic balance reports with --format + You can customise the layout of classic balance reports with --format FMT: $ hledger balance --format "%20(account) %12(total)" @@ -2029,7 +1691,7 @@ COMMANDS 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -2040,14 +1702,14 @@ COMMANDS o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -2064,24 +1726,24 @@ COMMANDS o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Colour support - In terminal output, when colour is enabled, the balance command shows + In terminal output, when colour is enabled, the balance command shows negative amounts in red. Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "exclusive" balance, excluding any subaccount balances. In + To see a flat list instead of the default hierarchical display, use + --flat. In this mode, accounts (unless depth-clipped) show their full + names and "exclusive" balance, excluding any subaccount balances. In this mode, you can also use --drop N to omit the first few account name components. @@ -2090,8 +1752,8 @@ COMMANDS $1 supplies Depth limited balance reports - With --depth N or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise + With --depth N or depth:N or just -N, balance reports show accounts + only to the specified numeric depth. This is very useful to summarise a complex set of accounts and get an overview. $ hledger balance -N -1 @@ -2104,9 +1766,9 @@ COMMANDS inclusive balances at the depth limit. Percentages - With -% or --percent, balance reports show each account's value ex- - pressed as a percentage of the column's total. This is useful to get - an overview of the relative sizes of account balances. For example to + With -% or --percent, balance reports show each account's value ex- + pressed as a percentage of the column's total. This is useful to get + an overview of the relative sizes of account balances. For example to obtain an overview of expenses: $ hledger balance expenses -% @@ -2116,43 +1778,43 @@ COMMANDS -------------------- 100.0 % - Note that --tree does not have an effect on -%. The percentages are - always relative to the total sum of each column, they are never rela- + Note that --tree does not have an effect on -%. The percentages are + always relative to the total sum of each column, they are never rela- tive to the parent account. - Since the percentages are relative to the columns sum, it is usually - not useful to calculate percentages if the signs of the amounts are - mixed. Although the results are technically correct, they are most - likely useless. Especially in a balance report that sums up to zero + Since the percentages are relative to the columns sum, it is usually + not useful to calculate percentages if the signs of the amounts are + mixed. Although the results are technically correct, they are most + likely useless. Especially in a balance report that sums up to zero (eg hledger balance -B) all percentage values will be zero. - This flag does not work if the report contains any mixed commodity ac- + This flag does not work if the report contains any mixed commodity ac- counts. If there are mixed commodity accounts in the report be sure to use -V or -B to coerce the report into using a single commodity. Sorting by amount - With -S/--sort-amount, accounts with the largest (most positive) bal- - ances are shown first. For example, hledger bal expenses -MAS shows + With -S/--sort-amount, accounts with the largest (most positive) bal- + ances are shown first. For example, hledger bal expenses -MAS shows your biggest averaged monthly expenses first. - Revenues and liability balances are typically negative, however, so -S - shows these in reverse order. To work around this, you can add --in- - vert to flip the signs. Or, use one of the sign-flipping reports like + Revenues and liability balances are typically negative, however, so -S + shows these in reverse order. To work around this, you can add --in- + vert to flip the signs. Or, use one of the sign-flipping reports like balancesheet or incomestatement, which also support -S. Eg: hledger is -MAS. Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting in- + Multicolumn or tabular balance reports are a very useful hledger fea- + ture, and usually the preferred style. They share many of the above + features, but they show the report as a table, with columns represent- + ing time periods. This mode is activated by providing a reporting in- terval. - There are three types of multicolumn balance report, showing different + There are three types of multicolumn balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg + the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E @@ -2168,7 +1830,7 @@ COMMANDS || $-1 $1 0 0 2. With --cumulative: each column shows the ending balance for that pe- - riod, accumulating the changes across periods, starting from 0 at + riod, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -2184,8 +1846,8 @@ COMMANDS || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -2204,26 +1866,26 @@ COMMANDS Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. - Multicolumn balance reports display accounts in flat mode by default; + Multicolumn balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports: + The -E/--empty flag does two things in multicolumn balance reports: first, the report will show all columns within the specified report pe- - riod (without -E, leading and trailing columns with all zeroes are not - shown). Second, all accounts which existed at the report start date - will be considered, not just the ones with activity during the report - period (use -E to include low-activity accounts which would otherwise + riod (without -E, leading and trailing columns with all zeroes are not + shown). Second, all accounts which existed at the report start date + will be considered, not just the ones with activity during the report + period (use -E to include low-activity accounts which would otherwise would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -2244,27 +1906,27 @@ COMMANDS (Average is rounded to the dollar here since all journal amounts are) - The --transpose flag can be used to exchange the rows and columns of a + The --transpose flag can be used to exchange the rows and columns of a multicolumn report. - When showing multicommodity amounts, multicolumn balance reports will + When showing multicommodity amounts, multicolumn balance reports will elide any amounts which have more than two commodities, since otherwise - columns could get very wide. The --no-elide flag disables this. Hid- - ing totals with the -N/--no-total flag can also help reduce the width + columns could get very wide. The --no-elide flag disables this. Hid- + ing totals with the -N/--no-total flag can also help reduce the width of multicommodity reports. When the report is still too wide, a good workaround is to pipe it into - less -RS (-R for colour, -S to chop long lines). Eg: hledger bal -D + less -RS (-R for colour, -S to chop long lines). Eg: hledger bal -D --color=yes | less -RS. Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic transactions. This is very useful for comparing planned and actual in- - come, expenses, time usage, etc. --budget is most often combined with + come, expenses, time usage, etc. --budget is most often combined with a report interval. - For example, you can take average monthly expenses in the common ex- + For example, you can take average monthly expenses in the common ex- pense categories to construct a minimal monthly budget: ;; Budget @@ -2311,26 +1973,26 @@ COMMANDS This is different from a normal balance report in several ways: - o Only accounts with budget goals during the report period are shown, + o Only accounts with budget goals during the report period are shown, by default. - o In each column, in square brackets after the actual amount, budget - goal amounts are shown, and the actual/goal percentage. (Note: bud- + o In each column, in square brackets after the actual amount, budget + goal amounts are shown, and the actual/goal percentage. (Note: bud- get goals should be in the same commodity as the actual amount.) - o All parent accounts are always shown, even in flat mode. Eg assets, + o All parent accounts are always shown, even in flat mode. Eg assets, assets:bank, and expenses above. - o Amounts always include all subaccounts, budgeted or unbudgeted, even + o Amounts always include all subaccounts, budgeted or unbudgeted, even in flat mode. This means that the numbers displayed will not always add up! Eg above, - the expenses actual amount includes the gifts and supplies transac- - tions, but the expenses:gifts and expenses:supplies accounts are not + the expenses actual amount includes the gifts and supplies transac- + tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty @@ -2372,12 +2034,12 @@ COMMANDS For more examples and notes, see Budgeting. Budget report start date - This might be a bug, but for now: when making budget reports, it's a + This might be a bug, but for now: when making budget reports, it's a good idea to explicitly set the report's start date to the first day of - a reporting period, because a periodic rule like ~ monthly generates - its transactions on the 1st of each month, and if your journal has no - regular transactions on the 1st, the default report start date could - exclude that budget goal, which can be a little surprising. Eg here + a reporting period, because a periodic rule like ~ monthly generates + its transactions on the 1st of each month, and if your journal has no + regular transactions on the 1st, the default report start date could + exclude that budget goal, which can be a little surprising. Eg here the default report period is just the day of 2020-01-15: ~ monthly in 2020 @@ -2396,9 +2058,9 @@ COMMANDS --------------++------------ || $400 - To avoid this, specify the budget report's period, or at least the - start date, with -b/-e/-p/date:, to ensure it includes the budget goal - transactions (periodic transactions) that you want. Eg, adding -b + To avoid this, specify the budget report's period, or at least the + start date, with -b/-e/-p/date:, to ensure it includes the budget goal + transactions (periodic transactions) that you want. Eg, adding -b 2020/1/1 to the above: $ hledger bal expenses --budget -b 2020/1/1 @@ -2411,12 +2073,12 @@ COMMANDS || $400 [80% of $500] Nested budgets - You can add budgets to any account in your account hierarchy. If you + You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud- - get(s) of the child account(s) would be added to the budget of their + get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any + In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget: @@ -2426,13 +2088,13 @@ COMMANDS expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicitly + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicitly means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both to- + Transactions in expenses:personal:electronics will be counted both to- wards its $100 budget and $1100 of expenses:personal , and transactions - in any other subaccount of expenses:personal would be counted towards + in any other subaccount of expenses:personal would be counted towards only towards the budget of expenses:personal. For example, let's consider these transactions: @@ -2458,9 +2120,9 @@ COMMANDS expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -2476,7 +2138,7 @@ COMMANDS -------------------------------++------------------------------- || 0 [ 0] - And with --empty, we can get a better picture of budget allocation and + And with --empty, we can get a better picture of budget allocation and consumption: $ hledger balance --budget -M --empty @@ -2495,16 +2157,19 @@ COMMANDS balancesheet balancesheet, bs - This command displays a balance sheet, showing historical ending bal- + This command displays a balance sheet, showing historical ending bal- ances of asset and liability accounts. (To see equity as well, use the - balancesheetequity command.) Amounts are shown with normal positive + balancesheetequity command.) Amounts are shown with normal positive sign, as in conventional financial statements. The asset and liability accounts shown are those accounts declared with - the Asset or Cash or Liability type, or otherwise all accounts under a - top-level asset or liability account (case insensitive, plurals al- + the Asset or Cash or Liability type, or otherwise all accounts under a + top-level asset or liability account (case insensitive, plurals al- lowed). + (This report is essentially similar to "hledger balance --historical + assets liabilities", with liabilities sign-flipped.) + Example: $ hledger balancesheet @@ -2550,6 +2215,9 @@ COMMANDS accounts under a top-level asset, liability or equity account (case in- sensitive, plurals allowed). + (This report is essentially similar to "hledger balance --historical + assets liabilities equity", with liabilities and equity sign-flipped.) + Example: $ hledger balancesheetequity @@ -2577,20 +2245,23 @@ COMMANDS 0 This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, html, and (experimen- + tions The output formats supported are txt, csv, html, and (experimen- tal) json. cashflow cashflow, cf - This command displays a cashflow statement, showing the inflows and - outflows affecting "cash" (ie, liquid) assets. Amounts are shown with + This command displays a cashflow statement, showing the inflows and + outflows affecting "cash" (ie, liquid) assets. Amounts are shown with normal positive sign, as in conventional financial statements. - The "cash" accounts shown are those accounts declared with the Cash - type, or otherwise all accounts under a top-level asset account (case - insensitive, plural allowed) which do not have fixed, investment, re- + The "cash" accounts shown are those accounts declared with the Cash + type, or otherwise all accounts under a top-level asset account (case + insensitive, plural allowed) which do not have fixed, investment, re- ceivable or A/R in their name. + (This report is essentially similar to "hledger balance --change assets + not:fixed not:investment not:receivable".) + Example: $ hledger cashflow @@ -2950,6 +2621,9 @@ COMMANDS level revenue or income or expense account (case insensitive, plurals allowed). + (This report is essentially similar to "hledger balance --change rev- + enues expenses", with revenues sign-flipped.) + Example: $ hledger incomestatement @@ -2974,13 +2648,13 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the - report mode with --change/--cumulative/--historical. Instead of abso- + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the + report mode with --change/--cumulative/--historical. Instead of abso- lute values percentages can be displayed with -%. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, html, and (experimen- + tions The output formats supported are txt, csv, html, and (experimen- tal) json. notes @@ -2988,8 +2662,8 @@ COMMANDS List the unique notes that appear in transactions. This command lists the unique notes that appear in transactions, in al- - phabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + phabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -2998,16 +2672,285 @@ COMMANDS Petrol Snacks + payees + payees + List the unique payee/payer names that appear in transactions. + + This command lists the unique payee/payer names that appear in transac- + tions, in alphabetic order. You can add a query to select a subset of + transactions. The payee/payer is the part of the transaction descrip- + tion before a | character (or if there is no |, the whole description). + + Example: + + $ hledger payees + Store Name + Gas Station + Person A + + prices + prices + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --in- + verted-costs, also print inverse prices based on transaction prices. + Prices (and postings providing prices) can be filtered by a query. + Price amounts are always displayed with their full precision. + + print + print, txns, p + Show transaction journal entries, sorted by date. + + The print command displays full journal entries (transactions) from the + journal file in date order, tidily formatted. With --date2, transac- + tions are sorted by secondary date instead. + + print's output is always a valid hledger journal. + It preserves all transaction information, but it does not preserve di- + rectives or inter-transaction comments + + $ hledger print + 2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + + 2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + + 2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + + 2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + + 2008/12/31 * pay off + liabilities:debts $1 + assets:bank:checking $-1 + + Normally, the journal entry's explicit or implicit amount style is pre- + served. For example, when an amount is omitted in the journal, it will + not appear in the output. Similarly, when a transaction price is im- + plied but not written, it will not appear in the output. You can use + the -x/--explicit flag to make all amounts and transaction prices ex- + plicit, which can be useful for troubleshooting or for making your + journal more readable and robust against data entry errors. -x is also + implied by using any of -B,-V,-X,--value. + + Note, -x/--explicit will cause postings with a multi-commodity amount + (these can arise when a multi-commodity transaction has an implicit + amount) to be split into multiple single-commodity postings, keeping + the output parseable. + + With -B/--cost, amounts with transaction prices are converted to cost + using that price. This can be used for troubleshooting. + + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is + no similar-enough match, no transaction will be shown. + + With --new, for each FILE being read, hledger reads (and writes) a spe- + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for ig- + noring 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) + + 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- + ordered. See also the import command. + + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, and (experimental) + json and sql. + + Here's an example of print's CSV output: + + $ hledger print -Ocsv + "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" + "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" + "1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" + "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" + "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" + "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" + "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" + "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" + "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" + "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" + "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" + "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + o There is one CSV record per posting, with the parent transaction's + fields repeated. + + o The "txnidx" (transaction index) field shows which postings belong to + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different + order, etc.) + + o The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + + o The numeric amount is repeated in either the "credit" or "debit" col- + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or + greater amounts under debit.) + + print-unique + print-unique + Print transactions which do not reuse an already-seen description. + + Example: + + $ cat unique.journal + 1/1 test + (acct:one) 1 + 2/2 test + (acct:two) 2 + $ LEDGER_FILE=unique.journal hledger print-unique + (-f option not supported) + 2015/01/01 test + (acct:one) 1 + + register + register, reg, r + Show postings and their running total. + + The register command displays matched postings, across all accounts, in + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a + specific account.) + + register normally shows line per posting, but note that multi-commodity + amounts will occupy multiple lines (one line per commodity). + + It is typically used with a query selecting a particular account, to + see that account's activity: + + $ hledger register checking + 2008/01/01 income assets:bank:checking $1 $1 + 2008/06/01 gift assets:bank:checking $1 $2 + 2008/06/02 save assets:bank:checking $-1 $1 + 2008/12/31 pay off assets:bank:checking $-1 0 + + With --date2, it shows and sorts by secondary date instead. + + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see + only recent activity, with a historically accurate running balance: + + $ hledger register checking -b 2008/6 --historical + 2008/06/01 gift assets:bank:checking $1 $2 + 2008/06/02 save assets:bank:checking $-1 $1 + 2008/12/31 pay off assets:bank:checking $-1 0 + + The --depth option limits the amount of sub-account detail displayed. + + The --average/-A flag shows the running average posting amount instead + of the running total (so, the final number displayed is the average for + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- + count and one commodity. + + The --related/-r flag shows the other postings in the transactions of + the postings which would normally be shown. + + The --invert flag negates all amounts. For example, it can be used on + an income account where amounts are normally displayed as negative num- + bers. It's also useful to show postings on the checking account to- + gether with the related account: + + $ hledger register --related --invert assets:checking + + With a reporting interval, register shows summary postings, one per in- + terval, aggregating the postings to each account: + + $ hledger register --monthly income + 2008/01 income:salary $-1 $-1 + 2008/06 income:gifts $-1 $-2 + + Periods with no activity, and summary postings with a zero amount, are + not shown by default; use the --empty/-E flag to see them: + + $ hledger register --monthly income -E + 2008/01 income:salary $-1 $-1 + 2008/02 0 $-1 + 2008/03 0 $-1 + 2008/04 0 $-1 + 2008/05 0 $-1 + 2008/06 income:gifts $-1 $-2 + 2008/07 0 $-2 + 2008/08 0 $-2 + 2008/09 0 $-2 + 2008/10 0 $-2 + 2008/11 0 $-2 + 2008/12 0 $-2 + + Often, you'll want to see just one line per interval. The --depth op- + tion helps with this, causing subaccounts to be aggregated: + + $ hledger register --monthly assets --depth 1h + 2008/01 assets $1 $1 + 2008/06 assets $-1 0 + 2008/12 assets $-1 $-1 + + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of in- + tervals. This ensures that the first and last intervals are full + length and comparable to the others in the report. + + Custom register output + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not + a bash shell variable) or by using the --width/-w option. + + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a de- + scription width as part of --width's argument, comma-separated: --width + W,D . Here's a diagram (won't display correctly in --help): + + <--------------------------------- width (W) ----------------------------------> + date (10) description (D) account (W-41-D) amount (12) balance (12) + DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA + + and some examples: + + $ hledger reg # use terminal width (or 80 on windows) + $ hledger reg -w 100 # use width 100 + $ COLUMNS=100 hledger reg # set with one-time environment variable + $ export COLUMNS=100; hledger reg # set till session end (or window resize) + $ hledger reg -w 100,40 # set overall width 100, description width 40 + $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 + + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, and (experimental) + json. + + register-match + register-match + Print the one posting whose transaction description is closest to DESC, + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- + tosync detect already-seen transactions when importing. + rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -3023,7 +2966,7 @@ COMMANDS (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -3033,16 +2976,16 @@ COMMANDS $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount in- + factor for an amount of original matched posting. If the amount in- cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- + modity; otherwise, it will be in the matched posting amount's commod- ity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -3057,7 +3000,7 @@ COMMANDS budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -3070,12 +3013,12 @@ COMMANDS --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + To use this tool for batch modification of your journal files you may find useful output in form of unified diff. $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' @@ -3099,10 +3042,10 @@ COMMANDS If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -3110,49 +3053,49 @@ COMMANDS https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. - o rewrite applies rules specified on command line or in the journal. + o rewrite applies rules specified on command line or in the journal. print --auto applies rules specified in the journal. roi roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - This command assumes that you have account(s) that hold nothing but + This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - Any transactions affecting balance of investment account(s) and not - originating from unrealized profit and loss account(s) are assumed to + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an ac- + At a minimum, you need to supply a query (which could be just an ac- count name) to select your investments with --inv, and another query to identify your profit and loss transactions with --pnl. - This command will compute and display the internalized rate of return - (IRR) and time-weighted rate of return (TWR) for your investments for - the time period requested. Both rates of return are annualized before + This command will compute and display the internalized rate of return + (IRR) and time-weighted rate of return (TWR) for your investments for + the time period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. Note, in some cases this report can fail, for these reasons: - o Error (NotBracketed): No solution for Internal Rate of Return (IRR). - Possible causes: IRR is huge (>1000000%), balance of investment be- + o Error (NotBracketed): No solution for Internal Rate of Return (IRR). + Possible causes: IRR is huge (>1000000%), balance of investment be- comes negative at some point in time. - o Error (SearchFailed): Failed to find solution for Internal Rate of + o Error (SearchFailed): Failed to find solution for Internal Rate of Return (IRR). Either search does not converge to a solution, or con- verges too slowly. @@ -3163,67 +3106,67 @@ COMMANDS More background: - "ROI" stands for "return on investment". Traditionally this was com- - puted as a difference between current value of investment and its ini- + "ROI" stands for "return on investment". Traditionally this was com- + puted as a difference between current value of investment and its ini- tial value, expressed in percentage of the initial value. However, this approach is only practical in simple cases, where invest- - ments receives no in-flows or out-flows of money, and where rate of + ments receives no in-flows or out-flows of money, and where rate of growth is fixed over time. For more complex scenarios you need differ- - ent ways to compute rate of return, and this command implements two of + ent ways to compute rate of return, and this command implements two of them: IRR and TWR. - Internal rate of return, or "IRR" (also called "money-weighted rate of - return") takes into account effects of in-flows and out-flows. + Internal rate of return, or "IRR" (also called "money-weighted rate of + return") takes into account effects of in-flows and out-flows. Naively, if you are withdrawing from your investment, your future gains - would be smaller (in absolute numbers), and will be a smaller percent- - age of your initial investment, and if you are adding to your invest- - ment, you will receive bigger absolute gains (but probably at the same - rate of return). IRR is a way to compute rate of return for each pe- - riod between in-flow or out-flow of money, and then combine them in a + would be smaller (in absolute numbers), and will be a smaller percent- + age of your initial investment, and if you are adding to your invest- + ment, you will receive bigger absolute gains (but probably at the same + rate of return). IRR is a way to compute rate of return for each pe- + riod between in-flow or out-flow of money, and then combine them in a way that gives you an annual rate of return that investment is expected to generate. - As mentioned before, in-flows and out-flows would be any cash that you - personally put in or withdraw, and for the "roi" command, these are - transactions that involve account(s) matching --inv argument and NOT + As mentioned before, in-flows and out-flows would be any cash that you + personally put in or withdraw, and for the "roi" command, these are + transactions that involve account(s) matching --inv argument and NOT involve account(s) matching --pnl argument. - Presumably, you will also record changes in the value of your invest- - ment, and balance them against "profit and loss" (or "unrealized + Presumably, you will also record changes in the value of your invest- + ment, and balance them against "profit and loss" (or "unrealized gains") account. Note that in order for IRR to compute the precise ef- - fect of your in-flows and out-flows on the rate of return, you will - need to record the value of your investement on or close to the days + fect of your in-flows and out-flows on the rate of return, you will + need to record the value of your investement on or close to the days when in- or out-flows occur. - Implementation of IRR in hledger should match the XIRR formula in Ex- + Implementation of IRR in hledger should match the XIRR formula in Ex- cel. - Second way to compute rate of return that roi command implements is + Second way to compute rate of return that roi command implements is called "time-weighted rate of return" or "TWR". Like IRR, it will also - break the history of your investment into periods between in-flows and + break the history of your investment into periods between in-flows and out-flows to compute rate of return per each period and then a compound rate of return. However, internal workings of TWR are quite different. - In technical terms, IRR uses the same approach as computation of net + In technical terms, IRR uses the same approach as computation of net present value, and tries to find a discount rate that makes net present value of all the cash flows of your investment to add up to zero. This - could be hard to wrap your head around, especially if you haven't done + could be hard to wrap your head around, especially if you haven't done discounted cash flow analysis before. - TWR represents your investment as an imaginary "unit fund" where in- - flows/ out-flows lead to buying or selling "units" of your investment + TWR represents your investment as an imaginary "unit fund" where in- + flows/ out-flows lead to buying or selling "units" of your investment and changes in its value change the value of "investment unit". Change - in "unit price" over the reporting period gives you rate of return of + in "unit price" over the reporting period gives you rate of return of your investment. - References: * Explanation of rate of return * Explanation of IRR * Ex- - planation of TWR * Examples of computing IRR and TWR and discussion of + References: * Explanation of rate of return * Explanation of IRR * Ex- + planation of TWR * Examples of computing IRR and TWR and discussion of the limitations of both metrics More examples: - Lets say that we found an investment in Snake Oil that is proising to + Lets say that we found an investment in Snake Oil that is proising to give us 10% annually: 2019-01-01 Investing in Snake Oil @@ -3234,7 +3177,7 @@ COMMANDS investment:snake oil = $110 equity:unrealized gains - For now, basic computation of the rate of return, as well as IRR and + For now, basic computation of the rate of return, as well as IRR and TWR, gives us the expected 10%: $ hledger roi -Y --inv investment --pnl "unrealized" @@ -3244,10 +3187,10 @@ COMMANDS | 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 110 | 10 || 10.00% | 10.00% | +---++------------+------------++---------------+----------+-------------+-----++--------+--------+ - However, lets say that shorty after investing in the Snake Oil we - started to have second thoughs, so we prompty withdrew $90, leaving - only $10 in. Before Christmas, though, we started to get the "fear of - mission out", so we put the $90 back in. So for most of the year, our + However, lets say that shorty after investing in the Snake Oil we + started to have second thoughs, so we prompty withdrew $90, leaving + only $10 in. Before Christmas, though, we started to get the "fear of + mission out", so we put the $90 back in. So for most of the year, our investment was just $10 dollars, and it gave us just $1 in growth: 2019-01-01 Investing in Snake Oil @@ -3278,10 +3221,10 @@ COMMANDS Here, IRR tells us that we made close to 10% on the $10 dollars that we had in the account most of the time. And TWR is ... just 1%? Why? - Based on the transactions in our journal, TWR "think" that we are buy- - ing back $90 worst of Snake Oil at the same price that it had at the + Based on the transactions in our journal, TWR "think" that we are buy- + ing back $90 worst of Snake Oil at the same price that it had at the beginning of they year, and then after that our $100 investment gets $1 - increase in value, or 1% of $100. Let's take a closer look at what is + increase in value, or 1% of $100. Let's take a closer look at what is happening here by asking for quarterly reports instead of annual: $ hledger roi -Q --inv investment --pnl "unrealized" @@ -3294,10 +3237,10 @@ COMMANDS | 4 || 2019-10-01 | 2019-12-31 || 10 | 90 | 101 | 1 || 37.80% | 4.03% | +---++------------+------------++---------------+----------+-------------+-----++--------+-------+ - Now both IRR and TWR are thrown off by the fact that all of the growth - for our investment happens in Q4 2019. This happes because IRR compu- + Now both IRR and TWR are thrown off by the fact that all of the growth + for our investment happens in Q4 2019. This happes because IRR compu- tation is still yielding 9.32% and TWR is still 1%, but this time these - are rates for three month period instead of twelve, so in order to get + are rates for three month period instead of twelve, so in order to get an annual rate they should be multiplied by four! Let's try to keep a better record of how Snake Oil grew in value: @@ -3342,10 +3285,10 @@ COMMANDS | 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 1.00% | +---++------------+------------++---------------+----------+-------------+------++--------+--------+ - Something is still wrong with TWR computation for Q4, and if you have - been paying attention you know what it is already: big $90 buy-back is - recorded prior to the only transaction that captures the change of - value of Snake Oil that happened in this time period. Lets combine + Something is still wrong with TWR computation for Q4, and if you have + been paying attention you know what it is already: big $90 buy-back is + recorded prior to the only transaction that captures the change of + value of Snake Oil that happened in this time period. Lets combine transactions from 30th and 31st of Dec into one: 2019-12-30 Fear of missing out and growth of Snake Oil @@ -3366,7 +3309,7 @@ COMMANDS | 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 9.57% | +---++------------+------------++---------------+----------+-------------+------++--------+--------+ - And for annual report, TWR now reports the exact profitability of our + And for annual report, TWR now reports the exact profitability of our investment: $ hledger roi -Y --inv investment --pnl "unrealized" @@ -3380,8 +3323,8 @@ COMMANDS stats Show some journal statistics. - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. Example: @@ -3399,35 +3342,35 @@ COMMANDS Commodities : 1 ($) Market prices : 12 ($) - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags tags - List the unique tag names used in the journal. With a TAGREGEX argu- + List the unique tag names used in the journal. With a TAGREGEX argu- ment, only tag names matching the regular expression (case insensitive) - are shown. With QUERY arguments, only transactions matching the query + are shown. With QUERY arguments, only transactions matching the query are considered. With the --values flag, the tags' unique values are listed instead. - With --parsed flag, all tags or values are shown in the order they are + With --parsed flag, all tags or values are shown in the order they are parsed from the input data, including duplicates. - With -E/--empty, any blank/empty values will also be shown, otherwise + With -E/--empty, any blank/empty values will also be shown, otherwise they are omitted. test test Run built-in unit tests. - This command runs the unit tests built in to hledger and hledger-lib, - printing the results on stdout. If any test fails, the exit code will + This command runs the unit tests built in to hledger and hledger-lib, + printing the results on stdout. If any test fails, the exit code will be non-zero. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! This command also accepts tasty test runner options, written after a -- @@ -3436,35 +3379,28 @@ COMMANDS $ hledger test -- -pData.Amount --color=never - 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). - Add-on commands - Any programs or scripts in your PATH named named hledger-SOMETHING will - also appear in the commands list (with a + mark). These are called - add-on commands. + About add-on commands + Add-on commands are programs or scripts in your PATH - These offical add-ons are maintained and released along with hledger: + o whose name starts with hledger- - o ui an efficient terminal interface for hledger (TUI) + o whose name ends with a recognised file extension: .bat,.com,.exe, + .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none - o web a simple web interface for hledger (WUI) + o and (on unix, mac) which are executable by the current user. - These add-ons are maintained separately: + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger library + functions that built-in commands use for command-line options, parsing + and reporting. Some experimental/example add-on scripts can be found + in the hledger repo's bin/ directory. - o iadd a more interactive alternative for the add command - - o interest generates interest transactions according to various schemes - - o stockquotes downloads market prices for your commodities from Alpha- - Vantage (experimental) - - Additional experimental add-ons, which may not be in a working state, - can be found in the bin/ directory in the hledger repo. - - Add-on command flags - In a hledger command line, add-on command flags must have a double dash - (--) preceding them. Eg you must write: + Note in a hledger command line, add-on command flags must have a double + dash (--) preceding them. Eg you must write: $ hledger web -- --serve @@ -3474,8 +3410,8 @@ COMMANDS (because the --serve flag belongs to hledger-web, not hledger). - The -h/--help and --version flags work without --, with their position - deciding which program they refer to. Eg hledger -h web shows + The -h/--help and --version flags work without --, with their position + deciding which program they refer to. Eg hledger -h web shows hledger's help, hledger web -h shows hledger-web's help. If you have any trouble with this, remember you can always run the add- @@ -3483,33 +3419,388 @@ COMMANDS $ hledger-web --serve - Making add-on commands - Add-on commands are programs or scripts in your PATH +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. - o whose name starts with hledger- + Getting 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 - o whose name ends with a recognised file extension: .bat,.com,.exe, - .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none + Find more docs, chat, mail list, reddit, issue tracker: + https://hledger.org#help-feedback - o and (on unix, mac) which are executable by the current user. + Constructing command lines + hledger has an extensive and powerful command line interface. We + strive to keep it simple and ergonomic, but you may run into one of the + confusing real world details described in OPTIONS, below. If that hap- + pens, here are some tips that may help: - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger library - functions that built-in commands use for command-line options, parsing - and reporting. + o command-specific options must go after the command (it's fine to put + all options there) (hledger CMD OPTS ARGS) + + o running add-on executables directly simplifies command line parsing + (hledger-ui OPTS ARGS) + + o enclose "problematic" args in single quotes + + o if needed, also add a backslash to hide regular expression metachar- + acters from the shell + + o to see how a misbehaving command is being parsed, add --debug=2. + + Starting a journal file + 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 -m '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 + + 2020.1.12 * farmers market + expenses:food $13 + assets:cash + + 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 -m 'txns' 2020.journal + + Reporting + Here are some basic reports. + + Show all transactions: + + $ hledger print + 2020-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + + 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 + $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 + 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 + + Show weekly posting counts as a bar chart: + + $ hledger activity -W + 2019-12-30 ***** + 2020-01-06 **** + 2020-01-13 **** + + Migrating to 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. + + If using version control, don't forget to git add the new file. ENVIRONMENT LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). - 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- + 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 + 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 @@ -3519,19 +3810,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. - NO_COLOR If this variable exists with any value, hledger will not use - ANSI color codes in terminal output. This overrides the + NO_COLOR If this variable exists with any value, hledger will not use + ANSI color codes in terminal output. This overrides the --color/--colour option. -FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). - LIMITATIONS The need to precede add-on command options with -- when invoked from hledger is awkward.