slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: hledger: add more content from old manual

Browse Source
This commit is contained in:
Simon Michael 2016-04-10 12:12:12 -07:00
parent db96d54ec0
commit b69b149d39
8 changed files with 2544 additions and 494 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
hledger-web/doc/hledger-web.1
View File

@ -13,6 +13,8 @@ hledger\-web \- web interface for the hledger accounting tool
.P .P
.PD .PD
\f[C]hledger\ web\ \-\-\ [OPTIONS]\f[] \f[C]hledger\ web\ \-\-\ [OPTIONS]\f[]
.PP
.PP
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
hledger is a cross\-platform program for tracking money, time, or any hledger is a cross\-platform program for tracking money, time, or any
@ -45,6 +47,15 @@ opens it in your default web browser if possible.
In this mode the web app will keep running for as long as you have it In this mode the web app will keep running for as long as you have it
open in a browser window, and will exit after two minutes of inactivity open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it). (no requests and no browser windows viewing it).
.IP
.nf
\f[C]
$\ hledger\ web
Starting\ web\ app\ on\ port\ 5000\ with\ base\ url\ http://localhost:5000
Starting\ web\ browser\ if\ possible
Web\ app\ will\ auto\-exit\ after\ a\ few\ minutes\ with\ no\ browsers\ (or\ press\ ctrl\-c)
\f[]
.fi
.PP .PP
With \f[C]\-\-server\f[], it starts the web app in non\-transient mode With \f[C]\-\-server\f[], it starts the web app in non\-transient mode
and logs requests to the console. and logs requests to the console.

32
hledger-web/doc/hledger-web.1.md
View File

@ -15,6 +15,16 @@ hledger-web - web interface for the hledger accounting tool
`hledger-web [OPTIONS]`\ `hledger-web [OPTIONS]`\
`hledger web -- [OPTIONS]` `hledger web -- [OPTIONS]`
<style>
.highslide img {max-width:250px; float:right; margin:0 0 1em 1em;}
.highslide-caption {color:white; background-color:black;}
</style>
<a href="images/hledger-web/normal/register.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/register.png" title="Account register view with accounts sidebar" /></a>
<a href="images/hledger-web/normal/journal.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/journal.png" title="Journal view" /></a>
<a href="images/hledger-web/normal/help.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/help.png" title="Help dialog" /></a>
<a href="images/hledger-web/normal/add.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/add.png" title="Add form" /></a>
# DESCRIPTION # DESCRIPTION
hledger is a cross-platform program for tracking money, time, or any other commodity, hledger is a cross-platform program for tracking money, time, or any other commodity,
@ -45,6 +55,13 @@ the web app will keep running for as long as you have it open in a
browser window, and will exit after two minutes of inactivity (no browser window, and will exit after two minutes of inactivity (no
requests and no browser windows viewing it). requests and no browser windows viewing it).
```shell
$ hledger web
Starting web app on port 5000 with base url http://localhost:5000
Starting web browser if possible
Web app will auto-exit after a few minutes with no browsers (or press ctrl-c)
```
With `--server`, it starts the web app in non-transient mode and logs With `--server`, it starts the web app in non-transient mode and logs
requests to the console. Typically when running hledger web as part requests to the console. Typically when running hledger web as part
of a website you'll want to use `--base-url` to set the of a website you'll want to use `--base-url` to set the
@ -65,6 +82,21 @@ the web app detects changes and will show the new data on the next request.
If a change makes the file unparseable, hledger-web will show an error If a change makes the file unparseable, hledger-web will show an error
until the file has been fixed. until the file has been fixed.
---
# disabled
# edit form
# Note: unlike any other hledger command, `web` can alter existing journal
# data, via the edit form. A numbered backup of the file is saved on
# each edit, normally (ie if file permissions allow, disk is not full, etc.)
# Also, there is no built-in access control. So unless you run it behind an
# authenticating proxy, any visitor to your server will be able to see and
# overwrite the journal file (and included files.)
# hledger-web disallows edits which would leave the journal file not in
# valid [journal format](#journal). If the file becomes unparseable
# by other means, hledger-web will show an error until the file has been
# fixed.
...
# OPTIONS # OPTIONS
Note: if invoking hledger-web as a hledger subcommand, write `--` before options as shown above. Note: if invoking hledger-web as a hledger subcommand, write `--` before options as shown above.

342
hledger/doc/commands-balance.m4.md Normal file
View File

@ -0,0 +1,342 @@
## balance
Show accounts and their balances. Alias: bal.
`--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.
The balance command displays accounts and balances.
It is hledger's most featureful and most useful command.
``` {.shell .right}
$ hledger balance
$-1 assets
$1 bank:saving
$-2 cash
$2 expenses
$1 food
$1 supplies
$-2 income
$-1 gifts
$-1 salary
$1 liabilities:debts
--------------------
0
```
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 balances, this is the same as the account's ending balance.
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 this.)
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
omitted. Use `-E/--empty` to show them.
``` {.shell .right .clear}
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
```
A final total is displayed by default; use `-N/--no-total` to suppress it.
### Flat mode
``` {.shell .right}
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 food
$1 supplies
```
To see a flat list of full account names instead of the default hierarchical 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 few account name components.
### Depth limiting
``` {.shell .right}
$ hledger balance -N --depth 1
$-1 assets
$2 expenses
$-2 income
$1 liabilities
```
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.
<!-- $ for y in 2006 2007 2008 2009 2010; do echo; echo $y; hledger -f $y.journal balance ^expenses --depth 2; done -->
### Multicolumn balance reports
With a [reporting interval](#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:
``` {.shell .right}
$ hledger balance --quarterly income expenses -E
Balance changes in 2008:
|| 2008q1 2008q2 2008q3 2008q4
===================++=================================
expenses:food || 0 $1 0 0
expenses:supplies || 0 $1 0 0
income:gifts || 0 $-1 0 0
income:salary || $-1 0 0 0
-------------------++---------------------------------
|| $-1 $1 0 0
```
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
for a monthly income statement.
<!--
multi-column income statement:
$ hledger balance ^income ^expense -p 'monthly this year' --depth 3
or cashflow statement:
$ hledger balance ^assets ^liabilities 'not:(receivable|payable)' -p 'weekly this month'
-->
<div style="clear:both;"></div>
``` {.shell .right}
$ hledger balance --quarterly income expenses -E --cumulative
Ending balances (cumulative) in 2008:
|| 2008/03/31 2008/06/30 2008/09/30 2008/12/31
===================++=================================================
expenses:food || 0 $1 $1 $1
expenses:supplies || 0 $1 $1 $1
income:gifts || 0 $-1 $-1 $-1
income:salary || $-1 $-1 $-1 $-1
-------------------++-------------------------------------------------
|| $-1 0 0 0
```
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. This mode is not often used.
<div style="clear:both;"></div>
``` {.shell .right}
$ hledger balance ^assets ^liabilities -Q
Balance changes in 2008:
|| 2008q1 2008q2 2008q3 2008q4
======================++=================================
assets:bank:checking || $1 0 0 $-1
assets:bank:saving || 0 $1 0 0
assets:cash || 0 $-2 0 0
liabilities:debts || 0 0 0 $1
----------------------++---------------------------------
|| $1 $-1 0 0
$ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
Ending balances (historical) in 2008/04/01-2008/12/31:
|| 2008/06/30 2008/09/30 2008/12/31
======================++=====================================
assets:bank:checking || $1 $1 0
assets:bank:saving || $1 $1 $1
assets:cash || $-2 $-2 $-2
liabilities:debts || 0 0 $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 useful eg for a multi-period balance sheet, and when
you are showing only the data after a certain start date.
<div style="clear:both;"></div>
``` {.shell .right}
$ hledger balance -Q income expenses --tree -E -TA
Balance changes in 2008:
|| 2008q1 2008q2 2008q3 2008q4 Total Average
============++===================================================
expenses || 0 $2 0 0 $2 $1
food || 0 $1 0 0 $1 0
supplies || 0 $1 0 0 $1 0
income || $-1 $-1 0 0 $-2 $-1
gifts || 0 $-1 0 0 $-1 0
salary || $-1 0 0 0 $-1 0
------------++---------------------------------------------------
|| $-1 $1 0 0 0 0
# Average is rounded to the dollar here since all journal amounts are
```
Multi-column balance reports display accounts in flat mode by default;
to see the hierarchy, use `--tree`.
Note that with a reporting interval, the report start/end dates will
be "enlarged" if necessary so that they encompass the displayed report
periods. This is so that the first and last periods will be "full" and
comparable to the others.
The `-E/--empty` flag does two things here: 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 otherwise would
be omitted).
The `-T/--row-total` flag adds an additional column showing the total
for each row. The `-A/--average` flag adds a column showing the
average value in each row. Note in `--H/--historical` mode only the
average is useful, and in `--cumulative` mode neither is useful.
### Market value
The `-V/--value` flag converts all the reported amounts to their
"current market value" using their default market price. That is the
latest [market price](#market-prices) (P directive) found in the
journal (or an included file), for the amount's commodity, dated on or
before the report end date.
Unlike Ledger, hledger's -V only uses the market prices recorded with
P directives, ignoring transaction prices recorded as part of posting
amounts (which -B/--cost uses). Using -B and -V together is allowed.
<!--
``` {.shell .right}
$ hledger balance -V ...
```
-->
### Custom balance output
``` {.shell .right}
$ hledger balance --format "%20(account) %12(total)"
assets $-1
bank:saving $1
cash $-2
expenses $2
food $1
supplies $1
income $-2
gifts $-1
salary $-1
liabilities:debts $1
---------------------------------
0
```
In simple (non-multi-column) balance reports, you can customise the
output with `--format FMT`. FMT (plus a newline) will be displayed for
each account/balance pair. It is a format string with data fields
interpolated by
`%[MIN][.MAX](FIELDNAME)`
where MIN means pad with spaces to at least this width, and MAX means
truncate at this width. The field name must be enclosed in
parentheses. Three fields are available:
- `depth_spacer` - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces.
- `account` - the account's name
- `total` - the account's balance/posted total, right justified
When the total has multiple commodities, by default each commodity is
displayed on a separate line, and the report item will be bottom
aligned. You can change how such multi-line values are rendered by
beginning the format with a special prefix:
- `%_` - render on multiple lines, bottom-aligned (the default)
- `%^` - render on multiple lines, top-aligned
- `%,` - render on one line, with multi-line values comma-separated
There are some quirks, and experimentation may be needed to get pleasing output.
In one-line mode, `%(depth_spacer)` has no effect, instead `%(account)` has indentation built in.
<!-- XXX retest:
Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
-->
Examples:
- `%(total)` - the account's total
- `%-20.20(account)` - the account's name, left justified, padded to 20 characters and clipped at 20 characters
- `%20(total) %2(depth_spacer)%-(account)` - default format for the single-column balance report
- `%,%-50(account) %25(total)` - account name padded to 50 characters, total padded to 20 characters, with multiple commodities rendered on one line
### Output destination
```{.shell .bold .right}
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE
```
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.
### CSV output
```{.shell .bold .right}
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv
```
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` option, or by specifying a `.csv` file extension
with `-o/--output-file`.

883
hledger/doc/commands.m4.md
View File

@ -1,71 +1,23 @@
# COMMANDS # COMMANDS
hledger provides a number of subcommands; `hledger` with no arguments shows a list. hledger provides a number of subcommands; `hledger` with no arguments
shows a list.
Select 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 displayed in the command list (`hledger is`). If you install additional `hledger-*` packages, or if you put programs
or scripts named `hledger-NAME` in your PATH, these will also be
listed as subcommands.
If you install additional `hledger-*` packages, Run a subcommand by writing its name as first argument (eg `hledger
or if you put programs or scripts named `hledger-NAME` in your PATH, these will also be listed as hledger subcommands. incomestatement`). You can also write any unambiguous prefix of a
command name (`hledger inc`), or one of the standard short aliases
displayed in the command list (`hledger is`).
Here is a summary (see http://hledger.org/manual#commands for the full command help): ---
# for each command: name, synopsis, description, examples.
...
## Data entry ## accounts
Show account names.
### 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
``` {.shell .right}
$ hledger accounts --tree
assets
bank
checking
saving
cash
expenses
food
supplies
income
gifts
salary
liabilities
debts
```
``` {.shell .right}
$ hledger accounts --drop 1
bank:checking
bank:saving
cash
food
supplies
gifts
salary
debts
```
``` {.shell .right}
$ hledger accounts
assets:bank:checking
assets:bank:saving
assets:cash
expenses:food
expenses:supplies
income:gifts
income:salary
liabilities:debts
```
show account names
`--tree` `--tree`
: show short account names, as a tree : show short account names, as a tree
@ -80,20 +32,140 @@ This command lists all account names that are in use (ie, all the
accounts which have at least one transaction posting to them). With accounts which have at least one transaction posting to them). With
query arguments, only matched account names are shown. query arguments, only matched account names are shown.
It shows a flat list by default. In this mode you can add `--drop N` It shows a flat list by default. With `--tree`, it uses indentation to
to omit the first few account name components. show the account hierarchy.
With `--tree`, it shows the account hierarchy. In flat mode you can add `--drop N` to omit the first few account name
components.
### activity Examples:
show an ascii barchart of posting counts per interval
(default: daily)
### balance, bal _col3_({{
show accounts and balances _shell_({{
$ hledger accounts --tree
assets
bank
checking
saving
cash
expenses
food
supplies
income
gifts
salary
liabilities
debts
}})
}},{{
_shell_({{
$ hledger accounts --drop 1
bank:checking
bank:saving
cash
food
supplies
gifts
salary
debts
}})
}},{{
_shell_({{
$ hledger accounts
assets:bank:checking
assets:bank:saving
assets:cash
expenses:food
expenses:supplies
income:gifts
income:salary
liabilities:debts
}})
}})
`--tree` ## activity
: show short account names, as a tree 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 default). With query arguments, it counts only matched transactions.
_col3_({{
_shell_({{
$ hledger activity --quarterly
2008-01-01 **
2008-04-01 *******
2008-07-01
2008-10-01 **
}})
}})
## add
Prompt for transactions and add them to the journal.
`--no-new-accounts`
: 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 transactions, and appends
them to the journal file (existing transactions are not changed).
This is the only hledger command that writes to the journal file.
To use it, just run `hledger add` and follow the prompts.
You can add as many transactions as you like; when you are finished,
enter `.` or press control-d or control-c to exit.
Features:
- add tries to provide useful defaults, using the most similar recent
transaction (by description) as a template.
- You can also set the initial defaults with command line arguments.
- [Readline-style edit keys](http://tiswww.case.edu/php/chet/readline/rluserman.html#SEC3)
can be used during data entry.
- The tab key will auto-complete whenever possible - accounts,
descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input
area is empty, it will insert the default value.
- If the journal defines a [default commodity](#default-commodity),
it will be added to any bare numbers entered.
- A parenthesised transaction [code](#entries) may be entered following a date.
- [Comments](#comments) and tags may be entered following a description or amount.
- If you make a mistake, enter `<` at any prompt to restart the transaction.
- Input prompts are displayed in a different colour when the terminal supports it.
Example (see the [tutorial](step-by-step.html#record-a-transaction-with-hledger-add) for a detailed explanation):
_shell_({{
$ hledger add
Adding transactions to journal file /src/hledger/data/sample.journal
Any command line arguments will be used as defaults.
Use tab key to complete, readline keys to edit, enter to accept defaults.
An optional (CODE) may follow transaction dates.
An optional ; COMMENT may follow descriptions or amounts.
If you make a mistake, enter < at any prompt to restart the transaction.
To end a transaction, enter . when prompted.
To quit, enter . at a date prompt or press control-d or control-c.
Date [2015/05/22]:
Description: supermarket
Account 1: expenses:food
Amount 1: $10
Account 2: assets:checking
Amount 2 [$-10.0]:
Account 3 (or . or enter to finish this transaction): .
2015/05/22 supermarket
expenses:food $10
assets:checking $-10.0
Save this transaction to the journal ? [y]:
Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $
}})
_include_({{commands-balance.m4.md}})
## balancesheet
Show a balance sheet. Alias: bs.
`--flat` `--flat`
: show full account names, as a list (default) : show full account names, as a list (default)
@ -101,39 +173,36 @@ show accounts and balances
`--drop=N` `--drop=N`
: in flat mode: omit N leading account name parts : in flat mode: omit N leading account name parts
`--format=LINEFORMAT` This command displays a simple
: in single-column balance reports: use this custom line format [balance sheet](http://en.wikipedia.org/wiki/Balance_sheet). It currently
assumes that you have top-level accounts named `asset` and `liability`
(plural forms also allowed.)
`--no-elide` _col3_({{
: in tree mode: don't squash boring parent accounts _shell_({{
$ hledger balancesheet
Balance Sheet
`-H --historical` Assets:
: in multicolumn mode: show historical ending balances $-1 assets
$1 bank:saving
$-2 cash
--------------------
$-1
`--cumulative` Liabilities:
: in multicolumn mode: show accumulated ending balances $1 liabilities:debts
--------------------
$1
`-A --average` Total:
: in multicolumn mode: show a row average column --------------------
0
}})
}})
`-T --row-total` ## cashflow
: in multicolumn mode: show a row total column Show a cashflow statement. Alias: cf.
`-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` `--flat`
: show full account names, as a list (default) : show full account names, as a list (default)
@ -141,8 +210,33 @@ show a balance sheet
`--drop=N` `--drop=N`
: in flat mode: omit N leading account name parts : in flat mode: omit N leading account name parts
### cashflow, cf This command displays a simple
show a cashflow statement [cashflow statement](http://en.wikipedia.org/wiki/Cash_flow_statement)
It shows the change in all "cash" (ie, liquid assets) accounts for the
period. It currently assumes that cash accounts are under a top-level
account named `asset` and do not contain `receivable` or `A/R` (plural
forms also allowed.)
_col3_({{
_shell_({{
$ hledger cashflow
Cashflow Statement
Cash flows:
$-1 assets
$1 bank:saving
$-2 cash
--------------------
$-1
Total:
--------------------
$-1
}})
}})
## incomestatement
Show an income statement. Alias: is.
`--flat` `--flat`
: show full account names, as a list (default) : show full account names, as a list (default)
@ -150,17 +244,38 @@ show a cashflow statement
`--drop=N` `--drop=N`
: in flat mode: omit N leading account name parts : in flat mode: omit N leading account name parts
### incomestatement, is This command displays a simple
show an income statement [income statement](http://en.wikipedia.org/wiki/Income_statement). It
currently assumes that you have top-level accounts named `income` (or
`revenue`) and `expense` (plural forms also allowed.)
`--flat` _col3_({{
: show full account names, as a list (default) _shell_({{
$ hledger incomestatement
Income Statement
`--drop=N` Revenues:
: in flat mode: omit N leading account name parts $-2 income
$-1 gifts
$-1 salary
--------------------
$-2
### print Expenses:
show transactions from the journal $2 expenses
$1 food
$1 supplies
--------------------
$2
Total:
--------------------
0
}})
}})
## print
Show transactions from the journal.
`-m STR --match=STR ` `-m STR --match=STR `
: show the transaction whose description is most similar to STR, and is most recent : show the transaction whose description is most similar to STR, and is most recent
@ -172,8 +287,48 @@ show transactions from the journal
: select the output format. Supported formats: : select the output format. Supported formats:
txt, csv. txt, csv.
### register, reg The print command displays full transactions from the journal file,
show postings and running total tidily formatted and showing all amounts explicitly. The output of
print is always a valid hledger journal, but it does always not
preserve all original content exactly (eg directives).
hledger's print command also shows all unit prices in effect, or (with
-B/--cost) shows cost amounts.
The print command also supports
[output destination](#output-destination)
and
[CSV output](#csv-output).
_col3_({{
_shell_({{
$ hledger print
2008/01/01 income
assets:bank:checking $1
income:salary $-1
2008/06/01 gift
assets:bank:checking $1
income:gifts $-1
2008/06/02 save
assets:bank:saving $1
assets:bank:checking $-1
2008/06/03 * eat & shop
expenses:food $1
expenses:supplies $1
assets:cash $-2
2008/12/31 * pay off
liabilities:debts $1
assets:bank:checking $-1
}})
}})
## register
Show postings and their running total. Alias: reg.
`-H --historical` `-H --historical`
: include prior postings in the running total : include prior postings in the running total
@ -194,35 +349,499 @@ show postings and running total
: select the output format. Supported formats: : select the output format. Supported formats:
txt, csv. txt, csv.
### stats ```{.shell .right}
show some journal statistics $ hledger register checking
2008/01/01 income assets:bank:checking $1 $1
2008/06/01 gift assets:bank:checking $1 $2
2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0
```
The register command displays postings, one per line, and their
running total. This is typically used with a [query](#queries)
selecting a particular account, to see that account's activity.
```{.shell .right .clear}
$ hledger register checking -b 2008/6 --historical
2008/06/01 gift assets:bank:checking $1 $2
2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0
```
The `--historical`/`-H` flag adds the balance from any prior postings
to the running total, to show the actual historical running balance.
This is useful when you want to see just the recent activity.
The `--depth` option limits the amount of sub-account detail displayed.
The `--average`/`-A` flag shows the running average posting amount
instead of the running total (so, the final number displayed is the
average for the whole report period). This flag implies `--empty` (see below).
It works best when showing just one account and one commodity.
The `--related`/`-r` flag shows the *other* postings in the transactions
of the postings which would normally be shown.
```{.shell .right}
$ hledger register --monthly income
2008/01 income:salary $-1 $-1
2008/06 income:gifts $-1 $-2
```
```{.shell .right}
$ hledger register --monthly income -E
2008/01 income:salary $-1 $-1
2008/02 0 $-1
2008/03 0 $-1
2008/04 0 $-1
2008/05 0 $-1
2008/06 income:gifts $-1 $-2
2008/07 0 $-2
2008/08 0 $-2
2008/09 0 $-2
2008/10 0 $-2
2008/11 0 $-2
2008/12 0 $-2
```
```{.shell .right .clear}
$ hledger register --monthly assets --depth 1 # cashflow (changes to assets) by month
2008/01 assets $1 $1
2008/06 assets $-1 0
2008/12 assets $-1 $-1
```
With a [reporting interval](#reporting-interval), register shows
summary postings, one per interval, aggregating the postings to each account.
Periods with no activity, and summary postings with a zero amount, are
not shown by default; use the `--empty`/`-E` flag to see them.
Often, you'll want to see just one line per interval.
The `--depth` option helps with this, causing subaccounts to be aggregated.
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 a bash shell variable)
or by using the `--width`/`-w` option.
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
description width as part of --width's argument, comma-separated:
`--width W,D` . Here's a diagram:
```
<--------------------------------- width (W) ---------------------------------->
date (10) description (D) account (W-41-D) amount (12) balance (12)
DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
```
and some examples:
```{.shell .bold}
$ hledger reg # use terminal width (or 80 on windows)
$ hledger reg -w 100 # use width 100
$ COLUMNS=100 hledger reg # set with one-time environment variable
$ export COLUMNS=100; hledger reg # set till session end (or window resize)
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
```
The register command also supports the
`-o/--output-file` and `-O/--output-format` options for controlling
[output destination](#output-destination) and [CSV output](#csv-output).
## stats
Show some journal statistics.
`-o FILE[.FMT] --output-file=FILE[.FMT]` `-o FILE[.FMT] --output-file=FILE[.FMT]`
: write output to FILE instead of stdout. A recognised FMT suffix influences the format. : write output to FILE instead of stdout. A recognised FMT suffix influences the format.
## Add-on commands ```{.shell .right}
$ hledger stats
Main journal file : /src/hledger/data/sample.journal
Included journal files :
Transactions span : 2008-01-01 to 2009-01-01 (366 days)
Last transaction : 2008-12-31 (2333 days ago)
Transactions : 5 (0.0 per day)
Transactions last 30 days: 0 (0.0 per day)
Transactions last 7 days : 0 (0.0 per day)
Payees/descriptions : 5
Accounts : 8 (depth 3)
Commodities : 1 ($)
```
Additional commands will be available when executables or scripts The stats command displays summary information for the whole journal, or
named "`hledger-`CMD" are installed in the PATH. These are often a matched part of it. With a [reporting interval](#reporting-interval),
provided by a package of the same name, or you can make your own custom scripts it shows a report for each report period.
(haskell scripts can use hledger-lib allowing tight integration).
Some available add-ons are:
### autosync The stats command also supports `-o/--output-file`
download OFX bank data and/or convert OFX to hledger journal format for controlling [output destination](#output-destination).
### diff ## test
show transactions present in one journal file but not another Run built-in unit tests.
### interest ```{.shell .right}
generate interest transactions $ hledger test
Cases: 74 Tried: 74 Errors: 0 Failures: 0
```
### irr This command runs hledger's built-in unit tests and displays a quick report.
calculate internal rate of return 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.
### ui # ADD-ON COMMANDS
curses-style interface, see hledger-ui(1)
### web Add-on commands are executables in your PATH whose name starts with
web interface, see hledger-web(1) `hledger-` and ends with any of these file extensions:
none, `.hs`,`.lhs`,`.pl`,`.py`,`.rb`,`.rkt`,`.sh`,`.bat`,`.com`,`.exe`.
Also, an add-on's name may not be the same as any built-in command or alias.
hledger will detect these and include them in the command list and let
you invoke them with `hledger ADDONCMD`. However there are some limitations:
- Options appearing before ADDONCMD will be visible only to hledger and will not be passed to the add-on.
Eg: `hledger --help web` shows hledger's help, `hledger web --help` shows hledger-web's help.
- Options understood only by the add-on must go after a `--` argument to hide them from hledger, which would otherwise reject them.
Eg: `hledger web -- --server`.
Sometimes it may be more convenient to just run the add-on directly, eg: `hledger-web --server`.
Add-ons which are written in haskell can take advantage of the hledger-lib library
for journal parsing, reporting, command-line options, etc.
Here are some hledger add-ons available from Hackage,
the [extra](https://github.com/simonmichael/hledger/tree/master/extra) directory in the hledger source,
or elsewhere:
## api
Web API server, see [hledger-api](hledger-api.html).
## autosync
Download OFX bank data and/or convert OFX to hledger journal format.
``` {.shell .right}
$ hledger autosync --help
usage: hledger-autosync [-h] [-m MAX] [-r] [-a ACCOUNT] [-l LEDGER] [-i INDENT]
[--initial] [--fid FID] [--assertions] [-d] [--hledger]
[--slow] [--which]
[PATH]
Synchronize ledger.
positional arguments:
PATH do not sync; import from OFX file
optional arguments:
-h, --help show this help message and exit
-m MAX, --max MAX maximum number of days to process
-r, --resync do not stop until max days reached
-a ACCOUNT, --account ACCOUNT
set account name for import
-l LEDGER, --ledger LEDGER
specify ledger file to READ for syncing
-i INDENT, --indent INDENT
number of spaces to use for indentation
--initial create initial balance entries
--fid FID pass in fid value for OFX files that do not supply it
--assertions create balance assertion entries
-d, --debug enable debug logging
--hledger force use of hledger (on by default if invoked as hledger-
autosync)
--slow use slow, but possibly more robust, method of calling ledger
(no subprocess)
--which display which version of ledger/hledger/ledger-python will
be used by ledger-autosync to check for previous
transactions
$ head acct1.ofx
OFXHEADER:100
DATA:OFXSGML
VERSION:102
SECURITY:NONE
ENCODING:USASCII
CHARSET:1252
COMPRESSION:NONE
OLDFILEUID:NONE
NEWFILEUIDe:8509488b59d1bb45
$ hledger autosync acct1.ofx
2013/08/30 MONTHLY SERVICE FEE
; ofxid: 3000.4303001832.201308301
WF:4303001832 -$6.00
[assets:business:bank:wf:bchecking:banking] $6.00
```
[ledger-autosync](https://bitbucket.org/egh/ledger-autosync/commits/all),
which includes a `hledger-autosync` alias, downloads transactions
from your bank(s) via OFX, and prints just the new ones as journal
entries which you can add to your journal. It can also operate on .OFX
files which you've downloaded manually. It can be a nice alternative
to hledger's built-in CSV reader, especially if your bank supports OFX
download.
## diff
Show transactions present in one journal file but not another
```{.shell .right}
$ hledger diff --help
Usage: hledger-diff account:name left.journal right.journal
$ cat a.journal
1/1
(acct:one) 1
$ cat b.journal
1/1
(acct:one) 1
2/2
(acct:two) 2
$ hledger diff acct:two a.journal b.journal
Unmatched transactions in the first journal:
Unmatched transactions in the second journal:
2015/02/02
(acct:two) $2
```
[hledger-diff](http://hackage.haskell.org/package/hledger-diff)
compares two journal files. Given an account name, it prints out the
transactions affecting that account which are in one journal file but
not in the other. This can be useful for reconciling existing
journals with bank statements.
## equity
Print a journal entry that resets account balances to zero.
```{.shell .right}
$ hledger balance --flat -E assets liabilities
0 assets:bank:checking
$1 assets:bank:saving
$-2 assets:cash
$1 liabilities:debts
--------------------
0
$ hledger equity assets liabilities
2015/05/23
assets:bank:saving $-1
assets:cash $2
liabilities:debts $-1
equity:closing balances 0
2015/05/23
assets:bank:saving $1
assets:cash $-2
liabilities:debts $1
equity:opening balances 0
```
This prints a journal entry which zeroes out the specified accounts
(or all accounts) with a transfer to/from "equity:closing balances"
(like Ledger's equity command). Also, it prints an similar entry with
opposite sign for restoring the balances from "equity:opening
balances".
These can be useful for ending one journal file and starting a new
one, respectively. By zeroing your asset and liability accounts at the
end of a file and restoring them at the start of the next one, you
will see correct asset/liability balances whether you run hledger on
just one file, or on several files concatenated with [include](#include).
## interest
Generate interest transactions.
```{.shell .right}
$ hledger interest --help
Usage: hledger-interest [OPTION...] ACCOUNT
-h --help print this message and exit
-V --version show version number and exit
-v --verbose echo input ledger to stdout (default)
-q --quiet don't echo input ledger to stdout
--today compute interest up until today
-f FILE --file=FILE input ledger file (pass '-' for stdin)
-s ACCOUNT --source=ACCOUNT interest source account
-t ACCOUNT --target=ACCOUNT interest target account
--act use 'act' day counting convention
--30-360 use '30/360' day counting convention
--30E-360 use '30E/360' day counting convention
--30E-360isda use '30E/360isda' day counting convention
--constant=RATE constant interest rate
--annual=RATE annual interest rate
--bgb288 compute interest according to German BGB288
--ing-diba compute interest according for Ing-Diba Tagesgeld account
```
```{.shell .right .clear}
$ cat interest.journal
2008/09/26 Loan
Assets:Bank EUR 10000.00
Liabilities:Bank
2008/11/27 Payment
Assets:Bank EUR -3771.12
Liabilities:Bank
2009/05/03 Payment
Assets:Bank EUR -1200.00
Liabilities:Bank
2010/12/10 Payment
Assets:Bank EUR -3700.00
Liabilities:Bank
```
```{.shell .right .clear}
$ hledger interest -- -f interest.journal --source=Expenses:Interest \
--target=Liabilities:Bank --30-360 --annual=0.05 Liabilities:Bank
2008/09/26 Loan
Assets:Bank EUR 10000.00
Liabilities:Bank EUR -10000.00
2008/11/27 0.05% interest for EUR -10000.00 over 61 days
Liabilities:Bank EUR -84.72
Expenses:Interest EUR 84.72
2008/11/27 Payment
Assets:Bank EUR -3771.12
Liabilities:Bank EUR 3771.12
2008/12/31 0.05% interest for EUR -6313.60 over 34 days
Liabilities:Bank EUR -29.81
Expenses:Interest EUR 29.81
2009/05/03 0.05% interest for EUR -6343.42 over 123 days
Liabilities:Bank EUR -108.37
Expenses:Interest EUR 108.37
2009/05/03 Payment
Assets:Bank EUR -1200.00
Liabilities:Bank EUR 1200.00
2009/12/31 0.05% interest for EUR -5251.78 over 238 days
Liabilities:Bank EUR -173.60
Expenses:Interest EUR 173.60
2010/12/10 0.05% interest for EUR -5425.38 over 340 days
Liabilities:Bank EUR -256.20
Expenses:Interest EUR 256.20
2010/12/10 Payment
Assets:Bank EUR -3700.00
Liabilities:Bank EUR 3700.00
```
[hledger-interest](http://hackage.haskell.org/package/hledger-interest)
computes interests for a given account. Using command line flags,
the program can be configured to use various schemes for day-counting,
such as act/act, 30/360, 30E/360, and 30/360isda. Furthermore, it
supports a (small) number of interest schemes, i.e. annual interest
with a fixed rate and the scheme mandated by the German BGB288
(Basiszins für Verbrauchergeschäfte). See the package page for more.
## irr
Calculate internal rate of return.
```{.shell .right}
$ hledger irr --help
Usage: hledger-irr [OPTION...]
-h --help print this message and exit
-V --version show version number and exit
-c --cashflow also show all revant transactions
-f FILE --file=FILE input ledger file (pass '-' for stdin)
-i ACCOUNT --investment-account=ACCOUNT investment account
-t ACCOUNT --interest-account=ACCOUNT interest/gain/fees/losses account
-b DATE --begin=DATE calculate interest from this date
-e DATE --end=DATE calculate interest until this date
-D --daily calculate interest for each day
-W --weekly calculate interest for each week
-M --monthly calculate interest for each month
-Y --yearly calculate interest for each year
```
```{.shell .right .clear}
$ cat irr.journal
2011-01-01 Some wild speculation – I wonder if it pays off
Speculation €100.00
Cash
2011-02-01 More speculation (and adjustment of value)
Cash -€10.00
Rate Gain -€1.00
Speculation
2011-03-01 Lets pull out some money (and adjustment of value)
Cash €30.00
Rate Gain -€3.00
Speculation
2011-04-01 More speculation (and it lost some money!)
Cash -€50.00
Rate Gain € 5.00
Speculation
2011-05-01 Getting some money out (and adjustment of value)
Speculation -€44.00
Rate Gain -€ 3.00
Cash
2011-06-01 Emptying the account (after adjusting the value)
Speculation -€85.00
Cash €90.00
Rate Gain -€ 5.00
```
```{.shell .right .clear}
$ hledger-irr -f irr.journal -t "Rate Gain" -i Speculation --monthly
2011/01/01 - 2011/02/01: 12.49%
2011/02/01 - 2011/03/01: 41.55%
2011/03/01 - 2011/04/01: -51.44%
2011/04/01 - 2011/05/01: 32.24%
2011/05/01 - 2011/06/01: 95.92%
```
[hledger-irr](http://hackage.haskell.org/package/hledger-irr)
computes the internal rate of return, also known as the effective
interest rate, of a given investment. After specifying what account
holds the investment, and what account stores the gains (or losses, or
fees, or cost), it calculates the hypothetical annual rate of fixed
rate investment that would have provided the exact same cash flow.
See the package page for more.
## print-unique
Print only only journal entries which have a unique description.
```{.shell .right}
$ cat unique.journal
1/1 test
(acct:one) 1
2/2 test
(acct:two) 2
$ LEDGER_FILE=unique.journal hledger print-unique
(-f option not supported)
2015/01/01 test
(acct:one) 1
```
## rewrite
Prints all journal entries, adding specified custom postings to matched entries.
```{.shell .right .bold}
$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
```
## ui
Curses-style interface, see [hledger-ui](hledger-ui.html).
## web
Web interface, see [hledger-web](hledger-web.html).

4
hledger/doc/description.m4.md
View File

@ -15,11 +15,11 @@ or standard input with `-f-`.
Transactions are dated movements of money between two (or more) named Transactions are dated movements of money between two (or more) named
accounts, and are recorded with journal entries like this: accounts, and are recorded with journal entries like this:
```journal _journal_({{
2015/10/16 bought food 2015/10/16 bought food
expenses:food $10 expenses:food $10
assets:cash assets:cash
``` }})
For more about the format, see hledger_journal(5). For more about the format, see hledger_journal(5).

1756
hledger/doc/hledger.1
View File

File diff suppressed because it is too large Load Diff

6
hledger/doc/hledger.1.m4.md
View File

@ -27,10 +27,10 @@ http://hledger.org/manual.
</div> </div>
_include_(description.m4.md) _include_(description.m4.md)
_include_(options.m4.md)
_include_(commands.m4.md)
_include_(queries.m4.md)
_include_(examples.m4.md) _include_(examples.m4.md)
_include_(options.m4.md)
_include_(queries.m4.md)
_include_(commands.m4.md)
<div class="man"> <div class="man">

4
hledger/doc/options.m4.md
View File

@ -10,10 +10,10 @@ COMMAND, not before it.
Also, when invoking external add-on commands, their options must be Also, when invoking external add-on commands, their options must be
written after a double hyphen. (Or, you can invoke the external command written after a double hyphen. (Or, you can invoke the external command
directly.) Eg: directly.) Eg:
```{.shell .bold} _shellbold_({{
$ hledger ui -- --register cash $ hledger ui -- --register cash
$ hledger-ui --register cash $ hledger-ui --register cash
``` }})
Options and command arguments can be intermixed. Arguments are usually Options and command arguments can be intermixed. Arguments are usually
interpreted as a search query which filters the data, see QUERIES. interpreted as a search query which filters the data, see QUERIES.