From d3ef6df75ac825f415609cc4d6bef1eadcbf29f7 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Tue, 8 Mar 2022 14:12:31 -1000 Subject: [PATCH] doc: README cleanup Updates inspired by some feedback from README reviewer Lars Wirzenius. ("I like that the README starts with an explanation of what the project is all about. I like that the README is short and to the point. I like that the license is stated explicitly. I feel that the README doesn't really present the whole plain text accounting concept very well, though. I realize that linked home page goes into that much more, but it might be worth add a short example of a ledger input file, and a sample output, to the README.") --- README.md | 168 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 123 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 02e508f7d..35445d48e 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,130 @@ -# hledger project README +# hledger +## Robust, intuitive plain text accounting +[![license](https://img.shields.io/badge/license-GPLv3+-brightgreen.svg)](https://www.gnu.org/licenses/gpl.html) +[![on hackage](https://img.shields.io/hackage/v/hledger.svg?label=hackage&colorB=green)](https://hackage.haskell.org/package/hledger) +[![](https://repology.org/badge/version-for-repo/stackage_lts/hledger.svg)](https://repology.org/metapackage/hledger) +[![](https://repology.org/badge/version-for-repo/stackage_nighly/hledger.svg)](https://repology.org/metapackage/hledger) +[![github issues](https://img.shields.io/github/issues/simonmichael/hledger.svg)](http://bugs.hledger.org) -## lightweight, portable, dependable accounting tools +Welcome! This a brief intro to hledger. For a more detailed version, see the home page: **** -hledger is a computer program for easily tracking money, time, or other commodities, -on unix, mac and windows (and web-capable mobile devices, to some extent). - -It is first a command-line tool, but there are also terminal and -web interfaces, and a Haskell library for building your own -programs and scripts (hledger is written in Haskell). hledger was -inspired by and is largely compatible with Ledger. hledger is free -software available under the GNU General Public License v3+. +hledger is lightweight, cross platform, multi-currency, double-entry accounting software. +It lets you track money, investments, cryptocurrencies, invoices, time, inventory and more, +in a safe, future-proof plain text data format with full version control and privacy. hledger aims to help both computer experts and regular folks -to gain clarity and control in their finances and time management, -but currently it is a bit more suited to techies. -I use it every day to: +gain clarity in their finances and time management. +Though the UIs are basic, hledger can model any accounting situation and provide precise, clear reports. +It is reliable, quick, and backed by the highly supportive [Plain Text Accounting](https://plaintextaccounting.org) ecosystem. +Using it is an excellent way to learn double entry accounting. -- track spending and income -- see time reports by day/week/month/project -- get accurate numbers for client billing and tax filing -- track invoices +Compared to [other PTA apps](https://plaintextaccounting.org/#software), +hledger is actively maintained, with regular releases, +and a strong focus on being easy to use and practical for everyday accounting. -Though limited in features, hledger is lightweight, usable and reliable. -For some, it is a simpler, less distracting, more future-proof alternative to Quicken or GnuCash. +More features: +- Installs easily on unix, mac or windows +- Complete, built-in documentation in multiple formats, beginner videos, tutorials etc. +- Multiple UIs: command-line, terminal, web, mobile, editors/IDEs +- Good at importing and exporting CSV; also outputs text/HTML/JSON/SQL +- A robust, general, well-specified multi-currency accounting engine +- Fast, analysing 25k transactions per second on a macbook air m1 +- Accurate to 255 decimal places +- Supports your preferred account names, currencies, number formats +- Inspired by and partly compatible with Ledger CLI; interconvertible with Beancount +- Scriptable by CLI, HTTP or API, with plenty of examples +- Clean Haskell codebase, continually improved since 2007, with $100 regression bounties +- Free software licensed under GPLv3+. -For more, see the home page: **** +## Examples -## Sponsorship +I use hledger to: +- track income and spending, sometimes with budgets +- see time reports by day/week/month/project +- track reimbursables, invoices and payments +- predict cashflow and account balances +- get accurate numbers for tax filing +- research past events -Your support, large or small, helps keep this project strong!\ -See also ****. +Here's an example of the journal file format: +```journal +2022-01-01 opening balances as of this date + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances - +2022-01-15 market + expenses:food $50 + assets:cash $-50 -Sponsor Simon (project leader): +2022-02-01 GOODWORKS CORP + assets:bank:checking $1000 + income:salary $-1000 +``` +and some simple reports: +```cli +$ hledger bs +Balance Sheet 2022-02-15 + + || 2022-02-15 +========================++============ + Assets || +------------------------++------------ + assets:bank:checking || $2000 + assets:bank:savings || $2000 + assets:cash || $50 +------------------------++------------ + || $4050 +========================++============ + Liabilities || +------------------------++------------ + liabilities:creditcard || $50 +------------------------++------------ + || $50 +========================++============ + Net: || $4000 +``` +```cli +$ hledger is --monthly +Income Statement 2022-01-01..2022-02-28 + + || Jan Feb +===============++============= + Revenues || +---------------++------------- + income:salary || 0 $1000 +---------------++------------- + || 0 $1000 +===============++============= + Expenses || +---------------++------------- + expenses:food || $50 0 +---------------++------------- + || $50 0 +===============++============= + Net: || $-50 $1000 +``` + +More examples: + +## Sponsors + +hledger is brought to you by [Simon Michael](http://joyful.com) +and [140+ contributors](CREDITS.html). +After enjoying some personal or organisational success with hledger, +you might want to become one of the generous sponsors helping to sustain this work. +(More info: ) + + + +### Sponsor Simon (project leader) [![github](https://img.shields.io/badge/Sponsor_on-Github-limegreen "Sponsor the project leader via Github")](https://github.com/sponsors/simonmichael) [![liberapay](https://img.shields.io/badge/Sponsor_on-Liberapay-limegreen "Sponsor the project leader via Liberapay")](https://liberapay.com/simonmichael) [![paypal](https://www.paypal.com/en_US/i/btn/x-click-but04.gif "Give one time or recurringly via Paypal")](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY) -Sponsor the hledger project as an organisation: +### Organisations sponsoring hledger [![OpenCollective](https://opencollective.com/hledger/sponsors/badge.svg)][oc contributors] \ [![](https://opencollective.com/hledger/sponsor/0/avatar.svg)](https://opencollective.com/hledger/sponsor/0/website) [![](https://opencollective.com/hledger/sponsor/1/avatar.svg)](https://opencollective.com/hledger/sponsor/1/website) @@ -51,7 +137,7 @@ Sponsor the hledger project as an organisation: [![](https://opencollective.com/hledger/sponsor/8/avatar.svg)](https://opencollective.com/hledger/sponsor/8/website) [![](https://opencollective.com/hledger/sponsor/9/avatar.svg)](https://opencollective.com/hledger/sponsor/9/website) -Sponsor the hledger project as an individual: +### Individuals sponsoring hledger [![OpenCollective](https://opencollective.com/hledger/backers/badge.svg)][oc contributors] \ [![](https://opencollective.com/hledger/backer/0/avatar.svg)](https://opencollective.com/hledger/backer/0/website) [![](https://opencollective.com/hledger/backer/1/avatar.svg)](https://opencollective.com/hledger/backer/1/website) @@ -74,26 +160,18 @@ Sponsor the hledger project as an individual: [![](https://opencollective.com/hledger/backer/18/avatar.svg)](https://opencollective.com/hledger/backer/18/website) [![](https://opencollective.com/hledger/backer/19/avatar.svg)](https://opencollective.com/hledger/backer/19/website) [![](https://opencollective.com/hledger/backer/20/avatar.svg)](https://opencollective.com/hledger/backer/20/website) +[![](https://opencollective.com/hledger/backer/21/avatar.svg)](https://opencollective.com/hledger/backer/21/website) +[![](https://opencollective.com/hledger/backer/22/avatar.svg)](https://opencollective.com/hledger/backer/22/website) +[![](https://opencollective.com/hledger/backer/23/avatar.svg)](https://opencollective.com/hledger/backer/23/website) +[![](https://opencollective.com/hledger/backer/24/avatar.svg)](https://opencollective.com/hledger/backer/24/website) +[![](https://opencollective.com/hledger/backer/25/avatar.svg)](https://opencollective.com/hledger/backer/25/website) +[![](https://opencollective.com/hledger/backer/26/avatar.svg)](https://opencollective.com/hledger/backer/26/website) +[![](https://opencollective.com/hledger/backer/27/avatar.svg)](https://opencollective.com/hledger/backer/27/website) +[![](https://opencollective.com/hledger/backer/28/avatar.svg)](https://opencollective.com/hledger/backer/28/website) +[![](https://opencollective.com/hledger/backer/29/avatar.svg)](https://opencollective.com/hledger/backer/29/website) -Bounties for specific tasks: +### Sponsor specific tasks [![all bounties](https://img.shields.io/badge/github-All_bountied_issues-30bae8 "all bountied issues, bountysource and otherwise")](https://github.com/simonmichael/hledger/issues?q=label:bounty) [![bountysource bounties](https://api.bountysource.com/badge/team?team_id=75979&style=bounties_received "issues bountied via bountysource")](https://www.bountysource.com/teams/hledger) - -
-
-
- -[![license](https://img.shields.io/badge/license-GPLv3+-brightgreen.svg)](http://www.gnu.org/licenses/gpl.html) -[![hledger CI](https://github.com/simonmichael/hledger/workflows/hledger%20CI/badge.svg)](https://github.com/simonmichael/hledger/actions) -[![on hackage](https://img.shields.io/hackage/v/hledger.svg?label=hackage&colorB=green)](http://hackage.haskell.org/package/hledger) -[![](https://img.shields.io/hackage-deps/v/hledger-lib.svg?label=hledger-lib+bounds)](http://packdeps.haskellers.com/feed?needle=hledger-lib) -[![](https://img.shields.io/hackage-deps/v/hledger.svg?label=hledger+bounds)](http://packdeps.haskellers.com/feed?needle=hledger) -[![](https://img.shields.io/hackage-deps/v/hledger-ui.svg?label=hledger-ui+bounds)](http://packdeps.haskellers.com/feed?needle=hledger-ui) -[![](https://img.shields.io/hackage-deps/v/hledger-web.svg?label=hledger-web+bounds)](http://packdeps.haskellers.com/feed?needle=hledger-web) -[![](https://repology.org/badge/version-for-repo/stackage_lts/hledger.svg)](https://repology.org/metapackage/hledger) -[![](https://repology.org/badge/version-for-repo/stackage_nighly/hledger.svg)](https://repology.org/metapackage/hledger) -[![github issues](https://img.shields.io/github/issues/simonmichael/hledger.svg)](http://bugs.hledger.org) - - [oc contributors]: https://opencollective.com/hledger#section-contributors