-
Notifications
You must be signed in to change notification settings - Fork 501
/
ledger3.texi
10404 lines (8289 loc) · 346 KB
/
ledger3.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo @c -*-texinfo-*-
@setfilename ledger3.info
@include version.texi
@set FIXME:UNDOCUMENTED @sc{undocumented}! Please help by contributing documentation for this feature.
@set InternalUseOnly For internal use only.
@settitle Ledger: Command-Line Accounting
@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with
@c a prefix arg). This updates the node pointers, which texinfmt.el
@c needs.
@c | Formating | Indexing | |
@c | | @cindex | concept |
@c | @command | @findex | Ledger CLI Command (like balance) |
@c | @option | @findex | Ledger CLI Option (like --market) |
@c | @var | | Ledger CLI option Variable (like -f FILE) |
@c | | | Ledger file Syntax |
@c | @samp | | Valued example or single char |
@c | @file | | File, Buffer |
@c | @file | | Program (like ledger, report, acprep) |
@c Restructuring manual ideas
@c http://beyondgrep.com/documentation/ack-2.04-man.html
@c How to make documented ledger examples validate automatically.
@c
@c The test/DocTests.py script will be run along with the other tests
@c when using ctest or acprep check.
@c The script parses the texinfo file and looks for three kinds of
@c specially marked @smallexamples, then it will run the ledger
@c command from the example, and compare the results with the output
@c from the documentation.
@c
@c To specially mark a @smallexample append @c command:UUID, where
@c UUID is the first 7 digits from the commands sha1sum, e.g.:
@c
@c @smallexample @c command:CDE330A
@c $ ledger -f sample.dat reg expenses
@c @end smallexample
@c
@c Then DocTests.py will look for corresponding documented output,
@c which may appear anywhere in the file, and is marked with
@c @smallexample @c output:UUID where UUID is the UUID from the
@c corresponding ledger command example, e.g.:
@c
@c @smallexample @c output:CDE330A
@c 04-May-27 Book Store Expenses:Books $20.00 $20.00
@c Expenses:Cards $40.00 $60.00
@c Expenses:Docs $30.00 $90.0
@c @end smallexample
@c
@c Now where does this data in sample.dat come from?
@c DocTests.py is a bit smart about ledger's file argument, since
@c it will check if the given filename exists in the test/input/
@c directory.
@c
@c Sometimes the journal data for an example is specified within
@c the documentation itself, in that case the journal example data
@c needs to be specially marked as well using @smallexample @c input:UUID,
@c again with the UUID being the UUID of the corresponding ledger example
@c command. If multiple inputs with the same UUID are found they will be
@c concatenated together and given as one set of data to the example command.
@c
@c @smallexample @c input:35CB2A3
@c 2014/02/09 The Italian Place
@c Expenses:Food:Dining $ 36.84
@c Assets:Cash
@c @end smallexample
@c
@c @smallexample @c command:35CB2A3
@c $ ledger -f inline.dat accounts
@c @end smallexample
@c
@c @smallexample @c output:35CB2A3
@c Assets:Cash
@c Expenses:Food:Dining
@c @end smallexample
@c
@c To use different example commands with the same input from the documentation
@c add with_input:UUID to the example command, where UUID is the UUID of the input,
@c e.g.:
@c
@c @smallexample @c command:94FD2B6,with_input:35CB2A3
@c $ ledger -f inline.dat bal expenses
@c @end smallexample
@c
@c @smallexample @c output:94FD2B6
@c $ 36.84 Expenses:Food:Dining
@c @end smallexample
@c
@c To pass additional input to ledger for certain commands, e.g. convert add
@c with_file:filename to the example command and add a file:UUID to an example
@c that holds the additional input, where UUID is the UUID of the command,
@c e.g.:
@c
@c @smallexample @c file:download.csv
@c 767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,,
@c @end smallexample
@c
@c @smallexample @c command:94FD2B6,with_file:download.csv
@c $ ledger -f sample.dat convert download.csv
@c @end smallexample
@c
@c Additionally DocTests.py will pass --args-only and --columns 80 to ledger
@c to ignore any default arguments from the environment or .ledgerrc.
@c
@c To manually run the tests in this file run:
@c $ ./test/DocTests.py -vv --ledger ./ledger --file ./doc/ledger3.texi
@copying
Copyright @copyright{} 2003--2019, John Wiegley. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
@itemize
@item
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
@item
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
@item
Neither the name of New Artisans LLC nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
@end itemize
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@end copying
@dircategory User Applications
@direntry
* Ledger3: (ledger3). Command-Line Accounting
@end direntry
@documentencoding UTF-8
@iftex
@finalout
@end iftex
@titlepage
@title Ledger: Command-Line Accounting
@subtitle For Version @value{VERSION} of Ledger
@author John Wiegley
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top, Introduction to Ledger, (dir), (dir)
@top Overview
Ledger is a command-line accounting tool that provides double-entry
accounting based on a text journal. It provides no bells or whistles,
and returns the user to the days before user interfaces were even a
twinkling in their fathers' CRTs.
@end ifnottex
@menu
* Introduction to Ledger::
* Ledger Tutorial::
* Principles of Accounting with Ledger::
* Keeping a Journal::
* Transactions::
* Building Reports::
* Reporting Commands::
* Command-Line Syntax::
* Budgeting and Forecasting::
* Time Keeping::
* Value Expressions::
* Format Strings::
* Extending with Python::
* Ledger for Developers::
* Major Changes from version 2.6::
* Example Journal File::
* Miscellaneous Notes::
* Concepts Index::
* Commands & Options Index::
@end menu
@node Introduction to Ledger, Ledger Tutorial, Top, Top
@chapter Introduction to Ledger
@menu
* Fat-free Accounting::
* Building the program::
* Getting help::
* Third-Party Ledger Tutorials::
@end menu
@node Fat-free Accounting, Building the program, Introduction to Ledger, Introduction to Ledger
@section Fat-free Accounting
Ledger is an accounting tool with the moxie to exist. It provides no
bells or whistles, and returns the user to the days before user
interfaces were even a twinkling in their father's CRT.
What it does offer is a double-entry accounting journal with all the
flexibility and muscle of its modern day cousins, without any of the
fat. Think of it as the Bran Muffin of accounting tools.
To use it, you need to start keeping a journal. This is the basis of
all accounting, and if you haven't started yet, now is the time to
learn. The little booklet that comes with your checkbook is a journal,
so we'll describe double-entry accounting in terms of that.
@c If you use another GUI accounting program like GnuCash, the vast
@c majority of its functionality is geared towards helping you keep
@c a journal.
A checkbook journal records debits (subtractions, or withdrawals) and
credits (additions, or deposits) with reference to a single account:
the checking account. Where the money comes from, and where it goes
to, are described in the payee field, where you write the person or
company's name. The ultimate aim of keeping a checkbook journal is to
know how much money is available to spend. That's really the aim of
all journals.
@cindex postings
What computers add is the ability to walk through these postings,
and tell you things about your spending habits; to let you devise
budgets and get control over your spending; to squirrel away money
into virtual savings account without having to physically move money
around; etc. As you keep your journal, you are recording information
about your life and habits, and sometimes that information can start
telling you things you aren't aware of. Such is the aim of all good
accounting tools.
The next step up from a checkbook journal, is a journal that keeps
track of all your accounts, not just checking. In such a journal, you
record not only who gets paid---in the case of a debit---but where the
money came from. In a checkbook journal, it's assumed that all the
money comes from your checking account. But in a general journal, you
write postings in two lines: the source account and target account.
@emph{There must always be a debit from at least one account for every
credit made to another account}. This is what is meant by
``double-entry'' accounting: the journal must always balance to zero,
with an equal number of debits and credits.
For example, let's say you have a checking account and a brokerage
account, and you can write checks from both of them. Rather than keep
two checkbooks, you decide to use one journal for both. In this
general journal you need to record a payment to Pacific Bell for your
monthly phone bill, and a transfer (via check) from your brokerage
account to your checking account. The Pacific Bell bill is $23.00,
let's say, and you want to pay it from your checking account. In the
general journal you need to say where the money came from, in addition
to where it's going to. These transactions might look like this:
@smallexample
9/29 Pacific Bell $23.00 $23.00
Checking $-23.00 0
9/30 Checking $100.00 $100.00
(123) Brokerage $-100.00 0
@end smallexample
The posting must balance to $0: $23 went to Pacific Bell, $23 came
from Checking. The next entry shows check number 123 written against
your brokerage account, transferring money to your checking account.
There is nothing left over to be accounted for, since the money has
simply moved from one account to another in both cases. This is the
basis of double-entry accounting: money never pops in or out of
existence; it is always a posting from one account to another.
Keeping a general journal is the same as keeping two separate
journals: One for Pacific Bell and one for Checking. In that case,
each time a payment is written into one, you write a corresponding
withdrawal into the other. This makes it easier to write in
a ``running balance'', since you don't have to look back at the last
time the account was referenced---but it also means having a lot of
journal books, if you deal with multiple accounts.
@cindex account, meaning of
@cindex meaning of account
Here is a good place for an aside on the use of the word ``account''.
Most private people consider an account to be something that holds
money at an institution for them. Ledger uses a more general
definition of the word. An account is anywhere money can go. Other
finance programs use ``categories'', Ledger uses accounts. So, for
example, if you buy some groceries at Trader Joe's, then more groceries
at Whole Food Market, you might assign the transactions like this
@smallexample @c input:validate
2011/03/15 Trader Joe's
Expenses:Groceries $100.00
Assets:Checking
2011/03/15 Whole Food Market
Expenses:Groceries $75.00
Assets:Checking
@end smallexample
In both cases the money goes to the @samp{Groceries} account, even
though the payees were different. You can set up your accounts in any
way you choose.
Enter the beauty of computerized accounting. The purpose of the
Ledger program is to make general journal accounting simple, by
keeping track of the balances for you. Your only job is to enter the
postings. If an individual posting does not balance, Ledger displays
an error and indicates the incorrect posting.@footnote{In some special
cases, it automatically balances this transaction for you.}
In summary, there are two aspects of Ledger use: updating the journal
data file, and using the Ledger tool to view the summarized result of
your transactions.
And just for the sake of example---as a starting point for those who
want to dive in head-first---here are the journal transactions from
above, formatted as the Ledger program wishes to see them:
@smallexample @c input:48DDF26
2004/09/29 Pacific Bell
Expenses:Pacific Bell $23.00
Assets:Checking
@end smallexample
The account balances and registers in this file, if saved as
@file{ledger.dat}, could be reported using:
@smallexample @c command:48DDF26
$ ledger -f ledger.dat balance
@end smallexample
@smallexample @c output:48DDF26
$-23.00 Assets:Checking
$23.00 Expenses:Pacific Bell
--------------------
0
@end smallexample
Or
@smallexample @c command:8C7295F,with_input:48DDF26
$ ledger -f ledger.dat register checking
@end smallexample
@smallexample @c output:8C7295F
04-Sep-29 Pacific Bell Assets:Checking $-23.00 $-23.00
@end smallexample
And even:
@smallexample @c command:BB32EF2,with_input:48DDF26
$ ledger -f ledger.dat register Bell
@end smallexample
@smallexample @c output:BB32EF2
04-Sep-29 Pacific Bell Expenses:Pacific Bell $23.00 $23.00
@end smallexample
An important difference between Ledger and other finance packages is
that Ledger will never alter your input file. You can create and edit
that file in any way you prefer, but Ledger is only for analyzing the
data, not for altering it.
@node Building the program, Getting help, Fat-free Accounting, Introduction to Ledger
@section Building the program
Ledger is written in ANSI C++, and should compile on any unix platform.
The easiest way to build and install ledger is to use the prepared
acprep script, that does a lot of the footwork:
@smallexample
# to install missing dependencies
./acprep dependencies
# building ledger
./acprep update
# to run the actual installation
make install
@end smallexample
See the `help` subcommand to `acprep`, which explains some of its many
options. You can run `make check` to confirm the result, and `make
install` to install. If these instructions do not work for you, you can check the
`INSTALL.md` in the source directory for more up to date build instructions.
@node Getting help, Third-Party Ledger Tutorials, Building the program, Introduction to Ledger
@section Getting help
@findex help
Ledger has a complete online help system based on GNU Info. This manual
can be searched directly from the command-line using @code{info ledger},
which will bring up this entire manual in your TTY. Alternatively, the
shorter man page can be accessed from the command-line either via
@code{man ledger} or @code{ledger --help}
If you need help on how to use Ledger, or run into problems, you can
join the Ledger mailing list at
@url{http://groups.google.com/group/ledger-cli}.
You can also find help in the @code{#ledger} channel on the IRC server
@code{irc.freenode.net}.
@node Third-Party Ledger Tutorials, , Getting help, Introduction to Ledger
@section Third-Party Ledger Tutorials
There are plenty of people using Ledger for accounting applications.
Some have documented how they use Ledger's features to solve their
accounting problems.
One such tutorial, specifically designed for non-profit charities that seek
to use Ledger, can be found at
@url{https://k.sfconservancy.org/NPO-Accounting/npo-ledger-cli} (with a copy on GitHub also
available at @url{https://github.com/conservancy/npo-ledger-cli/}). If
you're looking for information about how to use Ledger's tagging system to
handle invoicing, track expenses by program targets, and other such concepts,
you might find the tutorial useful. (Some of the auditor reporting scripts
that relate to the aforementioned Ledger setup can be found
@var{contrib/non-profit-audit-reports/} in Ledger's own source repository.)
@node Ledger Tutorial, Principles of Accounting with Ledger, Introduction to Ledger, Top
@chapter Ledger Tutorial
@cindex tutorial
@menu
* Start a Journal File::
* Run a Few Reports::
@end menu
@node Start a Journal File, Run a Few Reports, Ledger Tutorial, Ledger Tutorial
@section Start a Journal File
@cindex journals
A journal is a record of your financial transactions and will be central
to using Ledger. For now we just want to get a taste of what Ledger can
do. An example journal is included with the source code distribution,
called @file{drewr3.dat} (@pxref{Example Journal File}). Copy it
someplace convenient and open up a terminal window in that directory.
If you would rather start with your own journal right away please
@pxref{Keeping a Journal}.
@node Run a Few Reports, , Start a Journal File, Ledger Tutorial
@section Run a Few Reports
@menu
* Balance Report::
* Register Report::
* Cleared Report::
* Using the Windows Command-Line::
@end menu
Please note that as a command-line program, Ledger is controlled from
your shell. There are several different command shells that all
behave slightly differently with respect to some special characters.
In particular, the ``bash'' shell will interpret @samp{$} signs
differently than ledger and they must be escaped to reach the actual
program. Another example is ``zsh'', which will interpret @samp{^}
differently than ledger expects. In all cases that follow you should
take that into account when entering the command-line arguments as given.
There are too many variations between shells to give concrete examples
for each.
@node Balance Report, Register Report, Run a Few Reports, Run a Few Reports
@subsection Balance Report
@cindex balance report
@findex balance
To find the balances of all of your accounts, run this command:
@smallexample @c command:1071890
$ ledger -f drewr3.dat balance
@end smallexample
Ledger will generate:
@smallexample @c output:1071890
$ -3,804.00 Assets
$ 1,396.00 Checking
$ 30.00 Business
$ -5,200.00 Savings
$ -1,000.00 Equity:Opening Balances
$ 6,654.00 Expenses
$ 5,500.00 Auto
$ 20.00 Books
$ 300.00 Escrow
$ 334.00 Food:Groceries
$ 500.00 Interest:Mortgage
$ -2,030.00 Income
$ -2,000.00 Salary
$ -30.00 Sales
$ -63.60 Liabilities
$ -20.00 MasterCard
$ 200.00 Mortgage:Principal
$ -243.60 Tithe
--------------------
$ -243.60
@end smallexample
@noindent
Showing you the balance of all accounts. Options and search terms can
pare this down to show only the accounts you want.
A more useful report is to show only your Assets and Liabilities:
@smallexample @c command:5BF4D8E
$ ledger -f drewr3.dat balance Assets Liabilities
@end smallexample
@smallexample @c output:5BF4D8E
$ -3,804.00 Assets
$ 1,396.00 Checking
$ 30.00 Business
$ -5,200.00 Savings
$ -63.60 Liabilities
$ -20.00 MasterCard
$ 200.00 Mortgage:Principal
$ -243.60 Tithe
--------------------
$ -3,867.60
@end smallexample
@node Register Report, Cleared Report, Balance Report, Run a Few Reports
@subsection Register Report
@cindex register report
@findex register
To show all transactions and a running total:
@smallexample @c command:66E3A2C
$ ledger -f drewr3.dat register
@end smallexample
@noindent
Ledger will generate:
@smallexample @c output:66E3A2C
10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00
Equit:Opening Balances $ -1,000.00 0
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
Expense:Food:Groceries $ 37.50 $ 75.00
Expense:Food:Groceries $ 37.50 $ 112.50
Expense:Food:Groceries $ 37.50 $ 150.00
Expense:Food:Groceries $ 37.50 $ 187.50
Expense:Food:Groceries $ 37.50 $ 225.00
Assets:Checking $ -225.00 0
10-Dec-28 Acme Mortgage Lia:Mortgage:Principal $ 200.00 $ 200.00
Expe:Interest:Mortgage $ 500.00 $ 700.00
Expenses:Escrow $ 300.00 $ 1,000.00
Assets:Checking $ -1,000.00 0
11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 65.00
Assets:Checking $ -65.00 0
11-Jan-05 Employer Assets:Checking $ 2,000.00 $ 2,000.00
Income:Salary $ -2,000.00 0
(Liabilities:Tithe) $ -240.00 $ -240.00
11-Jan-14 Bank Assets:Savings $ 300.00 $ 60.00
Assets:Checking $ -300.00 $ -240.00
11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ -196.00
Assets:Checking $ -44.00 $ -240.00
11-Jan-25 Bank Assets:Checking $ 5,500.00 $ 5,260.00
Assets:Savings $ -5,500.00 $ -240.00
11-Jan-25 Tom's Used Cars Expenses:Auto $ 5,500.00 $ 5,260.00
Assets:Checking $ -5,500.00 $ -240.00
11-Jan-27 Book Store Expenses:Books $ 20.00 $ -220.00
Liabilities:MasterCard $ -20.00 $ -240.00
11-Dec-01 Sale Asse:Checking:Business $ 30.00 $ -210.00
Income:Sales $ -30.00 $ -240.00
(Liabilities:Tithe) $ -3.60 $ -243.60
@end smallexample
@noindent
To limit this to a more useful subset, simply add the accounts you are
interested in seeing transactions for:
@cindex accounts, limiting by
@cindex limiting by accounts
@smallexample @c command:96B0EB3
$ ledger -f drewr3.dat register Groceries
@end smallexample
@smallexample @c output:96B0EB3
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
Expense:Food:Groceries $ 37.50 $ 75.00
Expense:Food:Groceries $ 37.50 $ 112.50
Expense:Food:Groceries $ 37.50 $ 150.00
Expense:Food:Groceries $ 37.50 $ 187.50
Expense:Food:Groceries $ 37.50 $ 225.00
11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 290.00
11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ 334.00
@end smallexample
@noindent
Which matches the balance reported for the @samp{Groceries} account:
@smallexample @c command:AECD64E
$ ledger -f drewr3.dat balance Groceries
@end smallexample
@smallexample @c output:AECD64E
$ 334.00 Expenses:Food:Groceries
@end smallexample
@noindent
If you would like to find transaction to only a certain payee use
@samp{payee} or @samp{@@}:
@smallexample @c command:C6BC57E
$ ledger -f drewr3.dat register payee "Organic"
@end smallexample
@smallexample @c output:C6BC57E
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
Expense:Food:Groceries $ 37.50 $ 75.00
Expense:Food:Groceries $ 37.50 $ 112.50
Expense:Food:Groceries $ 37.50 $ 150.00
Expense:Food:Groceries $ 37.50 $ 187.50
Expense:Food:Groceries $ 37.50 $ 225.00
Assets:Checking $ -225.00 0
@end smallexample
@node Cleared Report, Using the Windows Command-Line, Register Report, Run a Few Reports
@subsection Cleared Report
@cindex cleared report
@findex cleared
A very useful report is to show what your obligations are versus what
expenditures have actually been recorded. It can take several days for
a check to clear, but you should treat it as money spent. The
@command{cleared} report shows just that (note that the
@command{cleared} report will not format correctly for accounts that
contain multiple commodities):
@smallexample @c command:B86F6A6
$ ledger -f drewr3.dat cleared
@end smallexample
@smallexample @c output:B86F6A6
$ -3,804.00 $ 775.00 Assets
$ 1,396.00 $ 775.00 10-Dec-20 Checking
$ 30.00 0 Business
$ -5,200.00 0 Savings
$ -1,000.00 $ -1,000.00 10-Dec-01 Equity:Opening Balances
$ 6,654.00 $ 225.00 Expenses
$ 5,500.00 0 Auto
$ 20.00 0 Books
$ 300.00 0 Escrow
$ 334.00 $ 225.00 10-Dec-20 Food:Groceries
$ 500.00 0 Interest:Mortgage
$ -2,030.00 0 Income
$ -2,000.00 0 Salary
$ -30.00 0 Sales
$ -63.60 0 Liabilities
$ -20.00 0 MasterCard
$ 200.00 0 Mortgage:Principal
$ -243.60 0 Tithe
---------------- ---------------- ---------
$ -243.60 0
@end smallexample
@noindent
The first column shows the outstanding balance, the second column
shows the ``cleared'' balance.
@node Using the Windows Command-Line, , Cleared Report, Run a Few Reports
@subsection Using the Windows Command-Line
@cindex windows cmd.exe
@cindex currency symbol display on windows
Using ledger under the windows command shell has one significant
limitation. CMD.EXE is limited to standard ASCII characters and as
such cannot display any currency symbols other than dollar signs
@samp{$}.
@node Principles of Accounting with Ledger, Keeping a Journal, Ledger Tutorial, Top
@chapter Principles of Accounting with Ledger
@menu
* Accounting with Ledger::
* Stating where money goes::
* Assets and Liabilities::
* Commodities and Currencies::
* Accounts and Inventories::
* Understanding Equity::
* Dealing with Petty Cash::
* Working with multiple funds and accounts::
@end menu
@node Accounting with Ledger, Stating where money goes, Principles of Accounting with Ledger, Principles of Accounting with Ledger
@section Accounting with Ledger
@cindex double-entry accounting
Accounting is simply tracking your money. It can range from nothing,
and just waiting for automatic overdraft protection to kick in, or
not, to a full-blown double-entry accounting system. Ledger
accomplishes the latter. With ledger you can handle your personal
finances or your business's. Double-entry accounting scales.
@node Stating where money goes, Assets and Liabilities, Accounting with Ledger, Principles of Accounting with Ledger
@section Stating where money goes
@cindex credits and debits
Accountants will talk of ``credits'' and ``debits'', but the meaning
is often different from the layman's understanding. To avoid
confusion, Ledger uses only subtractions and additions, although the
underlying intent is the same as standard accounting principles.
Recall that every posting will involve two or more accounts.
Money is transferred from one or more accounts to one or more other
accounts. To record the posting, an amount is @emph{subtracted}
from the source accounts, and @emph{added} to the target accounts.
In order to write a Ledger transaction correctly, you must determine
where the money comes from and where it goes to. For example, when
you are paid a salary, you must add money to your bank account and
also subtract it from an income account:
@smallexample @c input:validate
9/29 My Employer
Assets:Checking $500.00
Income:Salary $-500.00
@end smallexample
@cindex income is negative
@cindex why is income negative
Why is the Income a negative figure? When you look at the balance
totals for your ledger, you may be surprised to see that Expenses are
a positive figure, and Income is a negative figure. It may take some
getting used to, but to properly use a general ledger you must think
in terms of how money moves. Rather than Ledger ``fixing'' the minus
signs, let's understand why they are there.
When you earn money, the money has to come from somewhere. Let's call
that somewhere ``society''. In order for society to give you an
income, you must take money away (withdraw) from society in order to
put it into (make a payment to) your bank. When you then spend that
money, it leaves your bank account (a withdrawal) and goes back to
society (a payment). This is why Income will appear negative---it
reflects the money you have drawn from society---and why Expenses will
be positive---it is the amount you've given back. These additions and
subtractions will always cancel each other out in the end, because you
don't have the ability to create new money: it must always come from
somewhere, and in the end must always leave. This is the beginning of
economy, after which the explanation gets terribly difficult.
Based on that explanation, here's another way to look at your balance
report: every negative figure means that that account or person or
place has less money now than when you started your ledger; and every
positive figure means that that account or person or place has more
money now than when you started your ledger. Make sense?
@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Principles of Accounting with Ledger
@section Assets and Liabilities
@cindex assets and liabilities
@cindex debts are liabilities
Assets are money that you have, and Liabilities are money that you
owe. ``Liabilities'' is just a more inclusive name for Debts.
An Asset is typically increased by transferring money from an Income
account, such as when you get paid. Here is a typical transaction:
@smallexample @c input:6B43DD4
2004/09/29 My Employer
Assets:Checking $500.00
Income:Salary
@end smallexample
Money, here, comes from an Income account belonging to @samp{My
Employer}, and is transferred to your checking account. The money is
now yours, which makes it an Asset.
Liabilities track money owed to others. This can happen when you
borrow money to buy something, or if you owe someone money. Here is
an example of increasing a MasterCard liability by spending money with
it:
@smallexample @c input:6B43DD4
2004/09/30 Restaurant
Expenses:Dining $25.00
Liabilities:MasterCard
@end smallexample
The Dining account balance now shows $25 spent on Dining, and
a corresponding $25 owed on the MasterCard---and therefore shown as
$-25.00. The MasterCard liability shows up as negative because it
offsets the value of your assets.
The combined total of your Assets and Liabilities is your net worth.
So to see your current net worth, use this command:
@smallexample @c command:6B43DD4
$ ledger balance ^assets ^liabilities
@end smallexample
@smallexample @c output:6B43DD4
$500.00 Assets:Checking
$-25.00 Liabilities:MasterCard
--------------------
$475.00
@end smallexample
In a similar vein, your Income accounts show up negative, because they
transfer money @emph{from} an account in order to increase your
assets. Your Expenses show up positive because that is where the
money went to. The combined total of Income and Expenses is your cash
flow. A positive cash flow means you are spending more than you make,
since income is always a negative figure. To see your current cash
flow, use this command:
@smallexample @c command:DB128F3,with_input:6B43DD4
$ ledger balance ^income ^expenses
@end smallexample
@smallexample @c output:DB128F3
$25.00 Expenses:Dining
$-500.00 Income:Salary
--------------------
$-475.00
@end smallexample
Another common question to ask of your expenses is: How much do I
spend each month on X? Ledger provides a simple way of displaying
monthly totals for any account. Here is an example that summarizes
your monthly automobile expenses:
@smallexample @c command:DB524E4
$ ledger -M register -f drewr3.dat expenses:auto
@end smallexample
@smallexample @c output:DB524E4
11-Jan-01 - 11-Jan-31 Expenses:Auto $ 5,500.00 $ 5,500.00
@end smallexample
This assumes, of course, that you use account names like
@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}.
@menu
* Tracking reimbursable expenses::
@end menu
@node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities
@subsection Tracking reimbursable expenses
@cindex reimbursable expense tracking
Sometimes you will want to spend money on behalf of someone else, which
will eventually get repaid. Since the money is still @emph{yours}, it
is really an asset. And since the expenditure was for someone else, you
don't want it contaminating your Expenses reports. You will need to
keep an account for tracking reimbursements.
This is fairly easy to do in ledger. When spending the money, spend
it @emph{to} your Assets:Reimbursements, using a different account for
each person or business that you spend money for. For example:
@smallexample @c input:validate
2004/09/29 Circuit City
Assets:Reimbursements:Company XYZ $100.00
Liabilities:MasterCard
@end smallexample
This shows $100.00 spent on a MasterCard at Circuit City, with the
expense was made on behalf of Company XYZ. Later, when Company XYZ
pays the amount back, the money will transfer from that reimbursement
account back to a regular asset account:
@smallexample @c input:validate
2004/09/29 Company XYZ
Assets:Checking $100.00
Assets:Reimbursements:Company XYZ
@end smallexample
This deposits the money owed from Company XYZ into a checking account,
presumably because they paid the amount back with a check.
But what to do if you run your own business, and you want to keep
track of expenses made on your own behalf, while still tracking
everything in a single ledger file? This is more complex, because you
need to track two separate things: 1) The fact that the money should
be reimbursed to you, and 2) What the expense account was, so that you
can later determine where your company is spending its money.
This kind of posting is best handled with mirrored postings in
two different files, one for your personal accounts, and one for your
company accounts. But keeping them in one file involves the same
kinds of postings, so those are what is shown here. First, the
personal transaction, which shows the need for reimbursement:
@smallexample @c input:validate
2004/09/29 Circuit City
Assets:Reimbursements:Company XYZ $100.00
Liabilities:MasterCard
@end smallexample
This is the same as above, except that you own Company XYZ, and are
keeping track of its expenses in the same ledger file. This
transaction should be immediately followed by an equivalent
transaction, which shows the kind of expense, and also notes the fact
that $100.00 is now payable to you:
@smallexample @c input:validate
2004/09/29 Circuit City
Company XYZ:Expenses:Computer:Software $100.00
Company XYZ:Accounts Payable:Your Name
@end smallexample
This second transaction shows that Company XYZ has just spent $100.00
on software, and that this $100.00 came from Your Name, which must be
paid back.
These two transactions can also be merged, to make things a little
clearer. Note that all amounts must be specified now:
@smallexample @c input:validate
2004/09/29 Circuit City
Assets:Reimbursements:Company XYZ $100.00
Liabilities:MasterCard $-100.00
Company XYZ:Expenses:Computer:Software $100.00
Company XYZ:Accounts Payable:Your Name $-100.00
@end smallexample
To ``pay back'' the reimbursement, just reverse the order of
everything, except this time drawing the money from a company asset,
paying it to accounts payable, and then drawing it again from the
reimbursement account, and paying it to your personal asset account.
It's easier shown than said:
@smallexample @c input:validate
2004/10/15 Company XYZ
Assets:Checking $100.00
Assets:Reimbursements:Company XYZ $-100.00
Company XYZ:Accounts Payable:Your Name $100.00
Company XYZ:Assets:Checking $-100.00
@end smallexample
And now the reimbursements account is paid off, accounts payable is paid
off, and $100.00 has been effectively transferred from the company's
checking account to your personal checking account. The money simply
``waited''---in both @samp{Assets:Reimbursements:Company XYZ}, and
@samp{Company XYZ:Accounts Payable:Your Name}---until such time as it
could be paid off.
The value of tracking expenses from both sides like that is that you
do not contaminate your personal expense report with expenses made on
behalf of others, while at the same time making it possible to
generate accurate reports of your company's expenditures. It is more
verbose than just paying for things with your personal assets, but it
gives you a very accurate information trail.
The advantage to keep these doubled transactions together is that they
always stay in sync. The advantage to keeping them apart is that it
clarifies the transfer's point of view. To keep the postings in
separate files, just separate the two transactions that were joined
above. For example, for both the expense and the pay-back shown
above, the following four transactions would be created. Two in your
personal ledger file:
@smallexample @c input:990E0D1
2004/09/29 Circuit City
Assets:Reimbursements:Company XYZ $100.00
Liabilities:MasterCard $-100.00
2004/10/15 Company XYZ
Assets:Checking $100.00
Assets:Reimbursements:Company XYZ $-100.00
@end smallexample
And two in your company ledger file:
@smallexample @c input:990E0D1
apply account Company XYZ
2004/09/29 Circuit City
Expenses:Computer:Software $100.00
Accounts Payable:Your Name $-100.00
2004/10/15 Company XYZ
Accounts Payable:Your Name $100.00
Assets:Checking $-100.00
end apply account
@end smallexample