From 324dfaee49f5fb8c79fc7d88e94f5e4a6cf7b142 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Dec 2020 20:11:35 -0800 Subject: [PATCH] ;update manuals --- hledger-lib/hledger_csv.5 | 10 +- hledger-lib/hledger_csv.info | 452 ++++---- hledger-lib/hledger_csv.txt | 12 +- hledger-lib/hledger_journal.5 | 44 +- hledger-lib/hledger_journal.info | 445 ++++---- hledger-lib/hledger_journal.txt | 50 +- hledger-lib/hledger_timeclock.5 | 10 +- hledger-lib/hledger_timeclock.info | 11 +- hledger-lib/hledger_timeclock.txt | 12 +- hledger-lib/hledger_timedot.5 | 10 +- hledger-lib/hledger_timedot.info | 11 +- hledger-lib/hledger_timedot.txt | 12 +- hledger-ui/hledger-ui.1 | 107 +- hledger-ui/hledger-ui.info | 196 ++-- hledger-ui/hledger-ui.txt | 102 +- hledger-web/hledger-web.1 | 10 +- hledger-web/hledger-web.info | 43 +- hledger-web/hledger-web.txt | 12 +- hledger/hledger.1 | 620 +++-------- hledger/hledger.info | 1590 +++++++++++----------------- hledger/hledger.txt | 1122 ++++++++------------ 21 files changed, 2038 insertions(+), 2843 deletions(-) diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index 946d1d14a..7ca24ba44 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -1,12 +1,12 @@ .\"t -.TH "hledger_csv" "5" "December 2020" "hledger 1.20.99" "hledger User Manuals" +.TH "HLEDGER_CSV" "5" "December 2020" "hledger-lib-1.20.99 " "hledger User Manuals" .SH NAME .PP -CSV - how hledger reads CSV data, and the CSV rules file format +How hledger reads CSV data, and the CSV rules file format. .SH DESCRIPTION .PP hledger can read CSV files (Character Separated Value - usually comma, @@ -1295,6 +1295,6 @@ Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) + +hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index 634d707a1..e85038a28 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -3,10 +3,10 @@ This is hledger_csv.info, produced by makeinfo version 6.7 from stdin.  File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger_csv(5) hledger 1.20.99 -****************************** +hledger_csv(5) +************** -CSV - how hledger reads CSV data, and the CSV rules file format +How hledger reads CSV data, and the CSV rules file format. hledger can read CSV files (Character Separated Value - usually comma, semicolon, or tab) containing dated records as if they were @@ -60,37 +60,11 @@ below. * Menu: * EXAMPLES:: -* Basic:: -* Bank of Ireland:: -* Amazon:: -* Paypal:: * CSV RULES:: -* skip:: -* fields:: -* field assignment:: -* separator:: -* if block:: -* if table:: -* end:: -* date-format:: -* decimal-mark:: -* newest-first:: -* include:: -* balance-type:: * TIPS:: -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* Reading multiple CSV files:: -* Valid transactions:: -* Deduplicating importing:: -* Setting amounts:: -* Setting currency/commodity:: -* Referencing other fields:: -* How CSV rules are evaluated::  -File: hledger_csv.info, Node: EXAMPLES, Next: Basic, Prev: Top, Up: Top +File: hledger_csv.info, Node: EXAMPLES, Next: CSV RULES, Prev: Top, Up: Top 1 EXAMPLES ********** @@ -99,11 +73,18 @@ Here are some sample hledger CSV rules files. See also the full collection at: https://github.com/simonmichael/hledger/tree/master/examples/csv - -File: hledger_csv.info, Node: Basic, Next: Bank of Ireland, Prev: EXAMPLES, Up: Top +* Menu: -2 Basic -******* +* Basic:: +* Bank of Ireland:: +* Amazon:: +* Paypal:: + + +File: hledger_csv.info, Node: Basic, Next: Bank of Ireland, Up: EXAMPLES + +1.1 Basic +========= At minimum, the rules file must identify the date and amount fields, and often it also specifies the date format and how many header lines there @@ -125,10 +106,10 @@ $ hledger print -f basic.csv Default account names are chosen, since we didn't set them.  -File: hledger_csv.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: Top +File: hledger_csv.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: EXAMPLES -3 Bank of Ireland -***************** +1.2 Bank of Ireland +=================== Here's a CSV with two amount fields (Debit and Credit), and a balance field, which we can use to add balance assertions, which is not @@ -178,10 +159,10 @@ reading directly from CSV, but they will be checked if these entries are imported into a journal file.  -File: hledger_csv.info, Node: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: Top +File: hledger_csv.info, Node: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: EXAMPLES -4 Amazon -******** +1.3 Amazon +========== Here we convert amazon.com order history, and use an if block to generate a third posting if there's a fee. (In practice you'd probably @@ -236,10 +217,10 @@ $ hledger -f amazon-orders.csv print expenses:fees $1.00  -File: hledger_csv.info, Node: Paypal, Next: CSV RULES, Prev: Amazon, Up: Top +File: hledger_csv.info, Node: Paypal, Prev: Amazon, Up: EXAMPLES -5 Paypal -******** +1.4 Paypal +========== Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: @@ -390,19 +371,34 @@ $ hledger -f paypal-custom.csv print expenses:banking:paypal $0.59 ; business:  -File: hledger_csv.info, Node: CSV RULES, Next: skip, Prev: Paypal, Up: Top +File: hledger_csv.info, Node: CSV RULES, Next: TIPS, Prev: EXAMPLES, Up: Top -6 CSV RULES +2 CSV RULES *********** The following kinds of rule can appear in the rules file, in any order. Blank lines and lines beginning with '#' or ';' are ignored. - -File: hledger_csv.info, Node: skip, Next: fields, Prev: CSV RULES, Up: Top +* Menu: -7 'skip' -******** +* skip:: +* fields:: +* field assignment:: +* separator:: +* if block:: +* if table:: +* end:: +* date-format:: +* decimal-mark:: +* newest-first:: +* include:: +* balance-type:: + + +File: hledger_csv.info, Node: skip, Next: fields, Up: CSV RULES + +2.1 'skip' +========== skip N @@ -415,10 +411,10 @@ whenever your CSV data contains header lines. ignore certain CSV records (described below).  -File: hledger_csv.info, Node: fields, Next: field assignment, Prev: skip, Up: Top +File: hledger_csv.info, Node: fields, Next: field assignment, Prev: skip, Up: CSV RULES -8 'fields' -********** +2.2 'fields' +============ fields FIELDNAME1, FIELDNAME2, ... @@ -457,8 +453,8 @@ journal format.  File: hledger_csv.info, Node: Transaction field names, Next: Posting field names, Up: fields -8.1 Transaction field names -=========================== +2.2.1 Transaction field names +----------------------------- 'date', 'date2', 'status', 'code', 'description', 'comment' can be used to form the transaction's first line. @@ -466,8 +462,8 @@ to form the transaction's first line.  File: hledger_csv.info, Node: Posting field names, Prev: Transaction field names, Up: fields -8.2 Posting field names -======================= +2.2.2 Posting field names +------------------------- * Menu: @@ -480,8 +476,8 @@ File: hledger_csv.info, Node: Posting field names, Prev: Transaction field nam  File: hledger_csv.info, Node: account, Next: amount, Up: Posting field names -8.2.1 account -------------- +2.2.2.1 account +............... 'accountN', where N is 1 to 99, causes a posting to be generated, with that account name. @@ -498,8 +494,8 @@ or "income:unknown").  File: hledger_csv.info, Node: amount, Next: currency, Prev: account, Up: Posting field names -8.2.2 amount ------------- +2.2.2.2 amount +.............. 'amountN' sets posting N's amount. If the CSV uses separate fields for inflows and outflows, you can use 'amountN-in' and 'amountN-out' @@ -525,8 +521,8 @@ avoiding conflicts.  File: hledger_csv.info, Node: currency, Next: balance, Prev: amount, Up: Posting field names -8.2.3 currency --------------- +2.2.2.3 currency +................ If the CSV has the currency symbol in a separate field (ie, not part of the amount field), you can use 'currencyN' to prepend it to posting N's @@ -535,8 +531,8 @@ amount. Or, 'currency' with no number affects all postings.  File: hledger_csv.info, Node: balance, Next: comment, Prev: currency, Up: Posting field names -8.2.4 balance -------------- +2.2.2.4 balance +............... 'balanceN' sets a balance assertion amount (or if the posting amount is left empty, a balance assignment) on posting N. @@ -550,8 +546,8 @@ is equivalent to 'balance1'.  File: hledger_csv.info, Node: comment, Prev: balance, Up: Posting field names -8.2.5 comment -------------- +2.2.2.5 comment +............... Finally, 'commentN' sets a comment on the Nth posting. Comments can also contain tags, as usual. @@ -559,10 +555,10 @@ also contain tags, as usual. See TIPS below for more about setting amounts and currency.  -File: hledger_csv.info, Node: field assignment, Next: separator, Prev: fields, Up: Top +File: hledger_csv.info, Node: field assignment, Next: separator, Prev: fields, Up: CSV RULES -9 field assignment -****************** +2.3 field assignment +==================== HLEDGERFIELDNAME FIELDVALUE @@ -584,10 +580,10 @@ becomes '1' when interpolated) (#1051). See TIPS below for more about referencing other fields.  -File: hledger_csv.info, Node: separator, Next: if block, Prev: field assignment, Up: Top +File: hledger_csv.info, Node: separator, Next: if block, Prev: field assignment, Up: CSV RULES -10 'separator' -************** +2.4 'separator' +=============== You can use the 'separator' rule to read other kinds of character-separated data. The argument is any single separator @@ -609,10 +605,10 @@ separator TAB inferred automatically, and you won't need this rule.  -File: hledger_csv.info, Node: if block, Next: if table, Prev: separator, Up: Top +File: hledger_csv.info, Node: if block, Next: if table, Prev: separator, Up: CSV RULES -11 'if' block -************* +2.5 'if' block +============== if MATCHER RULE @@ -639,8 +635,8 @@ descriptions.  File: hledger_csv.info, Node: Matching the whole record, Next: Matching individual fields, Up: if block -11.1 Matching the whole record -============================== +2.5.1 Matching the whole record +------------------------------- Each MATCHER can be a record matcher, which looks like this: @@ -662,8 +658,8 @@ actually see '2020-01-01,Acme, Inc., 1,000').  File: hledger_csv.info, Node: Matching individual fields, Next: Combining matchers, Prev: Matching the whole record, Up: if block -11.2 Matching individual fields -=============================== +2.5.2 Matching individual fields +-------------------------------- Or, MATCHER can be a field matcher, like this: @@ -676,8 +672,8 @@ is a percent sign followed by the field's name or column number, like  File: hledger_csv.info, Node: Combining matchers, Next: Rules applied on successful match, Prev: Matching individual fields, Up: if block -11.3 Combining matchers -======================= +2.5.3 Combining matchers +------------------------ A single matcher can be written on the same line as the "if"; or multiple matchers can be written on the following lines, non-indented. @@ -693,8 +689,8 @@ MATCHER  File: hledger_csv.info, Node: Rules applied on successful match, Prev: Combining matchers, Up: if block -11.4 Rules applied on successful match -====================================== +2.5.4 Rules applied on successful match +--------------------------------------- After the patterns there should be one or more rules to apply, all indented by at least one space. Three kinds of rule are allowed in @@ -719,10 +715,10 @@ banking thru software comment XXX deductible ? check it  -File: hledger_csv.info, Node: if table, Next: end, Prev: if block, Up: Top +File: hledger_csv.info, Node: if table, Next: end, Prev: if block, Up: CSV RULES -12 'if' table -************* +2.6 'if' table +============== if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn MATCHER1,VALUE11,VALUE12,...,VALUE1n @@ -780,10 +776,10 @@ atm transaction fee,expenses:business:banking,deductible? check it 2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out  -File: hledger_csv.info, Node: end, Next: date-format, Prev: if table, Up: Top +File: hledger_csv.info, Node: end, Next: date-format, Prev: if table, Up: CSV RULES -13 'end' -******** +2.7 'end' +========= This rule can be used inside if blocks (only), to make hledger stop reading this CSV file and move on to the next input file, or to command @@ -794,10 +790,10 @@ if ,,,, end  -File: hledger_csv.info, Node: date-format, Next: decimal-mark, Prev: end, Up: Top +File: hledger_csv.info, Node: date-format, Next: decimal-mark, Prev: end, Up: CSV RULES -14 'date-format' -**************** +2.8 'date-format' +================= date-format DATEFMT @@ -825,10 +821,10 @@ date-format %-m/%-d/%Y %l:%M %p some other junk https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime  -File: hledger_csv.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: Top +File: hledger_csv.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: CSV RULES -15 'decimal-mark' -***************** +2.9 'decimal-mark' +================== decimal-mark . @@ -843,10 +839,10 @@ should declare the decimal mark explicitly with this rule, to avoid misparsed numbers.  -File: hledger_csv.info, Node: newest-first, Next: include, Prev: decimal-mark, Up: Top +File: hledger_csv.info, Node: newest-first, Next: include, Prev: decimal-mark, Up: CSV RULES -16 'newest-first' -***************** +2.10 'newest-first' +=================== hledger always sorts the generated transactions by date. Transactions on the same date should appear in the same order as their CSV records, @@ -865,10 +861,10 @@ oldest first or newest first. But if all of the following are true: newest-first  -File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: Top +File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV RULES -17 'include' -************ +2.11 'include' +============== include RULESFILE @@ -879,19 +875,19 @@ several rules files, eg: # someaccount.csv.rules -# someaccount-specific rules +## someaccount-specific rules fields date,description,amount account1 assets:someaccount account2 expenses:misc -# common rules +## common rules include categorisation.rules  -File: hledger_csv.info, Node: balance-type, Next: TIPS, Prev: include, Up: Top +File: hledger_csv.info, Node: balance-type, Prev: include, Up: CSV RULES -18 'balance-type' -***************** +2.12 'balance-type' +=================== Balance assertions generated by assigning to balanceN are of the simple '=' type by default, which is a single-commodity, subaccount-excluding @@ -911,16 +907,29 @@ balance-type ==* ==* multi commodity, include subaccounts  -File: hledger_csv.info, Node: TIPS, Next: Rapid feedback, Prev: balance-type, Up: Top +File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top -19 TIPS -******* +3 TIPS +****** + +* Menu: + +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* Reading multiple CSV files:: +* Valid transactions:: +* Deduplicating importing:: +* Setting amounts:: +* Setting currency/commodity:: +* Referencing other fields:: +* How CSV rules are evaluated::  -File: hledger_csv.info, Node: Rapid feedback, Next: Valid CSV, Prev: TIPS, Up: Top +File: hledger_csv.info, Node: Rapid feedback, Next: Valid CSV, Up: TIPS -20 Rapid feedback -***************** +3.1 Rapid feedback +================== It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from @@ -934,10 +943,10 @@ a separator each time the command re-runs, making it easier to read the output.  -File: hledger_csv.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Top +File: hledger_csv.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: TIPS -21 Valid CSV -************ +3.2 Valid CSV +============= hledger accepts CSV conforming to RFC 4180. When CSV values are enclosed in quotes, note: @@ -946,10 +955,10 @@ enclosed in quotes, note: * spaces outside the quotes are not allowed  -File: hledger_csv.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: Top +File: hledger_csv.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: TIPS -22 File Extension -***************** +3.3 File Extension +================== To help hledger identify the format and show the right error messages, CSV/SSV/TSV files should normally be named with a '.csv', '.ssv' or @@ -966,10 +975,10 @@ $ cat foo | hledger -f ssv:- foo See also: Input files in the hledger manual.  -File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: Top +File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: TIPS -23 Reading multiple CSV files -***************************** +3.4 Reading multiple CSV files +============================== If you use multiple '-f' options to read multiple CSV files at once, hledger will look for a correspondingly-named rules file for each CSV @@ -977,10 +986,10 @@ file. But if you use the '--rules-file' option, that rules file will be used for all the CSV files.  -File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Top +File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: TIPS -24 Valid transactions -********************* +3.5 Valid transactions +====================== After reading a CSV file, hledger post-processes and validates the generated journal entries as it would for a journal file - balancing @@ -996,10 +1005,10 @@ assertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print  -File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Top +File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: TIPS -25 Deduplicating, importing -*************************** +3.6 Deduplicating, importing +============================ When you download a CSV file periodically, eg to get your latest bank transactions, the new file may overlap with the old one, containing some @@ -1026,10 +1035,10 @@ CSV data. See: * https://plaintextaccounting.org -> data import/conversion  -File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: Top +File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: TIPS -26 Setting amounts -****************** +3.7 Setting amounts +=================== A posting amount can be set in one of these ways: @@ -1055,10 +1064,10 @@ A posting amount can be set in one of these ways: * If an amount value begins with a plus sign, that will be removed  -File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: Top +File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: TIPS -27 Setting currency/commodity -***************************** +3.8 Setting currency/commodity +============================== If the currency/commodity symbol is included in the CSV's amount field(s): @@ -1103,10 +1112,10 @@ amount %amt %cur that would trigger the prepending effect, which we don't want here.  -File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: Top +File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS -28 Referencing other fields -*************************** +3.9 Referencing other fields +============================ In field assignments, you can interpolate only CSV fields, not hledger fields. In the example below, there's both a CSV field and a hledger @@ -1140,10 +1149,10 @@ if something comment C  -File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: Top +File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: TIPS -29 How CSV rules are evaluated -****************************** +3.10 How CSV rules are evaluated +================================ Here's how to think of CSV rules being evaluated (if you really need to). First, @@ -1183,90 +1192,85 @@ command the user specified.  Tag Table: Node: Top72 -Node: EXAMPLES3259 -Ref: #examples3361 -Node: Basic3507 -Ref: #basic3615 -Node: Bank of Ireland4157 -Ref: #bank-of-ireland4283 -Node: Amazon5745 -Ref: #amazon5854 -Node: Paypal7573 -Ref: #paypal7676 -Node: CSV RULES15320 -Ref: #csv-rules15427 -Node: skip15561 -Ref: #skip15662 -Node: fields16037 -Ref: #fields16149 -Node: Transaction field names17314 -Ref: #transaction-field-names17470 -Node: Posting field names17581 -Ref: #posting-field-names17729 -Node: account17799 -Ref: #account17911 -Node: amount18448 -Ref: #amount18575 -Node: currency19682 -Ref: #currency19813 -Node: balance20019 -Ref: #balance20149 -Node: comment20466 -Ref: #comment20579 -Node: field assignment20742 -Ref: #field-assignment20875 -Node: separator21693 -Ref: #separator21820 -Node: if block22360 -Ref: #if-block22477 -Node: Matching the whole record22878 -Ref: #matching-the-whole-record23051 -Node: Matching individual fields23855 -Ref: #matching-individual-fields24057 -Node: Combining matchers24281 -Ref: #combining-matchers24475 -Node: Rules applied on successful match24788 -Ref: #rules-applied-on-successful-match24977 -Node: if table25631 -Ref: #if-table25742 -Node: end27480 -Ref: #end27584 -Node: date-format27808 -Ref: #date-format27932 -Node: decimal-mark28681 -Ref: #decimal-mark28816 -Node: newest-first29155 -Ref: #newest-first29286 -Node: include29969 -Ref: #include30090 -Node: balance-type30532 -Ref: #balance-type30655 -Node: TIPS31355 -Ref: #tips31465 -Node: Rapid feedback31465 -Ref: #rapid-feedback31592 -Node: Valid CSV32052 -Ref: #valid-csv32179 -Node: File Extension32371 -Ref: #file-extension32520 -Node: Reading multiple CSV files32949 -Ref: #reading-multiple-csv-files33131 -Node: Valid transactions33372 -Ref: #valid-transactions33547 -Node: Deduplicating importing34175 -Ref: #deduplicating-importing34351 -Node: Setting amounts35384 -Ref: #setting-amounts35550 -Node: Setting currency/commodity36537 -Ref: #setting-currencycommodity36726 -Node: Referencing other fields37900 -Ref: #referencing-other-fields38097 -Node: How CSV rules are evaluated38994 -Ref: #how-csv-rules-are-evaluated39162 +Node: EXAMPLES2756 +Ref: #examples2862 +Node: Basic3070 +Ref: #basic3170 +Node: Bank of Ireland3712 +Ref: #bank-of-ireland3847 +Node: Amazon5309 +Ref: #amazon5427 +Node: Paypal7146 +Ref: #paypal7240 +Node: CSV RULES14884 +Ref: #csv-rules14993 +Node: skip15305 +Ref: #skip15398 +Node: fields15773 +Ref: #fields15895 +Node: Transaction field names17060 +Ref: #transaction-field-names17220 +Node: Posting field names17331 +Ref: #posting-field-names17483 +Node: account17553 +Ref: #account17669 +Node: amount18206 +Ref: #amount18337 +Node: currency19444 +Ref: #currency19579 +Node: balance19785 +Ref: #balance19919 +Node: comment20236 +Ref: #comment20353 +Node: field assignment20516 +Ref: #field-assignment20659 +Node: separator21477 +Ref: #separator21612 +Node: if block22152 +Ref: #if-block22277 +Node: Matching the whole record22678 +Ref: #matching-the-whole-record22853 +Node: Matching individual fields23657 +Ref: #matching-individual-fields23861 +Node: Combining matchers24085 +Ref: #combining-matchers24281 +Node: Rules applied on successful match24594 +Ref: #rules-applied-on-successful-match24785 +Node: if table25439 +Ref: #if-table25558 +Node: end27296 +Ref: #end27408 +Node: date-format27632 +Ref: #date-format27764 +Node: decimal-mark28513 +Ref: #decimal-mark28656 +Node: newest-first28995 +Ref: #newest-first29136 +Node: include29819 +Ref: #include29950 +Node: balance-type30394 +Ref: #balance-type30514 +Node: TIPS31214 +Ref: #tips31296 +Node: Rapid feedback31552 +Ref: #rapid-feedback31669 +Node: Valid CSV32129 +Ref: #valid-csv32259 +Node: File Extension32451 +Ref: #file-extension32603 +Node: Reading multiple CSV files33032 +Ref: #reading-multiple-csv-files33217 +Node: Valid transactions33458 +Ref: #valid-transactions33636 +Node: Deduplicating importing34264 +Ref: #deduplicating-importing34443 +Node: Setting amounts35476 +Ref: #setting-amounts35645 +Node: Setting currency/commodity36632 +Ref: #setting-currencycommodity36824 +Node: Referencing other fields37998 +Ref: #referencing-other-fields38198 +Node: How CSV rules are evaluated39095 +Ref: #how-csv-rules-are-evaluated39268  End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index f4e12fb2e..42151fd3e 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -1,10 +1,10 @@ -hledger_csv(5) hledger User Manuals hledger_csv(5) +HLEDGER_CSV(5) hledger User Manuals HLEDGER_CSV(5) NAME - CSV - how hledger reads CSV data, and the CSV rules file format + How hledger reads CSV data, and the CSV rules file format. DESCRIPTION hledger can read CSV files (Character Separated Value - usually comma, @@ -951,9 +951,11 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), - hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time- + dot(5) -hledger 1.20.99 December 2020 hledger_csv(5) +hledger-lib-1.20.99 December 2020 HLEDGER_CSV(5) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 70df45364..aa052a98f 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1,13 +1,12 @@ .\"t -.TH "hledger_journal" "5" "December 2020" "hledger 1.20.99" "hledger User Manuals" +.TH "HLEDGER_JOURNAL" "5" "December 2020" "hledger-lib-1.20.99 " "hledger User Manuals" .SH NAME .PP -Journal - hledger\[aq]s default file format, representing a General -Journal +hledger\[aq]s default file format, representing a General Journal. .SH DESCRIPTION .PP hledger\[aq]s usual data source is a plain text file containing journal @@ -34,7 +33,6 @@ Editor addons such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and hledger-vscode for Visual Studio Code, make this easier, adding colour, formatting, tab completion, and useful commands. See Editor configuration at hledger.org for the full list. -.SH FILE FORMAT .PP Here\[aq]s a description of each part of the file format (and hledger\[aq]s data model). @@ -42,7 +40,7 @@ These are mostly in the order you\[aq]ll use them, but in some cases related concepts have been grouped together for easy reference, or linked before they are introduced, so feel free to skip over anything that looks unnecessary right now. -.SS Transactions +.SH TRANSACTIONS .PP Transactions are the main unit of information in a journal file. They represent events, typically a movement of some quantity of @@ -75,7 +73,7 @@ Here\[aq]s a simple journal file containing one transaction: income:salary $-1 \f[R] .fi -.SS Dates +.SH DATES .SS Simple dates .PP Dates in the journal file use \f[I]simple dates\f[R] format: @@ -181,7 +179,7 @@ hledger will attempt to parse any square-bracketed sequence of the \f[C]0123456789/-.=\f[R] characters in this way. With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. -.SS Status +.SH STATUS .PP Transactions, or individual postings within a transaction, can have a status mark, which is a single character before the transaction @@ -268,7 +266,7 @@ With this scheme, you would use \f[C]-PC\f[R] to see the current balance at your bank, \f[C]-U\f[R] to see things which will probably hit your bank soon (like uncashed checks), and no flags to see the most up-to-date state of your finances. -.SS Description +.SH DESCRIPTION .PP A transaction\[aq]s description is the rest of the line following the date and status mark (or until a comment begins). @@ -283,7 +281,7 @@ payee/payer name on the left (up to the first \f[C]|\f[R]) and an additional note field on the right (after the first \f[C]|\f[R]). This may be worthwhile if you need to do more precise querying and pivoting by payee or by note. -.SS Comments +.SH COMMENTS .PP Lines in the journal beginning with a semicolon (\f[C];\f[R]) or hash (\f[C]#\f[R]) or star (\f[C]*\f[R]) are comments, and will be ignored. @@ -324,7 +322,7 @@ end comment .PP You can also comment larger regions of a file using \f[C]comment\f[R] and \f[C]end comment\f[R] directives. -.SS Tags +.SH TAGS .PP Tags are a way to add extra labels or labelled data to postings and transactions, which you can then search or pivot on. @@ -383,7 +381,7 @@ plus \f[C]posting-tag\f[R]): .PP Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag values are simple strings. -.SS Postings +.SH POSTINGS .PP A posting is an addition of some amount to, or removal of some amount from, an account. @@ -454,7 +452,7 @@ Ordinary non-parenthesised, non-bracketed postings are called \f[I]real postings\f[R]. You can exclude virtual postings from reports with the \f[C]-R/--real\f[R] flag or \f[C]real:1\f[R] query. -.SS Account names +.SH ACCOUNT NAMES .PP Account names typically have several parts separated by a full colon, from which hledger derives a hierarchical chart of accounts. @@ -468,7 +466,7 @@ Because of this, they must always be followed by \f[B]two or more spaces\f[R] (or newline). .PP Account names can be aliased. -.SS Amounts +.SH AMOUNTS .PP After the account name, there is usually an amount. (Important: between account name and amount, there must be \f[B]two or @@ -637,7 +635,7 @@ Note, hledger uses banker\[aq]s rounding: it rounds to the nearest even number, eg 0.5 displayed with zero decimal places is \[dq]0\[dq]). (Guaranteed since hledger 1.17.1; in older versions this could vary if hledger was built with Decimal < 0.5.1.) -.SS Transaction prices +.SH TRANSACTION PRICES .PP Within a transaction, you can note an amount\[aq]s price in another commodity. @@ -734,7 +732,7 @@ $ hledger bal -N --flat -B \[Eu]100 assets:euros \f[R] .fi -.SS Lot prices and lot dates +.SH LOT PRICES, LOT DATES .PP Ledger allows another kind of price, lot price (four variants: \f[C]{UNITPRICE}\f[R], \f[C]{{TOTALPRICE}}\f[R], @@ -745,7 +743,7 @@ hledger will parse these, for compatibility with Ledger journals, but currently ignores them. A transaction price, lot price and/or lot date may appear in any order, after the posting amount and before the balance assertion if any. -.SS Balance assertions +.SH BALANCE ASSERTIONS .PP hledger supports Ledger-style balance assertions in journal files. These look like, for example, \f[C]= EXPECTEDBALANCE\f[R] following a @@ -901,7 +899,7 @@ always what is shown by reports. Eg a commodity directive may limit the display precision, but this will not affect balance assertions. Balance assertion failure messages show exact amounts. -.SS Balance assignments +.SH BALANCE ASSIGNMENTS .PP Ledger-style balance assignments are also supported. These are like balance assertions, but with no posting amount on the @@ -958,7 +956,7 @@ $ hledger print --explicit (a) $1 \[at] \[Eu]2 = $1 \[at] \[Eu]2 \f[R] .fi -.SS Directives +.SH DIRECTIVES .PP A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. @@ -1850,7 +1848,7 @@ It does not affect account names being entered via hledger add or hledger-web. If account aliases are present, they are applied after the default parent account. -.SS Periodic transactions +.SH PERIODIC TRANSACTIONS .PP Periodic transaction rules describe transactions that recur. They allow hledger to generate temporary future transactions to help @@ -2004,7 +2002,7 @@ Goals and actual performance can then be compared in budget reports. .PP See also: Budgeting and Forecasting. .PP -.SS Auto postings +.SH AUTO POSTINGS .PP \[dq]Automated postings\[dq] or \[dq]auto postings\[dq] are extra postings which get added automatically to transactions which match @@ -2150,6 +2148,6 @@ Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) + +hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 236561a5c..75a33e160 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -2,12 +2,12 @@ This is hledger_journal.info, produced by makeinfo version 6.7 from stdin.  -File: hledger_journal.info, Node: Top, Next: Transactions, Up: (dir) +File: hledger_journal.info, Node: Top, Next: TRANSACTIONS, Up: (dir) -hledger_journal(5) hledger 1.20.99 -********************************** +hledger_journal(5) +****************** -Journal - hledger's default file format, representing a General Journal +hledger's default file format, representing a General Journal. hledger's usual data source is a plain text file containing journal entries in hledger journal format. This file represents a standard @@ -40,27 +40,27 @@ that looks unnecessary right now. * Menu: -* Transactions:: -* Dates:: -* Status:: -* Description:: -* Comments:: -* Tags:: -* Postings:: -* Account names:: -* Amounts:: -* Transaction prices:: -* Lot prices and lot dates:: -* Balance assertions:: -* Balance assignments:: -* Directives:: -* Periodic transactions:: -* Auto postings:: +* TRANSACTIONS:: +* DATES:: +* STATUS:: +* DESCRIPTION:: +* COMMENTS:: +* TAGS:: +* POSTINGS:: +* ACCOUNT NAMES:: +* AMOUNTS:: +* TRANSACTION PRICES:: +* LOT PRICES LOT DATES:: +* BALANCE ASSERTIONS:: +* BALANCE ASSIGNMENTS:: +* DIRECTIVES:: +* PERIODIC TRANSACTIONS:: +* AUTO POSTINGS::  -File: hledger_journal.info, Node: Transactions, Next: Dates, Prev: Top, Up: Top +File: hledger_journal.info, Node: TRANSACTIONS, Next: DATES, Prev: Top, Up: Top -1 Transactions +1 TRANSACTIONS ************** Transactions are the main unit of information in a journal file. They @@ -87,9 +87,9 @@ optional fields, separated by spaces: income:salary $-1  -File: hledger_journal.info, Node: Dates, Next: Status, Prev: Transactions, Up: Top +File: hledger_journal.info, Node: DATES, Next: STATUS, Prev: TRANSACTIONS, Up: Top -2 Dates +2 DATES ******* * Menu: @@ -99,7 +99,7 @@ File: hledger_journal.info, Node: Dates, Next: Status, Prev: Transactions, U * Posting dates::  -File: hledger_journal.info, Node: Simple dates, Next: Secondary dates, Up: Dates +File: hledger_journal.info, Node: Simple dates, Next: Secondary dates, Up: DATES 2.1 Simple dates ================ @@ -115,7 +115,7 @@ or the current date when the command is run. Some examples: dates documented in the hledger manual.)  -File: hledger_journal.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates +File: hledger_journal.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: DATES 2.2 Secondary dates =================== @@ -151,7 +151,7 @@ $ hledger register checking --date2 2010-02-19 movie ticket assets:checking $-10 $-10  -File: hledger_journal.info, Node: Posting dates, Prev: Secondary dates, Up: Dates +File: hledger_journal.info, Node: Posting dates, Prev: Secondary dates, Up: DATES 2.3 Posting dates ================= @@ -186,9 +186,9 @@ characters in this way. With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE.  -File: hledger_journal.info, Node: Status, Next: Description, Prev: Dates, Up: Top +File: hledger_journal.info, Node: STATUS, Next: DESCRIPTION, Prev: DATES, Up: Top -3 Status +3 STATUS ******** Transactions, or individual postings within a transaction, can have a @@ -236,9 +236,9 @@ your bank, '-U' to see things which will probably hit your bank soon your finances.  -File: hledger_journal.info, Node: Description, Next: Comments, Prev: Status, Up: Top +File: hledger_journal.info, Node: DESCRIPTION, Next: COMMENTS, Prev: STATUS, Up: Top -4 Description +4 DESCRIPTION ************* A transaction's description is the rest of the line following the date @@ -252,7 +252,7 @@ comments. * Payee and note::  -File: hledger_journal.info, Node: Payee and note, Up: Description +File: hledger_journal.info, Node: Payee and note, Up: DESCRIPTION 4.1 Payee and note ================== @@ -264,9 +264,9 @@ the left (up to the first '|') and an additional note field on the right precise querying and pivoting by payee or by note.  -File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Description, Up: Top +File: hledger_journal.info, Node: COMMENTS, Next: TAGS, Prev: DESCRIPTION, Up: Top -5 Comments +5 COMMENTS ********** Lines in the journal beginning with a semicolon (';') or hash ('#') or @@ -304,9 +304,9 @@ end comment 'end comment' directives.  -File: hledger_journal.info, Node: Tags, Next: Postings, Prev: Comments, Up: Top +File: hledger_journal.info, Node: TAGS, Next: POSTINGS, Prev: COMMENTS, Up: Top -6 Tags +6 TAGS ****** Tags are a way to add extra labels or labelled data to postings and @@ -347,9 +347,9 @@ example, the following transaction has three tags ('A', 'TAG2', are simple strings.  -File: hledger_journal.info, Node: Postings, Next: Account names, Prev: Tags, Up: Top +File: hledger_journal.info, Node: POSTINGS, Next: ACCOUNT NAMES, Prev: TAGS, Up: Top -7 Postings +7 POSTINGS ********** A posting is an addition of some amount to, or removal of some amount @@ -379,7 +379,7 @@ the amount, the amount will be considered part of the account name. * Virtual postings::  -File: hledger_journal.info, Node: Virtual postings, Up: Postings +File: hledger_journal.info, Node: Virtual postings, Up: POSTINGS 7.1 Virtual postings ==================== @@ -414,9 +414,9 @@ postings_. You can exclude virtual postings from reports with the '-R/--real' flag or 'real:1' query.  -File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Top +File: hledger_journal.info, Node: ACCOUNT NAMES, Next: AMOUNTS, Prev: POSTINGS, Up: Top -8 Account names +8 ACCOUNT NAMES *************** Account names typically have several parts separated by a full colon, @@ -432,9 +432,9 @@ more spaces* (or newline). Account names can be aliased.  -File: hledger_journal.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: Top +File: hledger_journal.info, Node: AMOUNTS, Next: TRANSACTION PRICES, Prev: ACCOUNT NAMES, Up: Top -9 Amounts +9 AMOUNTS ********* After the account name, there is usually an amount. (Important: between @@ -488,7 +488,7 @@ EUR 1E3 * Rounding::  -File: hledger_journal.info, Node: Digit group marks, Next: Commodity display style, Up: Amounts +File: hledger_journal.info, Node: Digit group marks, Next: Commodity display style, Up: AMOUNTS 9.1 Digit group marks ===================== @@ -521,7 +521,7 @@ commodity INR 9,99,99,999.00 commodity 1 000 000.9455  -File: hledger_journal.info, Node: Commodity display style, Next: Rounding, Prev: Digit group marks, Up: Amounts +File: hledger_journal.info, Node: Commodity display style, Next: Rounding, Prev: Digit group marks, Up: AMOUNTS 9.2 Commodity display style =========================== @@ -566,7 +566,7 @@ many decimal places), use a commodity directive to set your preferred style.  -File: hledger_journal.info, Node: Rounding, Prev: Commodity display style, Up: Amounts +File: hledger_journal.info, Node: Rounding, Prev: Commodity display style, Up: AMOUNTS 9.3 Rounding ============ @@ -579,9 +579,9 @@ places is "0"). (Guaranteed since hledger 1.17.1; in older versions this could vary if hledger was built with Decimal < 0.5.1.)  -File: hledger_journal.info, Node: Transaction prices, Next: Lot prices and lot dates, Prev: Amounts, Up: Top +File: hledger_journal.info, Node: TRANSACTION PRICES, Next: LOT PRICES LOT DATES, Prev: AMOUNTS, Up: Top -10 Transaction prices +10 TRANSACTION PRICES ********************* Within a transaction, you can note an amount's price in another @@ -646,10 +646,10 @@ $ hledger bal -N --flat -B €100 assets:euros  -File: hledger_journal.info, Node: Lot prices and lot dates, Next: Balance assertions, Prev: Transaction prices, Up: Top +File: hledger_journal.info, Node: LOT PRICES LOT DATES, Next: BALANCE ASSERTIONS, Prev: TRANSACTION PRICES, Up: Top -11 Lot prices and lot dates -*************************** +11 LOT PRICES, LOT DATES +************************ Ledger allows another kind of price, lot price (four variants: '{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}', @@ -661,9 +661,9 @@ may appear in any order, after the posting amount and before the balance assertion if any.  -File: hledger_journal.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices and lot dates, Up: Top +File: hledger_journal.info, Node: BALANCE ASSERTIONS, Next: BALANCE ASSIGNMENTS, Prev: LOT PRICES LOT DATES, Up: Top -12 Balance assertions +12 BALANCE ASSERTIONS ********************* hledger supports Ledger-style balance assertions in journal files. @@ -699,7 +699,7 @@ does not disable balance assignments, below). * Assertions and precision::  -File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance assertions +File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: BALANCE ASSERTIONS 12.1 Assertions and ordering ============================ @@ -718,7 +718,7 @@ control over the order of postings and assertions within a day, so you can assert intra-day balances.  -File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance assertions +File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: BALANCE ASSERTIONS 12.2 Assertions and included files ================================== @@ -730,7 +730,7 @@ and you also want to assert the account's balance on the same day, you'll have to put the assertion in the right file.  -File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance assertions +File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: BALANCE ASSERTIONS 12.3 Assertions and multiple -f options ======================================= @@ -739,7 +739,7 @@ Balance assertions don't work well across files specified with multiple -f options. Use include or concatenate the files instead.  -File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: Balance assertions +File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: BALANCE ASSERTIONS 12.4 Assertions and commodities =============================== @@ -787,7 +787,7 @@ commodity into its own subaccount: a:euro 0 == 1€  -File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions +File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: BALANCE ASSERTIONS 12.5 Assertions and prices ========================== @@ -805,7 +805,7 @@ to generate balance assertions with prices), and because balance _assignments_ do use them (see below).  -File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions +File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: BALANCE ASSERTIONS 12.6 Assertions and subaccounts =============================== @@ -822,7 +822,7 @@ eg: checking 1 ==* 11  -File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance assertions +File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: BALANCE ASSERTIONS 12.7 Assertions and virtual postings ==================================== @@ -832,7 +832,7 @@ virtual. They are not affected by the '--real/-R' flag or 'real:' query.  -File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions +File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: BALANCE ASSERTIONS 12.8 Assertions and precision ============================= @@ -843,9 +843,9 @@ display precision, but this will not affect balance assertions. Balance assertion failure messages show exact amounts.  -File: hledger_journal.info, Node: Balance assignments, Next: Directives, Prev: Balance assertions, Up: Top +File: hledger_journal.info, Node: BALANCE ASSIGNMENTS, Next: DIRECTIVES, Prev: BALANCE ASSERTIONS, Up: Top -13 Balance assignments +13 BALANCE ASSIGNMENTS ********************** Ledger-style balance assignments are also supported. These are like @@ -880,7 +880,7 @@ hledger or do the calculations yourself, instead of just reading it. * Balance assignments and prices::  -File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance assignments +File: hledger_journal.info, Node: Balance assignments and prices, Up: BALANCE ASSIGNMENTS 13.1 Balance assignments and prices =================================== @@ -896,9 +896,9 @@ $ hledger print --explicit (a) $1 @ €2 = $1 @ €2  -File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Balance assignments, Up: Top +File: hledger_journal.info, Node: DIRECTIVES, Next: PERIODIC TRANSACTIONS, Prev: BALANCE ASSIGNMENTS, Up: Top -14 Directives +14 DIRECTIVES ************* A directive is a line in the journal beginning with a special keyword, @@ -997,7 +997,7 @@ they affect, and whether they are focussed on input (parsing) or output * Default parent account::  -File: hledger_journal.info, Node: Directives and multiple files, Next: Comment blocks, Up: Directives +File: hledger_journal.info, Node: Directives and multiple files, Next: Comment blocks, Up: DIRECTIVES 14.1 Directives and multiple files ================================== @@ -1017,7 +1017,7 @@ files. directives do not affect parent or sibling files (see below).  -File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: Directives +File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: DIRECTIVES 14.2 Comment blocks =================== @@ -1027,7 +1027,7 @@ and a line containing just 'end comment' (or the end of the current file) ends it. See also comments.  -File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives +File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: DIRECTIVES 14.3 Including other files ========================== @@ -1058,7 +1058,7 @@ overriding the file extension (as described in hledger.1 -> Input files): 'include timedot:~/notes/2020*.md'.  -File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives +File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: DIRECTIVES 14.4 Default year ================= @@ -1084,7 +1084,7 @@ Y2010 ; change default year to 2010 assets  -File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives +File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: DIRECTIVES 14.5 Declaring commodities ========================== @@ -1152,7 +1152,7 @@ by a 'commodity' directive. This works similarly to account error checking, see the notes there for more details.  -File: hledger_journal.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: Directives +File: hledger_journal.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: DIRECTIVES 14.6 Default commodity ====================== @@ -1179,7 +1179,7 @@ D $1,000.00 b  -File: hledger_journal.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives +File: hledger_journal.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: DIRECTIVES 14.7 Declaring market prices ============================ @@ -1209,7 +1209,7 @@ P 2010/1/1 € $1.40 amount values in another commodity. See Valuation.  -File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: Directives +File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: DIRECTIVES 14.8 Declaring accounts ======================= @@ -1471,7 +1471,7 @@ means: between 'a:b' and 'a:c').  -File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives +File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: DIRECTIVES 14.9 Rewriting accounts ======================= @@ -1629,7 +1629,7 @@ aliases' directive: end aliases  -File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives +File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: DIRECTIVES 14.10 Default parent account ============================ @@ -1670,9 +1670,9 @@ If account aliases are present, they are applied after the default parent account.  -File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings, Prev: Directives, Up: Top +File: hledger_journal.info, Node: PERIODIC TRANSACTIONS, Next: AUTO POSTINGS, Prev: DIRECTIVES, Up: Top -15 Periodic transactions +15 PERIODIC TRANSACTIONS ************************ Periodic transaction rules describe transactions that recur. They allow @@ -1717,7 +1717,7 @@ to define budget goals, shown in budget reports. * Budgeting with periodic transactions::  -File: hledger_journal.info, Node: Periodic rule syntax, Next: Two spaces between period expression and description!, Up: Periodic transactions +File: hledger_journal.info, Node: Periodic rule syntax, Next: Two spaces between period expression and description!, Up: PERIODIC TRANSACTIONS 15.1 Periodic rule syntax ========================= @@ -1740,7 +1740,7 @@ date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1.  -File: hledger_journal.info, Node: Two spaces between period expression and description!, Next: Forecasting with periodic transactions, Prev: Periodic rule syntax, Up: Periodic transactions +File: hledger_journal.info, Node: Two spaces between period expression and description!, Next: Forecasting with periodic transactions, Prev: Periodic rule syntax, Up: PERIODIC TRANSACTIONS 15.2 Two spaces between period expression and description! ========================================================== @@ -1765,7 +1765,7 @@ accidentally alter their meaning, as in this example: expression.  -File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions +File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: PERIODIC TRANSACTIONS 15.3 Forecasting with periodic transactions =========================================== @@ -1811,7 +1811,7 @@ examples: '--forecast=202001-202004', '--forecast=jan-', '--forecast=2020'.  -File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions +File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: PERIODIC TRANSACTIONS 15.4 Budgeting with periodic transactions ========================================= @@ -1826,9 +1826,9 @@ compared in budget reports. See also: Budgeting and Forecasting.  -File: hledger_journal.info, Node: Auto postings, Prev: Periodic transactions, Up: Top +File: hledger_journal.info, Node: AUTO POSTINGS, Prev: PERIODIC TRANSACTIONS, Up: Top -16 Auto postings +16 AUTO POSTINGS **************** "Automated postings" or "auto postings" are extra postings which get @@ -1904,7 +1904,7 @@ $ hledger print --auto * Auto posting tags::  -File: hledger_journal.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings +File: hledger_journal.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: AUTO POSTINGS 16.1 Auto postings and multiple files ===================================== @@ -1914,7 +1914,7 @@ in any parent file or child file. Note, currently it will not affect sibling files (when multiple '-f'/'--file' are used - see #1212).  -File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings +File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: AUTO POSTINGS 16.2 Auto postings and dates ============================ @@ -1924,7 +1924,7 @@ precedence) a posting date in the auto posting rule itself, will also be used in the generated posting.  -File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings +File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: AUTO POSTINGS 16.3 Auto postings and transaction balancing / inferred amounts / ================================================================= @@ -1940,7 +1940,7 @@ after auto postings are added. This changed in hledger 1.12+; see #893 for background.  -File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings +File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: AUTO POSTINGS 16.4 Auto posting tags ====================== @@ -1964,142 +1964,137 @@ will have these tags added:  Tag Table: Node: Top76 -Node: Transactions2156 -Ref: #transactions2274 -Node: Dates3288 -Ref: #dates3395 -Node: Simple dates3460 -Ref: #simple-dates3582 -Node: Secondary dates4091 -Ref: #secondary-dates4241 -Node: Posting dates5577 -Ref: #posting-dates5702 -Node: Status7074 -Ref: #status7182 -Node: Description8890 -Ref: #description9011 -Node: Payee and note9331 -Ref: #payee-and-note9441 -Node: Comments9776 -Ref: #comments9889 -Node: Tags11083 -Ref: #tags11185 -Node: Postings12578 -Ref: #postings12693 -Node: Virtual postings13719 -Ref: #virtual-postings13832 -Node: Account names15137 -Ref: #account-names15265 -Node: Amounts15752 -Ref: #amounts15878 -Node: Digit group marks17002 -Ref: #digit-group-marks17149 -Node: Commodity display style18087 -Ref: #commodity-display-style18263 -Node: Rounding19806 -Ref: #rounding19926 -Node: Transaction prices20338 -Ref: #transaction-prices20499 -Node: Lot prices and lot dates22930 -Ref: #lot-prices-and-lot-dates23114 -Node: Balance assertions23602 -Ref: #balance-assertions23775 -Node: Assertions and ordering24808 -Ref: #assertions-and-ordering24992 -Node: Assertions and included files25692 -Ref: #assertions-and-included-files25931 -Node: Assertions and multiple -f options26264 -Ref: #assertions-and-multiple--f-options26516 -Node: Assertions and commodities26648 -Ref: #assertions-and-commodities26876 -Node: Assertions and prices28033 -Ref: #assertions-and-prices28243 -Node: Assertions and subaccounts28683 -Ref: #assertions-and-subaccounts28908 -Node: Assertions and virtual postings29232 -Ref: #assertions-and-virtual-postings29470 -Node: Assertions and precision29612 -Ref: #assertions-and-precision29801 -Node: Balance assignments30068 -Ref: #balance-assignments30229 -Node: Balance assignments and prices31393 -Ref: #balance-assignments-and-prices31561 -Node: Directives31785 -Ref: #directives31931 -Node: Directives and multiple files37429 -Ref: #directives-and-multiple-files37608 -Node: Comment blocks38272 -Ref: #comment-blocks38451 -Node: Including other files38627 -Ref: #including-other-files38803 -Node: Default year39727 -Ref: #default-year39892 -Node: Declaring commodities40299 -Ref: #declaring-commodities40478 -Node: Commodity error checking42322 -Ref: #commodity-error-checking42478 -Node: Default commodity42735 -Ref: #default-commodity42917 -Node: Declaring market prices43806 -Ref: #declaring-market-prices43997 -Node: Declaring accounts44854 -Ref: #declaring-accounts45036 -Node: Account error checking46238 -Ref: #account-error-checking46410 -Node: Account comments47589 -Ref: #account-comments47779 -Node: Account subdirectives48203 -Ref: #account-subdirectives48394 -Node: Account types48707 -Ref: #account-types48887 -Node: Declaring account types49623 -Ref: #declaring-account-types49808 -Node: Auto-detected account types50458 -Ref: #auto-detected-account-types50705 -Node: Interference from auto-detected account types51602 -Ref: #interference-from-auto-detected-account-types51885 -Node: Old account type syntax52368 -Ref: #old-account-type-syntax52571 -Node: Account display order52871 -Ref: #account-display-order53037 -Node: Rewriting accounts54188 -Ref: #rewriting-accounts54369 -Node: Basic aliases55126 -Ref: #basic-aliases55268 -Node: Regex aliases55972 -Ref: #regex-aliases56140 -Node: Combining aliases56859 -Ref: #combining-aliases57048 -Node: Aliases and multiple files58324 -Ref: #aliases-and-multiple-files58529 -Node: end aliases59108 -Ref: #end-aliases59261 -Node: Default parent account59362 -Ref: #default-parent-account59526 -Node: Periodic transactions60410 -Ref: #periodic-transactions60572 -Node: Periodic rule syntax62489 -Ref: #periodic-rule-syntax62691 -Node: Two spaces between period expression and description!63395 -Ref: #two-spaces-between-period-expression-and-description63710 -Node: Forecasting with periodic transactions64394 -Ref: #forecasting-with-periodic-transactions64695 -Node: Budgeting with periodic transactions66750 -Ref: #budgeting-with-periodic-transactions66985 -Node: Auto postings67394 -Ref: #auto-postings67521 -Node: Auto postings and multiple files69700 -Ref: #auto-postings-and-multiple-files69900 -Node: Auto postings and dates70109 -Ref: #auto-postings-and-dates70379 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions70554 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions70901 -Node: Auto posting tags71243 -Ref: #auto-posting-tags71454 +Node: TRANSACTIONS2111 +Ref: #transactions2229 +Node: DATES3243 +Ref: #dates3350 +Node: Simple dates3415 +Ref: #simple-dates3537 +Node: Secondary dates4046 +Ref: #secondary-dates4196 +Node: Posting dates5532 +Ref: #posting-dates5657 +Node: STATUS7029 +Ref: #status7137 +Node: DESCRIPTION8845 +Ref: #description8966 +Node: Payee and note9286 +Ref: #payee-and-note9396 +Node: COMMENTS9731 +Ref: #comments9844 +Node: TAGS11038 +Ref: #tags11140 +Node: POSTINGS12533 +Ref: #postings12648 +Node: Virtual postings13674 +Ref: #virtual-postings13787 +Node: ACCOUNT NAMES15092 +Ref: #account-names15220 +Node: AMOUNTS15707 +Ref: #amounts15833 +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  End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index daa3155a5..21b0d3b7e 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -1,10 +1,10 @@ -hledger_journal(5) hledger User Manuals hledger_journal(5) +HLEDGER_JOURNAL(5) hledger User Manuals HLEDGER_JOURNAL(5) NAME - Journal - hledger's default file format, representing a General Journal + hledger's default file format, representing a General Journal. DESCRIPTION hledger's usual data source is a plain text file containing journal en- @@ -31,14 +31,13 @@ DESCRIPTION formatting, tab completion, and useful commands. See Editor configura- tion at hledger.org for the full list. -FILE FORMAT Here's a description of each part of the file format (and hledger's data model). These are mostly in the order you'll use them, but in some cases related concepts have been grouped together for easy refer- ence, or linked before they are introduced, so feel free to skip over anything that looks unnecessary right now. - Transactions +TRANSACTIONS Transactions are the main unit of information in a journal file. They represent events, typically a movement of some quantity of commodities between two or more named accounts. @@ -66,7 +65,7 @@ FILE FORMAT assets:bank:checking $1 income:salary $-1 - Dates +DATES Simple dates Dates in the journal file use simple dates format: YYYY-MM-DD or YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be @@ -139,7 +138,7 @@ FILE FORMAT With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. - Status +STATUS Transactions, or individual postings within a transaction, can have a status mark, which is a single character before the transaction de- scription or posting account name, separated from it by a space, indi- @@ -183,7 +182,7 @@ FILE FORMAT cashed checks), and no flags to see the most up-to-date state of your finances. - Description +DESCRIPTION A transaction's description is the rest of the line following the date and status mark (or until a comment begins). Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you @@ -197,7 +196,7 @@ FILE FORMAT ter the first |). This may be worthwhile if you need to do more pre- cise querying and pivoting by payee or by note. - Comments +COMMENTS Lines in the journal beginning with a semicolon (;) or hash (#) or star (*) are comments, and will be ignored. (Star comments cause org-mode nodes to be ignored, allowing emacs users to fold and navigate their @@ -232,7 +231,7 @@ FILE FORMAT You can also comment larger regions of a file using comment and end comment directives. - Tags +TAGS Tags are a way to add extra labels or labelled data to postings and transactions, which you can then search or pivot on. @@ -272,7 +271,7 @@ FILE FORMAT Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. - Postings +POSTINGS A posting is an addition of some amount to, or removal of some amount from, an account. Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: @@ -326,7 +325,7 @@ FILE FORMAT postings. You can exclude virtual postings from reports with the -R/--real flag or real:1 query. - Account names +ACCOUNT NAMES Account names typically have several parts separated by a full colon, from which hledger derives a hierarchical chart of accounts. They can be anything you like, but in finance there are traditionally five top- @@ -338,7 +337,7 @@ FILE FORMAT Account names can be aliased. - Amounts +AMOUNTS After the account name, there is usually an amount. (Important: be- tween account name and amount, there must be two or more spaces.) @@ -460,7 +459,7 @@ FILE FORMAT places is "0"). (Guaranteed since hledger 1.17.1; in older versions this could vary if hledger was built with Decimal < 0.5.1.) - Transaction prices +TRANSACTION PRICES Within a transaction, you can note an amount's price in another commod- ity. This can be used to document the cost (in a purchase) or selling price (in a sale). For example, transaction prices are useful to @@ -521,7 +520,7 @@ FILE FORMAT EUR-100 assets:dollars # <- the dollars' selling price EUR100 assets:euros - Lot prices and lot dates +LOT PRICES, LOT DATES Ledger allows another kind of price, lot price (four variants: {UNIT- PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}), and/or a lot date ([DATE]) to be specified. These are normally used to @@ -530,7 +529,7 @@ FILE FORMAT transaction price, lot price and/or lot date may appear in any order, after the posting amount and before the balance assertion if any. - Balance assertions +BALANCE ASSERTIONS hledger supports Ledger-style balance assertions in journal files. These look like, for example, = EXPECTEDBALANCE following a posting's amount. Eg here we assert the expected dollar balance in accounts a @@ -653,7 +652,7 @@ FILE FORMAT limit the display precision, but this will not affect balance asser- tions. Balance assertion failure messages show exact amounts. - Balance assignments +BALANCE ASSIGNMENTS Ledger-style balance assignments are also supported. These are like balance assertions, but with no posting amount on the left side of the equals sign; instead it is calculated automatically so as to satisfy @@ -692,7 +691,7 @@ FILE FORMAT 2019-01-01 (a) $1 @ EUR2 = $1 @ EUR2 - Directives +DIRECTIVES A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. hledger's directives are based on a subset of Ledger's, but there are many differences (and also @@ -729,8 +728,6 @@ FILE FORMAT play style: amounts of that commodity in reports - - D declare a commodity to be default commodity: used for commodityless following commod- amounts, and its number no- ityless entries un- @@ -743,6 +740,8 @@ FILE FORMAT 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 @@ -1075,7 +1074,6 @@ FILE FORMAT ^(debts?|lia- Liability bilit(y|ies))(:|$) ^equity(:|$) Equity - ^(income|revenue)s?(:|$) Revenue ^expenses?(:|$) Expense @@ -1312,7 +1310,7 @@ FILE FORMAT account aliases are present, they are applied after the default parent account. - Periodic transactions +PERIODIC TRANSACTIONS Periodic transaction rules describe transactions that recur. They al- low hledger to generate temporary future transactions to help with forecasting, so you don't have to write out each one in the journal, @@ -1443,7 +1441,7 @@ FILE FORMAT See also: Budgeting and Forecasting. - Auto postings +AUTO POSTINGS "Automated postings" or "auto postings" are extra postings which get added automatically to transactions which match certain queries, de- fined by "auto posting rules", when you use the --auto flag. @@ -1570,9 +1568,11 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), - hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time- + dot(5) -hledger 1.20.99 December 2020 hledger_journal(5) +hledger-lib-1.20.99 December 2020 HLEDGER_JOURNAL(5) diff --git a/hledger-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index ea5ac2600..171585746 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -1,11 +1,11 @@ -.TH "hledger_timeclock" "5" "December 2020" "hledger 1.20.99" "hledger User Manuals" +.TH "HLEDGER_TIMECLOCK" "5" "December 2020" "hledger-lib-1.20.99 " "hledger User Manuals" .SH NAME .PP -Timeclock - the time logging format of timeclock.el, as read by hledger +The time logging format of timeclock.el, as read by hledger. .SH DESCRIPTION .PP hledger can read timeclock files. @@ -85,6 +85,6 @@ Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) + +hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) diff --git a/hledger-lib/hledger_timeclock.info b/hledger-lib/hledger_timeclock.info index 6e1485b40..9dc395818 100644 --- a/hledger-lib/hledger_timeclock.info +++ b/hledger-lib/hledger_timeclock.info @@ -4,10 +4,10 @@ stdin.  File: hledger_timeclock.info, Node: Top, Up: (dir) -hledger_timeclock(5) hledger 1.20.99 -************************************ +hledger_timeclock(5) +******************** -Timeclock - the time logging format of timeclock.el, as read by hledger +The time logging format of timeclock.el, as read by hledger. hledger can read timeclock files. As with Ledger, these are (a subset of) timeclock.el's format, containing clock-in and clock-out @@ -61,8 +61,3 @@ Tag Table: Node: Top78  End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/hledger-lib/hledger_timeclock.txt b/hledger-lib/hledger_timeclock.txt index d3e600106..89b7c6589 100644 --- a/hledger-lib/hledger_timeclock.txt +++ b/hledger-lib/hledger_timeclock.txt @@ -1,10 +1,10 @@ -hledger_timeclock(5) hledger User Manuals hledger_timeclock(5) +HLEDGER_TIMECLOCK(5) hledger User Manuals HLEDGER_TIMECLOCK(5) NAME - Timeclock - the time logging format of timeclock.el, as read by hledger + The time logging format of timeclock.el, as read by hledger. DESCRIPTION hledger can read timeclock files. As with Ledger, these are (a subset @@ -70,9 +70,11 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), - hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time- + dot(5) -hledger 1.20.99 December 2020 hledger_timeclock(5) +hledger-lib-1.20.99 December 2020 HLEDGER_TIMECLOCK(5) diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index edba78732..86f4d29ad 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -1,11 +1,11 @@ -.TH "hledger_timedot" "5" "December 2020" "hledger 1.20.99" "hledger User Manuals" +.TH "HLEDGER_TIMEDOT" "5" "December 2020" "hledger-lib-1.20.99 " "hledger User Manuals" .SH NAME .PP -Timedot - hledger\[aq]s human-friendly time logging format +hledger\[aq]s human-friendly time logging format. .SH DESCRIPTION .PP Timedot is a plain text format for logging dated, categorised quantities @@ -194,6 +194,6 @@ Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) + +hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) diff --git a/hledger-lib/hledger_timedot.info b/hledger-lib/hledger_timedot.info index e9a613437..97adc540d 100644 --- a/hledger-lib/hledger_timedot.info +++ b/hledger-lib/hledger_timedot.info @@ -4,10 +4,10 @@ stdin.  File: hledger_timedot.info, Node: Top, Up: (dir) -hledger_timedot(5) hledger 1.20.99 -********************************** +hledger_timedot(5) +****************** -Timedot - hledger's human-friendly time logging format +hledger's human-friendly time logging format. Timedot is a plain text format for logging dated, categorised quantities (of time, usually), supported by hledger. It is convenient @@ -143,8 +143,3 @@ Tag Table: Node: Top76  End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/hledger-lib/hledger_timedot.txt b/hledger-lib/hledger_timedot.txt index 968a0475e..349f10f2c 100644 --- a/hledger-lib/hledger_timedot.txt +++ b/hledger-lib/hledger_timedot.txt @@ -1,10 +1,10 @@ -hledger_timedot(5) hledger User Manuals hledger_timedot(5) +HLEDGER_TIMEDOT(5) hledger User Manuals HLEDGER_TIMEDOT(5) NAME - Timedot - hledger's human-friendly time logging format + hledger's human-friendly time logging format. DESCRIPTION Timedot is a plain text format for logging dated, categorised quanti- @@ -153,9 +153,11 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), - hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time- + dot(5) -hledger 1.20.99 December 2020 hledger_timedot(5) +hledger-lib-1.20.99 December 2020 HLEDGER_TIMEDOT(5) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index c5a4942e1..5cdb6f8e0 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,11 +1,11 @@ -.TH "hledger-ui" "1" "December 2020" "hledger-ui 1.20.99" "hledger User Manuals" +.TH "HLEDGER-UI" "1" "December 2020" "hledger-ui-1.20.99 " "hledger User Manuals" .SH NAME .PP -hledger-ui - terminal interface for the hledger accounting tool +A terminal interface (TUI) for the hledger accounting tool. .SH SYNOPSIS .PP \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R] @@ -189,18 +189,18 @@ show version \f[B]\f[CB]--debug[=N]\f[B]\f[R] show debug output (levels 1-9, default: 1) .PP -a \[at]file argument will be expanded to the contents of file, which +A \[at]FILE argument will be expanded to the contents of FILE, which should contain one command line option/argument per line. -(to prevent this, insert a \f[C]--\f[R] argument before.) -.SH keys +(To prevent this, insert a \f[C]--\f[R] argument before.) +.SH KEYS .PP \f[C]?\f[R] shows a help dialog listing all keys. -(some of these also appear in the quick help at the bottom of each -screen.) press \f[C]?\f[R] again (or \f[C]escape\f[R], or -\f[C]left\f[R], or \f[C]q\f[R]) to close it. -the following keys work on most screens: +(Some of these also appear in the quick help at the bottom of each +screen.) Press \f[C]?\f[R] again (or \f[C]ESCAPE\f[R], or +\f[C]LEFT\f[R], or \f[C]q\f[R]) to close it. +The following keys work on most screens: .PP -the cursor keys navigate: \f[C]right\f[R] (or \f[C]enter\f[R]) goes +The cursor keys navigate: \f[C]right\f[R] (or \f[C]enter\f[R]) goes deeper, \f[C]left\f[R] returns to the previous screen, \f[C]up\f[R]/\f[C]down\f[R]/\f[C]page up\f[R]/\f[C]page down\f[R]/\f[C]home\f[R]/\f[C]end\f[R] move up and down through lists. @@ -212,104 +212,103 @@ A tip: movement speed is limited by your keyboard repeat rate, to move faster you may want to adjust it. (If you\[aq]re on a mac, the karabiner app is one way to do that.) .PP -with shift pressed, the cursor keys adjust the report period, limiting +With shift pressed, the cursor keys adjust the report period, limiting the transactions to be shown (by default, all are shown). \f[C]shift-down/up\f[R] steps downward and upward through these standard report period durations: year, quarter, month, week, day. -then, \f[C]shift-left/right\f[R] moves to the previous/next period. +Then, \f[C]shift-left/right\f[R] moves to the previous/next period. \f[C]T\f[R] sets the report period to today. -with the \f[C]--watch\f[R] option, when viewing a \[dq]current\[dq] +With the \f[C]--watch\f[R] option, when viewing a \[dq]current\[dq] period (the current day, week, month, quarter, or year), the period will move automatically to track the current date. -to set a non-standard period, you can use \f[C]/\f[R] and a +To set a non-standard period, you can use \f[C]/\f[R] and a \f[C]date:\f[R] query. .PP \f[C]/\f[R] lets you set a general filter query limiting the data shown, using the same query terms as in hledger and hledger-web. -while editing the query, you can use ctrl-a/e/d/k, bs, cursor keys; -press \f[C]enter\f[R] to set it, or \f[C]escape\f[R]to cancel. -there are also keys for quickly adjusting some common filters like +While editing the query, you can use CTRL-a/e/d/k, BS, cursor keys; +press \f[C]ENTER\f[R] to set it, or \f[C]ESCAPE\f[R]to cancel. +There are also keys for quickly adjusting some common filters like account depth and transaction status (see below). -\f[C]backspace\f[R] or \f[C]delete\f[R] removes all filters, showing all +\f[C]BACKSPACE\f[R] or \f[C]DELETE\f[R] removes all filters, showing all transactions. .PP -as mentioned above, by default hledger-ui hides future transactions - +As mentioned above, by default hledger-ui hides future transactions - both ordinary transactions recorded in the journal, and periodic transactions generated by rule. -\f[C]f\f[R] toggles forecast mode, in which future/forecasted +\f[C]F\f[R] toggles forecast mode, in which future/forecasted transactions are shown. -\f[I](experimental)\f[R] .PP -\f[C]escape\f[R] resets the UI state and jumps back to the top screen, +\f[C]ESCAPE\f[R] resets the UI state and jumps back to the top screen, restoring the app\[aq]s initial state at startup. Or, it cancels minibuffer data entry or the help dialog. .PP -\f[C]ctrl-l\f[R] redraws the screen and centers the selection if +\f[C]CTRL-l\f[R] redraws the screen and centers the selection if possible (selections near the top won\[aq]t be centered, since we don\[aq]t scroll above the top). .PP \f[C]g\f[R] reloads from the data file(s) and updates the current screen and any previous screens. -(with large files, this could cause a noticeable pause.) +(With large files, this could cause a noticeable pause.) .PP -\f[C]i\f[R] toggles balance assertion checking. -disabling balance assertions temporarily can be useful for +\f[C]I\f[R] toggles balance assertion checking. +Disabling balance assertions temporarily can be useful for troubleshooting. .PP \f[C]a\f[R] runs command-line hledger\[aq]s add command, and reloads the updated file. -this allows some basic data entry. +This allows some basic data entry. .PP -\f[C]a\f[R] is like \f[C]a\f[R], but runs the hledger-iadd tool, which +\f[C]A\f[R] is like \f[C]a\f[R], but runs the hledger-iadd tool, which provides a terminal interface. -this key will be available if \f[C]hledger-iadd\f[R] is installed in +This key will be available if \f[C]hledger-iadd\f[R] is installed in $path. .PP -\f[C]e\f[R] runs $hledger_ui_editor, or $editor, or a default +\f[C]E\f[R] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (\f[C]emacsclient -a \[dq]\[dq] -nw\f[R]) on the journal file. -with some editors (emacs, vi), the cursor will be positioned at the +With some editors (emacs, vi), the cursor will be positioned at the current transaction when invoked from the register and transaction screens, and at the error location (if possible) when invoked from the error screen. .PP -\f[C]b\f[R] toggles cost mode, showing amounts in their transaction -price\[aq]s commodity (like toggling the \f[C]-b/--cost\f[R] flag). +\f[C]B\f[R] toggles cost mode, showing amounts in their transaction +price\[aq]s commodity (like toggling the \f[C]-B/--cost\f[R] flag). .PP -\f[C]v\f[R] toggles value mode, showing amounts\[aq] current market +\f[C]V\f[R] toggles value mode, showing amounts\[aq] current market value in their default valuation commodity (like toggling the -\f[C]-v/--market\f[R] flag). -note, \[dq]current market value\[dq] means the value on the report end +\f[C]-V/--market\f[R] flag). +Note, \[dq]current market value\[dq] means the value on the report end date if specified, otherwise today. -to see the value on another date, you can temporarily set that as the +To see the value on another date, you can temporarily set that as the report end date. -eg: to see a transaction as it was valued on july 30, go to the accounts +Eg: to see a transaction as it was valued on july 30, go to the accounts or register screen, press \f[C]/\f[R], and add \f[C]date:-7/30\f[R] to the query. .PP -at most one of cost or value mode can be active at once. +At most one of cost or value mode can be active at once. .PP -there\[aq]s not yet any visual reminder when cost or value mode is +There\[aq]s not yet any visual reminder when cost or value mode is active; for now pressing \f[C]b\f[R] \f[C]b\f[R] \f[C]v\f[R] should reliably reset to normal mode. .PP -with --watch active, if you save an edit to the journal file while -viewing the transaction screen in cost or value mode, the -\f[C]b\f[R]/\f[C]v\f[R] keys will stop working. -to work around, press g to force a manual reload, or exit the +With \f[C]--watch\f[R] active, if you save an edit to the journal file +while viewing the transaction screen in cost or value mode, the +\f[C]B\f[R]/\f[C]V\f[R] keys will stop working. +To work around, press \f[C]g\f[R] to force a manual reload, or exit the transaction screen. .PP \f[C]q\f[R] quits the application. .PP -additional screen-specific keys are described below. -.SH screens -.SS accounts screen +Additional screen-specific keys are described below. +.SH SCREENS +.SS Accounts screen .PP -this is normally the first screen displayed. -it lists accounts and their balances, like hledger\[aq]s balance +This is normally the first screen displayed. +It lists accounts and their balances, like hledger\[aq]s balance command. -by default, it shows all accounts and their latest ending balances +By default, it shows all accounts and their latest ending balances (including the balances of subaccounts). -if you specify a query on the command line, it shows just the matched +If you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. .PP Account names are shown as a flat list by default; press \f[C]t\f[R] to @@ -505,6 +504,6 @@ Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) + +hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index c87783389..40663b914 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -3,10 +3,10 @@ This is hledger-ui.info, produced by makeinfo version 6.7 from stdin.  File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-ui(1) hledger-ui 1.20.99 -******************************** +hledger-ui(1) +************* -hledger-ui - terminal interface for the hledger accounting tool +A terminal interface (TUI) for the hledger accounting tool. 'hledger-ui [OPTIONS] [QUERYARGS]' 'hledger ui -- [OPTIONS] [QUERYARGS]' @@ -36,18 +36,14 @@ enable "forecast mode". * Menu: * OPTIONS:: -* keys:: -* screens:: -* accounts screen:: -* Register screen:: -* Transaction screen:: -* Error screen:: +* KEYS:: +* SCREENS:: * ENVIRONMENT:: * FILES:: * BUGS::  -File: hledger-ui.info, Node: OPTIONS, Next: keys, Prev: Top, Up: Top +File: hledger-ui.info, Node: OPTIONS, Next: KEYS, Prev: Top, Up: Top 1 OPTIONS ********* @@ -208,22 +204,22 @@ the last one takes precedence. show debug output (levels 1-9, default: 1) - a @file argument will be expanded to the contents of file, which -should contain one command line option/argument per line. (to prevent + A @FILE argument will be expanded to the contents of FILE, which +should contain one command line option/argument per line. (To prevent this, insert a '--' argument before.)  -File: hledger-ui.info, Node: keys, Next: screens, Prev: OPTIONS, Up: Top +File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top -2 keys +2 KEYS ****** -'?' shows a help dialog listing all keys. (some of these also appear in -the quick help at the bottom of each screen.) press '?' again (or -'escape', or 'left', or 'q') to close it. the following keys work on +'?' shows a help dialog listing all keys. (Some of these also appear in +the quick help at the bottom of each screen.) Press '?' again (or +'ESCAPE', or 'LEFT', or 'q') to close it. The following keys work on most screens: - the cursor keys navigate: 'right' (or 'enter') goes deeper, 'left' + The cursor keys navigate: 'right' (or 'enter') goes deeper, 'left' returns to the previous screen, 'up'/'down'/'page up'/'page down'/'home'/'end' move up and down through lists. Emacs-style ('ctrl-p'/'ctrl-n'/'ctrl-f'/'ctrl-b') movement keys are also supported @@ -232,99 +228,106 @@ speed is limited by your keyboard repeat rate, to move faster you may want to adjust it. (If you're on a mac, the karabiner app is one way to do that.) - with shift pressed, the cursor keys adjust the report period, + With shift pressed, the cursor keys adjust the report period, limiting the transactions to be shown (by default, all are shown). 'shift-down/up' steps downward and upward through these standard report -period durations: year, quarter, month, week, day. then, +period durations: year, quarter, month, week, day. Then, 'shift-left/right' moves to the previous/next period. 'T' sets the -report period to today. with the '--watch' option, when viewing a +report period to today. With the '--watch' option, when viewing a "current" period (the current day, week, month, quarter, or year), the -period will move automatically to track the current date. to set a +period will move automatically to track the current date. To set a non-standard period, you can use '/' and a 'date:' query. '/' lets you set a general filter query limiting the data shown, -using the same query terms as in hledger and hledger-web. while editing -the query, you can use ctrl-a/e/d/k, bs, cursor keys; press 'enter' to -set it, or 'escape'to cancel. there are also keys for quickly adjusting +using the same query terms as in hledger and hledger-web. While editing +the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to +set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting some common filters like account depth and transaction status (see -below). 'backspace' or 'delete' removes all filters, showing all +below). 'BACKSPACE' or 'DELETE' removes all filters, showing all transactions. - as mentioned above, by default hledger-ui hides future transactions - + As mentioned above, by default hledger-ui hides future transactions - both ordinary transactions recorded in the journal, and periodic -transactions generated by rule. 'f' toggles forecast mode, in which -future/forecasted transactions are shown. _(experimental)_ +transactions generated by rule. 'F' toggles forecast mode, in which +future/forecasted transactions are shown. - 'escape' resets the UI state and jumps back to the top screen, + 'ESCAPE' resets the UI state and jumps back to the top screen, restoring the app's initial state at startup. Or, it cancels minibuffer data entry or the help dialog. - 'ctrl-l' redraws the screen and centers the selection if possible + 'CTRL-l' redraws the screen and centers the selection if possible (selections near the top won't be centered, since we don't scroll above the top). 'g' reloads from the data file(s) and updates the current screen and -any previous screens. (with large files, this could cause a noticeable +any previous screens. (With large files, this could cause a noticeable pause.) - 'i' toggles balance assertion checking. disabling balance assertions + 'I' toggles balance assertion checking. Disabling balance assertions temporarily can be useful for troubleshooting. 'a' runs command-line hledger's add command, and reloads the updated -file. this allows some basic data entry. +file. This allows some basic data entry. - 'a' is like 'a', but runs the hledger-iadd tool, which provides a -terminal interface. this key will be available if 'hledger-iadd' is + 'A' is like 'a', but runs the hledger-iadd tool, which provides a +terminal interface. This key will be available if 'hledger-iadd' is installed in $path. - 'e' runs $hledger_ui_editor, or $editor, or a default ('emacsclient --a "" -nw') on the journal file. with some editors (emacs, vi), the + 'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient +-a "" -nw') on the journal file. With some editors (emacs, vi), the cursor will be positioned at the current transaction when invoked from the register and transaction screens, and at the error location (if possible) when invoked from the error screen. - 'b' toggles cost mode, showing amounts in their transaction price's -commodity (like toggling the '-b/--cost' flag). + 'B' toggles cost mode, showing amounts in their transaction price's +commodity (like toggling the '-B/--cost' flag). - 'v' toggles value mode, showing amounts' current market value in -their default valuation commodity (like toggling the '-v/--market' -flag). note, "current market value" means the value on the report end -date if specified, otherwise today. to see the value on another date, -you can temporarily set that as the report end date. eg: to see a + 'V' toggles value mode, showing amounts' current market value in +their default valuation commodity (like toggling the '-V/--market' +flag). Note, "current market value" means the value on the report end +date if specified, otherwise today. To see the value on another date, +you can temporarily set that as the report end date. Eg: to see a transaction as it was valued on july 30, go to the accounts or register screen, press '/', and add 'date:-7/30' to the query. - at most one of cost or value mode can be active at once. + At most one of cost or value mode can be active at once. - there's not yet any visual reminder when cost or value mode is + There's not yet any visual reminder when cost or value mode is active; for now pressing 'b' 'b' 'v' should reliably reset to normal mode. - with -watch active, if you save an edit to the journal file while -viewing the transaction screen in cost or value mode, the 'b'/'v' keys -will stop working. to work around, press g to force a manual reload, or -exit the transaction screen. + With '--watch' active, if you save an edit to the journal file while +viewing the transaction screen in cost or value mode, the 'B'/'V' keys +will stop working. To work around, press 'g' to force a manual reload, +or exit the transaction screen. 'q' quits the application. - additional screen-specific keys are described below. + Additional screen-specific keys are described below.  -File: hledger-ui.info, Node: screens, Next: accounts screen, Prev: keys, Up: Top +File: hledger-ui.info, Node: SCREENS, Next: ENVIRONMENT, Prev: KEYS, Up: Top -3 screens +3 SCREENS ********* +* Menu: + +* Accounts screen:: +* Register screen:: +* Transaction screen:: +* Error screen:: +  -File: hledger-ui.info, Node: accounts screen, Next: Register screen, Prev: screens, Up: Top +File: hledger-ui.info, Node: Accounts screen, Next: Register screen, Up: SCREENS -4 accounts screen -***************** +3.1 Accounts screen +=================== -this is normally the first screen displayed. it lists accounts and -their balances, like hledger's balance command. by default, it shows +This is normally the first screen displayed. It lists accounts and +their balances, like hledger's balance command. By default, it shows all accounts and their latest ending balances (including the balances of -subaccounts). if you specify a query on the command line, it shows just +subaccounts). If you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. Account names are shown as a flat list by default; press 't' to @@ -365,10 +368,10 @@ command-line hledger). Press 'right' or 'enter' to view an account's transactions register.  -File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev: accounts screen, Up: Top +File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS -5 Register screen -***************** +3.2 Register screen +=================== This screen shows the transactions affecting a particular account, like a check register. Each line represents one transaction and shows: @@ -412,10 +415,10 @@ command-line hledger). detail.  -File: hledger-ui.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: Top +File: hledger-ui.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS -6 Transaction screen -******************** +3.3 Transaction screen +====================== This screen shows a single transaction, as a general journal entry, similar to hledger's print command and journal format @@ -436,10 +439,10 @@ unfiltered journal, which is a more stable id (at least until the next reload).  -File: hledger-ui.info, Node: Error screen, Next: ENVIRONMENT, Prev: Transaction screen, Up: Top +File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS -7 Error screen -************** +3.4 Error screen +================ This screen will appear if there is a problem, such as a parse error, when you press g to reload. Once you have fixed the problem, press g @@ -447,9 +450,9 @@ again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.)  -File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: Error screen, Up: Top +File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: SCREENS, Up: Top -8 ENVIRONMENT +4 ENVIRONMENT ************* *COLUMNS* The screen width to use. Default: the full terminal width. @@ -477,7 +480,7 @@ a more thorough way that also affects applications started from the GUI  File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top -9 FILES +5 FILES ******* Reads data from one or more files in hledger journal, timeclock, @@ -488,8 +491,8 @@ timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or  File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top -10 BUGS -******* +6 BUGS +****** The need to precede options with '--' when invoked from hledger is awkward. @@ -516,30 +519,25 @@ program is restarted.  Tag Table: Node: Top71 -Node: OPTIONS1556 -Ref: #options1653 -Node: keys5720 -Ref: #keys5815 -Node: screens10147 -Ref: #screens10256 -Node: accounts screen10256 -Ref: #accounts-screen10392 -Node: Register screen12607 -Ref: #register-screen12754 -Node: Transaction screen14751 -Ref: #transaction-screen14901 -Node: Error screen15771 -Ref: #error-screen15905 -Node: ENVIRONMENT16149 -Ref: #environment16268 -Node: FILES17075 -Ref: #files17174 -Node: BUGS17387 -Ref: #bugs17466 +Node: OPTIONS1434 +Ref: #options1531 +Node: KEYS5598 +Ref: #keys5693 +Node: SCREENS10012 +Ref: #screens10117 +Node: Accounts screen10207 +Ref: #accounts-screen10335 +Node: Register screen12550 +Ref: #register-screen12705 +Node: Transaction screen14702 +Ref: #transaction-screen14860 +Node: Error screen15730 +Ref: #error-screen15852 +Node: ENVIRONMENT16096 +Ref: #environment16210 +Node: FILES17017 +Ref: #files17116 +Node: BUGS17329 +Ref: #bugs17406  End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index e13c73f1b..afb900ed2 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -1,10 +1,10 @@ -hledger-ui(1) hledger User Manuals hledger-ui(1) +HLEDGER-UI(1) hledger User Manuals HLEDGER-UI(1) NAME - hledger-ui - terminal interface for the hledger accounting tool + A terminal interface (TUI) for the hledger accounting tool. SYNOPSIS hledger-ui [OPTIONS] [QUERYARGS] @@ -185,16 +185,16 @@ OPTIONS --debug[=N] show debug output (levels 1-9, default: 1) - a @file argument will be expanded to the contents of file, which should - contain one command line option/argument per line. (to prevent this, + A @FILE argument will be expanded to the contents of FILE, which should + contain one command line option/argument per line. (To prevent this, insert a -- argument before.) -keys - ? shows a help dialog listing all keys. (some of these also appear in - the quick help at the bottom of each screen.) press ? again (or escape, - or left, or q) to close it. the following keys work on most screens: +KEYS + ? shows a help dialog listing all keys. (Some of these also appear in + the quick help at the bottom of each screen.) Press ? again (or ESCAPE, + or LEFT, or q) to close it. The following keys work on most screens: - the cursor keys navigate: right (or enter) goes deeper, left returns to + The cursor keys navigate: right (or enter) goes deeper, left returns to the previous screen, up/down/page up/page down/home/end move up and down through lists. Emacs-style (ctrl-p/ctrl-n/ctrl-f/ctrl-b) movement keys are also supported (but not vi-style keys, since hledger-1.19, @@ -202,87 +202,87 @@ keys rate, to move faster you may want to adjust it. (If you're on a mac, the karabiner app is one way to do that.) - with shift pressed, the cursor keys adjust the report period, limiting + With shift pressed, the cursor keys adjust the report period, limiting the transactions to be shown (by default, all are shown). shift- down/up steps downward and upward through these standard report period - durations: year, quarter, month, week, day. then, shift-left/right + durations: year, quarter, month, week, day. Then, shift-left/right moves to the previous/next period. T sets the report period to today. - with the --watch option, when viewing a "current" period (the current + With the --watch option, when viewing a "current" period (the current day, week, month, quarter, or year), the period will move automatically - to track the current date. to set a non-standard period, you can use / + to track the current date. To set a non-standard period, you can use / and a date: query. / lets you set a general filter query limiting the data shown, using - the same query terms as in hledger and hledger-web. while editing the - query, you can use ctrl-a/e/d/k, bs, cursor keys; press enter to set - it, or escapeto cancel. there are also keys for quickly adjusting some + the same query terms as in hledger and hledger-web. While editing the + query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set + it, or ESCAPEto cancel. There are also keys for quickly adjusting some common filters like account depth and transaction status (see below). - backspace or delete removes all filters, showing all transactions. + BACKSPACE or DELETE removes all filters, showing all transactions. - as mentioned above, by default hledger-ui hides future transactions - + As mentioned above, by default hledger-ui hides future transactions - both ordinary transactions recorded in the journal, and periodic trans- - actions generated by rule. f toggles forecast mode, in which fu- - ture/forecasted transactions are shown. (experimental) + actions generated by rule. F toggles forecast mode, in which fu- + ture/forecasted transactions are shown. - escape resets the UI state and jumps back to the top screen, restoring + ESCAPE resets the UI state and jumps back to the top screen, restoring the app's initial state at startup. Or, it cancels minibuffer data en- try or the help dialog. - ctrl-l redraws the screen and centers the selection if possible (selec- + CTRL-l redraws the screen and centers the selection if possible (selec- tions near the top won't be centered, since we don't scroll above the top). g reloads from the data file(s) and updates the current screen and any - previous screens. (with large files, this could cause a noticeable + previous screens. (With large files, this could cause a noticeable pause.) - i toggles balance assertion checking. disabling balance assertions + I toggles balance assertion checking. Disabling balance assertions temporarily can be useful for troubleshooting. a runs command-line hledger's add command, and reloads the updated - file. this allows some basic data entry. + file. This allows some basic data entry. - a is like a, but runs the hledger-iadd tool, which provides a terminal - interface. this key will be available if hledger-iadd is installed in + A is like a, but runs the hledger-iadd tool, which provides a terminal + interface. This key will be available if hledger-iadd is installed in $path. - e runs $hledger_ui_editor, or $editor, or a default (emacsclient -a "" - -nw) on the journal file. with some editors (emacs, vi), the cursor + E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" + -nw) on the journal file. With some editors (emacs, vi), the cursor will be positioned at the current transaction when invoked from the register and transaction screens, and at the error location (if possi- ble) when invoked from the error screen. - b toggles cost mode, showing amounts in their transaction price's com- - modity (like toggling the -b/--cost flag). + B toggles cost mode, showing amounts in their transaction price's com- + modity (like toggling the -B/--cost flag). - v toggles value mode, showing amounts' current market value in their - default valuation commodity (like toggling the -v/--market flag). - note, "current market value" means the value on the report end date if - specified, otherwise today. to see the value on another date, you can - temporarily set that as the report end date. eg: to see a transaction + V toggles value mode, showing amounts' current market value in their + default valuation commodity (like toggling the -V/--market flag). + Note, "current market value" means the value on the report end date if + specified, otherwise today. To see the value on another date, you can + temporarily set that as the report end date. Eg: to see a transaction as it was valued on july 30, go to the accounts or register screen, press /, and add date:-7/30 to the query. - at most one of cost or value mode can be active at once. + At most one of cost or value mode can be active at once. - there's not yet any visual reminder when cost or value mode is active; + There's not yet any visual reminder when cost or value mode is active; for now pressing b b v should reliably reset to normal mode. - with --watch active, if you save an edit to the journal file while - viewing the transaction screen in cost or value mode, the b/v keys will - stop working. to work around, press g to force a manual reload, or + With --watch active, if you save an edit to the journal file while + viewing the transaction screen in cost or value mode, the B/V keys will + stop working. To work around, press g to force a manual reload, or exit the transaction screen. q quits the application. - additional screen-specific keys are described below. + Additional screen-specific keys are described below. -screens - accounts screen - this is normally the first screen displayed. it lists accounts and - their balances, like hledger's balance command. by default, it shows +SCREENS + Accounts screen + This is normally the first screen displayed. It lists accounts and + their balances, like hledger's balance command. By default, it shows all accounts and their latest ending balances (including the balances - of subaccounts). if you specify a query on the command line, it shows + of subaccounts). If you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. Account names are shown as a flat list by default; press t to toggle @@ -452,9 +452,11 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), - hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time- + dot(5) -hledger-ui 1.20.99 December 2020 hledger-ui(1) +hledger-ui-1.20.99 December 2020 HLEDGER-UI(1) diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 107702425..e972776a8 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,11 +1,11 @@ -.TH "hledger-web" "1" "December 2020" "hledger-web 1.20.99" "hledger User Manuals" +.TH "HLEDGER-WEB" "1" "December 2020" "hledger-web-1.20.99 " "hledger User Manuals" .SH NAME .PP -hledger-web - web interface for the hledger accounting tool +A web interface (WUI) for the hledger accounting tool. .SH SYNOPSIS .PP \f[C]hledger-web [OPTIONS]\f[R] @@ -610,6 +610,6 @@ Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) + +hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 42f2d30cb..24832db4b 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -3,10 +3,10 @@ This is hledger-web.info, produced by makeinfo version 6.7 from stdin.  File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-web(1) hledger-web 1.20.99 -********************************** +hledger-web(1) +************** -hledger-web - web interface for the hledger accounting tool +A web interface (WUI) for the hledger accounting tool. 'hledger-web [OPTIONS]' 'hledger web -- [OPTIONS]' @@ -589,26 +589,21 @@ awkward.  Tag Table: Node: Top72 -Node: OPTIONS1752 -Ref: #options1857 -Node: PERMISSIONS8956 -Ref: #permissions9095 -Node: EDITING UPLOADING DOWNLOADING10307 -Ref: #editing-uploading-downloading10488 -Node: RELOADING11322 -Ref: #reloading11456 -Node: JSON API11889 -Ref: #json-api12003 -Node: ENVIRONMENT17493 -Ref: #environment17609 -Node: FILES18342 -Ref: #files18442 -Node: BUGS18655 -Ref: #bugs18733 +Node: OPTIONS1707 +Ref: #options1812 +Node: PERMISSIONS8911 +Ref: #permissions9050 +Node: EDITING UPLOADING DOWNLOADING10262 +Ref: #editing-uploading-downloading10443 +Node: RELOADING11277 +Ref: #reloading11411 +Node: JSON API11844 +Ref: #json-api11958 +Node: ENVIRONMENT17448 +Ref: #environment17564 +Node: FILES18297 +Ref: #files18397 +Node: BUGS18610 +Ref: #bugs18688  End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index f2039d0b0..26b28ee72 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -1,10 +1,10 @@ -hledger-web(1) hledger User Manuals hledger-web(1) +HLEDGER-WEB(1) hledger User Manuals HLEDGER-WEB(1) NAME - hledger-web - web interface for the hledger accounting tool + A web interface (WUI) for the hledger accounting tool. SYNOPSIS hledger-web [OPTIONS] @@ -545,9 +545,11 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), - hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time- + dot(5) -hledger-web 1.20.99 December 2020 hledger-web(1) +hledger-web-1.20.99 December 2020 HLEDGER-WEB(1) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index f06522d11..2fc0f96e5 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,23 +1,20 @@ .\"t -.TH "hledger" "1" "December 2020" "hledger 1.20.99" "hledger User Manuals" +.TH "HLEDGER" "1" "December 2020" "hledger-1.20.99 " "hledger User Manuals" .SH NAME .PP -hledger - a command-line accounting tool +A command-line accounting tool for both power users and folks new to +accounting. .SH SYNOPSIS .PP -\f[C]hledger [-f FILE] COMMAND [OPTIONS] [ARGS]\f[R] -.PD 0 -.P -.PD -\f[C]hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]\f[R] -.PD 0 -.P -.PD \f[C]hledger\f[R] +.PP +\f[C]hledger [-f FILE] COMMAND [OPTIONS] [ARGS]\f[R] +.PP +\f[C]hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]\f[R] .SH DESCRIPTION .PP hledger is a reliable, cross-platform set of programs for tracking @@ -1328,10 +1325,11 @@ T} .TE .SS Report start & end date .PP -Most hledger reports show the full span of time represented by the -journal data, by default. -So, the effective report start and end dates will be the earliest and -latest transaction or posting dates found in the journal. +By default, most hledger reports will show the full span of time +represented 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. .PP Often you will want to see a shorter time span, such as the current month. @@ -1789,7 +1787,7 @@ prices will be used. .PP For single period reports, if an explicit report end date is specified, that will be used as the valuation date; otherwise the valuation date is -\[dq]today\[dq]. +the journal\[aq]s end date. .PP For multiperiod reports, each column/period is valued on the last day of the period, by default. @@ -2466,22 +2464,85 @@ 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 COMMANDS .PP -hledger provides a number of subcommands; \f[C]hledger\f[R] with no -arguments shows a list. +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. .PP -If you install additional \f[C]hledger-*\f[R] packages, or if you put -programs or scripts named \f[C]hledger-NAME\f[R] in your PATH, these -will also be listed as subcommands. +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]. .PP -Run a subcommand by writing its name as first argument (eg -\f[C]hledger incomestatement\f[R]). -You can also write one of the standard short aliases displayed in -parentheses in the command list (\f[C]hledger b\f[R]), or any any -unambiguous prefix of a command name (\f[C]hledger inc\f[R]). +Here are the built-in commands: .PP -Here are all the builtin commands in alphabetical order. -See also \f[C]hledger\f[R] for a more organised command list, and -\f[C]hledger CMD -h\f[R] for detailed command help. +\f[B]Data entry (these modify the journal file):\f[R] +.IP \[bu] 2 +add - add transactions using guided prompts +.IP \[bu] 2 +import - add any new transactions from other files (eg csv) +.PP +\f[B]Data management\f[R]: +.IP \[bu] 2 +check - check for various kinds of issue in the data +.IP \[bu] 2 +close (equity) - generate balance-resetting transactions +.IP \[bu] 2 +diff - compare account transactions in two journal files +.IP \[bu] 2 +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 +.IP \[bu] 2 +balancesheet (bs) - 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 +.IP \[bu] 2 +roi - show return on investments +.PP +\f[B]Miscellaneous reports:\f[R] +.IP \[bu] 2 +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 +.IP \[bu] 2 +codes - show transaction codes +.IP \[bu] 2 +commodities - show commodity/currency symbols +.IP \[bu] 2 +descriptions - show unique transaction descriptions +.IP \[bu] 2 +files - show input file paths +.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) +.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 +.IP \[bu] 2 +register-match - show a recent posting that best matches a description +.IP \[bu] 2 +stats - show journal statistics +.IP \[bu] 2 +tags - show tag names +.IP \[bu] 2 +test - run self tests +.PP +Next, the detailed command docs, in alphabetical order. .SS accounts .PP accounts, a @@ -2664,6 +2725,10 @@ shown. .PP Transactions making a net change of zero are not shown by default; add the \f[C]-E/--empty\f[R] flag to show them. +.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 \f[C]json\f[R]. .SS aregister and custom posting dates .PP Transactions whose date is outside the report period can still be shown, @@ -2677,11 +2742,6 @@ To filter strictly by transaction date instead, add the \f[C]--txn-dates\f[R] flag. If you use this flag and some of your postings have custom dates, it\[aq]s probably best to assume the running balance is wrong. -.SS Output format -.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 \f[C]json\f[R]. .PP Examples: .PP @@ -2734,6 +2794,10 @@ Then the balance command will show real-world account balances. In some cases the -H/--historical flag is used to ensure this (more below). .PP +This command also supports the output destination and output format +options The output formats supported are (in most modes): \f[C]txt\f[R], +\f[C]csv\f[R], \f[C]html\f[R], and \f[C]json\f[R]. +.PP The balance command can produce several styles of report: .SS Classic balance report .PP @@ -3378,11 +3442,6 @@ Budget performance in 2019/01: || 0 [ 0] \f[R] .fi -.SS Output format -.PP -This command also supports the output destination and output format -options The output formats supported are (in most modes): \f[C]txt\f[R], -\f[C]csv\f[R], \f[C]html\f[R], and \f[C]json\f[R]. .SS balancesheet .PP balancesheet, bs @@ -4047,371 +4106,6 @@ 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 @@ -4979,62 +4673,82 @@ 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 .PP -hledger also searches for external add-on commands, and will include -these in the commands list. -These are programs or scripts in your PATH whose name starts with -\f[C]hledger-\f[R] and ends with a recognised file extension (currently: -no 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]). +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. .PP -Add-ons can be invoked like any hledger command, but there are a few -things to be aware of. -Eg if the \f[C]hledger-web\f[R] add-on is installed, +These offical add-ons are maintained and released along with hledger: .IP \[bu] 2 -\f[C]hledger -h web\f[R] shows hledger\[aq]s help, while +ui an efficient terminal interface for hledger (TUI) +.IP \[bu] 2 +web a simple web interface for hledger (WUI) +.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. +Eg you must write: +.IP +.nf +\f[C] +$ hledger web -- --serve +\f[R] +.fi +.PP +and not: +.IP +.nf +\f[C] +$ hledger web --serve +\f[R] +.fi +.PP +(because the \f[C]--serve\f[R] flag belongs to \f[C]hledger-web\f[R], +not \f[C]hledger\f[R]). +.PP +The \f[C]-h/--help\f[R] and \f[C]--version\f[R] flags work without +\f[C]--\f[R], with their position deciding which program they refer to. +Eg \f[C]hledger -h web\f[R] shows hledger\[aq]s help, \f[C]hledger web -h\f[R] shows hledger-web\[aq]s help. +.PP +If you have any trouble with this, remember you can always run the +add-on program directly, eg: +.IP +.nf +\f[C] +$ hledger-web --serve +\f[R] +.fi +.SS Making add-on commands +.PP +Add-on commands are programs or scripts in your PATH .IP \[bu] 2 -Flags specific to the add-on must have a preceding \f[C]--\f[R] to hide -them from hledger. -So \f[C]hledger web --serve --port 9000\f[R] will be rejected; you must -use \f[C]hledger web -- --serve --port 9000\f[R]. +whose name starts with \f[C]hledger-\f[R] .IP \[bu] 2 -You can always run add-ons directly if preferred: -\f[C]hledger-web --serve --port 9000\f[R]. +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 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 (and haskell) library functions -that built-in commands do, for command-line options, journal parsing, -reporting, etc. -.PP -Two important add-ons are the hledger-ui and hledger-web user -interfaces. -These are maintained and released along with hledger: -.SS ui -.PP -hledger-ui provides an efficient terminal interface. -.SS web -.PP -hledger-web provides a simple web interface. -.PP -Third party add-ons, maintained separately from hledger, include: -.SS iadd -.PP -hledger-iadd is a more interactive, terminal UI replacement for the add -command. -.SS interest -.PP -hledger-interest generates interest transactions for an account -according to various schemes. -.SS stockquotes -.PP -hledger-stockquotes downloads market prices for the commodities in your -journal from AlphaVantage. -.PP -A few more experimental or old add-ons can be found in hledger\[aq]s -bin/ directory. -These are typically prototypes and not guaranteed to work. +advantage: they can use the same hledger library functions that built-in +commands use for command-line options, parsing and reporting. .SH ENVIRONMENT .PP \f[B]LEDGER_FILE\f[R] The journal file path when not specified with @@ -5214,6 +4928,6 @@ Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) + +hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) diff --git a/hledger/hledger.info b/hledger/hledger.info index 2860101ab..8f5850388 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -3,14 +3,17 @@ This is hledger.info, produced by makeinfo version 6.7 from stdin.  File: hledger.info, Node: Top, Next: COMMON TASKS, Up: (dir) -hledger(1) hledger 1.20.99 -************************** +hledger(1) +********** -hledger - a command-line accounting tool +A command-line accounting tool for both power users and folks new to +accounting. + + 'hledger' 'hledger [-f FILE] COMMAND [OPTIONS] [ARGS]' -'hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]' -'hledger' + + 'hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]' hledger is a reliable, cross-platform set of programs for tracking money, time, or any other commodity, using double-entry accounting and a @@ -55,72 +58,15 @@ try some commands like 'hledger print' or 'hledger balance'. Run * Menu: * COMMON TASKS:: -* Getting help:: -* Constructing command lines:: -* Starting a journal file:: -* Setting opening balances:: -* Recording transactions:: -* Reconciling:: -* Reporting:: -* Migrating to a new file:: * OPTIONS:: -* General options:: -* Command options:: -* Command arguments:: -* Queries:: -* Special characters in arguments and queries:: -* 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:: * COMMANDS:: -* accounts:: -* activity:: -* add:: -* aregister:: -* balance:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* check:: -* close:: -* codes:: -* commodities:: -* descriptions:: -* diff:: -* files:: -* help:: -* import:: -* incomestatement:: -* notes:: -* payees:: -* prices:: -* print:: -* print-unique:: -* register:: -* register-match:: -* rewrite:: -* roi:: -* stats:: -* tags:: -* test:: -* Add-on commands:: * ENVIRONMENT:: * FILES:: * LIMITATIONS:: * TROUBLESHOOTING::  -File: hledger.info, Node: COMMON TASKS, Next: Getting help, Prev: Top, Up: Top +File: hledger.info, Node: COMMON TASKS, Next: OPTIONS, Prev: Top, Up: Top 1 COMMON TASKS ************** @@ -130,11 +76,22 @@ For more details, see the reference section below, the hledger_journal(5) manual, or the more extensive docs at https://hledger.org. - -File: hledger.info, Node: Getting help, Next: Constructing command lines, Prev: COMMON TASKS, Up: Top +* Menu: -2 Getting help -************** +* 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 @@ -148,10 +105,10 @@ $ hledger help --help # show more detailed help for the help command https://hledger.org#help-feedback  -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: Top +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: COMMON TASKS -3 Constructing command lines -**************************** +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 @@ -168,10 +125,10 @@ happens, here are some tips that may help: * 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: Top +File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: COMMON TASKS -4 Starting a journal file -************************* +1.3 Starting a journal file +=========================== hledger looks for your accounting data in a journal file, '$HOME/.hledger.journal' by default: @@ -207,10 +164,10 @@ Commodities : 0 () Market prices : 0 ()  -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: Top +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: COMMON TASKS -5 Setting opening balances -************************** +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 @@ -290,10 +247,10 @@ the journal. Eg: $ git commit -m 'initial balances' 2020.journal  -File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: Top +File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: COMMON TASKS -6 Recording transactions -************************ +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 @@ -316,10 +273,10 @@ and hledger.org for more ideas: assets:bank:checking $1000  -File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: Top +File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: COMMON TASKS -7 Reconciling -************* +1.6 Reconciling +=============== Periodically you should reconcile - compare your hledger-reported balances against external sources of truth, like bank statements or your @@ -371,10 +328,10 @@ commit: $ git commit -m 'txns' 2020.journal  -File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: Top +File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: COMMON TASKS -8 Reporting -*********** +1.7 Reporting +============= Here are some basic reports. @@ -519,10 +476,10 @@ $ hledger activity -W 2020-01-13 ****  -File: hledger.info, Node: Migrating to a new file, Next: OPTIONS, Prev: Reporting, Up: Top +File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: COMMON TASKS -9 Migrating to a new file -************************* +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, @@ -532,16 +489,37 @@ close command. If using version control, don't forget to 'git add' the new file.  -File: hledger.info, Node: OPTIONS, Next: General options, Prev: Migrating to a new file, Up: Top +File: hledger.info, Node: OPTIONS, Next: COMMANDS, Prev: COMMON TASKS, Up: Top -10 OPTIONS -********** +2 OPTIONS +********* + +* Menu: + +* General options:: +* Command options:: +* Command arguments:: +* Queries:: +* Special characters in arguments and queries:: +* 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, Prev: OPTIONS, Up: Top +File: hledger.info, Node: General options, Next: Command options, Up: OPTIONS -11 General options -****************** +2.1 General options +=================== To see general usage help, including general options which are supported by most hledger commands, run 'hledger -h'. @@ -677,10 +655,10 @@ the last one takes precedence. Some reporting options can also be written as query arguments.  -File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: Top +File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS -12 Command options -****************** +2.2 Command options +=================== To see options for a particular command, including command-specific options, run: 'hledger COMMAND -h'. @@ -693,10 +671,10 @@ 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: Top +File: hledger.info, Node: Command arguments, Next: Queries, Prev: Command options, Up: OPTIONS -13 Command arguments -******************** +2.3 Command arguments +===================== Most hledger commands accept arguments after the command name, which are often a query, filtering the data in some way. @@ -733,10 +711,10 @@ 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: Top +File: hledger.info, Node: Queries, Next: Special characters in arguments and queries, Prev: Command arguments, Up: OPTIONS -14 Queries -********** +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 @@ -842,10 +820,10 @@ 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: Top +File: hledger.info, Node: Special characters in arguments and queries, Next: Unicode characters, Prev: Queries, Up: OPTIONS -15 Special characters in arguments and queries -********************************************** +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 @@ -865,8 +843,8 @@ characters. Eg:  File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries -15.1 More escaping -================== +2.5.1 More escaping +------------------- Characters significant both to the shell and in regular expressions may need one extra level of escaping. These include parentheses, the pipe @@ -882,8 +860,8 @@ should do:  File: hledger.info, Node: Even more escaping, Next: Less escaping, Prev: More escaping, Up: Special characters in arguments and queries -15.2 Even more escaping -======================= +2.5.2 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 @@ -914,8 +892,8 @@ add-on directly:  File: hledger.info, Node: Less escaping, Prev: Even more escaping, Up: Special characters in arguments and queries -15.3 Less escaping -================== +2.5.3 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 @@ -925,10 +903,10 @@ Eg: 'ghci> :main balance cur:\$'  -File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Special characters in arguments and queries, Up: Top +File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Special characters in arguments and queries, Up: OPTIONS -16 Unicode characters -********************* +2.6 Unicode characters +====================== hledger is expected to handle non-ascii characters correctly: @@ -964,10 +942,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: Top +File: hledger.info, Node: Input files, Next: Strict mode, Prev: Unicode characters, Up: OPTIONS -17 Input files -************** +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 @@ -1027,10 +1005,10 @@ big journal. There are some limitations with this: a.journal b.journal | hledger -f- CMD'.  -File: hledger.info, Node: Strict mode, Next: Output destination, Prev: Input files, Up: Top +File: hledger.info, Node: Strict mode, Next: Output destination, Prev: Input files, Up: OPTIONS -18 Strict mode -************** +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 @@ -1052,10 +1030,10 @@ without a lot of declarations: _experimental._  -File: hledger.info, Node: Output destination, Next: Output format, Prev: Strict mode, Up: Top +File: hledger.info, Node: Output destination, Next: Output format, Prev: Strict mode, Up: OPTIONS -19 Output destination -********************* +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: @@ -1070,10 +1048,10 @@ $ 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: Top +File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS -20 Output format -**************** +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'), @@ -1124,10 +1102,10 @@ $ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt postings will be duped.  -File: hledger.info, Node: Regular expressions, Next: Smart dates, Prev: Output format, Up: Top +File: hledger.info, Node: Regular expressions, Next: Smart dates, Prev: Output format, Up: OPTIONS -21 Regular expressions -********************** +2.11 Regular expressions +======================== hledger uses regular expressions in a number of places: @@ -1169,10 +1147,10 @@ they support: See Special characters.  -File: hledger.info, Node: Smart dates, Next: Report start & end date, Prev: Regular expressions, Up: Top +File: hledger.info, Node: Smart dates, Next: Report start & end date, Prev: Regular expressions, Up: OPTIONS -22 Smart dates -************** +2.12 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 @@ -1208,15 +1186,15 @@ 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: Top +File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS -23 Report start & end date -************************** +2.13 Report start & end date +============================ -Most hledger reports show the full span of time represented by the -journal data, by default. So, the effective report start and end dates -will be the earliest and latest transaction or posting dates found in -the journal. +By default, most hledger reports will show the full span of time +represented 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', @@ -1251,10 +1229,10 @@ thismonth' 'date:thismonth'  -File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: Top +File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS -24 Report intervals -******************* +2.14 Report intervals +===================== A report interval can be specified so that commands like register, balance and activity will divide their reports into multiple subperiods. @@ -1264,10 +1242,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: Top +File: hledger.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS -25 Period expressions -********************* +2.15 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. @@ -1304,13 +1282,17 @@ the earliest or latest transaction in your journal: 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; equivalent to “2009/1/1 to 2009/2/1” -'-p "2009/1/1"' just that day; equivalent to “2009/1/1 to 2009/1/2” +'-p "2009"' the year 2009; equivalent to “2009/1/1 to + 2010/1/1” +'-p "2009/1"' the month of jan; equivalent 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 "2009Q1"' first quarter of 2009, equivalent to “2009/1/1 to + 2009/4/1” '-p "q4"' fourth quarter of the current year The argument of '-p' can also begin with, or be, a report interval @@ -1389,10 +1371,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: Top +File: hledger.info, Node: Depth limiting, Next: Pivoting, Prev: Period expressions, Up: OPTIONS -26 Depth limiting -***************** +2.16 Depth limiting +=================== With the '--depth N' option (short form: '-N'), commands like account, balance and register will show only the uppermost accounts in the @@ -1401,10 +1383,10 @@ 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: Top +File: hledger.info, Node: Pivoting, Next: Valuation, Prev: Depth limiting, Up: OPTIONS -27 Pivoting -*********** +2.17 Pivoting +============= Normally hledger sums amounts, and organizes them in a hierarchy, based on account name. The '--pivot FIELD' option causes it to sum and @@ -1458,10 +1440,10 @@ $ hledger balance --pivot member acct:. -2 EUR  -File: hledger.info, Node: Valuation, Next: COMMANDS, Prev: Pivoting, Up: Top +File: hledger.info, Node: Valuation, Prev: Pivoting, Up: OPTIONS -28 Valuation -************ +2.18 Valuation +============== Instead of reporting amounts in their original commodity, hledger can convert them to cost/sale amount (using the conversion rate recorded in @@ -1487,8 +1469,8 @@ usually one of those is all you need.  File: hledger.info, Node: -B Cost, Next: -V Value, Up: Valuation -28.1 -B: Cost -============= +2.18.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. @@ -1496,8 +1478,8 @@ 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 -28.2 -V: Value -============== +2.18.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 @@ -1506,8 +1488,8 @@ _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 -28.3 -X: Value in specified commodity -===================================== +2.18.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 @@ -1516,8 +1498,8 @@ that.  File: hledger.info, Node: Valuation date, Next: Market prices, Prev: -X Value in specified commodity, Up: Valuation -28.4 Valuation date -=================== +2.18.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 @@ -1525,7 +1507,7 @@ prices will be used. For single period reports, if an explicit report end date is specified, that will be used as the valuation date; otherwise the -valuation date is "today". +valuation date is the journal's end date. For multiperiod reports, each column/period is valued on the last day of the period, by default. @@ -1533,8 +1515,8 @@ of the period, by default.  File: hledger.info, Node: Market prices, Next: --infer-value market prices from transactions, Prev: Valuation date, Up: Valuation -28.5 Market prices -================== +2.18.5 Market prices +-------------------- _(experimental)_ @@ -1564,8 +1546,8 @@ converted.  File: hledger.info, Node: --infer-value market prices from transactions, Next: Valuation commodity, Prev: Market prices, Up: Valuation -28.6 -infer-value: market prices from transactions -================================================== +2.18.6 -infer-value: market prices from transactions +---------------------------------------------------- _(experimental)_ @@ -1599,8 +1581,8 @@ you, read all of this Valuation section carefully, and try adding  File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-value market prices from transactions, Up: Valuation -28.7 Valuation commodity -======================== +2.18.7 Valuation commodity +-------------------------- _(experimental)_ @@ -1639,8 +1621,8 @@ converted.  File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation -28.8 Simple valuation examples -============================== +2.18.8 Simple valuation examples +-------------------------------- Here are some quick examples of '-V': @@ -1674,8 +1656,8 @@ $ hledger -f t.j bal -N euros -V  File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation -28.9 -value: Flexible valuation -=============================== +2.18.9 -value: Flexible valuation +--------------------------------- '-B', '-V' and '-X' are special cases of the more general '--value' option: @@ -1722,8 +1704,8 @@ 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 -28.10 More valuation examples -============================= +2.18.10 More valuation examples +------------------------------- Here are some examples showing the effect of '--value', as seen with 'print': @@ -1836,8 +1818,8 @@ $ hledger print -X A  File: hledger.info, Node: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation -28.11 Effect of valuation on reports -==================================== +2.18.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 @@ -1970,32 +1952,102 @@ _report interval_ subperiods).  -File: hledger.info, Node: COMMANDS, Next: accounts, Prev: Valuation, Up: Top +File: hledger.info, Node: COMMANDS, Next: ENVIRONMENT, Prev: OPTIONS, Up: Top -29 COMMANDS -*********** +3 COMMANDS +********** -hledger provides a number of subcommands; 'hledger' with no arguments -shows a list. +hledger provides a number of commands for producing reports and managing +your data. Run 'hledger' with no arguments to list the commands +available. - If you install additional 'hledger-*' packages, or if you put -programs or scripts named 'hledger-NAME' in your PATH, these will also -be listed as subcommands. + 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'. - Run a subcommand by writing its name as first argument (eg 'hledger -incomestatement'). You can also write one of the standard short aliases -displayed in parentheses in the command list ('hledger b'), or any any -unambiguous prefix of a command name ('hledger inc'). + Here are the built-in commands: - Here are all the builtin commands in alphabetical order. See also -'hledger' for a more organised command list, and 'hledger CMD -h' for -detailed command help. + *Data entry (these modify the journal file):* + + * add - add transactions using guided prompts + * import - add any new transactions from other files (eg csv) + + *Data management*: + + * check - check for various kinds of issue in the data + * close (equity) - generate balance-resetting transactions + * diff - compare account transactions in two journal files + * rewrite - generate extra postings, similar to print -auto + + *Financial statements:* + + * 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 + * 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 + * codes - show transaction codes + * commodities - show commodity/currency symbols + * descriptions - show unique transaction descriptions + * files - show input file paths + * 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-unique - show only transactions with unique descriptions + * 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 + + Next, the detailed command docs, in alphabetical order. + +* Menu: + +* accounts:: +* activity:: +* add:: +* aregister:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check:: +* close:: +* codes:: +* commodities:: +* descriptions:: +* diff:: +* files:: +* help:: +* import:: +* incomestatement:: +* notes:: +* rewrite:: +* roi:: +* stats:: +* tags:: +* test:: +* Add-on commands:: +* Add-on command flags:: +* Making add-on commands::  -File: hledger.info, Node: accounts, Next: activity, Prev: COMMANDS, Up: Top +File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS -30 accounts -*********** +3.1 accounts +============ accounts, a Show account names. @@ -2022,10 +2074,10 @@ income:salary liabilities:debts  -File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: Top +File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS -31 activity -*********** +3.2 activity +============ activity Show an ascii barchart of posting counts per interval. @@ -2043,10 +2095,10 @@ $ hledger activity --quarterly 2008-10-01 **  -File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: Top +File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: COMMANDS -32 add -****** +3.3 add +======= add Prompt for transactions and add them to the journal. Any arguments will @@ -2114,10 +2166,10 @@ Date [2015/05/22]: $ file path ends with a period, as that would cause problems (#1056).  -File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: Top +File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: COMMANDS -33 aregister -************ +3.4 aregister +============= aregister, areg Show transactions affecting a particular account, and the account's @@ -2150,16 +2202,18 @@ transactions shown. 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 +options The output formats supported are 'txt', 'csv', and 'json'. + * Menu: * aregister and custom posting dates:: -* Output format::  -File: hledger.info, Node: aregister and custom posting dates, Next: , Up: aregister +File: hledger.info, Node: aregister and custom posting dates, Up: aregister -33.1 aregister and custom posting dates -======================================= +3.4.1 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. @@ -2171,12 +2225,6 @@ matching the one shown by 'register -H' with the same arguments. 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. -33.2 Output format -================== - -This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', and 'json'. - Examples: Show all transactions and historical running balance in the first @@ -2190,10 +2238,10 @@ accounts during july: $ hledger areg assets date:jul  -File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: Top +File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: COMMANDS -34 balance -********** +3.5 balance +=========== balance, bal, b Show accounts and their balances. @@ -2218,6 +2266,10 @@ 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). + This command also supports the output destination and output format +options The output formats supported are (in most modes): 'txt', 'csv', +'html', and 'json'. + The balance command can produce several styles of report: * Menu: @@ -2231,13 +2283,12 @@ is used to ensure this (more below). * Sorting by amount:: * Multicolumn balance report:: * Budget report:: -* Output format::  File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance -34.1 Classic balance report -=========================== +3.5.1 Classic balance report +---------------------------- This is the original balance report, as found in Ledger. It usually looks like this: @@ -2282,8 +2333,8 @@ $ 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 -34.2 Customising the classic balance report -=========================================== +3.5.2 Customising the classic balance report +-------------------------------------------- You can customise the layout of classic balance reports with '--format FMT': @@ -2344,8 +2395,8 @@ may be needed to get pleasing results.  File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance -34.3 Colour support -=================== +3.5.3 Colour support +-------------------- In terminal output, when colour is enabled, the balance command shows negative amounts in red. @@ -2353,8 +2404,8 @@ negative amounts in red.  File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance -34.4 Flat mode -============== +3.5.4 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 @@ -2369,8 +2420,8 @@ $ 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 -34.5 Depth limited balance reports -================================== +3.5.5 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 @@ -2388,8 +2439,8 @@ show inclusive balances at the depth limit.  File: hledger.info, Node: Percentages, Next: Sorting by amount, Prev: Depth limited balance reports, Up: balance -34.6 Percentages -================ +3.5.6 Percentages +----------------- With '-%' or '--percent', balance reports show each account's value expressed as a percentage of the column's total. This is useful to get @@ -2420,8 +2471,8 @@ 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 -34.7 Sorting by amount -====================== +3.5.7 Sorting by amount +----------------------- With '-S'/'--sort-amount', accounts with the largest (most positive) balances are shown first. For example, 'hledger bal expenses -MAS' @@ -2436,8 +2487,8 @@ 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 -34.8 Multicolumn balance report -=============================== +3.5.8 Multicolumn balance report +-------------------------------- Multicolumn or tabular balance reports are a very useful hledger feature, and usually the preferred style. They share many of the above @@ -2555,10 +2606,10 @@ into 'less -RS' (-R for colour, -S to chop long lines). Eg: 'hledger bal -D --color=yes | less -RS'.  -File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance +File: hledger.info, Node: Budget report, Prev: Multicolumn balance report, Up: balance -34.9 Budget report -================== +3.5.9 Budget report +------------------- With '--budget', extra columns are displayed showing budget goals for each account and period, if any. Budget goals are defined by periodic @@ -2681,8 +2732,8 @@ Budget performance in 2017/11/01-2017/12/31:  File: hledger.info, Node: Budget report start date, Next: Nested budgets, Up: Budget report -34.9.1 Budget report start date -------------------------------- +3.5.9.1 Budget report start date +................................ 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 @@ -2725,8 +2776,8 @@ Budget performance in 2020-01-01..2020-01-15:  File: hledger.info, Node: Nested budgets, Prev: Budget report start date, Up: Budget report -34.9.2 Nested budgets ---------------------- +3.5.9.2 Nested budgets +...................... 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 @@ -2810,18 +2861,11 @@ Budget performance in 2019/01: ----------------------------------------++------------------------------- || 0 [ 0] -34.10 Output format -=================== - -This command also supports the output destination and output format -options The output formats supported are (in most modes): 'txt', 'csv', -'html', and 'json'. -  -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: Top +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS -35 balancesheet -*************** +3.6 balancesheet +================ balancesheet, bs This command displays a balance sheet, showing historical ending @@ -2869,10 +2913,10 @@ options The output formats supported are 'txt', 'csv', 'html', and (experimental) 'json'.  -File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: Top +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS -36 balancesheetequity -********************* +3.7 balancesheetequity +====================== balancesheetequity, bse This command displays a balance sheet, showing historical ending @@ -2915,10 +2959,10 @@ options The output formats supported are 'txt', 'csv', 'html', and (experimental) 'json'.  -File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: Top +File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: COMMANDS -37 cashflow -*********** +3.8 cashflow +============ cashflow, cf This command displays a cashflow statement, showing the inflows and @@ -2957,10 +3001,10 @@ options The output formats supported are 'txt', 'csv', 'html', and (experimental) 'json'.  -File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: Top +File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: COMMANDS -38 check -******** +3.9 check +========= check Check for various kinds of errors in your data. _experimental_ @@ -2986,8 +3030,8 @@ hledger check ordereddates uniqueleafnames # basic + specified checks  File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check -38.1 Basic checks -================= +3.9.1 Basic checks +------------------ These are always run by this command and other commands: @@ -3004,8 +3048,8 @@ These are always run by this command and other commands:  File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check -38.2 Strict checks -================== +3.9.2 Strict checks +------------------- These are always run by this and other commands when '-s'/'--strict' is used (strict mode): @@ -3018,8 +3062,8 @@ used (strict mode):  File: hledger.info, Node: Other checks, Next: Add-on checks, Prev: Strict checks, Up: check -38.3 Other checks -================= +3.9.3 Other checks +------------------ These checks can be run by specifying their names as arguments to the check command: @@ -3033,8 +3077,8 @@ check command:  File: hledger.info, Node: Add-on checks, Prev: Other checks, Up: check -38.4 Add-on checks -================== +3.9.4 Add-on checks +------------------- Some checks are not yet integrated with this command, but are available as add-on commands in @@ -3050,10 +3094,10 @@ https://github.com/simonmichael/hledger/tree/master/bin: Cookbook -> Scripting may be helpful.  -File: hledger.info, Node: close, Next: codes, Prev: check, Up: Top +File: hledger.info, Node: close, Next: codes, Prev: check, Up: COMMANDS -39 close -******** +3.10 close +========== close, equity Prints a "closing balances" transaction and an "opening balances" @@ -3092,8 +3136,8 @@ you have many foreign currency or investment transactions.  File: hledger.info, Node: close usage, Up: close -39.1 close usage -================ +3.10.1 close usage +------------------ If you split your journal files by time (eg yearly), you will typically run this command at the end of the year, and save the closing @@ -3161,10 +3205,10 @@ breaking balance assertions: assets:checking  -File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: Top +File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS -40 codes -******** +3.11 codes +========== codes List the codes seen in transactions, in the order parsed. @@ -3207,19 +3251,19 @@ $ hledger codes -E 126  -File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: Top +File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS -41 commodities -************** +3.12 commodities +================ commodities List all commodity/currency symbols used or declared in the journal.  -File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: Top +File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS -42 descriptions -*************** +3.13 descriptions +================= descriptions List the unique descriptions that appear in transactions. @@ -3236,10 +3280,10 @@ Gas Station | Petrol Person A  -File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: Top +File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS -43 diff -******* +3.14 diff +========= diff Compares a particular account's transactions in two input files. It @@ -3271,20 +3315,20 @@ These transactions are in the first file only: These transactions are in the second file only:  -File: hledger.info, Node: files, Next: help, Prev: diff, Up: Top +File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS -44 files -******** +3.15 files +========== files List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown.  -File: hledger.info, Node: help, Next: import, Prev: files, Up: Top +File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS -45 help -******* +3.16 help +========= help Show any of the hledger manuals. @@ -3321,10 +3365,10 @@ DESCRIPTION ...  -File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: Top +File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS -46 import -********* +3.17 import +=========== import Read new transactions added to each FILE since last run, and add them to @@ -3353,8 +3397,8 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions  File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Up: import -46.1 Importing balance assignments -================================== +3.17.1 Importing balance assignments +------------------------------------ Entries added by import will have their posting amounts made explicit (like 'hledger print -x'). This means that any balance assignments in @@ -3372,17 +3416,17 @@ please test it and send a pull request.)  File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import -46.2 Commodity display styles -============================= +3.17.2 Commodity display styles +------------------------------- Imported amounts will be formatted according to the canonical commodity styles (declared or inferred) in the main journal file.  -File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: Top +File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS -47 incomestatement -****************** +3.18 incomestatement +==================== incomestatement, is @@ -3429,10 +3473,10 @@ options The output formats supported are 'txt', 'csv', 'html', and (experimental) 'json'.  -File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: Top +File: hledger.info, Node: notes, Next: rewrite, Prev: incomestatement, Up: COMMANDS -48 notes -******** +3.19 notes +========== notes List the unique notes that appear in transactions. @@ -3449,318 +3493,10 @@ Petrol Snacks  -File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: Top +File: hledger.info, Node: rewrite, Next: roi, Prev: notes, Up: COMMANDS -49 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: Top - -50 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: Top - -51 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: Top - -52 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: Top - -53 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 - -53.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: Top - -54 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: Top - -55 rewrite -********** +3.20 rewrite +============ rewrite Print all transactions, rewriting the postings of matched transactions. @@ -3807,12 +3543,14 @@ commodity. * Menu: * Re-write rules in a file:: +* Diff output format:: +* rewrite vs print --auto::  -File: hledger.info, Node: Re-write rules in a file, Up: rewrite +File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite -55.1 Re-write rules in a file -============================= +3.20.1 Re-write rules in a file +------------------------------- During the run this tool will execute so called "Automated Transactions" found in any journal it process. I.e instead of specifying this @@ -3846,15 +3584,10 @@ $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) journal is important. You can re-use result of previously added postings. -* Menu: - -* Diff output format:: -* rewrite vs print --auto:: -  -File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file +File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite -55.1.1 Diff output format +3.20.2 Diff output format ------------------------- To use this tool for batch modification of your journal files you may @@ -3893,9 +3626,9 @@ output from 'hledger print'. https://github.com/simonmichael/hledger/issues/99  -File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file +File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite -55.1.2 rewrite vs. print -auto +3.20.3 rewrite vs. print -auto ------------------------------ This command predates print -auto, and currently does much the same @@ -3913,10 +3646,10 @@ thing, but with these differences: print -auto applies rules specified in the journal.  -File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: Top +File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS -56 roi -****** +3.21 roi +======== roi Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on @@ -4169,10 +3902,10 @@ $ hledger roi -Y --inv investment --pnl "unrealized" +---++------------+------------++---------------+----------+-------------+------++-------+--------+  -File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: Top +File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS -57 stats -******** +3.22 stats +========== stats Show some journal statistics. @@ -4200,10 +3933,10 @@ Market prices : 12 ($) selection.  -File: hledger.info, Node: tags, Next: test, Prev: stats, Up: Top +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS -58 tags -******* +3.23 tags +========= tags List the unique tag names used in the journal. With a TAGREGEX @@ -4220,10 +3953,10 @@ parsed from the input data, including duplicates. they are omitted.  -File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: Top +File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: COMMANDS -59 test -******* +3.24 test +========= test Run built-in unit tests. @@ -4247,100 +3980,82 @@ $ hledger test -- -pData.Amount --color=never ('-- --help' currently doesn't show them).  -File: hledger.info, Node: Add-on commands, Next: ENVIRONMENT, Prev: test, Up: Top +File: hledger.info, Node: Add-on commands, Next: Add-on command flags, Prev: test, Up: COMMANDS -60 Add-on commands -****************** +3.25 Add-on commands +==================== -hledger also searches for external add-on commands, and will include -these in the commands list. These are programs or scripts in your PATH -whose name starts with 'hledger-' and ends with a recognised file -extension (currently: no extension, 'bat','com','exe', -'hs','lhs','pl','py','rb','rkt','sh'). +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-ons can be invoked like any hledger command, but there are a few -things to be aware of. Eg if the 'hledger-web' add-on is installed, + These offical add-ons are maintained and released along with hledger: - * 'hledger -h web' shows hledger's help, while 'hledger web -h' shows - hledger-web's help. + * ui an efficient terminal interface for hledger (TUI) + * web a simple web interface for hledger (WUI) - * Flags specific to the add-on must have a preceding '--' to hide - them from hledger. So 'hledger web --serve --port 9000' will be - rejected; you must use 'hledger web -- --serve --port 9000'. + These add-ons are maintained separately: - * You can always run add-ons directly if preferred: 'hledger-web - --serve --port 9000'. + * 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: + +$ hledger web -- --serve + + and not: + +$ hledger web --serve + + (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 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-on program directly, eg: + +$ hledger-web --serve + + +File: hledger.info, Node: Making add-on commands, Prev: Add-on command flags, Up: COMMANDS + +3.27 Making add-on commands +=========================== + +Add-on commands are programs or scripts in your PATH + + * 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. 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 (and -haskell) library functions that built-in commands do, for command-line -options, journal parsing, reporting, etc. - - Two important add-ons are the hledger-ui and hledger-web user -interfaces. These are maintained and released along with hledger: - -* Menu: - -* ui:: -* web:: -* iadd:: -* interest:: -* stockquotes:: +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.  -File: hledger.info, Node: ui, Next: web, Up: Add-on commands +File: hledger.info, Node: ENVIRONMENT, Next: FILES, Prev: COMMANDS, Up: Top -60.1 ui -======= - -hledger-ui provides an efficient terminal interface. - - -File: hledger.info, Node: web, Next: iadd, Prev: ui, Up: Add-on commands - -60.2 web -======== - -hledger-web provides a simple web interface. - - Third party add-ons, maintained separately from hledger, include: - - -File: hledger.info, Node: iadd, Next: interest, Prev: web, Up: Add-on commands - -60.3 iadd -========= - -hledger-iadd is a more interactive, terminal UI replacement for the add -command. - - -File: hledger.info, Node: interest, Next: stockquotes, Prev: iadd, Up: Add-on commands - -60.4 interest -============= - -hledger-interest generates interest transactions for an account -according to various schemes. - - -File: hledger.info, Node: stockquotes, Prev: interest, Up: Add-on commands - -60.5 stockquotes -================ - -hledger-stockquotes downloads market prices for the commodities in your -journal from AlphaVantage. - - A few more experimental or old add-ons can be found in hledger's bin/ -directory. These are typically prototypes and not guaranteed to work. - - -File: hledger.info, Node: ENVIRONMENT, Next: FILES, Prev: Add-on commands, Up: Top - -61 ENVIRONMENT -************** +4 ENVIRONMENT +************* *LEDGER_FILE* The journal file path when not specified with '-f'. Default: '~/.hledger.journal' (on windows, perhaps @@ -4372,8 +4087,8 @@ use ANSI color codes in terminal output. This overrides the  File: hledger.info, Node: FILES, Next: LIMITATIONS, Prev: ENVIRONMENT, Up: Top -62 FILES -******** +5 FILES +******* Reads data from one or more files in hledger journal, timeclock, timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or @@ -4383,8 +4098,8 @@ timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or  File: hledger.info, Node: LIMITATIONS, Next: TROUBLESHOOTING, Prev: FILES, Up: Top -63 LIMITATIONS -************** +6 LIMITATIONS +************* The need to precede add-on command options with '--' when invoked from hledger is awkward. @@ -4411,8 +4126,8 @@ Ledger.  File: hledger.info, Node: TROUBLESHOOTING, Prev: LIMITATIONS, Up: Top -64 TROUBLESHOOTING -****************** +7 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 @@ -4484,224 +4199,197 @@ $ LANG=en_US.UTF-8 hledger -f my.journal print  Tag Table: Node: Top68 -Node: COMMON TASKS3281 -Ref: #common-tasks3398 -Node: Getting help3605 -Ref: #getting-help3745 -Node: Constructing command lines4298 -Ref: #constructing-command-lines4477 -Node: Starting a journal file5174 -Ref: #starting-a-journal-file5359 -Node: Setting opening balances6547 -Ref: #setting-opening-balances6730 -Node: Recording transactions9871 -Ref: #recording-transactions10038 -Node: Reconciling10594 -Ref: #reconciling10724 -Node: Reporting12981 -Ref: #reporting13108 -Node: Migrating to a new file17107 -Ref: #migrating-to-a-new-file17258 -Node: OPTIONS17557 -Ref: #options17684 -Node: General options17684 -Ref: #general-options17819 -Node: Command options21220 -Ref: #command-options21365 -Node: Command arguments21765 -Ref: #command-arguments21906 -Node: Queries22786 -Ref: #queries22935 -Node: Special characters in arguments and queries26897 -Ref: #special-characters-in-arguments-and-queries27119 -Node: More escaping27570 -Ref: #more-escaping27730 -Node: Even more escaping28026 -Ref: #even-more-escaping28218 -Node: Less escaping28892 -Ref: #less-escaping29052 -Node: Unicode characters29297 -Ref: #unicode-characters29473 -Node: Input files30885 -Ref: #input-files31015 -Node: Strict mode33314 -Ref: #strict-mode33444 -Node: Output destination34092 -Ref: #output-destination34238 -Node: Output format34663 -Ref: #output-format34807 -Node: Regular expressions36974 -Ref: #regular-expressions37123 -Node: Smart dates38859 -Ref: #smart-dates39002 -Node: Report start & end date40363 -Ref: #report-start-end-date40527 -Node: Report intervals42024 -Ref: #report-intervals42181 -Node: Period expressions42571 -Ref: #period-expressions42723 -Node: Depth limiting47096 -Ref: #depth-limiting47232 -Node: Pivoting47564 -Ref: #pivoting47679 -Node: Valuation49355 -Ref: #valuation49466 -Node: -B Cost50155 -Ref: #b-cost50255 -Node: -V Value50388 -Ref: #v-value50530 -Node: -X Value in specified commodity50725 -Ref: #x-value-in-specified-commodity50920 -Node: Valuation date51069 -Ref: #valuation-date51233 -Node: Market prices51655 -Ref: #market-prices51831 -Node: --infer-value market prices from transactions52773 -Ref: #infer-value-market-prices-from-transactions53018 -Node: Valuation commodity54300 -Ref: #valuation-commodity54505 -Node: Simple valuation examples55731 -Ref: #simple-valuation-examples55929 -Node: --value Flexible valuation56588 -Ref: #value-flexible-valuation56792 -Node: More valuation examples58739 -Ref: #more-valuation-examples58944 -Node: Effect of valuation on reports60949 -Ref: #effect-of-valuation-on-reports61133 -Node: COMMANDS68152 -Ref: #commands68261 -Node: accounts68943 -Ref: #accounts69051 -Node: activity69750 -Ref: #activity69853 -Node: add70236 -Ref: #add70330 -Node: aregister73123 -Ref: #aregister73228 -Node: aregister and custom posting dates74601 -Ref: #aregister-and-custom-posting-dates74772 -Ref: #output-format-175363 -Node: balance75768 -Ref: #balance75878 -Node: Classic balance report77358 -Ref: #classic-balance-report77529 -Node: Customising the classic balance report78853 -Ref: #customising-the-classic-balance-report79079 -Node: Colour support81155 -Ref: #colour-support81320 -Node: Flat mode81416 -Ref: #flat-mode81562 -Node: Depth limited balance reports81975 -Ref: #depth-limited-balance-reports82158 -Node: Percentages82614 -Ref: #percentages82769 -Node: Sorting by amount83906 -Ref: #sorting-by-amount84070 -Node: Multicolumn balance report84564 -Ref: #multicolumn-balance-report84748 -Node: Budget report90345 -Ref: #budget-report90486 -Node: Budget report start date95775 -Ref: #budget-report-start-date95938 -Node: Nested budgets97270 -Ref: #nested-budgets97413 -Ref: #output-format-2100894 -Node: balancesheet101055 -Ref: #balancesheet101184 -Node: balancesheetequity102696 -Ref: #balancesheetequity102838 -Node: cashflow103914 -Ref: #cashflow104029 -Node: check105245 -Ref: #check105341 -Node: Basic checks105946 -Ref: #basic-checks106060 -Node: Strict checks106553 -Ref: #strict-checks106690 -Node: Other checks106933 -Ref: #other-checks107069 -Node: Add-on checks107367 -Ref: #add-on-checks107483 -Node: close107936 -Ref: #close108029 -Node: close usage109551 -Ref: #close-usage109640 -Node: codes112453 -Ref: #codes112552 -Node: commodities113264 -Ref: #commodities113382 -Node: descriptions113464 -Ref: #descriptions113583 -Node: diff113887 -Ref: #diff113984 -Node: files115031 -Ref: #files115122 -Node: help115269 -Ref: #help115360 -Node: import116441 -Ref: #import116546 -Node: Importing balance assignments117468 -Ref: #importing-balance-assignments117645 -Node: Commodity display styles118294 -Ref: #commodity-display-styles118461 -Node: incomestatement118590 -Ref: #incomestatement118714 -Node: notes120059 -Ref: #notes120163 -Node: payees120531 -Ref: #payees120628 -Node: prices121048 -Ref: #prices121145 -Node: print121486 -Ref: #print121587 -Node: print-unique126383 -Ref: #print-unique126500 -Node: register126785 -Ref: #register126903 -Node: Custom register output131352 -Ref: #custom-register-output131477 -Node: register-match132814 -Ref: #register-match132939 -Node: rewrite133290 -Ref: #rewrite133396 -Node: Re-write rules in a file135251 -Ref: #re-write-rules-in-a-file135381 -Node: Diff output format136591 -Ref: #diff-output-format136756 -Node: rewrite vs print --auto137848 -Ref: #rewrite-vs.-print---auto138023 -Node: roi138579 -Ref: #roi138668 -Node: stats150878 -Ref: #stats150968 -Node: tags151756 -Ref: #tags151845 -Node: test152364 -Ref: #test152463 -Node: Add-on commands153210 -Ref: #add-on-commands153338 -Node: ui154697 -Ref: #ui154781 -Node: web154835 -Ref: #web154934 -Node: iadd155050 -Ref: #iadd155157 -Node: interest155239 -Ref: #interest155362 -Node: stockquotes155457 -Ref: #stockquotes155573 -Node: ENVIRONMENT155818 -Ref: #environment155939 -Node: FILES156924 -Ref: #files-1157029 -Node: LIMITATIONS157242 -Ref: #limitations157363 -Node: TROUBLESHOOTING158106 -Ref: #troubleshooting158221 +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  End Tag Table - - -Local Variables: -coding: utf-8 -End: diff --git a/hledger/hledger.txt b/hledger/hledger.txt index b15a0bbe8..2c9bcb362 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1,39 +1,42 @@ -hledger(1) hledger User Manuals hledger(1) +HLEDGER(1) hledger User Manuals HLEDGER(1) NAME - hledger - a command-line accounting tool + A command-line accounting tool for both power users and folks new to + accounting. SYNOPSIS - hledger [-f FILE] COMMAND [OPTIONS] [ARGS] - hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] hledger + hledger [-f FILE] COMMAND [OPTIONS] [ARGS] + + hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] + DESCRIPTION - hledger is a reliable, cross-platform set of programs for tracking - money, time, or any other commodity, using double-entry accounting and - a simple, editable file format. hledger is inspired by and largely + hledger is a reliable, cross-platform set of programs for tracking + money, time, or any other commodity, using double-entry accounting and + a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). - This is hledger's command-line interface (there are also terminal and - web interfaces). Its basic function is to read a plain text file de- - scribing financial transactions (in accounting terms, a general jour- - nal) and print useful reports on standard output, or export them as - CSV. hledger can also read some other file formats such as CSV files, - translating them to journal format. Additionally, hledger lists other - hledger-* executables found in the user's $PATH and can invoke them as + This is hledger's command-line interface (there are also terminal and + web interfaces). Its basic function is to read a plain text file de- + scribing financial transactions (in accounting terms, a general jour- + nal) and print useful reports on standard output, or export them as + CSV. hledger can also read some other file formats such as CSV files, + translating them to journal format. Additionally, hledger lists other + hledger-* executables found in the user's $PATH and can invoke them as subcommands. - hledger reads data from one or more files in hledger journal, time- - clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + hledger reads data from one or more files in hledger journal, time- + clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must - be a real environment variable, not a shell variable. You can specify + be a real environment variable, not a shell variable. You can specify standard input with -f-. - Transactions are dated movements of money between two (or more) named + Transactions are dated movements of money between two (or more) named accounts, and are recorded with journal entries like this: 2015/10/16 bought food @@ -42,20 +45,20 @@ DESCRIPTION For more about this format, see hledger_journal(5). - Most users use a text editor to edit the journal, usually with an edi- + Most users use a text editor to edit the journal, usually with an edi- tor mode such as ledger-mode for added convenience. hledger's interac- - tive add command is another way to record new transactions. hledger + tive add command is another way to record new transactions. hledger never changes existing transactions. - To get started, you can either save some entries like the above in - ~/.hledger.journal, or run hledger add and follow the prompts. Then - try some commands like hledger print or hledger balance. Run hledger + To get started, you can either save some entries like the above in + ~/.hledger.journal, or run hledger add and follow the prompts. Then + try some commands like hledger print or hledger balance. 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 + 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 @@ -71,26 +74,26 @@ COMMON TASKS https://hledger.org#help-feedback Constructing command lines - hledger has an extensive and powerful command line interface. We + 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 + 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 + 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- + 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, + hledger looks for your accounting data in a journal file, $HOME/.hledger.journal by default: $ hledger stats @@ -98,9 +101,9 @@ COMMON TASKS 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. + 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 + and to start a new file each year. So you could do something like this: $ mkdir ~/finance @@ -124,20 +127,20 @@ COMMON TASKS 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 + 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 + 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 + 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- + 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 + o The first way: open the journal in any text editor and save an entry like this: 2020-01-01 * opening balances @@ -147,19 +150,19 @@ COMMON TASKS liabilities:creditcard $-50 = $-50 equity:opening/closing balances - These are start-of-day balances, ie whatever was in the account at + 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 + 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 + 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 + The = amounts are optional balance assertions, providing extra error checking. - o The second way: run hledger add and follow the prompts to record a + o The second way: run hledger add and follow the prompts to record a similar transaction: $ hledger add @@ -196,18 +199,18 @@ COMMON TASKS 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 + 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 + 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 + Here are some simple transactions, see the hledger_journal(5) manual and hledger.org for more ideas: 2020/1/10 * gift received @@ -223,22 +226,22 @@ COMMON TASKS 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- + 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 + 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: @@ -248,26 +251,26 @@ COMMON TASKS 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 + 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- + 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- + 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, + 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- + If you're using version control, this can be another good time to com- mit: $ git commit -m 'txns' 2020.journal @@ -339,7 +342,7 @@ COMMON TASKS -------------------- 0 - Show only asset and liability balances, as a flat list, limited to + Show only asset and liability balances, as a flat list, limited to depth 2: $ hledger bal assets liabilities --flat -2 @@ -349,7 +352,7 @@ COMMON TASKS -------------------- $4055 - Show the same thing without negative numbers, formatted as a simple + Show the same thing without negative numbers, formatted as a simple balance sheet: $ hledger bs --flat -2 @@ -416,16 +419,16 @@ COMMON TASKS 2020-01-13 **** Migrating to a new file - At the end of the year, you may want to continue your journal in a new + 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 + 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: @@ -446,7 +449,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 @@ -465,7 +468,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: @@ -492,7 +495,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 @@ -515,21 +518,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 @@ -538,15 +541,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 @@ -558,26 +561,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 @@ -589,7 +592,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"$" @@ -601,16 +604,16 @@ OPTIONS See also: Save frequently used options. Queries - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a web search: one or more space-separated search terms, quotes to enclose - whitespace, prefixes to match specific fields, a not: prefix to negate + 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 + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match (or negatively match): o any of the description terms AND @@ -631,31 +634,31 @@ OPTIONS o match all the other terms. - The following kinds of search terms can be used. Remember these can + The following kinds of search terms can be used. Remember these can also be prefixed with not:, eg to exclude a particular subaccount. REGEX, acct:REGEX - match account names by this regular expression. (With no pre- + match account names by this regular expression. (With no pre- fix, 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 + 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, + are compared. Otherwise, the absolute magnitudes are compared, ignoring sign. code:REGEX match by transaction code (eg check number) cur:REGEX - match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a par- + match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a par- tial match, use .*REGEX.*). Note, to match characters which are regex-significant, like the dollar sign ($), you need to prepend - \. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: hledger + \. 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 @@ -663,20 +666,20 @@ OPTIONS 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 + 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 + match (or display, depending on command) accounts at or above this depth note:REGEX - match transaction notes (part of description right of |, or + match transaction notes (part of description right of |, or whole description when there's no |) payee:REGEX @@ -690,35 +693,35 @@ OPTIONS 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 + match by tag name, and optionally also by tag value. Note a + tag: query is considered to match a transaction if it matches + any of the postings. Also remember that postings inherit the tags of their parent transaction. The following special search term is used automatically in hledger-web, only: inacct:ACCTNAME - tells hledger-web to show the transaction register for this ac- + tells hledger-web to show the transaction register for this ac- count. Can be filtered further with acct etc. Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps + is equivalent to --depth 2). Generally you can mix options and query + arguments, and the resulting query will be their intersection (perhaps excluding the -p/--period option). Special characters in arguments and queries In shell command lines, option and argument values which contain "prob- lematic" characters, ie spaces, and also characters significant to your - shell such as <, >, (, ), | and $, should be escaped by enclosing them + 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- + 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 + 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: @@ -730,8 +733,8 @@ OPTIONS 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 + 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:'\\$' @@ -756,8 +759,8 @@ OPTIONS 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 + 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: @@ -766,41 +769,41 @@ OPTIONS 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 + 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- + 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- + 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..) + 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- + 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, + 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 + something like C:/Users/USER/.hledger.journal). You can override this with the $LEDGER_FILE environment variable: $ setenv LEDGER_FILE ~/finance/2016.journal @@ -814,52 +817,52 @@ OPTIONS $ cat some.journal | hledger -f- - Usually the data file is in hledger's journal format, but it can be in + 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 + journal hledger journal files and some Ledger .journal .j .hledger journals, for transactions .ledger - time- timeclock files, for precise time log- .timeclock + 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 + 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 + 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 + 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 + 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 + 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 + tant errors are detected, while still accepting easy journal files without a lot of declarations: o Are the input files parseable, with valid syntax ? @@ -870,7 +873,7 @@ OPTIONS With the -s/--strict flag, additional checks are performed: - o Are all accounts posted to, declared with an account directive ? + o Are all accounts posted to, declared with an account directive ? (Account error checking) o Are all commodities declared with a commodity directive ? (Commodity @@ -886,8 +889,8 @@ OPTIONS $ 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 + 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 @@ -896,7 +899,7 @@ OPTIONS 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- + are CSV (csv), HTML (html), JSON (json) and SQL (sql). This is con- trolled by the -O/--output-format option: $ hledger print -O csv @@ -911,99 +914,98 @@ OPTIONS Some notes about JSON output: - o This feature is marked experimental, and not yet much used; you + 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 + 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 + 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 + 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 + 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 + 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 + 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: + 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, + 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 + 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 + 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 + 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, + 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, + 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 + 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- + 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 + 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/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 @@ -1012,48 +1014,48 @@ OPTIONS 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- + Counterexamples - malformed digit sequences might give surprising re- sults: - 201813 6 digits with an invalid month is parsed as start of + 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 + 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 - Most hledger reports show the full span of time represented by the - journal data, by default. So, the effective report start and end dates - will be the earliest and latest transaction or posting dates found in - the journal. + 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, + 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 + 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 + 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 + 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 + -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- + date:2016/3/17.. the above written as queries instead (.. can also be re- placed with -) date:..12/1 date:thismonth.. @@ -1061,31 +1063,31 @@ OPTIONS 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- + 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 + 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 + 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 + 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 + Dates are smart dates, so if the current year is 2009, the above can also be written as: -p "1/1 4/1" @@ -1099,73 +1101,73 @@ OPTIONS 1, 2009 -p "from 2009/1" the same -p "from 2009" the same - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 - A single date with no "from" or "to" defines both the start and end + A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- + -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 + -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, + -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- + 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 + 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 + 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- + 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- + -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 + -p "monthly in starts on 2018/11/01 2008/11/25" - -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, + -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- + 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 + 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, + -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, + -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 + 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 + 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]. @@ -1175,42 +1177,42 @@ OPTIONS -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 + -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 + -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 + 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 + 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- + 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 + 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 + --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 + 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. @@ -1236,7 +1238,7 @@ OPTIONS -------------------- 0 - One way to show only amounts with a member: value (using a query, de- + One way to show only amounts with a member: value (using a query, de- scribed below): $ hledger balance --pivot member tag:member=. @@ -1244,7 +1246,7 @@ OPTIONS -------------------- -2 EUR - Another way (the acct: query matches against the pivoted "account + Another way (the acct: query matches against the pivoted "account name"): $ hledger balance --pivot member acct:. @@ -1253,49 +1255,49 @@ OPTIONS -2 EUR Valuation - Instead of reporting amounts in their original commodity, hledger can + 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- tain date). This is controlled by the --value=TYPE[,COMMODITY] option, - but we also provide the simpler -B/-V/-X flags, and usually one of + but we also provide the simpler -B/-V/-X flags, and usually one of those is all you need. -B: Cost - The -B/--cost flag converts amounts to their cost or sale amount at + The -B/--cost flag converts amounts to their cost or sale amount at transaction time, if they have a transaction price specified. -V: Value - The -V/--market flag converts amounts to market value in their default + 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. -X: Value in specified commodity The -X/--exchange=COMM option is like -V, except you tell it which cur- - rency you want to convert to, and it tries to convert everything to + rency you want to convert to, and it tries to convert everything to that. Valuation date - Since market prices can change from day to day, market value reports + Since market prices can change from day to day, market value reports have a valuation date (or more than one), which determines which market prices will be used. For single period reports, if an explicit report end date is specified, - that will be used as the valuation date; otherwise the valuation date - is "today". + that will be used as the valuation date; otherwise the valuation date + is the journal's end date. - For multiperiod reports, each column/period is valued on the last day + For multiperiod reports, each column/period is valued on the last day 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, + 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 : - 1. A declared market price or inferred market price: A's latest market + 1. A declared market price or inferred market price: A's latest market price in B on or before the valuation date as declared by a P direc- - tive, or (with the --infer-value flag) inferred from transaction + tive, or (with the --infer-value flag) inferred from transaction prices. 2. A reverse market price: the inverse of a declared or inferred market @@ -1305,8 +1307,8 @@ OPTIONS bining the shortest chain of "forward" (only 1 above) market prices, leading from A to B. - 4. A any chain of market prices: a chain of any market prices, includ- - ing both forward and reverse prices (1 and 2 above), leading from A + 4. A any chain of market prices: a chain of any market prices, includ- + ing both forward and reverse prices (1 and 2 above), leading from A to B. Amounts for which no applicable market price can be found, are not con- @@ -1317,17 +1319,17 @@ OPTIONS 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 + 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 need- ing P directives at all. - Adding the --infer-value flag to -V, -X or --value enables this. So - for example, hledger bs -V --infer-value will get market prices both + Adding the --infer-value flag to -V, -X or --value enables this. So + for example, hledger bs -V --infer-value will get market prices both from P directives and from transactions. There is a downside: value reports can sometimes be affected in confus- - ing/undesired ways by your journal entries. If this happens to you, + ing/undesired ways by your journal entries. If this happens to you, read all of this Valuation section carefully, and try adding --debug or --debug=2 to troubleshoot. @@ -1335,45 +1337,45 @@ OPTIONS o multicommodity transactions with explicit prices (@/@@) - o multicommodity transactions with implicit prices (no @, two commodi- - ties, unbalanced). (With these, the order of postings matters. + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. hledger print -x can be useful for troubleshooting.) - o but not, currently, from "more correct" multicommodity transactions + o but not, currently, from "more correct" multicommodity transactions (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- + hledger will convert all amounts to COMM, wherever it can find a suit- able market price (including by reversing or chaining prices). - When you leave the valuation commodity unspecified (-V or --value + When you leave the valuation commodity unspecified (-V or --value TYPE): - For each commodity A, hledger picks a default valuation commodity as + For each commodity A, hledger picks a default valuation commodity as follows, in this order of preference: 1. The price commodity from the latest P-declared market price for A on or before valuation date. 2. The price commodity from the latest P-declared market price for A on - any date. (Allows conversion to proceed when there are inferred + any date. (Allows conversion to proceed when there are inferred prices before the valuation date.) - 3. If there are no P directives at all (any commodity or date) and the - --infer-value flag is used: the price commodity from the latest + 3. If there are no P directives at all (any commodity or date) and the + --infer-value flag is used: the price commodity from the latest transaction-inferred price for A on or before valuation date. This means: - o If you have P directives, they determine which commodities -V will + o If you have P directives, they determine which commodities -V will convert, and to what. o If you have no P directives, and use the --infer-value flag, transac- tion prices determine it. - Amounts for which no valuation commodity can be found are not con- + Amounts for which no valuation commodity can be found are not con- verted. Simple valuation examples @@ -1400,7 +1402,7 @@ OPTIONS $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V @@ -1421,36 +1423,36 @@ OPTIONS The TYPE part selects cost or value and valuation date: --value=cost - Convert amounts to cost, using the prices recorded in transac- + Convert amounts to cost, using the prices recorded in transac- tions. --value=then - Convert amounts to their value in the default valuation commod- - ity, using market prices on each posting's date. This is cur- + Convert amounts to their value in the default valuation commod- + ity, using market prices on each posting's date. This is cur- rently supported only by the print and register commands. --value=end - Convert amounts to their value in the default valuation commod- - ity, using market prices on the last day of the report period - (or if unspecified, the journal's end date); or in multiperiod + Convert amounts to their value in the default valuation commod- + ity, using market prices on the last day of the report period + (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in the default valuation commod- - ity using current market prices (as of when report is gener- + Convert amounts to their value in the default valuation commod- + ity using current market prices (as of when report is gener- ated). --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity using market prices on this date. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, deducing market prices as described above. More valuation examples - Here are some examples showing the effect of --value, as seen with + Here are some examples showing the effect of --value, as seen with print: P 2000-01-01 A 1 B @@ -1488,7 +1490,7 @@ OPTIONS 2000-02-01 (a) 2 B - With no report period specified, that shows the value as of the last + With no report period specified, that shows the value as of the last day of the journal (2000-03-01): $ hledger -f- print --value=end @@ -1525,7 +1527,7 @@ OPTIONS 2000-03-01 (a) 1 B - You may need to explicitly set a commodity's display style, when re- + You may need to explicitly set a commodity's display style, when re- verse prices are used. Eg this output might be surprising: P 2000-01-01 A 2B @@ -1539,10 +1541,10 @@ OPTIONS a 0 b 0 - Explanation: because there's no amount or commodity directive specify- - ing a display style for A, 0.5A gets the default style, which shows no + Explanation: because there's no amount or commodity directive specify- + ing a display style for A, 0.5A gets the default style, which shows no decimal digits. Because the displayed amount looks like zero, the com- - modity symbol and minus sign are not displayed either. Adding a com- + modity symbol and minus sign are not displayed either. Adding a com- modity directive sets a more useful display style for A: P 2000-01-01 A 2B @@ -1558,9 +1560,9 @@ OPTIONS b -0.50A 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 sideways.) It may be useful when troubleshooting. If you find + 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 sideways.) It may be useful when troubleshooting. If you find problems, please report them, ideally with a reproducible example. Re- lated: #329, #1083. @@ -1568,7 +1570,7 @@ OPTIONS --value=cost --value=now -------------------------------------------------------------------------------------------- print - posting cost value at re- value at value at re- value at + posting cost value at re- value at value at re- value at amounts port end or posting date port or jour- DATE/today today nal end balance as- unchanged unchanged unchanged unchanged unchanged @@ -1577,15 +1579,15 @@ OPTIONS signments register - starting cost value at day not sup- value at day value at + 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 start start - posting cost value at re- value at value at re- value at + posting cost value at re- value at value at re- value at amounts port end or posting date port or jour- DATE/today today nal end - summary summarised value at pe- sum of post- value at pe- value at - posting cost riod ends ings in in- riod ends DATE/today + summary summarised value at pe- sum of post- value at pe- value at + posting cost riod ends ings in in- riod ends DATE/today amounts terval, val- with report ued at in- interval terval start @@ -1596,9 +1598,9 @@ OPTIONS balance (bs, bse, cf, is) - balance sums of costs value at re- not sup- value at re- value at + balance sums of costs value at re- not sup- value at re- value at changes port end or ported port or jour- DATE/today of - today of sums nal end of sums of post- + today of sums nal end of sums of post- of postings sums of post- ings ings budget like balance like balance not sup- like balances like balance @@ -1612,7 +1614,7 @@ OPTIONS cf, is) with report interval - starting sums of costs value at re- not sup- value at re- sums of post- + starting sums of costs value at re- not sup- value at re- sums of post- balances of postings port start of ported port start of ings before (-H) before report sums of all sums of all report start start postings be- postings be- @@ -1621,9 +1623,6 @@ OPTIONS - - - 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- @@ -1640,10 +1639,10 @@ OPTIONS amounts changes/end changes/end ported changes/end (--budget) balances balances balances row totals, sums, aver- sums, aver- not sup- sums, aver- sums, aver- - row aver- ages of dis- ages of dis- ported ages of dis- ages of dis- + row aver- ages of dis- ages of dis- ported ages of dis- ages of dis- ages (-T, played values played values played values played values -A) - column to- sums of dis- sums of dis- not sup- sums of dis- sums of dis- + column to- sums of dis- sums of dis- not sup- sums of dis- sums of dis- tals played values played values ported played values played values grand to- sum, average sum, average not sup- sum, average sum, average tal, grand of column to- of column to- ported of column to- of column to- @@ -1657,48 +1656,113 @@ OPTIONS cost calculated using price(s) recorded in the transaction(s). - value market value using available market price declarations, or the + value market value using available market price declarations, or the unchanged amount if no conversion rate can be found. report start - the first day of the report period specified with -b or -p or + the first day of the report period specified with -b or -p or date:, otherwise today. report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, otherwise today. report end - the last day of the report period specified with -e or -p or + the last day of the report period specified with -e or -p or date:, otherwise today. report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, otherwise today. report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperi- ods). COMMANDS - hledger provides a number of subcommands; hledger with no arguments - shows a list. + hledger provides a number of commands for producing reports and manag- + ing your data. Run hledger with no arguments to list the commands + available. - If you install additional hledger-* packages, or if you put programs or - scripts named hledger-NAME in your PATH, these will also be listed as - subcommands. + 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. - Run a subcommand by writing its name as first argument (eg hledger in- - comestatement). You can also write one of the standard short aliases - displayed in parentheses in the command list (hledger b), or any any - unambiguous prefix of a command name (hledger inc). + Here are the built-in commands: - Here are all the builtin commands in alphabetical order. See also - hledger for a more organised command list, and hledger CMD -h for de- - tailed command help. + Data entry (these modify the journal file): + + o add - add transactions using guided prompts + + o import - add any new transactions from other files (eg csv) + + Data management: + + o check - check for various kinds of issue in the data + + o close (equity) - generate balance-resetting transactions + + o diff - compare account transactions in two journal files + + o rewrite - generate extra postings, similar to print --auto + + Financial statements: + + o aregister (areg) - show transactions in a particular account + + o balancesheet (bs) - show assets, liabilities and net worth + + o balancesheetequity (bse) - show assets, liabilities and equity + + o cashflow (cf) - show changes in liquid assets + + o incomestatement (is) - show revenues and expenses + + o roi - show return on investments + + Miscellaneous reports: + + o accounts (a) - show account names + + o activity - show postings-per-interval bar charts + + o balance (b, bal) - show balance changes/end balances/budgets in ac- + counts + + o codes - show transaction codes + + o commodities - show commodity/currency symbols + + o descriptions - show unique transaction descriptions + + o files - show input file paths + + o notes - show unique note segments of transaction descriptions + + o payees - show unique payee segments of transaction descriptions + + o prices - show market price records + + o print (p, txns) - show transactions (journal entries) + + o print-unique - show only transactions with unique descriptions + + 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- + tion + + o stats - show journal statistics + + o tags - show tag names + + o test - run self tests + + Next, the detailed command docs, in alphabetical order. accounts accounts, a @@ -1849,21 +1913,20 @@ COMMANDS 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. - Output format - This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, and json. - Examples: Show all transactions and historical running balance in the first ac- @@ -1900,6 +1963,10 @@ COMMANDS real-world account balances. In some cases the -H/--historical flag is used to ensure this (more below). + This command also supports the output destination and output format op- + tions The output formats supported are (in most modes): txt, csv, html, + and json. + The balance command can produce several styles of report: Classic balance report @@ -2426,11 +2493,6 @@ COMMANDS ----------------------------------------++------------------------------- || 0 [ 0] - Output format - This command also supports the output destination and output format op- - tions The output formats supported are (in most modes): txt, csv, html, - and json. - balancesheet balancesheet, bs This command displays a balance sheet, showing historical ending bal- @@ -2936,275 +2998,6 @@ 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. @@ -3647,55 +3440,64 @@ COMMANDS --help currently doesn't show them). Add-on commands - hledger also searches for external add-on commands, and will include - these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- - sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). + 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-ons can be invoked like any hledger command, but there are a few - things to be aware of. Eg if the hledger-web add-on is installed, + These offical add-ons are maintained and released along with hledger: - o hledger -h web shows hledger's help, while hledger web -h shows - hledger-web's help. + o ui an efficient terminal interface for hledger (TUI) - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; - you must use hledger web -- --serve --port 9000. + o web a simple web interface for hledger (WUI) - o You can always run add-ons directly if preferred: hledger-web --serve - --port 9000. + 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 (and - haskell) library functions that built-in commands do, for command-line - options, journal parsing, reporting, etc. + o iadd a more interactive alternative for the add command - Two important add-ons are the hledger-ui and hledger-web user inter- - faces. These are maintained and released along with hledger: + o interest generates interest transactions according to various schemes - ui - hledger-ui provides an efficient terminal interface. + o stockquotes downloads market prices for your commodities from Alpha- + Vantage (experimental) - web - hledger-web provides a simple web interface. + Additional experimental add-ons, which may not be in a working state, + can be found in the bin/ directory in the hledger repo. - Third party add-ons, maintained separately from hledger, include: + Add-on command flags + In a hledger command line, add-on command flags must have a double dash + (--) preceding them. Eg you must write: - iadd - hledger-iadd is a more interactive, terminal UI replacement for the add - command. + $ hledger web -- --serve - interest - hledger-interest generates interest transactions for an account accord- - ing to various schemes. + and not: - stockquotes - hledger-stockquotes downloads market prices for the commodities in your - journal from AlphaVantage. + $ hledger web --serve - A few more experimental or old add-ons can be found in hledger's bin/ - directory. These are typically prototypes and not guaranteed to work. + (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 + 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- + on program directly, eg: + + $ hledger-web --serve + + Making add-on commands + Add-on commands are programs or scripts in your PATH + + o whose name starts with hledger- + + o whose name ends with a recognised file extension: .bat,.com,.exe, + .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none + + o and (on unix, mac) which are executable by the current user. + + 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. ENVIRONMENT LEDGER_FILE The journal file path when not specified with -f. Default: @@ -3837,9 +3639,11 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), - hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + + hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time- + dot(5) -hledger 1.20.99 December 2020 hledger(1) +hledger-1.20.99 December 2020 HLEDGER(1)