doc: use m4 just to assemble main hledger man page
I was about to drop the m4 experiment, but.. not yet. I want to split up the big man pages into chunks that are easier to deal with, so now using m4 for that (only. Pandoc is taking care of selective content stripping and other rendering adjustments.) I've switched the suffix of m4-enabled files from .md.m4 to .m4.md - less correct but activates more useful editor highlighting.
This commit is contained in:
Simon Michael
parent
88eb113f7b
commit
e4aaa302ce
64
Shake.hs
64
Shake.hs
@ -46,8 +46,6 @@ usage = [i|Usage:
|
|||||||
./Shake manpages # generate nroff files for man
|
./Shake manpages # generate nroff files for man
|
||||||
./Shake webmanpages # generate web man pages for hakyll
|
./Shake webmanpages # generate web man pages for hakyll
|
||||||
./Shake webmanual # generate combined web man page for hakyll
|
./Shake webmanual # generate combined web man page for hakyll
|
||||||
./Shake m4manpages # generate nroff files for man (alternate method)
|
|
||||||
./Shake m4webmanpages # generate web man pages for hakyll (alternate method)
|
|
||||||
|]
|
|]
|
||||||
|
|
||||||
buildDir = ".build"
|
buildDir = ".build"
|
||||||
@ -83,8 +81,6 @@ main = do
|
|||||||
phony "site" $ need [
|
phony "site" $ need [
|
||||||
"manpages"
|
"manpages"
|
||||||
,"webmanpages"
|
,"webmanpages"
|
||||||
,"m4manpages"
|
|
||||||
,"m4webmanpages"
|
|
||||||
,"site/manual2.md"
|
,"site/manual2.md"
|
||||||
]
|
]
|
||||||
|
|
||||||
@ -115,15 +111,25 @@ main = do
|
|||||||
| '_' `elem` m = "hledger-lib" </> "doc"
|
| '_' `elem` m = "hledger-lib" </> "doc"
|
||||||
| otherwise = dropExtension m </> "doc"
|
| otherwise = dropExtension m </> "doc"
|
||||||
|
|
||||||
-- method 1:
|
-- some man pages have their md source assembled from parts with m4
|
||||||
|
let m4manpages = [manpageDir m </> m <.> ".md" | m <- ["hledger.1"]] -- hledger/doc/hledger.1.md
|
||||||
|
m4manpages |%> \out -> do -- hledger/doc/hledger.1.md
|
||||||
|
let dir = takeDirectory out -- hledger/doc
|
||||||
|
m4src = out -<.> "m4" <.> "md" -- hledger/doc/hledger.1.m4.md
|
||||||
|
m4lib = "doc/lib.m4"
|
||||||
|
-- assume all other m4 files in dir are included by this one
|
||||||
|
m4deps <- liftIO $ filter (/= m4src) . filter (".m4.md" `isSuffixOf`) . map (dir </>)
|
||||||
|
<$> S.getDirectoryContents dir
|
||||||
|
need $ m4src : m4lib : m4deps
|
||||||
|
cmd Shell "m4 -P -DWEB -DMAN -I" dir m4lib m4src ">" out
|
||||||
|
|
||||||
-- pandoc filters, these adjust master md files for web or man output
|
-- compile pandoc filters, used eg for adjusting manpage md source for web or man output
|
||||||
phony "pandocfilters" $ need pandocFilters
|
phony "pandocfilters" $ need pandocFilters
|
||||||
pandocFilters |%> \out -> do
|
pandocFilters |%> \out -> do
|
||||||
need [out <.> "hs"]
|
need [out <.> "hs"]
|
||||||
cmd ("stack ghc") out
|
cmd ("stack ghc") out
|
||||||
|
|
||||||
-- man pages adjusted for man and converted to nroff, by pandoc
|
-- adjust man page mds for man output and convert to nroff, with pandoc
|
||||||
let manpages = [manpageDir m </> m | m <- manpageNames] -- hledger/doc/hledger.1, hledger-lib/doc/hledger_journal.5
|
let manpages = [manpageDir m </> m | m <- manpageNames] -- hledger/doc/hledger.1, hledger-lib/doc/hledger_journal.5
|
||||||
phony "manpages" $ need manpages
|
phony "manpages" $ need manpages
|
||||||
manpages |%> \out -> do
|
manpages |%> \out -> do
|
||||||
@ -138,7 +144,7 @@ main = do
|
|||||||
"--filter doc/pandoc-drop-notes"
|
"--filter doc/pandoc-drop-notes"
|
||||||
"-o" out
|
"-o" out
|
||||||
|
|
||||||
-- man pages adjusted for web by pandoc (ready for hakyll)
|
-- adjust man page mds for (hakyll) web output, with pandoc
|
||||||
let webmanpages = ["site" </> manpageNameToUri m <.>".md" | m <- manpageNames] -- site/hledger.md, site/journal.md
|
let webmanpages = ["site" </> manpageNameToUri m <.>".md" | m <- manpageNames] -- site/hledger.md, site/journal.md
|
||||||
phony "webmanpages" $ need webmanpages
|
phony "webmanpages" $ need webmanpages
|
||||||
webmanpages |%> \out -> do
|
webmanpages |%> \out -> do
|
||||||
@ -151,44 +157,7 @@ main = do
|
|||||||
-- "--filter doc/pandoc-drop-man-blocks"
|
-- "--filter doc/pandoc-drop-man-blocks"
|
||||||
"-o" out
|
"-o" out
|
||||||
|
|
||||||
-- method 2:
|
-- adjust and combine man page mds for single-page web output, using pandoc
|
||||||
|
|
||||||
-- man pages assembled from parts and adjusted for man with m4, adjusted more and converted to nroff with pandoc
|
|
||||||
let m4manpages = [manpageDir m </> "m4-"++m | m <- ["hledger.1"]] -- hledger/doc/m4-hledger.1
|
|
||||||
phony "m4manpages" $ need m4manpages
|
|
||||||
m4manpages |%> \out -> do -- hledger/doc/m4-hledger.1
|
|
||||||
let (dir,file) = splitFileName out -- hledger/doc, m4-hledger.1
|
|
||||||
m4src = dir </> drop 3 file <.> "md" <.> "m4" -- hledger/doc/hledger.1.md.m4
|
|
||||||
m4includes = map (dir </>) ["description.md","examples.md","queries.md","commands.md","options.md"]
|
|
||||||
m4lib = "doc/lib.m4"
|
|
||||||
tmpl = "doc/manpage.nroff"
|
|
||||||
need $ m4src : m4lib : tmpl : pandocFilters ++ m4includes
|
|
||||||
cmd Shell "m4 -P" "-DMAN" "-I" dir m4lib m4src
|
|
||||||
"|" pandoc "-s --template" tmpl
|
|
||||||
"--filter doc/pandoc-drop-html-blocks"
|
|
||||||
"--filter doc/pandoc-drop-html-inlines"
|
|
||||||
"--filter doc/pandoc-drop-links"
|
|
||||||
"--filter doc/pandoc-drop-notes"
|
|
||||||
"-o" out
|
|
||||||
|
|
||||||
-- man pages assembled from parts and adjusted for web with m4, adjusted slightly more with pandoc (ready for hakyll)
|
|
||||||
let m4webmanpages = ["site" </> "m4-" ++ manpageNameToUri m <.> ".md" | m <- ["hledger.1"]] -- site/m4-hledger.md
|
|
||||||
phony "m4webmanpages" $ need $ m4webmanpages
|
|
||||||
m4webmanpages |%> \out -> do -- site/m4-hledger.md
|
|
||||||
let file = takeFileName out -- m4-hledger.1.md
|
|
||||||
manpage = manpageUriToName $ drop 3 $ dropExtension file -- hledger.1
|
|
||||||
dir = manpageDir manpage -- hledger/doc
|
|
||||||
m4src = dir </> manpage <.> "md" <.> "m4" -- hledger/doc/hledger.1.md.m4
|
|
||||||
m4includes = map (dir </>) ["description.md","examples.md","queries.md","commands.md","options.md"]
|
|
||||||
m4lib = "doc/lib.m4"
|
|
||||||
need $ m4src : m4lib : m4includes
|
|
||||||
cmd Shell "m4 -P" "-DMAN -DWEB" "-I" dir m4lib m4src
|
|
||||||
"|" pandoc
|
|
||||||
"--filter doc/pandoc-demote-headers"
|
|
||||||
-- "--filter doc/pandoc-add-toc"
|
|
||||||
"-o" out
|
|
||||||
|
|
||||||
-- web manual combined from man pages
|
|
||||||
|
|
||||||
let webmanual = "site/manual2.md"
|
let webmanual = "site/manual2.md"
|
||||||
phony "webmanual" $ need [ webmanual ]
|
phony "webmanual" $ need [ webmanual ]
|
||||||
@ -225,8 +194,7 @@ main = do
|
|||||||
|
|
||||||
phony "clean" $ do
|
phony "clean" $ do
|
||||||
putNormal "Cleaning generated files"
|
putNormal "Cleaning generated files"
|
||||||
removeFilesAfter "." m4manpages
|
removeFilesAfter "." ["hledger/doc/hledger.1.md"]
|
||||||
removeFilesAfter "." m4webmanpages
|
|
||||||
removeFilesAfter "." webmanpages
|
removeFilesAfter "." webmanpages
|
||||||
removeFilesAfter "." [webmanual]
|
removeFilesAfter "." [webmanual]
|
||||||
|
|
||||||
|
|||||||
1
hledger/doc/.gitignore
vendored
Normal file
1
hledger/doc/.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
|||||||
|
hledger.1.md
|
||||||
@ -2,8 +2,11 @@
|
|||||||
%
|
%
|
||||||
% October 2015
|
% October 2015
|
||||||
|
|
||||||
_web_(* toc)
|
<div class="web">
|
||||||
_man_({{
|
* toc
|
||||||
|
</div>
|
||||||
|
<div class="man">
|
||||||
|
|
||||||
# NAME
|
# NAME
|
||||||
|
|
||||||
hledger - a command-line accounting tool
|
hledger - a command-line accounting tool
|
||||||
@ -21,13 +24,15 @@ file format. It is inspired by and largely compatible with ledger(1).
|
|||||||
hledger aims to be a reliable, practical tool for daily use. This man
|
hledger aims to be a reliable, practical tool for daily use. This man
|
||||||
page is a quick reference and introduction; for more complete docs, see
|
page is a quick reference and introduction; for more complete docs, see
|
||||||
http://hledger.org/manual.
|
http://hledger.org/manual.
|
||||||
}})
|
</div>
|
||||||
_include_(description.md)
|
|
||||||
_include_(options.md)
|
_include_(description.m4.md)
|
||||||
_include_(commands.md)
|
_include_(options.m4.md)
|
||||||
_include_(queries.md)
|
_include_(commands.m4.md)
|
||||||
_include_(examples.md)
|
_include_(queries.m4.md)
|
||||||
_man_({{
|
_include_(examples.m4.md)
|
||||||
|
|
||||||
|
<div class="man">
|
||||||
|
|
||||||
# ENVIRONMENT
|
# ENVIRONMENT
|
||||||
|
|
||||||
@ -57,3 +62,4 @@ Eg on POSIX, set LANG to something other than C.
|
|||||||
Report bugs at http://bugs.hledger.org.
|
Report bugs at http://bugs.hledger.org.
|
||||||
|
|
||||||
}})
|
}})
|
||||||
|
</div>
|
||||||
@ -1,520 +0,0 @@
|
|||||||
% hledger(1) hledger 0.26.98
|
|
||||||
%
|
|
||||||
% October 2015
|
|
||||||
|
|
||||||
<div class="web">
|
|
||||||
* toc
|
|
||||||
</div>
|
|
||||||
<div class="man">
|
|
||||||
# NAME
|
|
||||||
|
|
||||||
hledger - a command-line accounting tool
|
|
||||||
|
|
||||||
# SYNOPSIS
|
|
||||||
|
|
||||||
`hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS]`\
|
|
||||||
`hledger [-f FILE] ADDONCMD -- [OPTIONS] [CMDARGS]`
|
|
||||||
|
|
||||||
# DESCRIPTION
|
|
||||||
|
|
||||||
hledger is a cross-platform program for tracking money, time, or any
|
|
||||||
other commodity, using double-entry accounting and a simple, editable
|
|
||||||
file format. It is inspired by and largely compatible with ledger(1).
|
|
||||||
hledger aims to be a reliable, practical tool for daily use. This man
|
|
||||||
page is a quick reference and introduction; for more complete docs, see
|
|
||||||
http://hledger.org/manual.
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
This is hledger’s command-line interface (there are also curses and web
|
|
||||||
interfaces). Its basic function is to read a plain text file describing
|
|
||||||
financial transactions (in accounting terms, a general journal) and
|
|
||||||
print useful reports on standard output, or export them as CSV. hledger
|
|
||||||
can also read CSV files, converting them semi-automatically to journal
|
|
||||||
format. Additionally, hledger lists other hledger-\* executables found
|
|
||||||
in the user’s \$PATH and can invoke them as subcommands.
|
|
||||||
|
|
||||||
The journal file is `~/.hledger.journal` by default, or another file path
|
|
||||||
specified by `$LEDGER_FILE`.
|
|
||||||
(This should be a real environment variable, not a shell variable.)
|
|
||||||
You can also specify a file with `-f FILE`,
|
|
||||||
or standard input with `-f-`.
|
|
||||||
|
|
||||||
Transactions are dated movements of money between two (or more) named
|
|
||||||
accounts, and are recorded with journal entries like this:
|
|
||||||
|
|
||||||
```journal
|
|
||||||
2015/10/16 bought food
|
|
||||||
expenses:food $10
|
|
||||||
assets:cash
|
|
||||||
```
|
|
||||||
|
|
||||||
For more about the format, see hledger_journal(5).
|
|
||||||
|
|
||||||
Most users use a text editor to edit the journal, usually with an editor
|
|
||||||
mode such as ledger-mode for added convenience. hledger’s interactive
|
|
||||||
add command is another way to record new transactions. hledger never
|
|
||||||
changes existing transactions.
|
|
||||||
|
|
||||||
To get started, you can either save some entries like the above in
|
|
||||||
`~/.hledger.journal`, or run `hledger add` and follow the prompts. Then
|
|
||||||
try some commands like `hledger print` or `hledger balance`.
|
|
||||||
See COMMANDS and EXAMPLES below.
|
|
||||||
|
|
||||||
# OPTIONS
|
|
||||||
|
|
||||||
To see general help and the command list: `hledger --help` or `hledger`
|
|
||||||
|
|
||||||
To see all options available with a command: `hledger COMMAND --help`
|
|
||||||
|
|
||||||
Except for the General options below, options must be written after
|
|
||||||
COMMAND, not before it.
|
|
||||||
|
|
||||||
Also, when invoking external add-on commands, their options must be
|
|
||||||
written after a double hyphen. (Or, you can invoke the external command
|
|
||||||
directly.) Eg:
|
|
||||||
```{.shell .bold}
|
|
||||||
$ hledger ui -- --register cash
|
|
||||||
$ hledger-ui --register cash
|
|
||||||
```
|
|
||||||
|
|
||||||
Options and command arguments can be intermixed. Arguments are usually
|
|
||||||
interpreted as a search query which filters the data, see QUERIES.
|
|
||||||
|
|
||||||
There are three kinds of options.
|
|
||||||
General options are always available and can appear anywhere in the command line:
|
|
||||||
|
|
||||||
`-h --help`
|
|
||||||
: show general help or (after command) command help
|
|
||||||
|
|
||||||
`--version`
|
|
||||||
: show version information
|
|
||||||
|
|
||||||
`-f FILE --file=FILE`
|
|
||||||
: use a different input file. For stdin, use -
|
|
||||||
|
|
||||||
`--rules-file=RULESFILE`
|
|
||||||
: Conversion rules file to use when reading CSV (default: FILE.rules)
|
|
||||||
|
|
||||||
`--alias=OLD=NEW`
|
|
||||||
: display accounts named OLD as NEW
|
|
||||||
|
|
||||||
`--ignore-assertions`
|
|
||||||
: ignore any failing balance assertions in the journal
|
|
||||||
|
|
||||||
`--debug=N`
|
|
||||||
: : show debug output if N is 1-9 (default: 0)
|
|
||||||
|
|
||||||
|
|
||||||
Common reporting options are supported by most commands where applicable,
|
|
||||||
and individual commands may provide additional command-specific options.
|
|
||||||
Both of these must be written after the command name.
|
|
||||||
|
|
||||||
`-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 --aux-date`
|
|
||||||
: use postings/txns' 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 empty/zero things which are normally omitted
|
|
||||||
|
|
||||||
`-B --cost `
|
|
||||||
: show amounts in their cost price's commodity
|
|
||||||
|
|
||||||
If a reporting option is repeated, the last one takes precedence. Eg -p jan -p
|
|
||||||
feb is equivalent to -p feb.
|
|
||||||
|
|
||||||
# COMMANDS
|
|
||||||
|
|
||||||
COMMAND selects one of hledger's subcommands; omit it to list available commands.
|
|
||||||
To save typing, some commands have a short form; any unique prefix also works.
|
|
||||||
|
|
||||||
Here is a summary (see http://hledger.org/manual#commands for the full command help):
|
|
||||||
|
|
||||||
## Data entry
|
|
||||||
|
|
||||||
### add
|
|
||||||
prompt for transactions and add them to the journal.
|
|
||||||
|
|
||||||
This is the only hledger command that writes to the journal file.
|
|
||||||
It appends only, existing transactions are not changed.
|
|
||||||
|
|
||||||
`--no-new-accounts`
|
|
||||||
: don't allow creating new accounts; helps prevent typos when entering account names
|
|
||||||
|
|
||||||
## Reporting
|
|
||||||
|
|
||||||
### accounts
|
|
||||||
show account names
|
|
||||||
|
|
||||||
`--tree`
|
|
||||||
: show short account names, as a tree
|
|
||||||
|
|
||||||
`--flat`
|
|
||||||
: show full account names, as a list (default)
|
|
||||||
|
|
||||||
`--drop=N`
|
|
||||||
: in flat mode: omit N leading account name parts
|
|
||||||
|
|
||||||
### activity
|
|
||||||
show an ascii barchart of posting counts per interval
|
|
||||||
(default: daily)
|
|
||||||
|
|
||||||
### balance, bal
|
|
||||||
show accounts and balances
|
|
||||||
|
|
||||||
`--tree`
|
|
||||||
: show short account names, as a tree
|
|
||||||
|
|
||||||
`--flat`
|
|
||||||
: show full account names, as a list (default)
|
|
||||||
|
|
||||||
`--drop=N`
|
|
||||||
: in flat mode: omit N leading account name parts
|
|
||||||
|
|
||||||
`--format=LINEFORMAT`
|
|
||||||
: in single-column balance reports: use this custom line format
|
|
||||||
|
|
||||||
`--no-elide`
|
|
||||||
: in tree mode: don't squash boring parent accounts
|
|
||||||
|
|
||||||
`-H --historical`
|
|
||||||
: in multicolumn mode: show historical ending balances
|
|
||||||
|
|
||||||
`--cumulative`
|
|
||||||
: in multicolumn mode: show accumulated ending balances
|
|
||||||
|
|
||||||
`-A --average`
|
|
||||||
: in multicolumn mode: show a row average column
|
|
||||||
|
|
||||||
`-T --row-total`
|
|
||||||
: in multicolumn mode: show a row total column
|
|
||||||
|
|
||||||
`-N --no-total`
|
|
||||||
: don't show the final total row
|
|
||||||
|
|
||||||
`-V --value`
|
|
||||||
: show amounts as their current market value in their default valuation commodity
|
|
||||||
|
|
||||||
`-o FILE[.FMT] --output-file=FILE[.FMT]`
|
|
||||||
: write output to FILE instead of stdout. A recognised FMT suffix influences the format.
|
|
||||||
|
|
||||||
`-O FMT --output-format=FMT `
|
|
||||||
: select the output format. Supported formats:
|
|
||||||
txt, csv.
|
|
||||||
|
|
||||||
### balancesheet, bs
|
|
||||||
show a balance sheet
|
|
||||||
|
|
||||||
`--flat`
|
|
||||||
: show full account names, as a list (default)
|
|
||||||
|
|
||||||
`--drop=N`
|
|
||||||
: in flat mode: omit N leading account name parts
|
|
||||||
|
|
||||||
### cashflow, cf
|
|
||||||
show a cashflow statement
|
|
||||||
|
|
||||||
`--flat`
|
|
||||||
: show full account names, as a list (default)
|
|
||||||
|
|
||||||
`--drop=N`
|
|
||||||
: in flat mode: omit N leading account name parts
|
|
||||||
|
|
||||||
### incomestatement, is
|
|
||||||
show an income statement
|
|
||||||
|
|
||||||
`--flat`
|
|
||||||
: show full account names, as a list (default)
|
|
||||||
|
|
||||||
`--drop=N`
|
|
||||||
: in flat mode: omit N leading account name parts
|
|
||||||
|
|
||||||
### print
|
|
||||||
show transactions from the journal
|
|
||||||
|
|
||||||
`-m STR --match=STR `
|
|
||||||
: show the transaction whose description is most similar to STR, and is most recent
|
|
||||||
|
|
||||||
`-o FILE[.FMT] --output-file=FILE[.FMT]`
|
|
||||||
: write output to FILE instead of stdout. A recognised FMT suffix influences the format.
|
|
||||||
|
|
||||||
`-O FMT --output-format=FMT `
|
|
||||||
: select the output format. Supported formats:
|
|
||||||
txt, csv.
|
|
||||||
|
|
||||||
### register, reg
|
|
||||||
show postings and running total
|
|
||||||
|
|
||||||
`-H --historical`
|
|
||||||
: include prior postings in the running total
|
|
||||||
|
|
||||||
`-A --average`
|
|
||||||
: show a running average instead of the running total (implies --empty)
|
|
||||||
|
|
||||||
`-r --related`
|
|
||||||
: show postings' siblings instead
|
|
||||||
|
|
||||||
`-w N --width=N`
|
|
||||||
: set output width (default: terminal width or COLUMNS. -wN,M sets description width as well)
|
|
||||||
|
|
||||||
`-o FILE[.FMT] --output-file=FILE[.FMT]`
|
|
||||||
: write output to FILE instead of stdout. A recognised FMT suffix influences the format.
|
|
||||||
|
|
||||||
`-O FMT --output-format=FMT `
|
|
||||||
: select the output format. Supported formats:
|
|
||||||
txt, csv.
|
|
||||||
|
|
||||||
### stats
|
|
||||||
show some journal statistics
|
|
||||||
|
|
||||||
`-o FILE[.FMT] --output-file=FILE[.FMT]`
|
|
||||||
: write output to FILE instead of stdout. A recognised FMT suffix influences the format.
|
|
||||||
|
|
||||||
## Add-on commands
|
|
||||||
|
|
||||||
Additional commands will be available when executables or scripts
|
|
||||||
named "`hledger-`CMD" are installed in the PATH. These are often
|
|
||||||
provided by a package of the same name, or you can make your own custom scripts
|
|
||||||
(haskell scripts can use hledger-lib allowing tight integration).
|
|
||||||
Some available add-ons are:
|
|
||||||
|
|
||||||
### autosync
|
|
||||||
download OFX bank data and/or convert OFX to hledger journal format
|
|
||||||
|
|
||||||
### diff
|
|
||||||
show transactions present in one journal file but not another
|
|
||||||
|
|
||||||
### interest
|
|
||||||
generate interest transactions
|
|
||||||
|
|
||||||
### irr
|
|
||||||
calculate internal rate of return
|
|
||||||
|
|
||||||
### ui
|
|
||||||
curses-style interface, see hledger-ui(1)
|
|
||||||
|
|
||||||
### web
|
|
||||||
web interface, see hledger-web(1)
|
|
||||||
|
|
||||||
# QUERIES
|
|
||||||
|
|
||||||
Most commands accept an optional query expression, written as arguments after the command name,
|
|
||||||
to filter the data by date, account name or other criteria.
|
|
||||||
The syntax is similar to a web search:
|
|
||||||
one or more space-separated search terms,
|
|
||||||
quotes to enclose whitespace,
|
|
||||||
optional prefixes to match specific fields.
|
|
||||||
Multiple search terms are combined as follows:
|
|
||||||
|
|
||||||
All commands except print: show transactions/postings/accounts which match (or negatively match)
|
|
||||||
|
|
||||||
- any of the description terms AND
|
|
||||||
- any of the account terms AND
|
|
||||||
- all the other terms.
|
|
||||||
|
|
||||||
The print command: show transactions which
|
|
||||||
|
|
||||||
- match any of the description terms AND
|
|
||||||
- have any postings matching any of the positive account terms AND
|
|
||||||
- have no postings matching any of the negative account terms AND
|
|
||||||
- match all the other terms.
|
|
||||||
|
|
||||||
The following kinds of search terms can be used:
|
|
||||||
|
|
||||||
|
|
||||||
**`REGEX`**
|
|
||||||
: match account names by this regular expression
|
|
||||||
|
|
||||||
|
|
||||||
**`acct:REGEX`**
|
|
||||||
: same as above
|
|
||||||
|
|
||||||
|
|
||||||
**`amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N`**
|
|
||||||
: match postings with a single-commodity amount that is equal to, less
|
|
||||||
than, or greater than N. (Multi-commodity amounts are not tested, and
|
|
||||||
will always match.) The comparison has two modes: if N is preceded by
|
|
||||||
a + or - sign (or is 0), the two signed numbers are
|
|
||||||
compared. Otherwise, the absolute magnitudes are compared, ignoring
|
|
||||||
sign.
|
|
||||||
|
|
||||||
|
|
||||||
**`code:REGEX`**
|
|
||||||
: match by transaction code (eg check number)
|
|
||||||
|
|
||||||
|
|
||||||
**`cur:REGEX`**
|
|
||||||
: match postings or transactions including any amounts whose
|
|
||||||
currency/commodity symbol is fully matched by REGEX. (For a partial
|
|
||||||
match, use `.*REGEX.*`). Note, to match characters which are
|
|
||||||
regex-significant, like the dollar sign (`$`), you need to prepend `\`.
|
|
||||||
And when using the command line you need to add one more level of
|
|
||||||
quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
|
|
||||||
or `hledger print cur:\\$`.
|
|
||||||
|
|
||||||
|
|
||||||
**`desc:REGEX`**
|
|
||||||
: match transaction descriptions
|
|
||||||
|
|
||||||
|
|
||||||
**`date:PERIODEXPR`**
|
|
||||||
: match dates within the specified period (which should not include a
|
|
||||||
reporting interval
|
|
||||||
|
|
||||||
|
|
||||||
**`date2:PERIODEXPR`**
|
|
||||||
: as above, but match secondary dates
|
|
||||||
|
|
||||||
|
|
||||||
**`depth:N`**
|
|
||||||
: 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 respectively
|
|
||||||
|
|
||||||
|
|
||||||
**`tag:REGEX[=REGEX]`**
|
|
||||||
: match by tag name, and optionally also by tag value. Note a
|
|
||||||
tag: query is considered to match a transaction if it matches any of
|
|
||||||
the postings. Also remember that postings inherit the tags of their
|
|
||||||
parent transaction.
|
|
||||||
|
|
||||||
|
|
||||||
**`not:`**
|
|
||||||
: before any of the above negates the match.
|
|
||||||
|
|
||||||
# EXAMPLES
|
|
||||||
|
|
||||||
Two simple transactions in hledger journal format:
|
|
||||||
|
|
||||||
```journal
|
|
||||||
2015/9/30 gift received
|
|
||||||
assets:cash $20
|
|
||||||
income:gifts
|
|
||||||
|
|
||||||
2015/10/16 farmers market
|
|
||||||
expenses:food $10
|
|
||||||
assets:cash
|
|
||||||
```
|
|
||||||
|
|
||||||
Some basic reports:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ hledger print
|
|
||||||
2015/09/30 gift received
|
|
||||||
assets:cash $20
|
|
||||||
income:gifts $-20
|
|
||||||
|
|
||||||
2015/10/16 farmers market
|
|
||||||
expenses:food $10
|
|
||||||
assets:cash $-10
|
|
||||||
```
|
|
||||||
```shell
|
|
||||||
$ hledger accounts --tree
|
|
||||||
assets
|
|
||||||
cash
|
|
||||||
expenses
|
|
||||||
food
|
|
||||||
income
|
|
||||||
gifts
|
|
||||||
```
|
|
||||||
```shell
|
|
||||||
$ hledger balance
|
|
||||||
$10 assets:cash
|
|
||||||
$10 expenses:food
|
|
||||||
$-20 income:gifts
|
|
||||||
--------------------
|
|
||||||
0
|
|
||||||
```
|
|
||||||
```shell
|
|
||||||
$ hledger register cash
|
|
||||||
2015/09/30 gift received assets:cash $20 $20
|
|
||||||
2015/10/16 farmers market assets:cash $-10 $10
|
|
||||||
```
|
|
||||||
|
|
||||||
```{.shell .bold}
|
|
||||||
$ hledger # show available commands
|
|
||||||
$ hledger add # add more transactions to the journal file
|
|
||||||
$ hledger balance # all accounts with aggregated balances
|
|
||||||
$ hledger balance --help # show help for balance command
|
|
||||||
$ hledger balance --depth 1 # only top-level accounts
|
|
||||||
$ hledger register # show account postings, with running total
|
|
||||||
$ hledger reg income # show postings to/from income accounts
|
|
||||||
$ hledger reg 'assets:some bank:checking' # show postings to/from this checking account
|
|
||||||
$ hledger print desc:shop # show transactions with shop in the description
|
|
||||||
$ hledger activity -W # show transaction counts per week as a bar chart
|
|
||||||
```
|
|
||||||
|
|
||||||
<div class="man">
|
|
||||||
|
|
||||||
# ENVIRONMENT
|
|
||||||
|
|
||||||
**LEDGER_FILE**
|
|
||||||
sets the default journal file path. If not set, it is `~/.hledger.journal`.
|
|
||||||
|
|
||||||
**COLUMNS**
|
|
||||||
sets the default width used by the register command (normally the full terminal width).
|
|
||||||
|
|
||||||
# FILES
|
|
||||||
|
|
||||||
Reads data from a hledger journal file (`$LEDGER_FILE` or
|
|
||||||
`~/.hledger.journal` by default), or a CSV file plus associated CSV
|
|
||||||
rules file.
|
|
||||||
|
|
||||||
# BUGS
|
|
||||||
|
|
||||||
The need to precede options with `--` when invoked from hledger is awkward.
|
|
||||||
|
|
||||||
hledger can't render non-ascii characters when run from a Windows command 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
|
|
||||||
|
|
||||||
Report bugs at http://bugs.hledger.org.
|
|
||||||
|
|
||||||
</div>
|
|
||||||
Loading…
Reference in New Issue
Block a user