diff --git a/hledger-ui/doc/hledger-ui.1 b/hledger-ui/doc/hledger-ui.1 index dd59b4d8f..4289d3a4c 100644 --- a/hledger-ui/doc/hledger-ui.1 +++ b/hledger-ui/doc/hledger-ui.1 @@ -191,23 +191,23 @@ most recent applicable market price, if any) hledger help options: .TP .B \f[C]\-h\f[] -show general usage (or after COMMAND, the command\[aq]s usage) +show general usage (or after COMMAND, command usage) .RS .RE .TP .B \f[C]\-\-help\f[] -show the current program\[aq]s manual as plain text (or after an add\-on +show this program\[aq]s manual as plain text (or after an add\-on COMMAND, the add\-on\[aq]s manual) .RS .RE .TP .B \f[C]\-\-man\f[] -show the current program\[aq]s manual with man +show this program\[aq]s manual with man .RS .RE .TP .B \f[C]\-\-info\f[] -show the current program\[aq]s manual with info +show this program\[aq]s manual with info .RS .RE .TP diff --git a/hledger-ui/doc/hledger-ui.1.info b/hledger-ui/doc/hledger-ui.1.info index f78bd664a..2e1f10a65 100644 --- a/hledger-ui/doc/hledger-ui.1.info +++ b/hledger-ui/doc/hledger-ui.1.info @@ -135,17 +135,17 @@ the data. '-h' - show general usage (or after COMMAND, the command's usage) + show general usage (or after COMMAND, command usage) '--help' - show the current program's manual as plain text (or after an add-on + show this program's manual as plain text (or after an add-on COMMAND, the add-on's manual) '--man' - show the current program's manual with man + show this program's manual with man '--info' - show the current program's manual with info + show this program's manual with info '--version' show version @@ -357,17 +357,17 @@ Tag Table: Node: Top73 Node: OPTIONS825 Ref: #options924 -Node: KEYS3677 -Ref: #keys3774 -Node: SCREENS6362 -Ref: #screens6449 -Node: Accounts screen6539 -Ref: #accounts-screen6669 -Node: Register screen8718 -Ref: #register-screen8875 -Node: Transaction screen10764 -Ref: #transaction-screen10924 -Node: Error screen11794 -Ref: #error-screen11918 +Node: KEYS3650 +Ref: #keys3747 +Node: SCREENS6335 +Ref: #screens6422 +Node: Accounts screen6512 +Ref: #accounts-screen6642 +Node: Register screen8691 +Ref: #register-screen8848 +Node: Transaction screen10737 +Ref: #transaction-screen10897 +Node: Error screen11767 +Ref: #error-screen11891  End Tag Table diff --git a/hledger-ui/doc/hledger-ui.1.txt b/hledger-ui/doc/hledger-ui.1.txt index b54020a56..340cdb24d 100644 --- a/hledger-ui/doc/hledger-ui.1.txt +++ b/hledger-ui/doc/hledger-ui.1.txt @@ -129,14 +129,14 @@ OPTIONS hledger help options: - -h show general usage (or after COMMAND, the command's usage) + -h show general usage (or after COMMAND, command usage) - --help show the current program's manual as plain text (or after an - add-on COMMAND, the add-on's manual) + --help show this program's manual as plain text (or after an add-on + COMMAND, the add-on's manual) - --man show the current program's manual with man + --man show this program's manual with man - --info show the current program's manual with info + --info show this program's manual with info --version show version diff --git a/hledger-web/doc/hledger-web.1 b/hledger-web/doc/hledger-web.1 index 95ea241c9..880978550 100644 --- a/hledger-web/doc/hledger-web.1 +++ b/hledger-web/doc/hledger-web.1 @@ -247,23 +247,23 @@ most recent applicable market price, if any) hledger help options: .TP .B \f[C]\-h\f[] -show general usage (or after COMMAND, the command\[aq]s usage) +show general usage (or after COMMAND, command usage) .RS .RE .TP .B \f[C]\-\-help\f[] -show the current program\[aq]s manual as plain text (or after an add\-on +show this program\[aq]s manual as plain text (or after an add\-on COMMAND, the add\-on\[aq]s manual) .RS .RE .TP .B \f[C]\-\-man\f[] -show the current program\[aq]s manual with man +show this program\[aq]s manual with man .RS .RE .TP .B \f[C]\-\-info\f[] -show the current program\[aq]s manual with info +show this program\[aq]s manual with info .RS .RE .TP diff --git a/hledger-web/doc/hledger-web.1.info b/hledger-web/doc/hledger-web.1.info index 4aaecdc65..79d749e9d 100644 --- a/hledger-web/doc/hledger-web.1.info +++ b/hledger-web/doc/hledger-web.1.info @@ -180,17 +180,17 @@ options as shown above. '-h' - show general usage (or after COMMAND, the command's usage) + show general usage (or after COMMAND, command usage) '--help' - show the current program's manual as plain text (or after an add-on + show this program's manual as plain text (or after an add-on COMMAND, the add-on's manual) '--man' - show the current program's manual with man + show this program's manual with man '--info' - show the current program's manual with info + show this program's manual with info '--version' show version diff --git a/hledger-web/doc/hledger-web.1.txt b/hledger-web/doc/hledger-web.1.txt index 4e0242c7c..7be9c2057 100644 --- a/hledger-web/doc/hledger-web.1.txt +++ b/hledger-web/doc/hledger-web.1.txt @@ -174,14 +174,14 @@ OPTIONS hledger help options: - -h show general usage (or after COMMAND, the command's usage) + -h show general usage (or after COMMAND, command usage) - --help show the current program's manual as plain text (or after an - add-on COMMAND, the add-on's manual) + --help show this program's manual as plain text (or after an add-on + COMMAND, the add-on's manual) - --man show the current program's manual with man + --man show this program's manual with man - --info show the current program's manual with info + --info show this program's manual with info --version show version diff --git a/hledger/doc/hledger.1 b/hledger/doc/hledger.1 index c12b6814a..425760c4e 100644 --- a/hledger/doc/hledger.1 +++ b/hledger/doc/hledger.1 @@ -9,11 +9,15 @@ hledger \- a command\-line accounting tool .SH SYNOPSIS .PP -\f[C]hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [CMDARGS]\f[] +\f[C]hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [ARGS]\f[] .PD 0 .P .PD -\f[C]hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [CMDARGS]\f[] +\f[C]hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [ARGS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\f[] .SH DESCRIPTION .PP hledger is a cross\-platform program for tracking money, time, or any @@ -68,7 +72,7 @@ To get started, you can either save some entries like the above in prompts. Then try some commands like \f[C]hledger\ print\f[] or \f[C]hledger\ balance\f[]. -See COMMANDS and EXAMPLES below. +Run \f[C]hledger\f[] with no arguments for a list of commands. .SH EXAMPLES .PP Two simple transactions in hledger journal format: @@ -148,80 +152,32 @@ $\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ tran \f[] .fi .SH OPTIONS +.SS General options .PP To see general usage help, including general options which are supported by most hledger commands, run \f[C]hledger\ \-h\f[]. -(Note \-h and \-\-help are different, like git.) These options can -appear anywhere on the command line, and are listed below. +(Note \-h and \-\-help are different, like git.) .PP -To see usage for a specific command, run: -\f[C]hledger\ COMMAND\ \-h\f[]. -Command\-specific options must be written after the command name, eg: -\f[C]hledger\ print\ \-x\f[]. -.PP -Additionally, if the command is an add\-on, you may need to put its -options after a double\-hyphen, eg: -\f[C]hledger\ ui\ \-\-\ \-\-watch\f[]. -Or, you can run the add\-on executable directly, eg: -\f[C]hledger\-ui\ \-\-watch\f[]. -.PP -Most commands also accept arguments, which are often a query filtering -the data in some way. -.SS Special characters -.PP -Option and argument values which contain problematic characters should -be escaped with double quotes, backslashes, or (best) single quotes. -Problematic characters means spaces, and also characters which are -significant to your command shell, such as less\-than/greater\-than. -Eg: -\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. -.PP -Characters which are significant both to the shell and in regular -expressions sometimes need to be double\-escaped. -These include parentheses, the pipe symbol and the dollar sign. -Eg, to match the dollar symbol, bash users should do: -\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] or -\f[C]hledger\ balance\ cur:\\\\$\f[]. -.PP -There\[aq]s more.. -options and arguments get de\-escaped when hledger is passing them to an -addon executable. -In this case you might need \f[I]triple\f[]\-escaping. -Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or -\f[C]hledger\ ui\ cur:\\\\\\\\$\f[]. -.PP -If in doubt, keep things simple: -.IP \[bu] 2 -run add\-on executables directly -.IP \[bu] 2 -write options after the command -.IP \[bu] 2 -enclose problematic args in single quotes -.IP \[bu] 2 -if needed, also add a backslash to escape regexp metacharacters -.PP -If you\[aq]re really stumped, add \f[C]\-\-debug=2\f[] to troubleshoot. -.SS General options -.SS General help options +General help options: .TP .B \f[C]\-h\f[] -show general usage (or after COMMAND, the command\[aq]s usage) +show general usage (or after COMMAND, command usage) .RS .RE .TP .B \f[C]\-\-help\f[] -show the current program\[aq]s manual as plain text (or after an add\-on +show this program\[aq]s manual as plain text (or after an add\-on COMMAND, the add\-on\[aq]s manual) .RS .RE .TP .B \f[C]\-\-man\f[] -show the current program\[aq]s manual with man +show this program\[aq]s manual with man .RS .RE .TP .B \f[C]\-\-info\f[] -show the current program\[aq]s manual with info +show this program\[aq]s manual with info .RS .RE .TP @@ -234,7 +190,8 @@ show version show debug output (levels 1\-9, default: 1) .RS .RE -.SS General input options +.PP +General input options: .TP .B \f[C]\-f\ FILE\ \-\-file=FILE\f[] use a different input file. @@ -267,7 +224,8 @@ use some other field/tag for account names ignore any failing balance assertions .RS .RE -.SS General reporting options +.PP +General reporting options: .TP .B \f[C]\-b\ \-\-begin=DATE\f[] include postings/txns on or after this date @@ -362,6 +320,57 @@ takes precedence. Eg \f[C]\-p\ feb\ \-p\ mar\f[] is equivalent to \f[C]\-p\ mar\f[]. .PP Some of these can also be written as queries. +.SS Command options +.PP +To see options for a particular command, including command\-specific +options, run: \f[C]hledger\ COMMAND\ \-h\f[]. +.PP +Command\-specific options must be written after the command name, eg: +\f[C]hledger\ print\ \-x\f[]. +.PP +Additionally, if the command is an addon, you may need to put its +options after a double\-hyphen, eg: +\f[C]hledger\ ui\ \-\-\ \-\-watch\f[]. +Or, you can run the addon executable directly: +\f[C]hledger\-ui\ \-\-watch\f[]. +.SS Command arguments +.PP +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. +.SS Special characters +.PP +Option and argument values which contain problematic characters should +be escaped with double quotes, backslashes, or (best) single quotes. +Problematic characters means spaces, and also characters which are +significant to your command shell, such as less\-than/greater\-than. +Eg: +\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. +.PP +Characters which are significant both to the shell and in regular +expressions sometimes need to be double\-escaped. +These include parentheses, the pipe symbol and the dollar sign. +Eg, to match the dollar symbol, bash users should do: +\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] or +\f[C]hledger\ balance\ cur:\\\\$\f[]. +.PP +There\[aq]s more.. +options and arguments get de\-escaped when hledger is passing them to an +addon executable. +In this case you might need \f[I]triple\f[]\-escaping. +Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or +\f[C]hledger\ ui\ cur:\\\\\\\\$\f[]. +.PP +If in doubt, keep things simple: +.IP \[bu] 2 +run add\-on executables directly +.IP \[bu] 2 +write options after the command +.IP \[bu] 2 +enclose problematic args in single quotes +.IP \[bu] 2 +if needed, also add a backslash to escape regexp metacharacters +.PP +If you\[aq]re really stumped, add \f[C]\-\-debug=2\f[] to troubleshoot. .SS Input files .PP hledger reads transactions from a data file (and the add command writes @@ -768,11 +777,10 @@ As with account names, when tag values have displayed in tree\-mode reports, summarisable with a depth limit, and so on. .PP -\f[C]\-\-pivot\f[] affects all reports, and is one of those options you -can write before the command name if you wish. -You can think of hledger transforming the journal before any other -processing, replacing every posting\[aq]s account name with the value of -the specified tag on that posting, inheriting it from the transaction or +\f[C]\-\-pivot\f[] is a general option affecting all reports; you can +think of hledger transforming the journal before any other processing, +replacing every posting\[aq]s account name with the value of the +specified tag on that posting, inheriting it from the transaction or using a blank value if it\[aq]s not present. .PP An example: @@ -868,16 +876,14 @@ In the \f[C]alias\f[] directive and \f[C]\-\-alias\f[] option, regular expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[]). Elsewhere in hledger, these are not required. .IP \[bu] 2 -To match a regular expression metacharacter like \f[C]$\f[] as a literal -character, prepend a backslash. +In queries, to match a regular expression metacharacter like \f[C]$\f[] +as a literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger\-web, write \f[C]cur:\\$\f[]. .IP \[bu] 2 On the command line, some metacharacters like \f[C]$\f[] have a special -meaning to the shell and so must be escaped a second time, with single -or double quotes or another backslash. -Eg, to match amounts with the dollar sign from the command line, write -\f[C]cur:\[aq]\\$\[aq]\f[] or \f[C]cur:\\\\$\f[]. +meaning to the shell and so must be escaped at least once more. +See Special characters. .SH QUERIES .PP One of hledger\[aq]s strengths is being able to quickly report on @@ -2452,8 +2458,41 @@ transactions when importing. .PP hledger\-rewrite.hs Adds one or more custom postings to matched transactions. +.SH ENVIRONMENT +.PP +\f[B]COLUMNS\f[] The screen width used by the register command. +Default: the full terminal width. +.PP +\f[B]LEDGER_FILE\f[] The journal file path when not specified with +\f[C]\-f\f[]. +Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps +\f[C]C:/Users/USER/.hledger.journal\f[]). +.SH FILES +.PP +Reads data from one or more files in hledger journal, timeclock, +timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +.SH BUGS +.PP +The need to precede addon command options with \f[C]\-\-\f[] when +invoked from hledger is awkward. +.PP +When input data contains non\-ascii characters, a suitable system locale +must be configured (or there will be an unhelpful error). +Eg on POSIX, set LANG to something other than C. +.PP +In a Microsoft Windows CMD window, non\-ascii characters and colours are +not supported. +.PP +In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger +add. +.PP +Not all of Ledger\[aq]s journal file syntax is supported. +See file format differences. +.PP +On large data files, hledger is slower and uses more memory than Ledger. .SH TROUBLESHOOTING -.SS Run\-time problems .PP Here are some issues you might encounter when you run hledger (and remember you can also seek help from the IRC channel, mail list or bug @@ -2539,55 +2578,6 @@ $\ LANG=fr_FR.utf8\ hledger\ \-f\ my.journal\ print Note some platforms allow variant locale spellings, but not all (ubuntu accepts \f[C]fr_FR.UTF8\f[], mac osx requires exactly \f[C]fr_FR.UTF\-8\f[]). -.SS Known limitations -.PP -\f[B]Command line interface\f[] -.PP -Add\-on command options, unless they are also understood by the main -hledger executable, must be written after \f[C]\-\-\f[], like this: -\f[C]hledger\ web\ \-\-\ \-\-server\f[] -.PP -\f[B]Differences from Ledger\f[] -.PP -Not all of Ledger\[aq]s journal file syntax is supported. -See file format differences. -.PP -hledger is slower than Ledger, and uses more memory, on large data -files. -.PP -\f[B]Windows limitations\f[] -.PP -In a windows CMD window, non\-ascii characters and colours are not -supported. -.PP -In a windows Cygwin/MSYS/Mintty window, the tab key is not supported in -hledger add. -.SH ENVIRONMENT -.PP -\f[B]COLUMNS\f[] The screen width used by the register command. -Default: the full terminal width. -.PP -\f[B]LEDGER_FILE\f[] The journal file path when not specified with -\f[C]\-f\f[]. -Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps -\f[C]C:/Users/USER/.hledger.journal\f[]). -.SH FILES -.PP -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -.SH BUGS -.PP -The need to precede options with \f[C]\-\-\f[] when invoked from hledger -is awkward. -.PP -hledger can\[aq]t render non\-ascii characters when run from a Windows -command prompt (up to Windows 7 at least). -.PP -When input data contains non\-ascii characters, a suitable system locale -must be configured (or there will be an unhelpful error). -Eg on POSIX, set LANG to something other than C. .SH "REPORTING BUGS" diff --git a/hledger/doc/hledger.1.info b/hledger/doc/hledger.1.info index 3d1e01452..87c1f0ab6 100644 --- a/hledger/doc/hledger.1.info +++ b/hledger/doc/hledger.1.info @@ -38,8 +38,8 @@ 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'. See -COMMANDS and EXAMPLES below. +try some commands like 'hledger print' or 'hledger balance'. Run +'hledger' with no arguments for a list of commands. * Menu: * EXAMPLES:: @@ -47,7 +47,6 @@ COMMANDS and EXAMPLES below. * QUERIES:: * COMMANDS:: * ADD-ON COMMANDS:: -* TROUBLESHOOTING::  File: hledger.1.info, Node: EXAMPLES, Next: OPTIONS, Prev: Top, Up: Top @@ -114,25 +113,12 @@ File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top 2 OPTIONS ********* -To see general usage help, including general options which are supported -by most hledger commands, run 'hledger -h'. (Note -h and -help are -different, like git.) These options can appear anywhere on the command -line, and are listed below. - - To see usage for a specific command, run: 'hledger COMMAND -h'. -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 -options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can -run the add-on executable directly, eg: 'hledger-ui --watch'. - - Most commands also accept arguments, which are often a query -filtering the data in some way. * Menu: -* Special characters:: * General options:: +* Command options:: +* Command arguments:: +* Special characters:: * Input files:: * Smart dates:: * Report start & end date:: @@ -143,69 +129,30 @@ filtering the data in some way. * Regular expressions::  -File: hledger.1.info, Node: Special characters, Next: General options, Up: OPTIONS +File: hledger.1.info, Node: General options, Next: Command options, Up: OPTIONS -2.1 Special characters -====================== - -Option and argument values which contain problematic characters should -be escaped with double quotes, backslashes, or (best) single quotes. -Problematic characters means spaces, and also characters which are -significant to your command shell, such as less-than/greater-than. Eg: -'hledger register -p 'last year' "accounts receivable -(receivable|payable)" amt:\>100'. - - Characters which are significant both to the shell and in regular -expressions sometimes need to be double-escaped. These include -parentheses, the pipe symbol and the dollar sign. Eg, to match the -dollar symbol, bash users should do: 'hledger balance cur:'\$'' or -'hledger balance cur:\\$'. - - There's more.. options and arguments get de-escaped when hledger is -passing them to an addon executable. In this case you might need -_triple_-escaping. Eg: 'hledger ui cur:'\\$'' or 'hledger ui -cur:\\\\$'. - - If in doubt, keep things simple: - - * run add-on executables directly - * write options after the command - * enclose problematic args in single quotes - * if needed, also add a backslash to escape regexp metacharacters - - If you're really stumped, add '--debug=2' to troubleshoot. - - -File: hledger.1.info, Node: General options, Next: Input files, Prev: Special characters, Up: OPTIONS - -2.2 General options +2.1 General options =================== -* Menu: +To see general usage help, including general options which are supported +by most hledger commands, run 'hledger -h'. (Note -h and -help are +different, like git.) -* General help options:: -* General input options:: -* General reporting options:: - - -File: hledger.1.info, Node: General help options, Next: General input options, Up: General options - -2.2.1 General help options --------------------------- + General help options: '-h' - show general usage (or after COMMAND, the command's usage) + show general usage (or after COMMAND, command usage) '--help' - show the current program's manual as plain text (or after an add-on + show this program's manual as plain text (or after an add-on COMMAND, the add-on's manual) '--man' - show the current program's manual with man + show this program's manual with man '--info' - show the current program's manual with info + show this program's manual with info '--version' show version @@ -213,11 +160,7 @@ File: hledger.1.info, Node: General help options, Next: General input options, show debug output (levels 1-9, default: 1) - -File: hledger.1.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: General options - -2.2.2 General input options ---------------------------- + General input options: '-f FILE --file=FILE' @@ -239,11 +182,7 @@ File: hledger.1.info, Node: General input options, Next: General reporting opt ignore any failing balance assertions - -File: hledger.1.info, Node: General reporting options, Prev: General input options, Up: General options - -2.2.3 General reporting options -------------------------------- + General reporting options: '-b --begin=DATE' @@ -306,9 +245,67 @@ one takes precedence. Eg '-p feb -p mar' is equivalent to '-p mar'. Some of these can also be written as queries.  -File: hledger.1.info, Node: Input files, Next: Smart dates, Prev: General options, Up: OPTIONS +File: hledger.1.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS -2.3 Input files +2.2 Command options +=================== + +To see options for a particular command, including command-specific +options, run: 'hledger COMMAND -h'. + + Command-specific options must be written after the command name, eg: +'hledger print -x'. + + Additionally, if the command is an addon, you may need to put its +options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can +run the addon executable directly: 'hledger-ui --watch'. + + +File: hledger.1.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: OPTIONS + +2.3 Command arguments +===================== + +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. + + +File: hledger.1.info, Node: Special characters, Next: Input files, Prev: Command arguments, Up: OPTIONS + +2.4 Special characters +====================== + +Option and argument values which contain problematic characters should +be escaped with double quotes, backslashes, or (best) single quotes. +Problematic characters means spaces, and also characters which are +significant to your command shell, such as less-than/greater-than. Eg: +'hledger register -p 'last year' "accounts receivable +(receivable|payable)" amt:\>100'. + + Characters which are significant both to the shell and in regular +expressions sometimes need to be double-escaped. These include +parentheses, the pipe symbol and the dollar sign. Eg, to match the +dollar symbol, bash users should do: 'hledger balance cur:'\$'' or +'hledger balance cur:\\$'. + + There's more.. options and arguments get de-escaped when hledger is +passing them to an addon executable. In this case you might need +_triple_-escaping. Eg: 'hledger ui cur:'\\$'' or 'hledger ui +cur:\\\\$'. + + If in doubt, keep things simple: + + * run add-on executables directly + * write options after the command + * enclose problematic args in single quotes + * if needed, also add a backslash to escape regexp metacharacters + + If you're really stumped, add '--debug=2' to troubleshoot. + + +File: hledger.1.info, Node: Input files, Next: Smart dates, Prev: Special characters, Up: OPTIONS + +2.5 Input files =============== hledger reads transactions from a data file (and the add command writes @@ -363,7 +360,7 @@ the files, eg: 'cat a.journal b.journal | hledger -f- CMD'.  File: hledger.1.info, Node: Smart dates, Next: Report start & end date, Prev: Input files, Up: OPTIONS -2.4 Smart dates +2.6 Smart dates =============== hledger's user interfaces accept a flexible "smart date" syntax (unlike @@ -386,7 +383,7 @@ omitted (defaulting to 1).  File: hledger.1.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS -2.5 Report start & end date +2.7 Report start & end date =========================== Most hledger reports show the full span of time represented by the @@ -415,7 +412,7 @@ need to write the date _after_ the last day you want to include.  File: hledger.1.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS -2.6 Report intervals +2.8 Report intervals ==================== A report interval can be specified so that commands like register, @@ -428,7 +425,7 @@ intervals can not be specified with a query, currently.  File: hledger.1.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS -2.7 Period expressions +2.9 Period expressions ====================== The '-p/--period' option accepts period expressions, a shorthand way of @@ -503,8 +500,8 @@ start date and exclusive end date):  File: hledger.1.info, Node: Depth limiting, Next: Pivoting, Prev: Period expressions, Up: OPTIONS -2.8 Depth limiting -================== +2.10 Depth limiting +=================== With the '--depth N' option, commands like account, balance and register will show only the uppermost accounts in the account tree, down to level @@ -513,8 +510,8 @@ N. Use this when you want a summary with less detail.  File: hledger.1.info, Node: Pivoting, Next: Regular expressions, Prev: Depth limiting, Up: OPTIONS -2.9 Pivoting -============ +2.11 Pivoting +============= Normally hledger sums amounts, and organizes them in a hierarchy, based on account name. The '--pivot TAGNAME' option causes it to sum and @@ -526,10 +523,9 @@ account names, when tag values have 'multiple:colon-separated:parts' hledger will build hierarchy, displayed in tree-mode reports, summarisable with a depth limit, and so on. - '--pivot' affects all reports, and is one of those options you can -write before the command name if you wish. You can think of hledger -transforming the journal before any other processing, replacing every -posting's account name with the value of the specified tag on that + '--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 tag on that posting, inheriting it from the transaction or using a blank value if it's not present. @@ -574,7 +570,7 @@ $ hledger balance --pivot member acct:.  File: hledger.1.info, Node: Regular expressions, Prev: Pivoting, Up: OPTIONS -2.10 Regular expressions +2.12 Regular expressions ======================== hledger uses regular expressions in a number of places: @@ -603,15 +599,13 @@ general they: must be enclosed in forward slashes ('/REGEX/'). Elsewhere in hledger, these are not required. - * 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:\$'. + * 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:\$'. * On the command line, some metacharacters like '$' have a special - meaning to the shell and so must be escaped a second time, with - single or double quotes or another backslash. Eg, to match amounts - with the dollar sign from the command line, write 'cur:'\$'' or - 'cur:\\$'. + meaning to the shell and so must be escaped at least once more. + See Special characters.  File: hledger.1.info, Node: QUERIES, Next: COMMANDS, Prev: OPTIONS, Up: Top @@ -1854,7 +1848,7 @@ matching names. It's mainly used in development, but it's also nice to be able to check your hledger executable for smoke at any time.  -File: hledger.1.info, Node: ADD-ON COMMANDS, Next: TROUBLESHOOTING, Prev: COMMANDS, Up: Top +File: hledger.1.info, Node: ADD-ON COMMANDS, Prev: COMMANDS, Up: Top 5 ADD-ON COMMANDS ***************** @@ -2099,238 +2093,128 @@ File: hledger.1.info, Node: rewrite, Prev: register-match, Up: Experimental a hledger-rewrite.hs Adds one or more custom postings to matched transactions. - -File: hledger.1.info, Node: TROUBLESHOOTING, Prev: ADD-ON COMMANDS, Up: Top - -6 TROUBLESHOOTING -***************** - -* Menu: - -* Run-time problems:: -* Known limitations:: - - -File: hledger.1.info, Node: Run-time problems, Next: Known limitations, Up: TROUBLESHOOTING - -6.1 Run-time problems -===================== - -Here are some issues you might encounter when you run hledger (and -remember you can also seek help from the IRC channel, mail list or bug -tracker): - - *Successfully installed, but "No command 'hledger' found"* -stack and cabal install binaries into a special directory, which should -be added to your PATH environment variable. Eg on unix-like systems, -that is ~/.local/bin and ~/.cabal/bin respectively. - - *I set a custom LEDGER_FILE, but hledger is still using the default -file* -'LEDGER_FILE' should be a real environment variable, not just a shell -variable. The command 'env | grep LEDGER_FILE' should show it. You may -need to use 'export'. Here's an explanation. - - *"Illegal byte sequence" or "Invalid or incomplete multibyte or wide -character" errors* -In order to handle non-ascii letters and symbols (like £), hledger -needs an appropriate locale. This is usually configured system-wide; -you can also configure it temporarily. The locale may need to be one -that supports UTF-8, if you built hledger with GHC < 7.2 (or possibly -always, I'm not sure yet). - - Here's an example of setting the locale temporarily, on ubuntu -gnu/linux: - -$ file my.journal -my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded -$ locale -a -C -en_US.utf8 # <- a UTF8-aware locale is available -POSIX -$ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command - - Here's one way to set it permanently, there are probably better ways: - -$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile -$ bash --login - - If we preferred to use eg 'fr_FR.utf8', we might have to install that -first: - -$ apt-get install language-pack-fr -$ locale -a -C -en_US.utf8 -fr_BE.utf8 -fr_CA.utf8 -fr_CH.utf8 -fr_FR.utf8 -fr_LU.utf8 -POSIX -$ LANG=fr_FR.utf8 hledger -f my.journal print - - Note some platforms allow variant locale spellings, but not all -(ubuntu accepts 'fr_FR.UTF8', mac osx requires exactly 'fr_FR.UTF-8'). - - -File: hledger.1.info, Node: Known limitations, Prev: Run-time problems, Up: TROUBLESHOOTING - -6.2 Known limitations -===================== - -*Command line interface* - - Add-on command options, unless they are also understood by the main -hledger executable, must be written after '--', like this: 'hledger web --- --server' - - *Differences from Ledger* - - Not all of Ledger's journal file syntax is supported. See file -format differences. - - hledger is slower than Ledger, and uses more memory, on large data -files. - - *Windows limitations* - - In a windows CMD window, non-ascii characters and colours are not -supported. - - In a windows Cygwin/MSYS/Mintty window, the tab key is not supported -in hledger add. -  Tag Table: Node: Top70 -Node: EXAMPLES1883 -Ref: #examples1985 -Node: OPTIONS3631 -Ref: #options3735 -Node: Special characters4649 -Ref: #special-characters4785 -Node: General options5953 -Ref: #general-options6103 -Node: General help options6194 -Ref: #general-help-options6354 -Node: General input options6753 -Ref: #general-input-options6949 -Node: General reporting options7420 -Ref: #general-reporting-options7595 -Node: Input files9027 -Ref: #input-files9162 -Node: Smart dates11125 -Ref: #smart-dates11268 -Node: Report start & end date12247 -Ref: #report-start-end-date12419 -Node: Report intervals13485 -Ref: #report-intervals13650 -Node: Period expressions14051 -Ref: #period-expressions14211 -Node: Depth limiting16551 -Ref: #depth-limiting16695 -Node: Pivoting16896 -Ref: #pivoting17029 -Node: Regular expressions18858 -Ref: #regular-expressions18992 -Node: QUERIES20470 -Ref: #queries20574 -Node: COMMANDS24220 -Ref: #commands24334 -Node: accounts25007 -Ref: #accounts25107 -Node: activity26089 -Ref: #activity26201 -Node: add26560 -Ref: #add26661 -Node: balance29319 -Ref: #balance29432 -Node: Flat mode32374 -Ref: #flat-mode32501 -Node: Depth limited balance reports32921 -Ref: #depth-limited-balance-reports33124 -Node: Multicolumn balance reports33544 -Ref: #multicolumn-balance-reports33746 -Node: Market value38394 -Ref: #market-value38558 -Node: Custom balance output39858 -Ref: #custom-balance-output40031 -Node: Output destination42124 -Ref: #output-destination42289 -Node: CSV output42559 -Ref: #csv-output42678 -Node: balancesheet43075 -Ref: #balancesheet43203 -Node: cashflow45122 -Ref: #cashflow45239 -Node: help47137 -Ref: #help47249 -Node: incomestatement48087 -Ref: #incomestatement48217 -Node: info50132 -Ref: #info50239 -Node: man50603 -Ref: #man50700 -Node: print51105 -Ref: #print51210 -Node: register54966 -Ref: #register55079 -Node: Custom register output59575 -Ref: #custom-register-output59706 -Node: stats61003 -Ref: #stats61109 -Node: test61990 -Ref: #test62077 -Node: ADD-ON COMMANDS62445 -Ref: #add-on-commands62581 -Node: Official add-ons63868 -Ref: #official-add-ons64010 -Node: api64097 -Ref: #api64188 -Node: ui64240 -Ref: #ui64341 -Node: web64399 -Ref: #web64490 -Node: Third party add-ons64536 -Ref: #third-party-add-ons64713 -Node: diff64848 -Ref: #diff64947 -Node: iadd65046 -Ref: #iadd65162 -Node: interest65245 -Ref: #interest65368 -Node: irr65463 -Ref: #irr65563 -Node: Experimental add-ons65641 -Ref: #experimental-add-ons65795 -Node: autosync66188 -Ref: #autosync66302 -Node: budget66541 -Ref: #budget66665 -Node: chart66731 -Ref: #chart66850 -Node: check66921 -Ref: #check67045 -Node: check-dates67112 -Ref: #check-dates67254 -Node: check-dupes67327 -Ref: #check-dupes67470 -Node: equity67547 -Ref: #equity67675 -Node: prices67794 -Ref: #prices67923 -Node: print-unique67978 -Ref: #print-unique68127 -Node: register-match68220 -Ref: #register-match68376 -Node: rewrite68474 -Ref: #rewrite68595 -Node: TROUBLESHOOTING68673 -Ref: #troubleshooting68792 -Node: Run-time problems68846 -Ref: #run-time-problems68989 -Node: Known limitations70936 -Ref: #known-limitations71079 +Node: EXAMPLES1886 +Ref: #examples1988 +Node: OPTIONS3634 +Ref: #options3738 +Node: General options3993 +Ref: #general-options4120 +Node: Command options6643 +Ref: #command-options6796 +Node: Command arguments7194 +Ref: #command-arguments7354 +Node: Special characters7475 +Ref: #special-characters7633 +Node: Input files8801 +Ref: #input-files8939 +Node: Smart dates10902 +Ref: #smart-dates11045 +Node: Report start & end date12024 +Ref: #report-start-end-date12196 +Node: Report intervals13262 +Ref: #report-intervals13427 +Node: Period expressions13828 +Ref: #period-expressions13988 +Node: Depth limiting16328 +Ref: #depth-limiting16474 +Node: Pivoting16675 +Ref: #pivoting16810 +Node: Regular expressions18581 +Ref: #regular-expressions18715 +Node: QUERIES20076 +Ref: #queries20180 +Node: COMMANDS23826 +Ref: #commands23940 +Node: accounts24613 +Ref: #accounts24713 +Node: activity25695 +Ref: #activity25807 +Node: add26166 +Ref: #add26267 +Node: balance28925 +Ref: #balance29038 +Node: Flat mode31980 +Ref: #flat-mode32107 +Node: Depth limited balance reports32527 +Ref: #depth-limited-balance-reports32730 +Node: Multicolumn balance reports33150 +Ref: #multicolumn-balance-reports33352 +Node: Market value38000 +Ref: #market-value38164 +Node: Custom balance output39464 +Ref: #custom-balance-output39637 +Node: Output destination41730 +Ref: #output-destination41895 +Node: CSV output42165 +Ref: #csv-output42284 +Node: balancesheet42681 +Ref: #balancesheet42809 +Node: cashflow44728 +Ref: #cashflow44845 +Node: help46743 +Ref: #help46855 +Node: incomestatement47693 +Ref: #incomestatement47823 +Node: info49738 +Ref: #info49845 +Node: man50209 +Ref: #man50306 +Node: print50711 +Ref: #print50816 +Node: register54572 +Ref: #register54685 +Node: Custom register output59181 +Ref: #custom-register-output59312 +Node: stats60609 +Ref: #stats60715 +Node: test61596 +Ref: #test61683 +Node: ADD-ON COMMANDS62051 +Ref: #add-on-commands62163 +Node: Official add-ons63450 +Ref: #official-add-ons63592 +Node: api63679 +Ref: #api63770 +Node: ui63822 +Ref: #ui63923 +Node: web63981 +Ref: #web64072 +Node: Third party add-ons64118 +Ref: #third-party-add-ons64295 +Node: diff64430 +Ref: #diff64529 +Node: iadd64628 +Ref: #iadd64744 +Node: interest64827 +Ref: #interest64950 +Node: irr65045 +Ref: #irr65145 +Node: Experimental add-ons65223 +Ref: #experimental-add-ons65377 +Node: autosync65770 +Ref: #autosync65884 +Node: budget66123 +Ref: #budget66247 +Node: chart66313 +Ref: #chart66432 +Node: check66503 +Ref: #check66627 +Node: check-dates66694 +Ref: #check-dates66836 +Node: check-dupes66909 +Ref: #check-dupes67052 +Node: equity67129 +Ref: #equity67257 +Node: prices67376 +Ref: #prices67505 +Node: print-unique67560 +Ref: #print-unique67709 +Node: register-match67802 +Ref: #register-match67958 +Node: rewrite68056 +Ref: #rewrite68177  End Tag Table diff --git a/hledger/doc/hledger.1.txt b/hledger/doc/hledger.1.txt index a2c5dd186..3462b0fe9 100644 --- a/hledger/doc/hledger.1.txt +++ b/hledger/doc/hledger.1.txt @@ -7,8 +7,9 @@ NAME hledger - a command-line accounting tool SYNOPSIS - hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS] - hledger [-f FILE] ADDONCMD -- [OPTIONS] [CMDARGS] + hledger [-f FILE] COMMAND [OPTIONS] [ARGS] + hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] + hledger DESCRIPTION hledger is a cross-platform program for tracking money, time, or any @@ -50,8 +51,8 @@ DESCRIPTION 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. See COMMANDS - and EXAMPLES below. + try some commands like hledger print or hledger balance. Run hledger + with no arguments for a list of commands. EXAMPLES Two simple transactions in hledger journal format: @@ -108,21 +109,124 @@ EXAMPLES $ hledger activity -W # show transaction counts per week as a bar chart OPTIONS + General options To see general usage help, including general options which are sup- ported by most hledger commands, run hledger -h. (Note -h and --help - are different, like git.) These options can appear anywhere on the com- - mand line, and are listed below. + are different, like git.) - To see usage for a specific command, run: hledger COMMAND -h. Com- - mand-specific options must be written after the command name, eg: + General help options: + + -h show general usage (or after COMMAND, command usage) + + --help show this program's manual as plain text (or after an add-on + COMMAND, the add-on's manual) + + --man show this program's manual with man + + --info show this program's manual with info + + --version + show version + + --debug[=N] + show debug output (levels 1-9, default: 1) + + General input options: + + -f FILE --file=FILE + use a different input file. For stdin, use - (default: + $LEDGER_FILE or $HOME/.hledger.journal) + + --rules-file=RULESFILE + Conversion rules file to use when reading CSV (default: + FILE.rules) + + --alias=OLD=NEW + rename accounts named OLD to NEW + + --anon anonymize accounts and payees + + --pivot TAGNAME + use some other field/tag for account names + + -I --ignore-assertions + ignore any failing balance assertions + + General reporting options: + + -b --begin=DATE + include postings/txns on or after this date + + -e --end=DATE + include postings/txns before this date + + -D --daily + multiperiod/multicolumn report by day + + -W --weekly + multiperiod/multicolumn report by week + + -M --monthly + multiperiod/multicolumn report by month + + -Q --quarterly + multiperiod/multicolumn report by quarter + + -Y --yearly + multiperiod/multicolumn report by year + + -p --period=PERIODEXP + set start date, end date, and/or reporting interval all at once + (overrides the flags above) + + --date2 + show, and match with -b/-e/-p/date:, secondary dates instead + + -C --cleared + include only cleared postings/txns + + --pending + include only pending postings/txns + + -U --uncleared + include only uncleared (and pending) postings/txns + + -R --real + include only non-virtual postings + + --depth=N + hide accounts/postings deeper than N + + -E --empty + show items with zero amount, normally hidden + + -B --cost + convert amounts to their cost at transaction time (using the + transaction price, if any) + + -V --value + convert amounts to their market value on the report end date + (using the most recent applicable market price, if any) + + Note when multiple similar reporting options are provided, the last one + takes precedence. Eg -p feb -p mar is equivalent to -p mar. + + Some of these can also be written as queries. + + Command options + To see options for a particular command, including command-specific + options, run: hledger COMMAND -h. + + 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 + Additionally, if the command is an addon, you may need to put its options after a double-hyphen, eg: hledger ui -- --watch. Or, you can - run the add-on executable directly, eg: hledger-ui --watch. + run the addon executable directly: hledger-ui --watch. - Most commands also accept arguments, which are often a query filtering - the data in some way. + Command arguments + Most hledger commands accept arguments after the command name, which + are often a query, filtering the data in some way. Special characters Option and argument values which contain problematic characters should @@ -154,107 +258,10 @@ OPTIONS If you're really stumped, add --debug=2 to troubleshoot. - General options - General help options - -h show general usage (or after COMMAND, the command's usage) - - --help show the current program's manual as plain text (or after an - add-on COMMAND, the add-on's manual) - - --man show the current program's manual with man - - --info show the current program's manual with info - - --version - show version - - --debug[=N] - show debug output (levels 1-9, default: 1) - - General input options - -f FILE --file=FILE - use a different input file. For stdin, use - (default: - $LEDGER_FILE or $HOME/.hledger.journal) - - --rules-file=RULESFILE - Conversion rules file to use when reading CSV (default: - FILE.rules) - - --alias=OLD=NEW - rename accounts named OLD to NEW - - --anon anonymize accounts and payees - - --pivot TAGNAME - use some other field/tag for account names - - -I --ignore-assertions - ignore any failing balance assertions - - General reporting options - -b --begin=DATE - include postings/txns on or after this date - - -e --end=DATE - include postings/txns before this date - - -D --daily - multiperiod/multicolumn report by day - - -W --weekly - multiperiod/multicolumn report by week - - -M --monthly - multiperiod/multicolumn report by month - - -Q --quarterly - multiperiod/multicolumn report by quarter - - -Y --yearly - multiperiod/multicolumn report by year - - -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once - (overrides the flags above) - - --date2 - show, and match with -b/-e/-p/date:, secondary dates instead - - -C --cleared - include only cleared postings/txns - - --pending - include only pending postings/txns - - -U --uncleared - include only uncleared (and pending) postings/txns - - -R --real - include only non-virtual postings - - --depth=N - hide accounts/postings deeper than N - - -E --empty - show items with zero amount, normally hidden - - -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) - - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) - - Note when multiple similar reporting options are provided, the last one - takes precedence. Eg -p feb -p mar is equivalent to -p mar. - - Some of these can also be written as queries. - 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 @@ -268,9 +275,9 @@ OPTIONS $ cat some.journal | hledger -f- - Usually the data file is in hledger's journal format, but it can also - be one of several other formats, listed below. hledger detects the - format automatically based on the file extension, or if that is not + Usually the data file is in hledger's journal format, but it can also + be one of several other formats, listed below. hledger detects the + format automatically based on the file extension, or if that is not recognised, by trying each built-in "reader" in turn: @@ -278,15 +285,15 @@ OPTIONS ----------------------------------------------------------------------------- journal hledger's journal format, also .journal .j .hledger some Ledger journals .ledger - timeclock timeclock files (precise time .timeclock + timeclock timeclock files (precise time .timeclock logging) - timedot timedot files (approximate time .timedot + timedot timedot files (approximate time .timedot logging) - csv comma-separated values (data .csv + csv comma-separated values (data .csv interchange) - If needed (eg to ensure correct error messages when a file has the - "wrong" extension), you can force a specific reader/format by prepend- + If needed (eg to ensure correct error messages when a file has the + "wrong" extension), you can force a specific reader/format by prepend- ing it to the file path with a colon. Examples: $ hledger -f csv:/some/csv-file.dat stats @@ -297,7 +304,7 @@ OPTIONS 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 those, either use the include directive, or concatenate the @@ -305,8 +312,8 @@ OPTIONS 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: @@ -314,10 +321,10 @@ OPTIONS 2009/1/1, 2009/01/01, simple dates, several sep- 2009-1-1, 2009.1.1 arators allowed - 2009/1, 2009 same as above - a missing + 2009/1, 2009 same as above - a missing day or month defaults to 1 - 1/1, january, jan, relative dates, meaning - this year january 1 of the current + 1/1, january, jan, relative dates, meaning + this year january 1 of the current year next year january 1 of next year this month the 1st of the current @@ -329,16 +336,16 @@ OPTIONS today, yesterday, tomorrow Report start & end date - Most hledger reports show the full span of time represented by the + 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 + will be the earliest and latest transaction or posting dates found in the journal. - 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. One important thing to be aware of when - specifying end dates: as in Ledger, end dates are exclusive, so you + accept the smart date syntax. One important thing to be aware of when + specifying end dates: as in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. Examples: @@ -348,10 +355,10 @@ OPTIONS day 2016 -e 12/1 end at the start of decem- ber 1st of the current - year (11/30 will be the + year (11/30 will be the last date included) - -b thismonth all transactions on or - after the 1st of the cur- + -b thismonth all transactions on or + after the 1st of the cur- rent month -p thismonth all transactions in the current month @@ -363,24 +370,24 @@ 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 + 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 intervals can not be specified with a query, currently. 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. + 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 "-". These are equivalent to the above: @@ -388,7 +395,7 @@ OPTIONS -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: @@ -400,31 +407,29 @@ OPTIONS earliest or latest transaction in your journal: - - -p "from 2009/1/1" everything after january 1, 2009 -p "from 2009/1" the same -p "from 2009" the same - -p "to 2009" everything before january + -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" - The argument of -p can also begin with, or be, a report interval - expression. The basic report intervals are daily, weekly, monthly, + The argument of -p can also begin with, or be, a report interval + expression. The basic report intervals are daily, weekly, monthly, quarterly, 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 + -Y flags. Between report interval and start/end dates (if any), the word in is optional. Examples: @@ -433,7 +438,7 @@ OPTIONS -p "quarterly" The following more complex report intervals are also supported: - biweekly, bimonthly, every N days|weeks|months|quarters|years, + biweekly, bimonthly, every N days|weeks|months|quarters|years, every Nth day [of month], every Nth day of week. Examples: @@ -443,19 +448,19 @@ OPTIONS -p "every 2 weeks" -p "every 5 days from 1/3" - 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, commands like account, balance and register - will show only the uppermost accounts in the account tree, down to + With the --depth N option, commands like account, balance 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 detail. Pivoting @@ -463,18 +468,17 @@ OPTIONS on account name. The --pivot TAGNAME option causes it to sum and orga- nize hierarchy based on some other field instead. - TAGNAME is the full, case-insensitive name of a tag you have defined, - or one of the built-in implicit tags (like code or payee). As with - account names, when tag values have multiple:colon-separated:parts + TAGNAME is the full, case-insensitive name of a tag you have defined, + or one of the built-in implicit tags (like code or payee). As with + account names, when tag values have multiple:colon-separated:parts hledger will build hierarchy, displayed in tree-mode reports, summaris- able with a depth limit, and so on. - --pivot affects all reports, and is one of those options you can write - before the command name if you wish. You can think of hledger trans- - forming the journal before any other processing, replacing every post- - ing's account name with the value of the specified tag on that posting, - inheriting it from the transaction or using a blank value if it's not - present. + --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 tag on + that posting, inheriting it from the transaction or using a blank value + if it's not present. An example: @@ -548,25 +552,24 @@ OPTIONS be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o To match a regular expression metacharacter like $ as a literal char- - acter, prepend a backslash. Eg to search for amounts with the dollar - sign in hledger-web, write cur:\$. + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts + with the dollar sign in hledger-web, write cur:\$. o On the command line, some metacharacters like $ have a special mean- - ing to the shell and so must be escaped a second time, with single or - double quotes or another backslash. Eg, to match amounts with the - dollar sign from the command line, write cur:'\$' or cur:\\$. + ing to the shell and so must be escaped at least once more. See Spe- + cial characters. QUERIES - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a + 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, optional prefixes to match specific fields. Multiple + whitespace, optional prefixes to match specific fields. Multiple search terms are combined as follows: - All commands except print: show transactions/postings/accounts which + All commands except print: show transactions/postings/accounts which match (or negatively match) o any of the description terms AND @@ -593,22 +596,22 @@ QUERIES 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 + \. 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:\\$. @@ -617,29 +620,29 @@ QUERIES 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 real:, real:0 match real or virtual postings respectively status:*, status:!, status: - match cleared, pending, or uncleared/pending transactions + match cleared, pending, or uncleared/pending 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. not: before any of the above negates the match. @@ -647,24 +650,24 @@ QUERIES inacct:ACCTNAME a special term used automatically when you click an account name in hledger-web, specifying the account register we are currently - in (selects the transactions of that account and how to show - them, can be filtered further with acct etc). Not supported + in (selects the transactions of that account and how to show + them, can be filtered further with acct etc). Not supported elsewhere in hledger. 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). COMMANDS - hledger provides a number of subcommands; hledger with no arguments + hledger provides a number of subcommands; hledger with no arguments shows a list. 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 + scripts named hledger-NAME in your PATH, these will also be listed as subcommands. - Run a subcommand by writing its name as first argument (eg + Run a subcommand by writing its name as first argument (eg hledger incomestatement). You can also write any unambiguous prefix of a command name (hledger inc), or one of the standard short aliases dis- played in the command list (hledger is). @@ -679,14 +682,14 @@ COMMANDS --drop=N in flat mode: omit N leading account name parts - This command lists all account names that are in use (ie, all the - accounts which have at least one transaction posting to them). With + This command lists all account names that are in use (ie, all the + accounts which have at least one transaction posting to them). With query arguments, only matched account names are shown. - It shows a flat list by default. With --tree, it uses indentation to + It shows a flat list by default. With --tree, it uses indentation to show the account hierarchy. - In flat mode you can add --drop N to omit the first few account name + In flat mode you can add --drop N to omit the first few account name components. Examples: @@ -729,8 +732,8 @@ COMMANDS activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. $ hledger activity --quarterly @@ -743,24 +746,24 @@ COMMANDS Prompt for transactions and add them to the journal. --no-new-accounts - don't allow creating new accounts; helps prevent typos when + don't allow creating new accounts; helps prevent typos when entering account names - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the journal file (if there are multiple + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the journal file (if there are multiple -f FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar recent + o add tries to provide useful defaults, using the most similar recent transaction (by description) as a template. o You can also set the initial defaults with command line arguments. @@ -768,20 +771,20 @@ COMMANDS o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. o Comments and tags may be entered following a description or amount. - o If you make a mistake, enter < at any prompt to restart the transac- + o If you make a mistake, enter < at any prompt to restart the transac- tion. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -818,7 +821,7 @@ COMMANDS show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports) -H --historical @@ -853,13 +856,13 @@ COMMANDS select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. --pretty-tables Use unicode to display prettier tables. - The balance command displays accounts and balances. It is hledger's + The balance command displays accounts and balances. It is hledger's most featureful and most useful command. $ hledger balance @@ -876,24 +879,24 @@ COMMANDS -------------------- 0 - More precisely, the balance command shows the change to each account's + More precisely, the balance command shows the change to each account's balance caused by all (matched) postings. In the common case where you - do not filter by date and your journal sets the correct opening bal- + do not filter by date and your journal sets the correct opening bal- ances, this is the same as the account's ending balance. - By default, accounts are displayed hierarchically, with subaccounts + By default, accounts are displayed hierarchically, with subaccounts indented below their parent. "Boring" accounts, which contain a single interesting subaccount and no balance of their own, are elided into the - following line for more compact output. (Use --no-elide to prevent + following line for more compact output. (Use --no-elide to prevent this.) - Each account's balance is the "inclusive" balance - it includes the + Each account's balance is the "inclusive" balance - it includes the balances of any subaccounts. - Accounts which have zero balance (and no non-zero subaccounts) are + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use -E/--empty to show them. - A final total is displayed by default; use -N/--no-total to suppress + A final total is displayed by default; use -N/--no-total to suppress it: $ hledger balance -p 2008/6 expenses --no-total @@ -903,9 +906,9 @@ COMMANDS Flat mode To see a flat list of full account names instead of the default hierar- - chical display, use --flat. In this mode, accounts (unless + chical display, use --flat. In this mode, accounts (unless depth-clipped) show their "exclusive" balance, excluding any subaccount - balances. In this mode, you can also use --drop N to omit the first + balances. In this mode, you can also use --drop N to omit the first few account name components. $ hledger balance -p 2008/6 expenses -N --flat --drop 1 @@ -913,9 +916,9 @@ COMMANDS $1 supplies Depth limited balance reports - With --depth N, balance shows accounts only to the specified depth. - This is very useful to show a complex charts of accounts in less - detail. In flat mode, balances from accounts below the depth limit + With --depth N, balance shows accounts only to the specified depth. + This is very useful to show a complex charts of accounts in less + detail. In flat mode, balances from accounts below the depth limit will be shown as part of a parent account at the depth limit. $ hledger balance -N --depth 1 @@ -925,12 +928,12 @@ COMMANDS $1 liabilities Multicolumn balance reports - With a reporting interval, multiple balance columns will be shown, one - for each report period. There are three types of multi-column balance + With a reporting interval, multiple balance columns will be shown, one + for each report period. There are three types of multi-column balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg + the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E @@ -945,8 +948,8 @@ COMMANDS -------------------++--------------------------------- || $-1 $1 0 0 - 2. With --cumulative: each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at + 2. With --cumulative: each column shows the ending balance for that + period, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -962,8 +965,8 @@ COMMANDS || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -979,26 +982,26 @@ COMMANDS ----------------------++------------------------------------- || 0 0 0 - Multi-column balance reports display accounts in flat mode by default; + Multi-column balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports: - first, the report will show all columns within the specified report - period (without -E, leading and trailing columns with all zeroes are - not shown). Second, all accounts which existed at the report start - date will be considered, not just the ones with activity during the + The -E/--empty flag does two things in multicolumn balance reports: + first, the report will show all columns within the specified report + period (without -E, leading and trailing columns with all zeroes are + not shown). Second, all accounts which existed at the report start + date will be considered, not just the ones with activity during the report period (use -E to include low-activity accounts which would oth- erwise would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -1022,10 +1025,10 @@ COMMANDS Market value The -V/--value flag converts the reported amounts to their market value on the report end date, using the most recent applicable market prices, - when known. Specifically, when there is a market price (P directive) + when known. Specifically, when there is a market price (P directive) for the amount's commodity, dated on or before the report end date (see - hledger -> Report start & end date), the amount will be converted to - the price's commodity. If multiple applicable prices are defined, the + hledger -> Report start & end date), the amount will be converted to + the price's commodity. If multiple applicable prices are defined, the latest-dated one is used (and if dates are equal, the one last parsed). For example: @@ -1057,13 +1060,13 @@ COMMANDS $ hledger -f t.j bal euros -V -e 2016/12/21 $103.00 assets:euros - Currently, hledger's -V only uses market prices recorded with P direc- + Currently, hledger's -V only uses market prices recorded with P direc- tives, not transaction prices (unlike Ledger). Using -B and -V together is allowed. Custom balance output - In simple (non-multi-column) balance reports, you can customise the + In simple (non-multi-column) balance reports, you can customise the output with --format FMT: $ hledger balance --format "%20(account) %12(total)" @@ -1081,7 +1084,7 @@ COMMANDS 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -1092,14 +1095,14 @@ COMMANDS o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -1108,7 +1111,7 @@ COMMANDS o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no + There are some quirks. Eg in one-line mode, %(depth_spacer) has no effect, instead %(account) has indentation built in. Experimentation may be needed to get pleasing results. @@ -1116,19 +1119,19 @@ COMMANDS o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Output destination - The balance, print, register and stats commands can write their output - to a destination other than the console. This is controlled by the + The balance, print, register and stats commands can write their output + to a destination other than the console. This is controlled by the -o/--output-file option. $ hledger balance -o - # write to stdout (the default) @@ -1136,8 +1139,8 @@ COMMANDS CSV output The balance, print and register commands can write their output as CSV. - This is useful for exporting data to other applications, eg to make - charts in a spreadsheet. This is controlled by the -O/--output-format + This is useful for exporting data to other applications, eg to make + charts in a spreadsheet. This is controlled by the -O/--output-format option, or by specifying a .csv file extension with -o/--output-file. $ hledger balance -O csv # write CSV to stdout @@ -1151,7 +1154,7 @@ COMMANDS balances --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of historical ending balances -H --historical @@ -1182,8 +1185,8 @@ COMMANDS --format=LINEFORMAT in single-column balance reports: use this custom line format - This command displays a simple balance sheet. It currently assumes - that you have top-level accounts named asset and liability (plural + This command displays a simple balance sheet. It currently assumes + that you have top-level accounts named asset and liability (plural forms also allowed.) $ hledger balancesheet @@ -1205,12 +1208,12 @@ COMMANDS -------------------- 0 - If given a period flag, renders a multi-column balance with the same - format as balance, with asset and liability totals as well as an over- + If given a period flag, renders a multi-column balance with the same + format as balance, with asset and liability totals as well as an over- all total if desired. - This command shows normally historical end-balance reports, but for - flexibility, also accepts --cumulative and --change to display cumula- + This command shows normally historical end-balance reports, but for + flexibility, also accepts --cumulative and --change to display cumula- tive ending balances and changes in reporting periods. cashflow @@ -1220,7 +1223,7 @@ COMMANDS show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1251,9 +1254,9 @@ COMMANDS --format=LINEFORMAT in single-column balance reports: use this custom line format - This command displays a simple cashflow statement It shows the change - in all "cash" (ie, liquid assets) accounts for the period. It cur- - rently assumes that cash accounts are under a top-level account named + This command displays a simple cashflow statement It shows the change + in all "cash" (ie, liquid assets) accounts for the period. It cur- + rently assumes that cash accounts are under a top-level account named asset and do not contain receivable or A/R (plural forms also allowed.) $ hledger cashflow @@ -1270,7 +1273,7 @@ COMMANDS -------------------- $-1 - If given a period flag, renders a multi-column balance with the same + If given a period flag, renders a multi-column balance with the same format as balance. This command normally shows period change reports, but for flexibility, @@ -1280,11 +1283,11 @@ COMMANDS help Show any of the hledger manuals. - The help command displays any of the main hledger man pages. (Unlike - hledger --help, which displays only the hledger man page.) Run it with - no arguments to list available topics (their names are shortened for - easier typing), and run hledger help TOPIC to select one. The output - is similar to a man page, but fixed width. It may be long, so you may + The help command displays any of the main hledger man pages. (Unlike + hledger --help, which displays only the hledger man page.) Run it with + no arguments to list available topics (their names are shortened for + easier typing), and run hledger help TOPIC to select one. The output + is similar to a man page, but fixed width. It may be long, so you may wish to pipe it into a pager. See also info and man. $ hledger help @@ -1312,7 +1315,7 @@ COMMANDS show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1343,8 +1346,8 @@ COMMANDS --format=LINEFORMAT in single-column balance reports: use this custom line format - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -1368,7 +1371,7 @@ COMMANDS -------------------- 0 - If given a period flag, renders a multi-column balance with the same + If given a period flag, renders a multi-column balance with the same format as balance. This command normally shows period change reports, but for flexibility, @@ -1378,23 +1381,23 @@ COMMANDS info Show any of the hledger manuals using info. - The info command displays any of the hledger reference manuals using - the info hypertextual documentation viewer. This can be a very effi- - cient way to browse large manuals. It requires the "info" program to + The info command displays any of the hledger reference manuals using + the info hypertextual documentation viewer. This can be a very effi- + cient way to browse large manuals. It requires the "info" program to be available in your PATH. - As with help, run it with no arguments to list available topics (manu- + As with help, run it with no arguments to list available topics (manu- als). man Show any of the hledger manuals using man. - The man command displays any of the hledger reference manuals using - man, the standard documentation viewer on unix systems. This will fit - the text to your terminal width, and probably invoke a pager automati- + The man command displays any of the hledger reference manuals using + man, the standard documentation viewer on unix systems. This will fit + the text to your terminal width, and probably invoke a pager automati- cally. It requires the "man" program to be available in your PATH. - As with help, run it with no arguments to list available topics (manu- + As with help, run it with no arguments to list available topics (manu- als). print @@ -1404,14 +1407,14 @@ COMMANDS show all amounts explicitly -m STR --match=STR - show the transaction whose description is most similar to STR, + show the transaction whose description is most similar to STR, and is most recent -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger print @@ -1439,23 +1442,23 @@ COMMANDS The print command displays full journal entries (transactions) from the journal file, tidily formatted. - As of hledger 1.2, print's output is always a valid hledger journal. - However it may not preserve all original content, eg it does not print + As of hledger 1.2, print's output is always a valid hledger journal. + However it may not preserve all original content, eg it does not print directives or inter-transaction comments. - Normally, transactions' implicit/explicit amount style is preserved: - when an amount is omitted in the journal, it will be omitted in the - output. You can use the -x/--explicit flag to make all amounts - explicit, which can be useful for troubleshooting or for making your - journal more readable and robust against data entry errors. Note, in - this mode postings with a multi-commodity amount (possible with an - implicit amount in a multi-commodity transaction) will be split into + Normally, transactions' implicit/explicit amount style is preserved: + when an amount is omitted in the journal, it will be omitted in the + output. You can use the -x/--explicit flag to make all amounts + explicit, which can be useful for troubleshooting or for making your + journal more readable and robust against data entry errors. Note, in + this mode postings with a multi-commodity amount (possible with an + implicit amount in a multi-commodity transaction) will be split into multiple single-commodity postings, for valid journal output. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost (using the transaction price). - The print command also supports output destination and CSV output. + The print command also supports output destination and CSV output. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -1472,20 +1475,20 @@ COMMANDS "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 + 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 + 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" + 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 + 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.) register @@ -1495,7 +1498,7 @@ COMMANDS show running total from report start date (default) -H --historical - show historical running total/balance (includes postings before + show historical running total/balance (includes postings before report start date) -A --average @@ -1506,18 +1509,18 @@ COMMANDS show postings' siblings instead -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M + set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular + total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -1526,8 +1529,8 @@ COMMANDS 2008/06/02 save assets:bank:checking $-1 $1 2008/12/31 pay off assets:bank:checking $-1 0 - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + 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 @@ -1537,23 +1540,23 @@ COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + 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 + 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 --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - With a reporting interval, register shows summary postings, one per + 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 + 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 @@ -1570,7 +1573,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth + 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 @@ -1578,19 +1581,19 @@ COMMANDS 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 + 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. 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 + 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: + 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: <--------------------------------- width (W) ----------------------------------> @@ -1606,14 +1609,14 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - The register command also supports the -o/--output-file and -O/--out- + The register command also supports the -o/--output-file and -O/--out- put-format options for controlling output destination and CSV output. stats Show some journal statistics. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger stats @@ -1628,8 +1631,8 @@ COMMANDS Accounts : 8 (depth 3) Commodities : 1 ($) - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. The stats command also supports -o/--output-file for controlling output @@ -1641,34 +1644,34 @@ COMMANDS $ hledger test Cases: 74 Tried: 74 Errors: 0 Failures: 0 - This command runs hledger's built-in unit tests and displays a quick + This command runs hledger's built-in unit tests and displays a quick report. With a regular expression argument, it selects only tests with matching names. It's mainly used in development, but it's also nice to be able to check your hledger executable for smoke at any time. ADD-ON COMMANDS - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + 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). - Add-ons can be invoked like any hledger command, but there are a few + 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, o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - 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; + 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 You can always run add-ons directly if preferred: + o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - 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 + 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. Here are some hledger add-ons available: @@ -1686,7 +1689,7 @@ ADD-ON COMMANDS hledger-web provides a simple web interface. Third party add-ons - These are maintained separately, and usually updated shortly after a + These are maintained separately, and usually updated shortly after a hledger release. diff @@ -1694,7 +1697,7 @@ ADD-ON COMMANDS journal file and another. iadd - hledger-iadd is a curses-style, more interactive replacement for the + hledger-iadd is a curses-style, more interactive replacement for the add command. interest @@ -1702,19 +1705,19 @@ ADD-ON COMMANDS ing to various schemes. irr - hledger-irr calculates the internal rate of return of an investment + hledger-irr calculates the internal rate of return of an investment account. Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- + These are available in source form in the hledger repo's bin/ direc- tory; installing them is pretty easy. They may be less mature and doc- - umented than built-in commands. Reading and tweaking these is a good + umented than built-in commands. Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. budget @@ -1730,18 +1733,18 @@ ADD-ON COMMANDS hledger-check-dates.hs checks that journal entries are ordered by date. check-dupes - hledger-check-dupes.hs checks for account names sharing the same leaf + hledger-check-dupes.hs checks for account names sharing the same leaf name. equity - hledger-equity.hs prints balance-resetting transactions, useful for + hledger-equity.hs prints balance-resetting transactions, useful for bringing account balances across file boundaries. prices hledger-prices.hs prints all prices from the journal. print-unique - hledger-print-unique.hs prints transactions which do not reuse an + hledger-print-unique.hs prints transactions which do not reuse an already-seen description. register-match @@ -1752,8 +1755,41 @@ ADD-ON COMMANDS hledger-rewrite.hs Adds one or more custom postings to matched transac- tions. +ENVIRONMENT + COLUMNS The screen width used by the register command. Default: the + full terminal width. + + LEDGER_FILE The journal file path when not specified with -f. Default: + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + nal). + +FILES + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). + +BUGS + The need to precede addon command options with -- when invoked from + hledger is awkward. + + When input data contains non-ascii characters, a suitable system locale + must be configured (or there will be an unhelpful error). Eg on POSIX, + set LANG to something other than C. + + In a Microsoft Windows CMD window, non-ascii characters and colours are + not supported. + + In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger + add. + + Not all of Ledger's journal file syntax is supported. See file format + differences. + + On large data files, hledger is slower and uses more memory than + Ledger. + TROUBLESHOOTING - Run-time problems Here are some issues you might encounter when you run hledger (and remember you can also seek help from the IRC channel, mail list or bug tracker): @@ -1810,54 +1846,6 @@ TROUBLESHOOTING Note some platforms allow variant locale spellings, but not all (ubuntu accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8). - Known limitations - Command line interface - - Add-on command options, unless they are also understood by the main - hledger executable, must be written after --, like this: - hledger web -- --server - - Differences from Ledger - - Not all of Ledger's journal file syntax is supported. See file format - differences. - - hledger is slower than Ledger, and uses more memory, on large data - files. - - Windows limitations - - In a windows CMD window, non-ascii characters and colours are not sup- - ported. - - In a windows Cygwin/MSYS/Mintty window, the tab key is not supported in - hledger add. - -ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the - full terminal width. - - LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- - nal). - -FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). - -BUGS - The need to precede options with -- when invoked from hledger is awk- - ward. - - hledger can't render non-ascii characters when run from a Windows com- - mand prompt (up to Windows 7 at least). - - When input data contains non-ascii characters, a suitable system locale - must be configured (or there will be an unhelpful error). Eg on POSIX, - set LANG to something other than C. - REPORTING BUGS