From 94b67cd1a558bb3af038a54f001ec8154e32b743 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 14 Jan 2022 17:24:16 -1000 Subject: [PATCH] move to cloudflare pages, drop html files --- .gitignore | 2 +- CNAME | 1 - index.html | 1264 ------------------------------ plaintext-accounting-errors.html | 107 --- quickref/index.html | 1219 ---------------------------- quickref/quickref-beancount.html | 142 ---- quickref/quickref-hledger.html | 117 --- quickref/quickref-ledger.html | 174 ---- 8 files changed, 1 insertion(+), 3025 deletions(-) delete mode 100644 CNAME delete mode 100644 index.html delete mode 100644 plaintext-accounting-errors.html delete mode 100755 quickref/index.html delete mode 100644 quickref/quickref-beancount.html delete mode 100644 quickref/quickref-hledger.html delete mode 100644 quickref/quickref-ledger.html diff --git a/.gitignore b/.gitignore index 5666dbd..f7a3eb7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ .idea/ .vendor/ -README.html +*.html .* _* diff --git a/CNAME b/CNAME deleted file mode 100644 index 858d049..0000000 --- a/CNAME +++ /dev/null @@ -1 +0,0 @@ -plaintextaccounting.org \ No newline at end of file diff --git a/index.html b/index.html deleted file mode 100644 index abe2cf7..0000000 --- a/index.html +++ /dev/null @@ -1,1264 +0,0 @@ - - - - - - - Plain Text Accounting, a guide to Ledger and friends - plaintextaccounting.org - - - - - - - - - - - - - - - - - - - - - -
- - - -
-

github

-
-
-

-
-
-

plain text accounting

-
-

Plain text accounting means doing accounting with plain text data formats and scriptable software, in the style of Ledger, hledger, beancount, and co. This site is a FAQ and directory for the PTA community's tools, docs and practices. It is maintained by Simon Michael (hledger project leader, Ledger contributor, PTA researcher & fan), and contributors like you. Got feedback ? Join us in #plaintextaccounting:libera.chat or #plaintextaccounting:matrix.org or send an edit. See also wiki.plaintextaccounting.org, new for 2022!

-
-
-
-

FAQ

-

(A work in progress; improvements always welcome.)

-

What and why

-
What is Accounting, and what can it do for me?
-

Accounting is tracking the flow of valuable commodities, such as money or time. It clarifies activity, priorities, obligations, opportunities. It can reduce stress and even be enjoyable.

-
What is Plain Text Accounting?
-

In 2003, John Wiegley invented Ledger: a command-line reporting tool and a plain text data format for efficient double-entry-style accounting. Ledger's ideas appealed to many software developers and technical folk. In 2007 and 2008 it was joined by hledger and Beancount respectively, and as of 2019 there are more than a dozen Ledger-likes, many add-on tools and an active community. This site was started in 2016 to help keep track of it all.

-
What is double-entry?
-

Double-entry bookkeeping is a process for keeping accounting records reliably. For every movement of value (a transaction), both the source and destination are recorded. Simple arithmetic invariants help prevent errors.

-

Value at any point in time is tracked in various accounts, classified as asset (owned), liability (owed) or equity (invested). Two more classifications track changes during some period: revenues (inflows) and expenses (outflows).

-

Transactions consist of debits (increases to asset or expense accounts, or decreases to liability or equity accounts) or credits (decreases to asset or expense accounts, or increases to liability or equity accounts).

-
What are some characteristics of Plain Text Accounting ?
-

Accounting data is valuable; we want to know that it will be accessible for ever - even without software. We want to know when it changes, and revision-control it. We want to search and manipulate it efficiently. So, we store it as human-readable plain text.

-

We simplify debits and credits by using signed numbers - positive for inflows to an account, negative for outflows from an account.

-

We define arbitrary account hierarchy to suit our needs. This scales smoothly from simple to complex scenarios, and from high-level overview to fine detail.

-

Ledger-likes are, at least in part, command-line tools. This makes them efficient to use and very scriptable and flexible.

-

Ledger-likes also, at their core, tend towards functional operation: they read the input data without changing it, and output a report. This simple model makes them easy to understand and rely on.

-
- - - -
-

-
- -
-
Who is using this, and how?
-

Who's using Ledger? has some stories.

-
Is it a good fit for me?
-

If you would like to use a GUI that provides lots of guidance, PTA tools currently don't meet that need. Most current PTA users tend to be comfortable using the command line, editing plain text, and perhaps using version control.

-
What are the alternatives?
-

Traditional GUI-centric accounting software:
-Free/open-source: GNUCash, Grisbi, KMyMoney..
-Commercial: Quicken, Quickbooks, You Need A Budget..

-

Online/cloud-based accounting software: Xero, FreeAgent..

-

Here is Wikipedia's Comparison of accounting software. Also:

-
    -
  • spreadsheets
    • -
  • keeping accounts on paper
    • -
  • using a bookkeeper/accountant.
    • -
-
What are the advantages over traditional (Free/open-source) accounting software, like GnuCash?
- -

Some key factors:

- -

a. The plain text, human readable, well supported data formats.

-

b. The division of concerns between creating and managing the data (your responsibility) and analysing it (the tool's responsibility). Ie "immutable data" + "referentially transparent reporting tools".

-

c. The command-line interface.

-

d. The ecosystem of related tools.

-

create synergies such as:

-

1. The data is more future proof. You can access it relatively easily with different software, newly-written software, or no software.

-

2. The command-line based UI, together with the plain text format, allows easy integration with other software, custom workflows and automation.

-

3. The user's responsibilities and mental model feel simpler, ie: "I just need to keep a list of transactions". Complex features and tools are not visible until you need them. Common actions can be easily scripted for daily use.

-

4. The data can be managed using the rich ecosystem of tools for managing text. This is appealing to folks familiar with such tools.

-

5. Most significantly, the data can be effectively version controlled, providing an audit trail, unlimited "undo", and collaboration.

-

6. Because the software (mostly) does not touch your data, and because version control would let you know and roll back if it did, you can have great confidence in the integrity of your data. If the software misbehaves, your data is not at risk. It's safe and relaxing to try out new features or new software on your data.

-

7. The data/tool separation facilitates decentralised development, stimulating an ecosystem of more tools and integrations.

-

8. The free form DSL-style format provides great expressiveness for modelling and documenting real-world financial activities, without UI-imposed limitations.

-
What are the advantages over commercial accounting software, like QuickBooks?
-

In addition to the advantages above, being Free or Open Source software helps ensure: - No lockin - your data remains accessible, and there are no yearly fees. - You can fix, enhance and port the software. - The software is more portable, scriptable, and lightweight.

-
Where can I read more discussion of this approach ?
- -

Objections and Concerns

-
Isn't personal accounting a waste of time?
-

People have very different needs and practise personal accounting for many different reasons. There is of course a point of diminishing returns; tailor your accounting practices to your needs. Needs change over time. Some of us would benefit from doing more (or better) accounting, some less (I would guess this second group is smaller). In The Millionaire Next Door (highly recommended), one research finding was that above-average wealth accumulators spend more time on financial planning, which for many of us requires accounting as a foundation. "Minimal time dedicated to financial planning is a leading indicator of a UAW [Under Accumulator of Wealth]".

-
Must I edit text and type cryptic commands?
-

Not entirely! "Plain Text Accounting" is a broad description, referring mainly to the data format. We welcome optional GUIs, and they are coming.

-
Do you really enter every little transaction?
-

Yes! Many folks in our community do it. Mahatma Gandhi reconciled to the penny every night. J.D. Rockefeller was famous for his ledgers. It's not required. I started doing it as a temporary learning exercise, and still like it. It makes troubleshooting and reconciling easier.

-
How is that possible?
-

Practice, and a process/toolset that suits you. Some folks import most of the data from their banks, so little manual data entry is required. A few prefer to manually enter everything, for the increased awareness and insight. "Manual" data entry is usually assisted in some way: interactive console tools (hledger add and similar), web-based tools (hledger-web and similar), GUI tools (ledgerhelpers), smart editors (eg emacs & ledger-mode), recurring transaction scripts. I currently use a mixture of bank CSV import and rapid copy/paste in emacs. I spend 15 minutes a day on average, and for me that's currently a good investment.

-
How do I use the transaction data in my bank's web or mobile app?
-

If you can export it as CSV, you can import it and run queries against it. There are also some tools for converting OFX, QIF etc.

-
So I've got a huge list of transactions recorded, duplicating my bank statements. How does that help?
-

Accounting is modelling flows of money (or other value). Such a model aggregates information from many sources, in one trusted place. With it you can efficiently generate reports, forecast things (cashflow!), answer questions, try experiments. Some people need a very simple model, others benefit from a more detailed one, and we don't know up front what we might need in future. The most fundamental accounting data is a simple list of transactions (the journal). Once you have captured this, you can mine it for anything you may want later on. Plain text accounting provides nice open data format(s), tools and practices for doing this, and could be a good foundation for more powerful tools.

-
Isn't a command-line tool too limited for real-world accounting needs?
-

"I am sure for a simple expense/budget ledger it will work OK, but when it comes to recurring journals, multiple reconciliation accounts, inter company transfers, control account tracing etc., give me a nice GUI any day..."
-Understandable. The current plain text accounting tools provide a very generic double entry accounting system with which you can model such things, and script them. There are a number of generic GUIs available (hledger has curses and web interfaces, and there are web/curses/GTK interfaces for Ledger and beancount). But there are not yet a lot of rich task-specific GUIs. There's no reason they can't be built, though.

-
Isn't a plain text format too limited for large organizations?
-

"it's pretty obvious that plain-text files don't scale to a multinational, with hundreds of accountants of various types all trying to work with the same files. Even with proper use of Git I bet that would get old fast. You would instead want a real database, with a schema, and some data validation and some programs/webpages to smooth out the data entry and querying and whatnot."
-I'm not sure. Current plain text accounting tools can do some schema definition and data validation, and will do more in future. The plain text storage format is open, human-readable, future-proof (useful even without the software), scales smoothly from simple to complex needs, and taps a huge ecosystem of highly useful tooling, such as version control systems. And, despite the name, there's no reason these tools can't support other kinds of storage, such as a database.

-
If this is double entry accounting, where are the debits and credits?
-

Most (not all) plain text accounting implementations use signed amounts instead of debits and credits. This makes them "double entry light" perhaps, but it has been a rather successful simplification, intuitive to most newcomers.

-
How do I communicate with my accountant?
-

Clean up text reports by hand, print them as PDF, export CSV reports to a spreadsheet..

-
What if my accountant only uses QuickBooks?
-

You'll need a new accountant, or a duplicate set of books in QuickBooks, or to pioneer *ledger -> QuickBooks exporting.

-
Can I use this to do my taxes?
-

You can use this to track and report the data needed for tax reporting. Fill out and submit tax forms with another tool, or by hand.

-

Getting started, Practicalities

-
Where can I see a comparison of hledger, Ledger, beancount, and the rest?
-

Glad you asked! See below, and also comparisons. hledger's FAQ discusses differences from Ledger, Beancount docs probably do too.

-
How to organise files ? Should I split the journal into many files ?
-

All in one file (or one file per year) and ordered by date is simplest and creates the fewest headaches (balance assertions/assignments, scope of directives, where to put entries, finding things..).

-

If you use emacs: it’s possible to insert org headings (which are comments to h/ledger) and then use org-mode or org-minor-mode to collapse/expand/navigate sections of your journal.

-

Also in emacs: in ledger-mode, C-c C-f can give you a filtered view of just one account’s transactions. (But be careful, if you edit in the wrong place it will lose data.)

-

https://www.reddit.com/r/plaintextaccounting/comments/d69slp/how_do_you_manage_multiple_accounts_in/

-
How big is your ledger/journal file ?
-

For individual accounting, somewhere between 500-1500 transactions and 100-400 Kb of journal file per year seems typical.

-

https://www.reddit.com/r/plaintextaccounting/comments/dbjizl/how_big_is_your_ledgerjournal_file/

-
How do I do budgeting?
-

See budgeting below.

- -
-

-
-

news/discussion

-
-
-
mail lists/IRC

-
-#plaintextaccounting:matrix.org or #plaintextaccounting:libera.chat (bridged); project-specific mail lists/chats -
- -
-
-
twitter
-
-

#plaintextaccounting, #ledgercli, #hledger, #beancount, @LedgerTips

-
- -
-
-
reddit
-
-

/r/plaintextaccounting

-
- -
-
-
hacker news
-
-

stories, comments

-
- -
-
-
stack exchange
-
-

[ledger-cli] / "ledger-cli", [hledger] / "hledger"

-
-

-
-

-
- - -

software

-

-

plain text accounting apps

- - - - - - ---------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ProjectStartLast releaseCodeCommittersStarsMail list, ~sizeChat, ~size
Ledger20032021-05C++1763.9kledger 920irc 60
hledger20072021-12haskell1431.9khledger 200matrix/irc 120
Beancount20082020-06python59975beancount 380irc 20, fava gitter/matrix 40
Abandon20132019-09scala11156gitter/matrix
Transity20182019-05purescript7472gitter/matrix
Ledger in Go20132019-11go6221
cl-ledger2007common lisp466
rust_ledger20192020-09rust218
.Net Ledger20172018-08C#167gitter/matrix
goledger2019go113
monescript20172018-01javascript112
blossom2020F#112
Tackler20172021-01scala16gitter/matrix
acc2020rust11
bankroll20202020-08rust21
ledg20212021-04javascript1
pta20202020-09perl1
Prudent2018js (closed; addons)1@PrudentLedger
knut2020go1
 
Inactive:
beans20192019haskell
uledger2015python
pacioli2013python
ledger.pl2013perl
Penny20122014haskell
UMM20092010haskell
sm-Ledger2007squeak smalltalk
 
See also:
plaintextaccounting.orgmatrix/irc 90
/r/plaintextaccounting 2800
- -

Next, related add-ons and helpers by category (note: *ledger below means Ledger and hledger-style journal format):

-

data import/conversion

-
    -
  • Ledger and hledger have CSV conversion built in. Also:
    • -
  • bean-identify, bean-extract, bean-file - Beancount built-in tools
    • -
  • banks2ledger - CSV to *ledger converter
    • -
  • beancount-import web app/framework for converting various formats to beancount (python)
    • -
  • beancount-ynab You Need A Budget to beancount converter
    • -
  • buchhaltung CSV/FinTS/HBCI/OFX to *ledger conversion/deduplication (haskell)
    • -
  • csv2beancount CSV to beancount converter (clojure)
    • -
  • CSV2Ledger CSV to *ledger converter (perl)
    • -
  • fints2ledger FinTS/HBCI to csv to *ledger or beancount journals (python)
    • -
  • gcash2ledger.py GNUCash XML to *ledger converter (python)
    • -
  • gnucash-to-beancount GNUCash sqlite to beancount converter (python)
    • -
  • gnucash2ledger.py GNUCash sqlite to *ledger converter (python)
    • -
  • grisbi2Ledger Grisbi to *ledger converter
    • -
  • hledger-import-dsl alternate, programmable CSV converter for hledger
    • -
  • hledger-to-influxdb hledger to InfluxDB converter (haskell)
    • -
  • hledger2beancount hledger to beancount converter (haskell)
    • -
  • homebank2ledger HomeBank to ledger and beancount converter (perl)
    • -
  • icsvledger interactive CSV to *ledger converter (python)
    • -
  • into-ledger CSV to *ledger converter
    • -
  • jali downloader/importer to *ledger (python)
    • -
  • kmymoney2hledger KMyMoney to *ledger converter (clojure)
    • -
  • kmymoney2ledgers KMyMoney to *ledger/beancount converter (python)
    • -
  • kmymoney2ledgers.awk KMyMoney to *ledger/beancount converter (Awk)
    • -
  • Ledger in Go has limport, a CSV to *ledger converter
    • -
  • ledger-autosync OFX download, OFX to *ledger conversion, deduplication
    • -
  • ledger-guesser neural network for generating entries like past ones, can be used with ledger-autosync (javascript)
    • -
  • ledger-myexpenses MyExpenses android app sqlite db to *ledger conversion (python)
    • -
  • ledger-to-beancount yet another simple ledger to beancount converter (python)
    • -
  • ledger-tutorials convert Pete Keen's tutorials to ebook format
    • -
  • ledger2beancount.py *ledger to beancount converter
    • -
  • ledger2beancount/beancount2ledger the best converter between h/ledger and beancount formats (perl).
    • -
  • outofit QuickBooks to *ledger converter
    • -
  • piecash GNUCash SQL to *ledger converter (python)
    • -
  • plaid2qif Download transactions from plaid as QIF or CSV files
    • -
  • plaid2text Plaid API to *ledger/beancount download/conversion
    • -
  • qb2ledger QuickBooks General Journal CSV to *ledger converter
    • -
  • QIFtoLedger (Bank of America's) QIF to *ledger converter
    • -
  • reckon smart interactive/non-interactive CSV to *ledger converter
    • -
  • slc generates Ledger accounting entries, works with generic CSV files as well as the Stripe API
    • -
  • smart_importer library for building smarter CSV to beancount/Fava converters
    • -
  • total_recall CSV to *ledger converter
    • -
  • ynab-to-ledger You Need A Budget (YNAB) to *ledger converter. Handles multiple currencies, multiple number formats, reconciliation, memos, transfers, and split transactions
    • -
  • ynab_to_ledger You Need A Budget to *ledger converter
    • -
  • Costflow convert one line message to beancount/*ledger format
    • -
  • Go Ledger parser a parser and ledgerfmt, ledger2json, json2ledger tools (go)
    • -
-

data generation

-
    -
  • beancount-extract-price generate prices transactions based on your beancount ledger (python)
    • -
  • bean-price Beancount's price fetching tool (python)
    • -
  • DepreciateForLedger generate *ledger depreciation transactions (python)
    • -
  • hledger-interest generate *ledger interest entries (haskell)
    • -
  • ledger-get-prices download market prices (ruby)
    • -
  • ledgerbil schedule recurring txns, interactive reconcile, date sorting
    • -
  • LedgerScheduler move entries from one file to another when they come due (python)
    • -
  • LedgerStockUpdate update a Ledger price database (go)
    • -
  • lotter generate postings for capital gain/loss (go)
    • -
  • market-prices download market prices from several sources (python)
    • -
  • market-prices.hs small, easy to adapt script to scrape market data from the internet (Haskell)
    • -
  • pricehist fetch and format historical price data, with support for multiple sources and output formats (python)
    • -
  • recurring generate recurring *ledger entries (python)
    • -
  • reorder-journal.sh sort hledger entries, preserving directives/comments at top of file (bash)
    • -
  • sassetti adds lisp macros to ledger files (common lisp)
    • -
-

reports

-
    -
  • budget_report budget reporting with beancount (python)
    • -
  • hledger-diff report differing transactions between two journals (haskell)
    • -
  • hledger-irr calculate an account's internal rate of return (superseded by roi) (haskell)
    • -
  • hreports save custom reports and PDF templates (python)
    • -
  • ledger-plot interactive tool for making GNUplot charts from Ledger (python)
    • -
  • ledger-plots R package & script to make charts from Ledger (R)
    • -
  • ludget generate charts from Ledger (python)
    • -
  • r-ledger an R package for reading and reporting on ledger/hledger/beancount files (R)
    • -
  • TaxingLots calculates capital gains for a ledger journal (python)
    • -
-

time logging

-
    -
  • org2tc org to timeclock converter
    • -
  • on-modify.timetrack.py taskwarrior hook for timeclock output
    • -
  • t ledger timeclock shellscript
    • -
  • tim time logging/reporting tool using hledger
    • -
  • timekeeping-template time logging/reporting examples/how-to using hledger
    • -
  • tito time logging bash scripts that avoid double clock-in
    • -
-

UI, console

-
    -
  • bean-add interactive transaction entry tool (python)
    • -
  • hledger add interactive transaction entry tool (builtin command)
    • -
  • ladd create and edit a new *ledger transaction by fuzzy-matching past descriptions
    • -
  • ldgr command line tool to add/sort/tag ledger files (ruby)
    • -
  • ledger xact history-aware transaction generator (builtin command)
    • -
-

UI, curses

-
    -
  • hledger-iadd TUI for *ledger transaction entry (haskell)
    • -
  • hledger-ui TUI for *ledger browsing (haskell, video)
    • -
  • ledger-add TUI for *ledger transaction entry (python)
    • -
  • regdel TUI for browsing Ledger files (python)
    • -
-

UI, GUI

-
    -
  • ledgerble reporting GUI with charts & adjustable reports (Javascript)
    • -
  • ledgerhelpers misc. GUI tools + helper library (Python, GTK)
    • -
  • Prudent integrated journal editing/importing/reporting GUI for Ledger (Javascript, mac only, closed source)
    • -
-

UI, web

- -

UI, mobile

-
    -
  • beancount-mobile data entry app for beancount (Android, javascript)
    • -
  • cashier mobile or desktop client for ledger and hledger-web (Android/Desktop, javascript, app)
    • -
  • cone data entry app for the h/ledger format (Android, dart)
    • -
  • MoLe mobile client for hledger-web (Android, java)
    • -
-

API

-
    -
  • gledger Go package to interface with Ledger (go)
    • -
  • hledger-lib library for parsing and generating reports from *ledger files (haskell)
    • -
  • hledger-web the web app includes a JSON API server for *ledger files (haskell)
    • -
  • ledgerhelpers extends Ledger's python library (python)
    • -
  • node-hledger Node.js API for *ledger files (javascript)
    • -
- -

editor support

-

Editor plugins. Note these often work quite well for other ledger-likes, not just the one they are named for.

-
-
-
Atom
-
-

language-ledger, ledger

-
- -
-
-
Emacs
-
-

beancount-mode, hledger-mode, ledger-mode (also works for hledger, beancount etc.)

-
- -
-
-
VIM
-
-

vim-ledger (supports ledger & hledger), vim-beancount, hledger-vim

-
- -
-
-
Sublime
-
-

sublime-ledger-syntax

-
- -
-
-
TextMate
-
-

Ledger.tmbundle

-
- -
-
-
VS Code
-
-hledger-vscode, ledger, vscode-beancount -
- -
-
-
Jetbrains (IntelliJ)
-
-

Ledger Plugin

-
-

-
- -

docs

-

general accounting

- -

plain text accounting

- - - -

comparisons

- -

presentations

- -

videos

- -

articles & blog posts

-

in 2021

- -

in 2020

- -

in 2019

- -

in 2018

- -

in 2017

- -

in 2016

- -

in 2015

- -

in 2014

- -

in 2013

- -

in 2012

- -

in 2011

- -

in 2010

- -

in 2009

- -

in 2006

- -

common tasks

-

choosing accounts

- -

choosing cash vs accrual

- -

entering data

- -

importing

- -

reconciling

- -

reporting

- -

budgeting

-

The purpose of a budget is to help thy purse to fatten. It is to assist thee to have thy necessities, and insofar as attainable, thy other desires. It is to enable thee to realise thy most cherished desires, by defending them from thy casual wishes. Like a bright light in a dark cave, thy budget shows up the leaks from thy purse, and enables thee to stop them and control thy expenditures for definite and gratifying purposes. -- The Richest Man in Babylon

-

Periodic budgeting: setting per-period goals

- -

Envelope budgeting: pre-allocating funds

- -

Envelope budgeting with auto postings

- -

Envelope budgeting with auto postings, org-mode and babel

- -

More

- -

forecasting

- -

invoicing

- -

multiple currencies

- -

trip expenses

- -

shared expenses

- -

taxes

- -

time tracking

- -

inventory tracking

- -

investing

- -

non-profit accounting

- -

exporting

- -

customising

- -

API access

- -
-

-
- -
-

(c) 2016-2021 Simon Michael & contributors | Send updates via github (latest changes)

-
- -
- - - - diff --git a/plaintext-accounting-errors.html b/plaintext-accounting-errors.html deleted file mode 100644 index 60e86dc..0000000 --- a/plaintext-accounting-errors.html +++ /dev/null @@ -1,107 +0,0 @@ - - - - - - - Don’t Sink Your First Attempts at Plaintext Accounting - plaintextaccounting.org - - - - - - - - - - - - - - - - - - - - - -
- -

Don’t Sink Your First Attempts at Plaintext Accounting

-
-

I wrote the article below to help newcomers to plaintext accounting. Simon, if you think this would be useful for any of your websites, you have my permission to post it there. Enjoy! --Robert Nielsen, 2017/04/19

-
-

Plain text accounting programs such as Ledger and Hledger are powerful, helpful tools, but your own user errors can take the wind out of your sails when you would rather be breezing through your accounting. Here, then, are several mistakes—ones that I have personally tested—that you will want to avoid in order to enjoy the benefits of plaintext accounting without unnecessary pain.

-

Preliminary assumptions:

-
    -

  • You have Ledger or Hledger already installed and running on your PC, and you are ready, or have already begun, to start entering your data.

    • -

  • You understand that there are normally three lines of text for each transaction, and you know basically what’s supposed to go in each line.

    • -
-

Formatting Can Be Critical

-

The following two formatting errors will cause your work to come to a screeching halt. Here’s how to avoid them.

-

First, as you enter transactions, make sure that the second and third (and any additional) lines in a transaction are indented by at least one space. In other words, do this:

-
2017/01/15 Acme 
-  Expenses:Household   $20.00 ;roadrunner trap
-  Liabilities:CreditCard
-

Not this:

-
2017/01/15 Acme
-Expenses:Household   $20.00 ;roadrunner trap
-Liabilities:CreditCard
-

The above two transactions look very similar to the human eye, but the second one doesn’t work.

-

Another formatting issue that’s easy to miss, is that you need at least two spaces between the category ”Expenses:Household,” below) and the amount of the transaction (“$20.00”):

-
2017/01/15 Acme
-  Expenses:Household  $20.00
-  Liabilities:CreditCard
-

Contrast this with the wrong way:

-
2017/01/15 Acme
-  Expenses:Household $20.00
-  Liabilities:CreditCard
-

As it’s very hard to see the number of spaces in the critical parts, I have written them out in the two transactions below.

-

Correct:

-
2017/01/15 Acme
-  Expenses:Household[space][space]$20.00
-  Liabilities:CreditCard
-

Wrong:

-
2017/01/15 Acme
-  Expenses:Household[space]$20.00
-  Liabilities:CreditCard
-

Again, it’s easy for us humans to miss the difference between one space and two, but your plaintext accounting program will notice.

-

Use Currency Symbols Consistently

-

Here’s another error that’s easy to make and easy to overlook – omitting a currency symbol. For example:

-
2017/01/15 Acme
-  Expenses:Household   20.00
-  Liabilities:CreditCard
-

If you have been working with US dollars, it’s very easy to think that the above 20.00 refers to $20.00, but Ledger and Hledger will process this amount as something other than US dollars.

-

Using a Comma When You Need a Period

-

Another mistake to avoid is inadvertently typing a comma where a decimal in required. Let’s say, for example, that you are recording the purchase of a yacht for slightly more than $1.2 million. Here is the error:

-
2017/01/16 Mega Yacht Company
-   Expenses:Leisure   $1,245,449,72
-   Assets:Bank:Checking
-

The correct way to write this is:

-
2017/01/16 Mega Yacht Company
-   Expenses:Leisure   $1,245,449.72
-   Assets:Bank:Checking
-

If you are using Emacs, erroneously using a comma instead of a decimal point as shown above can manifest itself as a confusing error message about no transactions that need to be cleared.

-

Finally, the above examples assume you are using a numbering system that separates thousands with commas and integers from fractions with periods. There are systems that separate thousands with periods and that use commas to separate integers and fractions. From my reading of the documentation, both Ledger and Hledger can work with either system, but the point remains not to use a comma when you mean to use a period and vice versa.

-

Summary

-
    -

  • Indent the second and following lines of each transaction. The first line of the transaction needs to be flush left.

    • -

  • Use two spaces after the transaction category and before the currency symbol (assuming that you are working with currency).

    • -

  • Use the currency symbol before every amount that’s currency.

    • -

  • Don’t use a comma when you need to write a decimal point.

    • -
-

So, avoid the above mistakes and enjoy some clear sailing with plaintext accounting.

- -
- - - - diff --git a/quickref/index.html b/quickref/index.html deleted file mode 100755 index 053eb38..0000000 --- a/quickref/index.html +++ /dev/null @@ -1,1219 +0,0 @@ - - -Syntax Quick Reference for the Ledger-Likes - plaintextaccounting.org - - - - - - - - - - -
-

- -270px-Rosetta_Stone.JPG - -

-

- - -

-

- -Syntax Quick Reference for the Ledger-Likes -

-

- -Some information about the major - -Plain Text Accounting - - implementations, drawn from existing docs and informal testing, that I needed to see in one place. Currently, it compares the main journal syntax for Ledger, hledger and Beancount. For more, see the manuals and cheatsheets linked below, or - - -plaintextaccounting.org - - -. - -I hope you find it useful. -

-

- -First draft, created 2016/03, corrections to: sm on - - -#hledger - - - or - - -#ledger - - - or - - -#beancount - - -, or the - - -google doc - -

-

- - -

-

- - -Quick Reference for the Ledger-Likes - -

-

- - -Journal Format - -

-

- - -Basic example - -

-

- - -Comments - -

-

- - -Basic transactions - -

-

- - -Dates - -

-

- - -Account names - -

-

- - -Amounts - -

-

- - -More transaction features - -

-

- - -Prices - -

-

- - -Balance assertions - -

-

- - -Balance assignments - -

-

- - -Directives - -

-

- - -account, open - -

-

- - -close - -

-

- - -commodity - -

-

- - -market price - -

-

- - -

-

- -Journal Format -

-

- -Legend - -:
-Things in - -[ ] - -are - - optional.
-Syntax should be the latest preferred syntax for each implementation, may be incomplete.
-Some notes in the Ledger column are common to all.
-
- -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

- - -

-		 -

- -Ledger
- - - -http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format - - -
- - - -http://ricostacruz.com/cheatsheets/ledger.html - -

-		 -

- -hledger
- - - -https://hledger.org/hledger.html#journal-format - -

-		 -

- -Beancount
- - - -http://furius.ca/beancount/doc/syntax - - -
- - - -http://furius.ca/beancount/doc/cheatsheet - -

-

- - -

-
-
- -Basic example -
-		 -

- -; a comment
-
-2016/1/1 set opening balance
-    assets:checking       $500.00
-    equity:opening balances
-
-2016/1/5 farmer's market
-    expenses:groceries     $50.00
-    Assets:checking
-
-
-
-
-
- - -Comments, directives, and/or transactions in any order -

-		 -

- -; a comment
-
-2016/1/1 set opening balance
-    assets:checking       $500.00
-    equity:opening balances
-
-2016/1/5 farmer's market
-    expenses:groceries     $50.00
-    assets:checking -

-		 -

- -; a comment
-
-2016-01-01 open Assets:Checking
-2016-01-01 open Equity:Opening-Balances
-2016-01-01 open Expenses:Groceries
-
-2016-01-01 txn "set opening balance"
-    Assets:Checking         500.00 USD
-    Equity:Opening-Balances
-
-2016-01-05 txn "farmer's market"
-    Expenses:Groceries     50 USD
-    Assets:Checking
-
- - -All referenced accounts must have an open directive -

-
-
- -Comments -
-		 -

- -; comment
-# comment
-% comment
-| comment
-* comment and org-mode outline node
-
- - -Non-comment lines may end with a comment
-Indented comments are attached to the preceding transaction or posting -

-		 -

- -; comment
-# comment
-* comment and org-mode outline node
- -

-		 -

- -; comment
-Any unrecognised line is also a comment
-
-
-
-
- -

-
-
- -Basic transactions -
-		 -

- -DATE [[PAYEE | ] DESCRIPTION]
-    ACCOUNT    AMOUNT
-    ACCOUNT    [AMOUNT]
-
- - -A transaction contains any number of indented postings (usually two), whose amounts must sum to zero
-At least two spaces required between account and amount
-One amount may be omitted
- -

-		 -

- -DATE [DESCRIPTION]
-    ACCOUNT    AMOUNT
-    ACCOUNT    [AMOUNT]
-
- - -Same -

-

- - -

-		 -

- -DATE txn [["PAYEE"] "DESCRIPTION"]
-    ACCOUNT    AMOUNT
-    ACCOUNT    [AMOUNT]
-
- - -DESCRIPTION must be in double quotes, can be multiline
-No need for two spaces between account and amount -

-
-
- -Dates -
-		 -

- -YYYY-MM-DD
-YYYY/MM/DD
-YYYY.MM.DD
-MM-DD
-MM/DD
-MM.DD
-
- - -Other formats specified with - - --input-date-format -

-		 -

- -YYYY-MM-DD
-YYYY/MM/DD
-YYYY.MM.DD
-MM-DD
-MM/DD
-MM.DD -

-		 -

- -YYYY-MM-DD
-YYYY/MM/DD
-YYYY.MM.DD
-
-
-
-
- - -Only YYYY-MM-DD with 8 digits is officially supported -

-
-
- -Account names -
-		 -

- -TOPACCT[:SUBACCT[:...]]
-
-Revenues:Salary
-liabilities:credit card:CITI 1234
-other assets:house
-
- - -Account names begin with a letter
-May contain single spaces
-May contain subaccounts separated by : -

-		 -

- -TOPACCT[:SUBACCT[:...]]
-
-
-
-
-
- - -Same -

-		 -

- -TOPACCT[:SUBACCT[:...]]
-
-Income:Salary
-Liabilities:CreditCard:CITI-1234
-Assets:House
-
- - -Top level account must be one of Assets, Liabilities, Equity, Income, Expenses
-Each subaccount must be capitalised
-Letters, digits and hyphen are allowed (no spaces) - -  -

-
-
- -Amounts -
-		 -

- -One of
-COMMODITY QUANTITY
-QUANTITY COMMODITY
-QUANTITY
-
-10
-$10.00
-1,000.0001 USD
-10 "prepaid classes"
-
-
-
- - -COMMODITY is a symbol, word or phrase; if it contains spaces or numbers, it must be in double quotes
-It can be on the left or right, with or without a separating space
-QUANTITY is a number with 0 or more decimal places
-Decimal point is - -. - -
-Digits can be grouped into thousands by - -, - -
-Amount styles influence the standard display style for each commodity -

-

- - -

-		 -

- -One of
-COMMODITY QUANTITY
-QUANTITY COMMODITY
-QUANTITY
-
-10
-$10.00
-1,000.0001 USD
-10 "prepaid classes"
-1.000.000,01
-12,34,567.89
-
- - -Decimal point is - -. - - or - -,
- - -Digit group separator is - -, - - or - -. - -
-Any digit grouping can be used, not just thousands -

-

- - -

-		 -

- -QUANTITY COMMODITY
-
-
-
-
-10USD
-1000.0001 USD
-
-
-
-
-
- - -COMMODITY is all capital letters, on the right, and required - -
- - -Decimal point is - -. - -
-Digit group separator - -, - - is allowed and ignored -

-
-
- -More transaction - -  - -features -
-		 -

- -DATE [FLAG] [(CODE)] DESCRIPTION
-    [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL]
-    ...
-    [FLAG] ACCOUNT  [AMOUNT [PRICE] [=BAL]]
-
- - -FLAG (aka STATE) is empty, ! or * meaning uncleared, pending or cleared
-CODE is any string, in parentheses
-DESCRIPTION can be a payee name, narration, or both -

-		 -

- -DATE [FLAG] [(CODE)] DESCRIPTION
-    [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL]
-    ...
-    [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL] -

-		 -

- -DATE [txn|FLAG] [["PAYEE"] "DESCRIPTION"]
-    [FLAG] ACCOUNT       AMOUNT [PRICE]
-    ...
-    [FLAG] ACCOUNT       AMOUNT [PRICE]
-
- - -The txn keyword may be replaced by a FLAG
-For just a payee, use "PAYEE" ""
- - -  -

-
-
- -Prices -
-		 -

- -One of
-@ UNITPRICE
-@@ TOTALPRICE
-and/or one of
-{LOTUNITPRICE}
-{=FIXEDLOTUNITPRICE}
-and/or
-[LOTDATE]
-
- - -A UNITPRICE or TOTALPRICE also records a market price on this date
-A LOTDATE is written in square brackets -

-		 -

- -One of
-@ FIXEDUNITPRICE
-@@ FIXEDTOTALPRICE
-and/or
-{=FIXEDLOTUNITPRICE}
-
-
-
-
- - -These do not record market prices
-The lot price syntax is ignored -

-		 -

- -{LOTUNITPRICE[ / LOTDATE]}
-and/or one of
-@ UNITPRICE
-@@ TOTALPRICE
-
-
-
-
- - -Lot prices are remembered and form distinct commodities, other prices are not
-If there is both a lot price and a regular price, the latter records a market price -

-
-
- -Balance assertions -
-		 -

- -= AMOUNT (after posting amount & price)
-
-2016-03-10
-    Expenses:Food      $20
-    Assets:Cash       $-20 = $80
-
- - -Asserts the balance in this commodity
-in this account, excluding subaccounts
-at this point in the parse order -

-		 -

- -= AMOUNT (after posting amount & price)
-
-
-
-
-
- - -Asserts the balance in this commodity
-in this account, excluding subaccounts
-on this day. Same day events are processed in parse order -

-		 -

- -DATE balance ACCOUNT AMOUNT
-
-2014-08-09 balance Assets:Cash 562.00 USD
-2014-08-09 balance Assets:Cash 210.00 CAD
-
-
- - -Asserts the balance in this commodity
-in this account, including subaccounts
-at the start of this day -

-
-
- -Balance assignments -
-		 -

- -= AMOUNT (no preceding/inferred posting amount)
-
-2012-03-10 Adjustment
-    Assets:Cash            = $50
-    Expenses:Misc -

-

- -
- - -Sets the posting amount so as to make the balance assertion true. (The other amountless posting allows the transaction to balance) -

-		 -

- - -

-		 -

- - -

-
-

- -Directives -

-		 -

- -KEYWORD ARGS...
-    [SUBDIRECTIVES]
-
-account -

-

- -alias
-apply
-assert
-bucket
-capture
-check
-comment
-commodity
-define
-end
-expr
-fixed
-include
-P -

-

- -payee
-tag
-test
-year
-
-Timeclock directives:
-i
-o
-b
-h -

-		 -

- -KEYWORD ARGS...
-
-
-account (alias for apply)
-alias
-apply
-comment
-D
-end
-include
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- -

-		 -

- -[DATE] KEYWORD ARGS...
-    [SUBDIRECTIVES]
-
-DATE balance
-DATE close
-DATE commodity
-DATE document
-DATE event
-DATE note
-DATE open
-DATE pad
-DATE price
-DATE txn
-include
-option
-plugin
-poptag
-pushtag
-
-
-
-
-
-
- -

-
-
- -account, open -
-		 -

- -account ACCOUNT -

-

- -    [SUBDIRECTIVES]
-
-account Revenues:Salary
-account Expenses:Food:Chicken
-    note chicken food expenses
-    alias food
-    payee ^(KFC|Popeyes)$
-    check commodity == "$"
-    assert commodity == "$"
-    eval print("Hello!")
-    default
-
- - -Gives more error checking with - ---strict - - or - ---pedantic
- - -Optional subdirectives do more stuff -

-		 -

- - -

-		 -

- -DATE open ACCOUNT [COMMODITY[,...]] [METHOD]
-
-2014-05-01 open Assets:Cash USD,CAD
-
-
-
-
-
-
-
-
-
- - -Every account posted to needs an open directive with prior date -

-
-
- -close -
-		 -

- - -

-		 -

- - -

-		 -

- -DATE close ACCOUNT -

-
-
- -commodity -
-		 -

- -commodity COMMODITY
-
-commodity EUR
-commodity $
-   note American Dollars
-   format $1,000.00
-   nomarket
-   default
-
- - -Gives more error checking with - ---strict - - or - ---pedantic
- - -Optional subdirectives do more stuff -

-		 -

- - -

-		 -

- -DATE commodity COMMODITY
-    [METADATA]
-
-1867-01-01 commodity CAD
-    name: "Canadian Dollar"
-    asset-class: "cash"
-
-
-
- - -Attaches metadata to a commodity -

-
-
- -market price -
-		 -

- -P DATE TIME COMMODITY UNITPRICE
-
-P 2004/06/21 02:18:02 AAPL $32.91
-P 2004/06/21 02:18:02 AU $400.00 -

-

- -
- - -Used by -V and -X
-Also set by transaction prices -

-		 -

- -P DATE [TIME] COMMODITY UNITPRICE
-
-P 2015/8/9 GBP $1.55
-
-
- - -Used by -V
-A time is ignored -

-		 -

- -DATE price COMMODITY AMOUNT
-
-2014-07-09 price USD  1.08 CAD
-
-
- - -Also set by transaction prices -

-
-

- - -

-

- - -

-

- - -

-

- - -

-

- - -

-

- - -

-

- - -

-

- - -

-

- - -

-

- - -

-
- - diff --git a/quickref/quickref-beancount.html b/quickref/quickref-beancount.html deleted file mode 100644 index c9ac0c2..0000000 --- a/quickref/quickref-beancount.html +++ /dev/null @@ -1,142 +0,0 @@ - - - - - - - Syntax quick reference: Beancount - plaintextaccounting.org - - - - - - - - - - - - - - - - - - - - - -
- -

Beancount

-

http://furius.ca/beancount/doc/syntax
-http://furius.ca/beancount/doc/cheatsheet

-

Basic example

-
; a comment
-
-2016-01-01 open Assets:Checking
-2016-01-01 open Equity:Opening-Balances
-2016-01-01 open Expenses:Groceries
-
-2016-01-01 txn "set opening balance"
-   Assets:Checking         500.00 USD
-   Equity:Opening-Balances
-
-2016-01-05 txn "farmer's market"
-   Expenses:Groceries     50 USD
-   Assets:Checking
-

All referenced accounts must have an open directive.

-

Comments

-
; comment
-

Any unrecognised line is also a comment

-

Basic transactions

-
DATE txn [["PAYEE"] "DESCRIPTION"]
-   ACCOUNT    AMOUNT
-   ACCOUNT    [AMOUNT]
-

DESCRIPTION must be in double quotes, can be multiline. No need for two spaces between account and amount.

-

Dates

-
YYYY-MM-DD
-YYYY/MM/DD
-YYYY.MM.DD
-

Only YYYY-MM-DD with 8 digits is officially supported.

-

Account names

-
TOPACCT[:SUBACCT[:...]]
-
-Income:Salary
-Liabilities:CreditCard:CITI-1234
-Assets:House
-

Top level account must be one of Assets, Liabilities, Equity, Income, Expenses. Each subaccount must be capitalised. Letters, digits and hyphen are allowed (no spaces).

-

Amounts

-
QUANTITY COMMODITY
-
-10USD
-1000.0001 USD
-

COMMODITY is all capital letters, on the right, and required . Decimal point is . (period). Digit group separator , (comma) is allowed and ignored.

-

More transaction features

-
DATE [txn|FLAG] [["PAYEE"] "DESCRIPTION"]
-   [FLAG] ACCOUNT       AMOUNT [PRICE]
-   ...
-   [FLAG] ACCOUNT       AMOUNT [PRICE]
-

The txn keyword may be replaced by a FLAG. For just a payee, use "PAYEE" "".

-

Prices

-

{LOTUNITPRICE[ / LOTDATE]} and/or one of @ UNITPRICE, @@ TOTALPRICE.

-

Lot prices are remembered and form distinct commodities, other prices are not. If there is both a lot price and a regular price, the latter records a market price.

-

Balance assertions

-
DATE balance ACCOUNT AMOUNT
-
-2014-08-09 balance Assets:Cash 562.00 USD
-2014-08-09 balance Assets:Cash 210.00 CAD
-

Asserts the balance in this commodity, in this account, including subaccounts, at the start of this day.

-

Balance assignments

-

Directives

-
[DATE] KEYWORD ARGS...
-   [SUBDIRECTIVES]
-
-DATE balance
-DATE close
-DATE commodity
-DATE document
-DATE event
-DATE note
-DATE open
-DATE pad
-DATE price
-DATE txn
-include
-option
-plugin
-poptag
-pushtag
-

account, open

-
DATE open ACCOUNT [COMMODITY[,...]] [METHOD]
-
-2014-05-01 open Assets:Cash USD,CAD
-

Every account posted to needs an open directive with prior date.

-

close

-
DATE close ACCOUNT
-

commodity

-
DATE commodity COMMODITY
-   [METADATA]
-
-1867-01-01 commodity CAD
-   name: "Canadian Dollar"
-   asset-class: "cash"
-

Attaches metadata to a commodity.

-

market price

-
DATE price COMMODITY AMOUNT
-
-2014-07-09 price USD  1.08 CAD
-

Also set by transaction prices.

- -
- - - - diff --git a/quickref/quickref-hledger.html b/quickref/quickref-hledger.html deleted file mode 100644 index 52af7f2..0000000 --- a/quickref/quickref-hledger.html +++ /dev/null @@ -1,117 +0,0 @@ - - - - - - - Syntax quick reference: hledger - plaintextaccounting.org - - - - - - - - - - - - - - - - - - - - - -
- -

hledger

-

http://hledger.org/journal.html

-

Basic example

-
; a comment
-
-2016/1/1 set opening balance
-   assets:checking       $500.00
-   equity:opening balances
-
-2016/1/5 farmer's market
-   expenses:groceries     $50.00
-   assets:checking
-

Comments

-
; comment
-# comment
-* comment and org-mode outline node
-

Basic transactions

-
DATE [DESCRIPTION]
-   ACCOUNT    AMOUNT
-   ACCOUNT    [AMOUNT]
-

Non-comment lines may end with a comment. Indented comments are attached to the preceding transaction or posting.

-

Dates

-
YYYY-MM-DD
-YYYY/MM/DD
-YYYY.MM.DD
-MM-DD
-MM/DD
-MM.DD
-

Account names

-
TOPACCT[:SUBACCT[:...]]
-
-Revenues:Salary
-liabilities:credit card:CITI 1234
-other assets:house
-

Account names begin with a letter. May contain single spaces. May contain subaccounts separated by : (colon).

-

Amounts

-

One of COMMODITY QUANTITY, QUANTITY COMMODITY, QUANTITY.

-
10
-$10.00
-1,000.0001 USD
-10 "prepaid classes"
-1.000.000,01
-12,34,567.89
-

Decimal point is . or , (period or comma). Digit group separator is , or . (the one not used for decimal point). Any digit grouping can be used, not just thousands.

-

More transaction features

-
DATE [FLAG] [(CODE)] DESCRIPTION
-   [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL]
-   ...
-   [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL]
-

Prices

-

One of @ FIXEDUNITPRICE @@ FIXEDTOTALPRICE and/or {=FIXEDLOTUNITPRICE}.

-

These do not record market prices. The lot price syntax is ignored.

-

Balance assertions

-

= AMOUNT after posting amount & price.

-

Asserts the balance in this commodity, in this account, excluding subaccounts, on this day. Same day events are processed in parse order.

-

Balance assignments

-

Directives

-
KEYWORD ARGS...
-
-account (alias for apply)
-alias
-apply
-comment
-D
-end
-include
-

account, open

-

close

-

commodity

-

market price

-
P DATE [TIME] COMMODITY UNITPRICE
-
-P 2015/8/9 GBP $1.55
-

Used by -V. A time is ignored.

- -
- - - - diff --git a/quickref/quickref-ledger.html b/quickref/quickref-ledger.html deleted file mode 100644 index 633c5e8..0000000 --- a/quickref/quickref-ledger.html +++ /dev/null @@ -1,174 +0,0 @@ - - - - - - - Syntax quick reference: Ledger - plaintextaccounting.org - - - - - - - - - - - - - - - - - - - - - -
- -

Ledger

-

https://www.ledger-cli.org/3.0/doc/ledger3.html#Journal-Format
-http://ricostacruz.com/cheatsheets/ledger.html

-

Basic example

-
; a comment
-
-2016/1/1 set opening balance
-   assets:checking       $500.00
-   equity:opening balances
-
-2016/1/5 farmer's market
-   expenses:groceries     $50.00
-   Assets:checking
-

Comments, directives, and/or transactions in any order.

-

Comments

-
; comment
-# comment
-% comment
-| comment
-* comment and org-mode outline node
-

Non-comment lines may end with a comment. Indented comments are attached to the preceding transaction or posting.

-

Basic transactions

-
DATE [DESCRIPTION]
-   ACCOUNT    AMOUNT
-   ACCOUNT    [AMOUNT]
-

A transaction contains any number of indented postings (usually two), whose amounts must sum to zero. At least two spaces required between account and amount. One amount may be omitted.

-

Dates

-
YYYY-MM-DD
-YYYY/MM/DD
-YYYY.MM.DD
-MM-DD
-MM/DD
-MM.DD
-

Other formats allowed if specified with --input-date-format.

-

Account names

-
TOPACCT[:SUBACCT[:...]]
-
-Revenues:Salary
-liabilities:credit card:CITI 1234
-other assets:house
-

Account names begin with a letter. May contain single spaces. May contain subaccounts separated by : (colon).

-

Amounts

-

One of COMMODITY QUANTITY, QUANTITY COMMODITY, QUANTITY.

-
10
-$10.00
-1,000.0001 USD
-10 "prepaid classes"
-

COMMODITY is a symbol, word or phrase; if it contains spaces or numbers, it must be in double quotes. It can be on the left or right, with or without a separating space. QUANTITY is a number with 0 or more decimal places. Decimal point is . (period). Digits can be grouped into thousands by , (comma). Amount styles influence the standard display style for each commodity.

-

More transaction features

-
DATE [FLAG] [(CODE)] DESCRIPTION
-   [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL]
-   ...
-   [FLAG] ACCOUNT  [AMOUNT [PRICE] [=BAL]]
-

FLAG (aka STATE) is empty, ! or * meaning uncleared, pending or cleared CODE is any string, in parentheses DESCRIPTION can be a payee name, narration, or both

-

Prices

-

One of @ UNITPRICE, @@ TOTALPRICE and/or one of {LOTUNITPRICE}, {=FIXEDLOTUNITPRICE} and/or [LOTDATE].

-

A UNITPRICE or TOTALPRICE also records a market price on this date. A LOTDATE is written in square brackets.

-

Balance assertions

-

= AMOUNT after posting amount & price.

-
2016-03-10
-   Expenses:Food      $20
-   Assets:Cash       $-20 = $80
-

Asserts the balance in this commodity, in this account, excluding subaccounts, at this point in the parse order.

-

Balance assignments

-

= AMOUNT with no preceding/inferred posting amount.

-
2012-03-10 Adjustment
-   Assets:Cash            = $50
-   Expenses:Misc
-

Sets the posting amount so as to make the balance assertion true. (The other amountless posting allows the transaction to balance).

-

Directives

-
KEYWORD ARGS...
-   [SUBDIRECTIVES]
-
-account 
-
-alias
-apply
-assert
-bucket
-capture
-check
-comment
-commodity
-define
-end
-expr
-fixed
-include
-P 
-
-payee
-tag
-test
-year
-
-Timeclock directives:
-i
-o
-b
-h
-

account, open

-
account ACCOUNT 
-   [SUBDIRECTIVES]
-
-account Revenues:Salary
-account Expenses:Food:Chicken
-   note chicken food expenses
-   alias food
-   payee ^(KFC|Popeyes)$
-   check commodity == "$"
-   assert commodity == "$"
-   eval print("Hello!")
-   default
-

Gives more error checking with --strict or --pedantic. Optional subdirectives do more stuff.

-

close

-

commodity

-
commodity COMMODITY
-
-commodity EUR
-commodity $
-  note American Dollars
-  format $1,000.00
-  nomarket
-  default
-

Gives more error checking with --strict or --pedantic. Optional subdirectives do more stuff.

-

market price

-
P DATE TIME COMMODITY UNITPRICE
-
-P 2004/06/21 02:18:02 AAPL $32.91
-P 2004/06/21 02:18:02 AU $400.00
-

Used by -V and -X. Also set by transaction prices.

- -
- - - -