simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-09-18 17:57:11 +03:00
Code Issues Projects Releases Wiki Activity

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2022-11-03 08:31:47 -10:00
parent 14c31cc23d
commit 80eb461063
12 changed files with 2862 additions and 2656 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2022}})m4_dnl
m4_define({{_monthyear_}}, {{November 2022}})m4_dnl

2
hledger-ui/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2022}})m4_dnl
m4_define({{_monthyear_}}, {{November 2022}})m4_dnl

2
hledger-ui/hledger-ui.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER-UI" "1" "October 2022" "hledger-ui-1.27.99 " "hledger User Manuals"
.TH "HLEDGER-UI" "1" "November 2022" "hledger-ui-1.27.99 " "hledger User Manuals"

2
hledger-ui/hledger-ui.txt
View File

@ -574,4 +574,4 @@ SEE ALSO
hledger-ui-1.27.99 October 2022 HLEDGER-UI(1)
hledger-ui-1.27.99 November 2022 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2022}})m4_dnl
m4_define({{_monthyear_}}, {{November 2022}})m4_dnl

53
hledger-web/hledger-web.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER-WEB" "1" "October 2022" "hledger-web-1.27.99 " "hledger User Manuals"
.TH "HLEDGER-WEB" "1" "November 2022" "hledger-web-1.27.99 " "hledger User Manuals"
@ -9,11 +9,18 @@ hledger-web is a web interface (WUI) for the hledger accounting tool.
This manual is for hledger-web 1.27.99.
.SH SYNOPSIS
.PP
\f[C]hledger-web [OPTIONS]\f[R]
\f[C]hledger-web [OPTIONS] # run temporarily & browse\f[R]
.PD 0
.P
.PD
\f[C]hledger-web --serve [OPTIONS] # run without stopping\f[R]
.PD 0
.P
.PD
\f[C]hledger-web --serve-api [OPTIONS] # run JSON server only\f[R]
.PD 0
.P
.PD
\f[C]hledger web -- [OPTIONS]\f[R]
.SH DESCRIPTION
.PP
hledger is a reliable, cross-platform set of programs for tracking
@ -21,27 +28,41 @@ money, time, or any other commodity, using double-entry accounting and a
simple, editable file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger-web is hledger\[aq]s web interface.
It starts a simple web application for browsing and adding transactions,
and optionally opens it in a web browser window if possible.
hledger-web is a simple web application for browsing and adding
transactions.
It provides a more user-friendly UI than the hledger CLI or hledger-ui
interface, showing more at once (accounts, the current account register,
TUI, showing more at once (accounts, the current account register,
balance charts) and allowing history-aware data entry, interactive
searching, and bookmarking.
.PP
hledger-web also lets you share a ledger with multiple users, or even
hledger-web also lets you share a journal with multiple users, or even
the public web.
There is no access control, so if you need that you should put it behind
a suitable web proxy.
As a small protection against data loss when running an unprotected
instance, it writes a numbered backup of the main journal file (only ?)
on every edit.
instance, it writes a numbered backup of the main journal file (only) on
every edit.
.PP
Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1).
.PP
hledger-web can be run in three modes:
.IP \[bu] 2
Transient mode (the default): your default web browser will be opened to
show the app if possible, and the app exits automatically after two
minutes of inactivity (no requests received and no open browser windows
viewing it).
.IP \[bu] 2
With \f[C]--serve\f[R]: the app runs without stopping, and without
opening a browser.
.IP \[bu] 2
With \f[C]--serve-api\f[R]: only the JSON API is served.
.PP
In all cases hledger-web runs as a foreground process, logging requests
to stdout.
.SH OPTIONS
.PP
Command-line options and arguments may be used to set an initial filter
@ -53,7 +74,7 @@ Note: if invoking hledger-web as a hledger subcommand, write
\f[C]--\f[R] before options, as shown in the synopsis above.
.TP
\f[B]\f[CB]--serve\f[B]\f[R]
serve and log requests, don\[aq]t browse or auto-exit
serve and log requests, don\[aq]t browse or auto-exit after timeout
.TP
\f[B]\f[CB]--serve-api\f[B]\f[R]
like --serve, but serve only the JSON web API, without the server-side
@ -249,16 +270,6 @@ A \[at]FILE argument will be expanded to the contents of FILE, which
should contain one command line option/argument per line.
(To prevent this, insert a \f[C]--\f[R] argument before.)
.PP
By default, hledger-web starts the web app in \[dq]transient mode\[dq]
and also 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
open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it).
With \f[C]--serve\f[R], it just runs the web app without exiting, and
logs requests to the console.
With \f[C]--serve-api\f[R], only the JSON web api (see below) is served,
with the usual HTML server-side web UI disabled.
.PP
By default the server listens on IP address 127.0.0.1, accessible only
to local requests.
You can use \f[C]--host\f[R] to change this, eg \f[C]--host 0.0.0.0\f[R]

83
hledger-web/hledger-web.info
View File

@ -14,33 +14,47 @@ hledger-web(1)
hledger-web is a web interface (WUI) for the hledger accounting tool.
This manual is for hledger-web 1.27.99.
'hledger-web [OPTIONS]'
'hledger web -- [OPTIONS]'
'hledger-web [OPTIONS] # run temporarily & browse'
'hledger-web --serve [OPTIONS] # run without stopping'
'hledger-web --serve-api [OPTIONS] # run JSON server only'
hledger is a reliable, cross-platform set of programs for tracking
money, time, or any other commodity, using double-entry accounting and a
simple, editable file format. hledger is inspired by and largely
compatible with ledger(1).
hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions, and optionally opens
it in a web browser window if possible. It provides a more
user-friendly UI than the hledger CLI or hledger-ui interface, showing
more at once (accounts, the current account register, balance charts)
and allowing history-aware data entry, interactive searching, and
bookmarking.
hledger-web is a simple web application for browsing and adding
transactions. It provides a more user-friendly UI than the hledger CLI
or hledger-ui TUI, showing more at once (accounts, the current account
register, balance charts) and allowing history-aware data entry,
interactive searching, and bookmarking.
hledger-web also lets you share a ledger with multiple users, or even
the public web. There is no access control, so if you need that you
should put it behind a suitable web proxy. As a small protection
hledger-web also lets you share a journal with multiple users, or
even the public web. There is no access control, so if you need that
you should put it behind a suitable web proxy. As a small protection
against data loss when running an unprotected instance, it writes a
numbered backup of the main journal file (only ?) on every edit.
numbered backup of the main journal file (only) on every edit.
Like hledger, it reads data from one or more files in hledger
journal, timeclock, timedot, or CSV format specified with '-f', or
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1).
hledger-web can be run in three modes:
* Transient mode (the default): your default web browser will be
opened to show the app if possible, and the app exits automatically
after two minutes of inactivity (no requests received and no open
browser windows viewing it).
* With '--serve': the app runs without stopping, and without opening
a browser.
* With '--serve-api': only the JSON API is served.
In all cases hledger-web runs as a foreground process, logging
requests to stdout.
* Menu:
* OPTIONS::
@ -67,7 +81,7 @@ before options, as shown in the synopsis above.
'--serve'
serve and log requests, don't browse or auto-exit
serve and log requests, don't browse or auto-exit after timeout
'--serve-api'
like -serve, but serve only the JSON web API, without the
@ -264,15 +278,6 @@ the last one takes precedence.
should contain one command line option/argument per line. (To prevent
this, insert a '--' argument before.)
By default, hledger-web starts the web app in "transient mode" and
also 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 open in a browser
window, and will exit after two minutes of inactivity (no requests and
no browser windows viewing it). With '--serve', it just runs the web
app without exiting, and logs requests to the console. With
'--serve-api', only the JSON web api (see below) is served, with the
usual HTML server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible
only to local requests. You can use '--host' to change this, eg '--host
0.0.0.0' to listen on all configured addresses.
@ -632,22 +637,22 @@ awkward.

Tag Table:
Node: Top223
Node: OPTIONS1889
Ref: #options1994
Node: PERMISSIONS9905
Ref: #permissions10044
Node: EDITING UPLOADING DOWNLOADING11256
Ref: #editing-uploading-downloading11437
Node: RELOADING12271
Ref: #reloading12405
Node: JSON API12838
Ref: #json-api12952
Node: ENVIRONMENT18442
Ref: #environment18558
Node: FILES19869
Ref: #files19969
Node: BUGS20182
Ref: #bugs20260
Node: OPTIONS2419
Ref: #options2524
Node: PERMISSIONS9923
Ref: #permissions10062
Node: EDITING UPLOADING DOWNLOADING11274
Ref: #editing-uploading-downloading11455
Node: RELOADING12289
Ref: #reloading12423
Node: JSON API12856
Ref: #json-api12970
Node: ENVIRONMENT18460
Ref: #environment18576
Node: FILES19887
Ref: #files19987
Node: BUGS20200
Ref: #bugs20278

End Tag Table

186
hledger-web/hledger-web.txt
View File

@ -8,8 +8,9 @@ NAME
This manual is for hledger-web 1.27.99.
SYNOPSIS
hledger-web [OPTIONS]
hledger web -- [OPTIONS]
hledger-web [OPTIONS] # run temporarily & browse
hledger-web --serve [OPTIONS] # run without stopping
hledger-web --serve-api [OPTIONS] # run JSON server only
DESCRIPTION
hledger is a reliable, cross-platform set of programs for tracking
@ -17,24 +18,38 @@ DESCRIPTION
a simple, editable file format. hledger is inspired by and largely
compatible with ledger(1).
hledger-web is hledger's web interface. It starts a simple web appli-
cation for browsing and adding transactions, and optionally opens it in
a web browser window if possible. It provides a more user-friendly UI
than the hledger CLI or hledger-ui interface, showing more at once
(accounts, the current account register, balance charts) and allowing
history-aware data entry, interactive searching, and bookmarking.
hledger-web is a simple web application for browsing and adding trans-
actions. It provides a more user-friendly UI than the hledger CLI or
hledger-ui TUI, showing more at once (accounts, the current account
register, balance charts) and allowing history-aware data entry, inter-
active searching, and bookmarking.
hledger-web also lets you share a ledger with multiple users, or even
the public web. There is no access control, so if you need that you
should put it behind a suitable web proxy. As a small protection
against data loss when running an unprotected instance, it writes a
numbered backup of the main journal file (only ?) on every edit.
hledger-web also lets you share a journal with multiple users, or even
the public web. There is no access control, so if you need that you
should put it behind a suitable web proxy. As a small protection
against data loss when running an unprotected instance, it writes a
numbered backup of the main journal file (only) on every edit.
Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE,
or $HOME/.hledger.journal (on windows, perhaps
Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE,
or $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal). For more about this see hledger(1).
hledger-web can be run in three modes:
o Transient mode (the default): your default web browser will be opened
to show the app if possible, and the app exits automatically after
two minutes of inactivity (no requests received and no open browser
windows viewing it).
o With --serve: the app runs without stopping, and without opening a
browser.
o With --serve-api: only the JSON API is served.
In all cases hledger-web runs as a foreground process, logging requests
to stdout.
OPTIONS
Command-line options and arguments may be used to set an initial filter
on the data. These filter options are not shown in the web UI, but it
@ -44,7 +59,7 @@ OPTIONS
options, as shown in the synopsis above.
--serve
serve and log requests, don't browse or auto-exit
serve and log requests, don't browse or auto-exit after timeout
--serve-api
like --serve, but serve only the JSON web API, without the
@ -234,51 +249,42 @@ OPTIONS
contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
By default, hledger-web starts the web app in "transient mode" and also
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 open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console. With --serve-api,
only the JSON web api (see below) is served, with the usual HTML
server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg --host
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg --host
0.0.0.0 to listen on all configured addresses.
Similarly, use --port to set a TCP port other than 5000, eg if you are
Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances.
Both of these options are ignored when --socket is used. In this case,
it creates an AF_UNIX socket file at the supplied path and uses that
for communication. This is an alternative way of running multiple
hledger-web instances behind a reverse proxy that handles authentica-
tion for different users. The path can be derived in a predictable
it creates an AF_UNIX socket file at the supplied path and uses that
for communication. This is an alternative way of running multiple
hledger-web instances behind a reverse proxy that handles authentica-
tion for different users. The path can be derived in a predictable
way, eg by using the username within the path. As an example, nginx as
reverse proxy can use the variable $remote_user to derive a path from
the username used in a HTTP basic authentication. The following
proxy_pass directive allows access to all hledger-web instances that
reverse proxy can use the variable $remote_user to derive a path from
the username used in a HTTP basic authentication. The following
proxy_pass directive allows access to all hledger-web instances that
created a socket in /tmp/hledger/:
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
You can use --base-url to change the protocol, hostname, port and path
You can use --base-url to change the protocol, hostname, port and path
that appear in hyperlinks, useful eg for integrating hledger-web within
a larger website. The default is http://HOST:PORT/ using the server's
a larger website. The default is http://HOST:PORT/ using the server's
configured host address and TCP port (or http://HOST if PORT is 80).
With --file-url you can set a different base url for static files, eg
With --file-url you can set a different base url for static files, eg
for better caching or cookie-less serving on high performance websites.
PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the
By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local
machine.
o putting it behind an authenticating proxy, using eg apache or nginx
@ -288,53 +294,53 @@ PERMISSIONS
You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is
one or more of the following capabilities. The default value is
view,add:
o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or
o manage - allows editing, uploading or downloading the main or
included files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it
includes.
Note, unlike any other hledger command, in this mode you (or any visi-
Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.)
RELOADING
hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message
until the file has been fixed.
(Note: if you are viewing files mounted from another machine, make sure
that both machine clocks are roughly in step.)
JSON API
In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions. If you want the JSON API
In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions. If you want the JSON API
only, you can use the --serve-api flag. Eg:
$ hledger-web -f examples/sample.journal --serve-api
@ -351,7 +357,7 @@ JSON API
/accounttransactions/ACCOUNTNAME
Eg, all account names in the journal (similar to the accounts command).
(hledger-web's JSON does not include newlines, here we use python to
(hledger-web's JSON does not include newlines, here we use python to
prettify it):
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
@ -392,25 +398,25 @@ JSON API
"aprice": null,
...
Most of the JSON corresponds to hledger's data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. And for a higher level
Most of the JSON corresponds to hledger's data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. And for a higher level
understanding, see the journal manual.
In some cases there is outer JSON corresponding to a "Report" type. To
understand that, go to the Hledger.Web.Handler.MiscR haddock and look
at the source for the appropriate handler to see what it returns. Eg
understand that, go to the Hledger.Web.Handler.MiscR haddock and look
at the source for the appropriate handler to see what it returns. Eg
for /accounttransactions it's getAccounttransactionsR, returning a
"accountTransactionsReport ...". Looking up the haddock for that we
"accountTransactionsReport ...". Looking up the haddock for that we
can see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of AccountTransactionsRe-
which consists of a report title and a list of AccountTransactionsRe-
portItem (etc).
You can add a new transaction to the journal with a PUT request to
/add, if hledger-web was started with the add capability (enabled by
You can add a new transaction to the journal with a PUT request to
/add, if hledger-web was started with the add capability (enabled by
default). The payload must be the full, exact JSON representation of a
hledger transaction (partial data won't do). You can get sample JSON
from hledger-web's /transactions or /accounttransactions, or you can
hledger transaction (partial data won't do). You can get sample JSON
from hledger-web's /transactions or /accounttransactions, or you can
export it with hledger-lib, eg like so:
.../hledger$ stack ghci hledger-lib
@ -506,7 +512,7 @@ JSON API
"tstatus": "Unmarked"
}
And here's how to test adding it with curl. This should add a new
And here's how to test adding it with curl. This should add a new
entry to your journal:
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
@ -516,17 +522,17 @@ ENVIRONMENT
On unix computers, the default value is: ~/.hledger.journal.
A more typical value is something like ~/finance/YYYY.journal, where
~/finance is a version-controlled finance directory and YYYY is the
current year. Or, ~/finance/current.journal, where current.journal is
A more typical value is something like ~/finance/YYYY.journal, where
~/finance is a version-controlled finance directory and YYYY is the
current year. Or, ~/finance/current.journal, where current.journal is
a symbolic link to YYYY.journal.
The usual way to set this permanently is to add a command to one of
The usual way to set this permanently is to add a command to one of
your shell's startup files (eg ~/.profile):
export LEDGER_FILE=~/finance/current.journal`
On some Mac computers, there is a more thorough way to set environment
On some Mac computers, there is a more thorough way to set environment
variables, that will also affect applications started from the GUI (eg,
Emacs started from a dock icon): In ~/.MacOSX/environment.plist, add an
entry like:
@ -537,24 +543,24 @@ ENVIRONMENT
For this to take effect you might need to killall Dock, or reboot.
On Windows computers, the default value is probably C:\Users\YOUR-
NAME\.hledger.journal. You can change this by running a command like
this in a powershell window (let us know if you need to be an Adminis-
On Windows computers, the default value is probably C:\Users\YOUR-
NAME\.hledger.journal. You can change this by running a command like
this in a powershell window (let us know if you need to be an Adminis-
trator, and if this persists across a reboot):
> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"
Or, change it in settings: see https://www.java.com/en/down-
Or, change it in settings: see https://www.java.com/en/down-
load/help/path.html.
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
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-
The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-web can't read from stdin).
@ -568,7 +574,7 @@ BUGS
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -586,4 +592,4 @@ SEE ALSO
hledger-web-1.27.99 October 2022 HLEDGER-WEB(1)
hledger-web-1.27.99 November 2022 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2022}})m4_dnl
m4_define({{_monthyear_}}, {{November 2022}})m4_dnl

639
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "HLEDGER" "1" "October 2022" "hledger-1.27.99 " "hledger User Manuals"
.TH "HLEDGER" "1" "November 2022" "hledger-1.27.99 " "hledger User Manuals"
@ -563,7 +563,7 @@ Default: the full terminal width.
\f[B]NO_COLOR\f[R] If this variable exists with any value, hledger will
not use ANSI color codes in terminal output.
This is overriden by the --color/--colour option.
.SH DATA FILES
.SH INPUT
.PP
hledger reads transactions from one or more data files.
The default data file is \f[C]$HOME/.hledger.journal\f[R] (or on
@ -710,6 +710,283 @@ Are all commodity conversions declared explicitly ?
.PP
You can use the check command to run individual checks -- the ones
listed above and some more.
.SH OUTPUT
.PP
Some of this section may refer to things explained further below.
.SS Output destination
.PP
hledger commands send their output to the terminal by default.
You can of course redirect this, eg into a file, using standard shell
syntax:
.IP
.nf
\f[C]
$ hledger print > foo.txt
\f[R]
.fi
.PP
Some commands (print, register, stats, the balance commands) also
provide the \f[C]-o/--output-file\f[R] option, which does the same thing
without needing the shell.
Eg:
.IP
.nf
\f[C]
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
\f[R]
.fi
.SS Output styling
.PP
hledger commands can produce colour output when the terminal supports
it.
This is controlled by the \f[C]--color/--colour\f[R] option: - if the
\f[C]--color/--colour\f[R] option is given a value of \f[C]yes\f[R] or
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), colour will (or
will not) be used; - otherwise, if the \f[C]NO_COLOR\f[R] environment
variable is set, colour will not be used; - otherwise, colour will be
used if the output (terminal or file) supports it.
.PP
hledger commands can also use unicode box-drawing characters to produce
prettier tables and output.
This is controlled by the \f[C]--pretty\f[R] option: - if the
\f[C]--pretty\f[R] option is given a value of \f[C]yes\f[R] or
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), unicode
characters will (or will not) be used; - otherwise, unicode characters
will not be used.
.SS Output format
.PP
Some commands offer additional output formats, other than the usual
plain text terminal output.
Here are those commands and the formats currently supported:
.PP
.TS
tab(@);
l l l l l l.
T{
-
T}@T{
txt
T}@T{
csv
T}@T{
html
T}@T{
json
T}@T{
sql
T}
_
T{
aregister
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
T{
balance
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1,2\f[R]
T}@T{
Y
T}@T{
T}
T{
balancesheet
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
balancesheetequity
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
cashflow
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
incomestatement
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
print
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
Y
T}
T{
register
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
.TE
.IP \[bu] 2
\f[I]1 Also affected by the balance commands\[aq] \f[CI]--layout\f[I]
option.\f[R]
.IP \[bu] 2
\f[I]2 \f[CI]balance\f[I] does not support html output without a report
interval or with \f[CI]--budget\f[I].\f[R]
.PP
The output format is selected by the \f[C]-O/--output-format=FMT\f[R]
option:
.IP
.nf
\f[C]
$ hledger print -O csv # print CSV on stdout
\f[R]
.fi
.PP
or by the filename extension of an output file specified with the
\f[C]-o/--output-file=FILE.FMT\f[R] option:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.csv # write CSV to foo.csv
\f[R]
.fi
.PP
The \f[C]-O\f[R] option can be combined with \f[C]-o\f[R] to override
the file extension, if needed:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
\f[R]
.fi
.SS CSV output
.IP \[bu] 2
In CSV output, digit group marks (such as thousands separators) are
disabled automatically.
.SS HTML output
.IP \[bu] 2
HTML output can be styled by an optional \f[C]hledger.css\f[R] file in
the same directory.
.SS JSON output
.IP \[bu] 2
Not yet much used; real-world feedback is welcome.
.IP \[bu] 2
Our JSON is rather large and verbose, as it is quite a faithful
representation of hledger\[aq]s internal data types.
To understand the JSON, read the Haskell type definitions, which are
mostly in
https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.
.IP \[bu] 2
hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals.
Such numbers can arise in practice (from automatically-calculated
transaction prices), and would break most JSON consumers.
So in JSON, we show quantities as simple Numbers with at most 10 decimal
places.
We don\[aq]t limit the number of integer digits, but that part is under
your control.
We hope this approach will not cause problems in practice; if you find
otherwise, please let us know.
(Cf #1195)
.SS SQL output
.IP \[bu] 2
Not yet much used; real-world feedback is welcome.
.IP \[bu] 2
SQL output is expected to work with sqlite, MySQL and PostgreSQL
.IP \[bu] 2
SQL output is structured with the expectations that statements will be
executed in the empty database.
If you already have tables created via SQL output of hledger, you would
probably want to either clear tables of existing data (via
\f[C]delete\f[R] or \f[C]truncate\f[R] SQL statements) or drop tables
completely as otherwise your postings will be duped.
.SS Commodity styles
.PP
The display style of a commodity/currency is inferred according to the
rules described in Commodity display style.
The inferred display style can be overridden by an optional
\f[C]-c/--commodity-style\f[R] option (Exceptions: as is the case for
inferred styles, price amounts, and all amounts displayed by the
\f[C]print\f[R] command, will be displayed with all of their decimal
digits visible, regardless of the specified precision).
For example, the following will override the display style for dollars.
.IP
.nf
\f[C]
$ hledger print -c \[aq]$1.000,0\[aq]
\f[R]
.fi
.PP
The format specification of the style is identical to the commodity
display style specification for the commodity directive.
The command line option can be supplied repeatedly to override the
display style for multiple commodity/currency symbols.
.SS Debug output
.PP
We aim for hledger to be relatively easy to troubleshoot, introspect and
develop.
You can add \f[C]--debug[=N]\f[R] to any hledger command line to see
additional debug output.
N ranges from 1 (least output, the default) to 9 (maximum output).
Typically you would start with 1 and increase until you are seeing
enough.
Debug output goes to stderr, and is not affected by
\f[C]-o/--output-file\f[R] (unless you redirect stderr to stdout, eg:
\f[C]2>&1\f[R]).
It will be interleaved with normal output, which can help reveal when
parts of the code are evaluated.
To capture debug output in a log file instead, you can usually redirect
stderr, eg:
.PD 0
.P
.PD
\f[C]hledger bal --debug=3 2>hledger.log\f[R].
.SH TIME PERIODS
.SS Smart dates
.PP
@ -2790,267 +3067,6 @@ $ hledger balance --pivot member acct:.
-2 EUR
\f[R]
.fi
.SH OUTPUT
.SS Output destination
.PP
hledger commands send their output to the terminal by default.
You can of course redirect this, eg into a file, using standard shell
syntax:
.IP
.nf
\f[C]
$ hledger print > foo.txt
\f[R]
.fi
.PP
Some commands (print, register, stats, the balance commands) also
provide the \f[C]-o/--output-file\f[R] option, which does the same thing
without needing the shell.
Eg:
.IP
.nf
\f[C]
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
\f[R]
.fi
.PP
hledger can optionally produce debug output (if enabled with
\f[C]--debug=N\f[R]); this goes to stderr, and is not affected by
\f[C]-o/--output-file\f[R].
If you need to capture it, use shell redirects, eg:
\f[C]hledger bal --debug=3 >file 2>&1\f[R].
.SS Output styling
.PP
hledger commands can produce colour output when the terminal supports
it.
This is controlled by the \f[C]--color/--colour\f[R] option: - if the
\f[C]--color/--colour\f[R] option is given a value of \f[C]yes\f[R] or
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), colour will (or
will not) be used; - otherwise, if the \f[C]NO_COLOR\f[R] environment
variable is set, colour will not be used; - otherwise, colour will be
used if the output (terminal or file) supports it.
.PP
hledger commands can also use unicode box-drawing characters to produce
prettier tables and output.
This is controlled by the \f[C]--pretty\f[R] option: - if the
\f[C]--pretty\f[R] option is given a value of \f[C]yes\f[R] or
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), unicode
characters will (or will not) be used; - otherwise, unicode characters
will not be used.
.SS Output format
.PP
Some commands offer additional output formats, other than the usual
plain text terminal output.
Here are those commands and the formats currently supported:
.PP
.TS
tab(@);
l l l l l l.
T{
-
T}@T{
txt
T}@T{
csv
T}@T{
html
T}@T{
json
T}@T{
sql
T}
_
T{
aregister
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
T{
balance
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1,2\f[R]
T}@T{
Y
T}@T{
T}
T{
balancesheet
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
balancesheetequity
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
cashflow
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
incomestatement
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
print
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
Y
T}
T{
register
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
.TE
.IP \[bu] 2
\f[I]1 Also affected by the balance commands\[aq] \f[CI]--layout\f[I]
option.\f[R]
.IP \[bu] 2
\f[I]2 \f[CI]balance\f[I] does not support html output without a report
interval or with \f[CI]--budget\f[I].\f[R]
.PP
The output format is selected by the \f[C]-O/--output-format=FMT\f[R]
option:
.IP
.nf
\f[C]
$ hledger print -O csv # print CSV on stdout
\f[R]
.fi
.PP
or by the filename extension of an output file specified with the
\f[C]-o/--output-file=FILE.FMT\f[R] option:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.csv # write CSV to foo.csv
\f[R]
.fi
.PP
The \f[C]-O\f[R] option can be combined with \f[C]-o\f[R] to override
the file extension, if needed:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
\f[R]
.fi
.SS CSV output
.IP \[bu] 2
In CSV output, digit group marks (such as thousands separators) are
disabled automatically.
.SS HTML output
.IP \[bu] 2
HTML output can be styled by an optional \f[C]hledger.css\f[R] file in
the same directory.
.SS JSON output
.IP \[bu] 2
Not yet much used; real-world feedback is welcome.
.IP \[bu] 2
Our JSON is rather large and verbose, as it is quite a faithful
representation of hledger\[aq]s internal data types.
To understand the JSON, read the Haskell type definitions, which are
mostly in
https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.
.IP \[bu] 2
hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals.
Such numbers can arise in practice (from automatically-calculated
transaction prices), and would break most JSON consumers.
So in JSON, we show quantities as simple Numbers with at most 10 decimal
places.
We don\[aq]t limit the number of integer digits, but that part is under
your control.
We hope this approach will not cause problems in practice; if you find
otherwise, please let us know.
(Cf #1195)
.SS SQL output
.IP \[bu] 2
Not yet much used; real-world feedback is welcome.
.IP \[bu] 2
SQL output is expected to work with sqlite, MySQL and PostgreSQL
.IP \[bu] 2
SQL output is structured with the expectations that statements will be
executed in the empty database.
If you already have tables created via SQL output of hledger, you would
probably want to either clear tables of existing data (via
\f[C]delete\f[R] or \f[C]truncate\f[R] SQL statements) or drop tables
completely as otherwise your postings will be duped.
.SS Commodity styles
.PP
The display style of a commodity/currency is inferred according to the
rules described in Commodity display style.
The inferred display style can be overridden by an optional
\f[C]-c/--commodity-style\f[R] option (Exceptions: as is the case for
inferred styles, price amounts, and all amounts displayed by the
\f[C]print\f[R] command, will be displayed with all of their decimal
digits visible, regardless of the specified precision).
For example, the following will override the display style for dollars.
.IP
.nf
\f[C]
$ hledger print -c \[aq]$1.000,0\[aq]
\f[R]
.fi
.PP
The format specification of the style is identical to the commodity
display style specification for the commodity directive.
The command line option can be supplied repeatedly to override the
display style for multiple commodity/currency symbols.
.SH COMMANDS
.PP
hledger provides a number of commands for producing reports and managing
@ -3165,11 +3181,19 @@ accounts
.PD
Show account names.
.PP
This command lists account names, either declared with account
directives (--declared), posted to (--used), or both (the default).
This command lists account names.
By default it shows all known accounts, either used in transactions or
declared with account directives.
.PP
With query arguments, only matched account names and account names
referenced by matched postings are shown.
.PP
Or it can show just the used accounts (\f[C]--used\f[R]/\f[C]-u\f[R]),
the declared accounts (\f[C]--declared\f[R]/\f[C]-d\f[R]), the accounts
declared but not used (\f[C]--unused\f[R]), the accounts used but not
declared (\f[C]--undeclared\f[R]), or the first account matched by an
account name pattern, if any (\f[C]--find\f[R]).
.PP
It shows a flat list by default.
With \f[C]--tree\f[R], it uses indentation to show the account
hierarchy.
@ -3190,6 +3214,13 @@ display order.
With \f[C]--directives\f[R], it adds the \f[C]account\f[R] keyword,
showing valid account directives which can be pasted into a journal
file.
This is useful together with \f[C]--undeclared\f[R] when updating your
account declarations to satisfy \f[C]hledger check accounts\f[R].
.PP
The \f[C]--find\f[R] flag can be used to look up a single account name,
in the same way that the \f[C]aregister\f[R] command does.
It returns the alphanumerically-first matched account name, or if none
can be found, it fails with a non-zero exit code.
.PP
Examples:
.IP
@ -3206,6 +3237,13 @@ income:salary
liabilities:debts
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger accounts --undeclared --directives >> $LEDGER_FILE
$ hledger check accounts
\f[R]
.fi
.SS activity
.PP
activity
@ -8979,7 +9017,14 @@ T}
T{
\f[B]\f[CB]newest-first\f[B]\f[R]
T}@T{
disambiguate record order when there\[aq]s only one date
improve txn order when there are multiple records, newest first, all
with the same date
T}
T{
\f[B]\f[CB]intra-day-reversed\f[B]\f[R]
T}@T{
improve txn order when each day\[aq]s txns are reverse of the overall
date order
T}
T{
\f[B]\f[CB]include\f[B]\f[R]
@ -9842,7 +9887,7 @@ the TZ environment variable, eg:
.IP
.nf
\f[C]
$ TZ=HST hledger print -f foo.csv # or TZ=HST hledger import foo.csv
$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv
\f[R]
.fi
.PP
@ -9874,29 +9919,55 @@ thousand-separating commas, you should declare the decimal mark
explicitly with this rule, to avoid misparsed numbers.
.SS \f[C]newest-first\f[R]
.PP
hledger always sorts the generated transactions by date.
Transactions on the same date should appear in the same order as their
CSV records, as hledger can usually auto-detect whether the CSV\[aq]s
normal order is oldest first or newest first.
But if all of the following are true:
.IP \[bu] 2
the CSV might sometimes contain just one day of data (all records having
the same date)
.IP \[bu] 2
the CSV records are normally in reverse chronological order (newest at
the top)
.IP \[bu] 2
and you care about preserving the order of same-day transactions
.PP
then, you should add the \f[C]newest-first\f[R] rule as a hint.
Eg:
hledger tries to ensure that the generated transactions will be ordered
chronologically, including intra-day transactions.
Usually it can auto-detect how the CSV records are ordered.
But if it encounters CSV where all records are on the same date, it
assumes that the records are oldest first.
If in fact the CSV\[aq]s records are normally newest first, like:
.IP
.nf
\f[C]
# tell hledger explicitly that the CSV is normally newest first
2022-10-01, txn 3...
2022-10-01, txn 2...
2022-10-01, txn 1...
\f[R]
.fi
.PP
you can add the \f[C]newest-first\f[R] rule to help hledger generate the
transactions in correct order.
.IP
.nf
\f[C]
# same-day CSV records are newest first
newest-first
\f[R]
.fi
.SS \f[C]intra-day-reversed\f[R]
.PP
CSV records for each day are sometimes ordered in reverse compared to
the overall date order.
Eg, here dates are newest first, but the transactions on each date are
oldest first:
.IP
.nf
\f[C]
2022-10-02, txn 3...
2022-10-02, txn 4...
2022-10-01, txn 1...
2022-10-01, txn 2...
\f[R]
.fi
.PP
In this situation, add the \f[C]intra-day-reversed\f[R] rule, and
hledger will compensate, improving the order of transactions.
.IP
.nf
\f[C]
# transactions within each day are reversed with respect to the overall date order
intra-day-reversed
\f[R]
.fi
.SS \f[C]include\f[R]
.IP
.nf

1686
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

2859
hledger/hledger.txt
View File

File diff suppressed because it is too large Load Diff