@@ -730,36 +730,62 @@ quoting than you would at the command prompt.)
730
730
.PP
731
731
Argument files are now superseded by..
732
732
.SS Config files
733
- hledger will read extra command line options from a
734
- \f[CR] hledger.conf \f[ R ] config file.
735
- These will be inserted early in the command line, so your later options
736
- can override them if needed.
737
- The config file can contain general options (which will be used with all
738
- commands that support them), and command\- specific options (or
739
- arguments).
740
- hledger.conf.sample is an example, which you can install as, eg,
741
- \f[CR] ./hledger.conf \f[ R ] or \f[CR] $HOME/.hledger.conf \f[ R ] .
742
- .PP
743
- To be precise, hledger looks for \f[CR] hledger.conf \f[ R ] in the current
744
- directory or above, or in your home directory (with a dotted name,
745
- \f[CR] \[ti ] /.hledger.conf \f[ R ] ), or finally in your XDG config directory
746
- (\f[CR] \[ti ] /.config/hledger/hledger.conf \f[ R ] ).
747
- Or you can select a particular config file by using the
748
- \f[CR] \-\- conf \f[ R ] option, or by adding a \f[CR] hledger \-\- conf \f[ R ]
749
- shebang line to a config file and executing it like a script (see the
750
- example file).
751
- You can inspect the finding and processing of config files with
752
- \f[CR] \-\- debug \f[ R ] or \f[CR] \-\- debug=8 \f[ R ] .
753
- .PP
754
- If you want to run hledger without a config file, to ensure standard
755
- defaults and behaviour, use the \f[CR] \- n/ \-\- no \- conf \f[ R ] flag.
756
- This is recommended when using hledger in scripts, and when
757
- troubleshooting problems.
758
- .PP
759
- When both \f[CR] \-\- conf \f[ R ] and \f[CR] \-\- no \- conf \f[ R ] options are
760
- used, the last (right\- most) wins.
761
- .PP
762
- \f[I] (in master, experimental) \f[ R ]
733
+ As of hledger 1.40, you can optionally save command line options (or
734
+ arguments) to be used when running hledger commands, in a config file.
735
+ Here\[aq ] s a small example:
736
+ .IP
737
+ .EX
738
+ \f[I] # General options are listed first, one or more per line. \f[ R ]
739
+ \f[I] # These will be used with all hledger commands that support them. \f[ R ]
740
+ \-\- pretty
741
+
742
+ \f[I] # Options following a \[ga ] [COMMANDNAME] \[ga ] heading are used with that hledger command only. \f[ R ]
743
+ \f[B] [print] \f[ R ]
744
+ \-\- explicit \-\- show\- costs
745
+ .EE
746
+ .PP
747
+ To use a config file, specify it with the \f[CR] \-\- conf \f[ R ] option.
748
+ Its options will be inserted near the start of your command line (so you
749
+ can override them if needed).
750
+ Or, you can add a \f[CR] hledger \-\- conf \f[ R ] shebang line to a config
751
+ file and execute it like a script.
752
+ .PP
753
+ Or, you can set up an automatic config file that is used whenever you
754
+ run hledger.
755
+ This can be \f[CR] hledger.conf \f[ R ] in the current directory or above,
756
+ or \f[CR] .hledger.conf \f[ R ] in your home directory
757
+ (\f[CR] \[ti ] /.hledger.conf \f[ R ] ), or \f[CR] hledger.conf \f[ R ] in your XDG
758
+ config directory (\f[CR] \[ti ] /.config/hledger/hledger.conf \f[ R ] ).
759
+ .PP
760
+ You can ignore config files by adding the \f[CR] \- n/ \-\- no \- conf \f[ R ]
761
+ flag.
762
+ This is useful when using hledger in scripts, or when troubleshooting.
763
+ (When both \f[CR] \-\- conf \f[ R ] and \f[CR] \-\- no \- conf \f[ R ] options are
764
+ used, the right\- most wins.)
765
+ To inspect the processing of config files, use \f[CR] \-\- debug \f[ R ] or
766
+ \f[CR] \-\- debug=8 \f[ R ] .
767
+ .PP
768
+ Here is another example config file you could start with:
769
+ https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
770
+ .PP
771
+ Automatic config files are convenient, but have a cost: it\[aq ] s easy to
772
+ change a report\[aq ] s behaviour, or break scripts/applications which use
773
+ hledger, in unintended ways that will surprise you later.
774
+ They change the nature of hledger somewhat, making it less transparent
775
+ and predictable.
776
+ If you decide to use one, here are some tips:
777
+ .IP \[bu ] 2
778
+ Be conservative about what you put in it.
779
+ Try to consider the effect on all your reports.
780
+ .IP \[bu ] 2
781
+ Whenever a hledger command does not work as expected, try it again with
782
+ \f[CR] \- n \f[ R ] .
783
+ .IP \[bu ] 2
784
+ If that helps, you can run it with \f[CR] \-\- debug \f[ R ] to see how a
785
+ config file affected it.
786
+ .PP
787
+ This feature has been added in hledger 1.40 and is considered
788
+ \f[I] experimental \f[ R ] .
763
789
.SH Output
764
790
.SS Output destination
765
791
hledger commands send their output to the terminal by default.
@@ -8876,6 +8902,9 @@ Flags:
8876
8902
description closest to DESC
8877
8903
\- r \-\- related show postings\[aq ] siblings instead
8878
8904
\-\- invert display all amounts with reversed sign
8905
+ \-\- sort=FIELDS sort by: date, desc, account, amount, absamount,
8906
+ or a comma\- separated combination of these. For a
8907
+ descending sort, prefix with \- . (Default: date)
8879
8908
\- w \-\- width=N set output width (default: terminal width or
8880
8909
$COLUMNS). \- wN,M sets description width as well.
8881
8910
\-\- align\- all guarantee alignment across all lines (slower)
@@ -8943,6 +8972,16 @@ For example, it can be used on an income account where amounts are
8943
8972
normally displayed as negative numbers.
8944
8973
It\[aq ] s also useful to show postings on the checking account together
8945
8974
with the related account:
8975
+ .PP
8976
+ The \f[CR] \-\- sort=FIELDS \f[ R ] flag sorts by the fields given, which can
8977
+ be any of \f[CR] account \f[ R ] , \f[CR] amount \f[ R ] , \f[CR] absamount \f[ R ] ,
8978
+ \f[CR] date \f[ R ] , or \f[CR] desc \f[ R ] /\f[CR] description \f[ R ] , optionally
8979
+ separated by commas.
8980
+ For example, \f[CR] \-\- sort account,amount \f[ R ] will group all
8981
+ transactions in each account, sorted by transaction amount.
8982
+ Each field can be negated by a preceding \f[CR] \- \f[ R ] , so
8983
+ \f[CR] \-\- sort \- amount \f[ R ] will show transactions ordered from
8984
+ smallest amount to largest amount.
8946
8985
.IP
8947
8986
.EX
8948
8987
$ hledger register \-\- related \-\- invert assets:checking
0 commit comments