Debian Codegraph @

Hledger/Cli/Commands/Add.txt

raw
1 add
2
3 Add new transactions to a journal file, with interactive prompting.
4
5 Flags:
6 --no-new-accounts don't allow creating new accounts
7
8 Many hledger users edit their journals directly with a text editor, or
9 generate them from CSV. For more interactive data entry, there is the
10 add command, which prompts interactively on the console for new
11 transactions, and appends them to the main journal file (which should be
12 in journal format). Existing transactions are not changed. This is one
13 of the few hledger commands that writes to the journal file (see also
14 import).
15
16 To use it, just run hledger add and follow the prompts. You can add as
17 many transactions as you like; when you are finished, enter . or press
18 control-d or control-c to exit.
19
20 Features:
21
22 - add tries to provide useful defaults, using the most similar (by
23 description) recent transaction (filtered by the query, if any) as a
24 template.
25 - You can also set the initial defaults with command line arguments.
26 - Readline-style edit keys can be used during data entry.
27 - The tab key will auto-complete whenever possible - accounts,
28 payees/descriptions, dates (yesterday, today, tomorrow). If the input
29 area is empty, it will insert the default value.
30 - A parenthesised transaction code may be entered following a date.
31 - Comments and tags may be entered following a description or amount.
32 - If you make a mistake, enter < at any prompt to go one step backward.
33 - Input prompts are displayed in a different colour when the terminal
34 supports it.
35
36 Notes:
37
38 - If you enter a number with no commodity symbol, and you have declared
39 a default commodity with a D directive, you might expect add to add
40 this symbol for you. It does not do this; we assume that if you are
41 using a D directive you prefer not to see the commodity symbol
42 repeated on amounts in the journal.
43 - add creates entries in journal format; it won't work with timeclock or
44 timedot files.
45 - There is a known issue on Windows if this hledger version is built
46 from stackage: the prompts will show ANSI junk instead of colours
47 (#2410). You can avoid this by using official hledger release binaries
48 or by building it with haskeline >=0.8.4; or by running add with
49 --color=no, perhaps configured in your config file.
50
51 Examples:
52
53 - Record new transactions, saving to the default journal file:
54
55 hledger add
56
57 - Add transactions to 2024.journal, but also load 2023.journal for
58 completions:
59
60 hledger add --file 2024.journal --file 2023.journal
61
62 - Provide answers for the first four prompts:
63
64 hledger add today 'best buy' expenses:supplies '$20'
65
66 There is a detailed tutorial at https://hledger.org/add.html.
67
68 add and balance assertions
69
70 Since hledger 1.43, you can add a balance assertion by writing
71 AMOUNT = BALANCE when asked for an amount. Eg 100 = 500.
72
73 Also, each time you enter a new amount, hledger re-checks all balance
74 assertions in the journal and rejects the new amount if it would make
75 any of them fail. You can run add with -I/--ignore-assertions to disable
76 balance assertion checking.
77
78 add and balance assignments
79
80 Since hledger 1.51, you can add a balance assignment by writing
81 = BALANCE (or ==, =* etc) when asked for an amount. The missing amount
82 will be calculated automatically.
83
84 add normally won't let you add a new posting which is dated earlier than
85 an existing balance assignment. (Because when add runs, existing balance
86 assignments have already been calculated and converted to amounts and
87 balance assertions.) You can allow it by disabling balance assertion
88 checking with -I.