https://github.com/woodruffw/pledger
A small personal expense ledger.
https://github.com/woodruffw/pledger
Last synced: 7 months ago
JSON representation
A small personal expense ledger.
- Host: GitHub
- URL: https://github.com/woodruffw/pledger
- Owner: woodruffw
- License: other
- Archived: true
- Created: 2020-03-14T20:55:35.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-07-08T03:30:34.000Z (about 1 year ago)
- Last Synced: 2025-02-20T01:06:53.422Z (8 months ago)
- Language: Rust
- Homepage: https://crates.io/crates/pledger
- Size: 446 KB
- Stars: 6
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
pledger
=======
[](https://github.com/woodruffw/pledger/actions/workflows/ci.yml)
> [!WARNING]
>
> This project has been archived and is not being actively maintained.
A small personal expense ledger.
All `pledger` does is track monthly expenses.
## Installation
`pledger` is a single command-line program. You can install it using `cargo`:
```bash
cargo install pledger
```
Or by building it locally:
```bash
git clone https://github.com/woodruffw/pledger && cd pledger
cargo build
```
## Usage
`pledger` takes only one input: a directory where monthly ledgers are stored:
```bash
pledger expenses/
```
Alternatively, you can use `PLEDGER_DIR` to pass the directory:
```bash
PLEDGER_DIR=expenses/ pledger
```
Ledgers are stored as structured text files with the filename `YYYY-MM.ledger`. Read about the `pledger`
format [below](#ledger-format).
For example, here's a listing for a directory with three months of expenses:
```bash
$ ls expenses/
2018-02.ledger
2020-01.ledger
2020-02.ledger
```
`pledger` ignores files that don't match the `YYYY-MM.ledger` format.
By default, `pledger` reports expenses for the current month.
To run `pledger` on a previous date, use `pledger -d ` or `pledger -l`:
```bash
# do a report on january 2017
pledger -d 2017-01 expenses/
# the month name or single number is also enough for the current year
# do a report on april, then march
pledger -d april expenses/
pledger -d 3 expenses
# -l/--last is a shortcut for last month's ledger
pledger -l expenses/
```
`pledger` can also generate a report for all records with `pledger --all`, or for a specific year
with `pledger --year YEAR`.
By default, pledger outputs a plain text report. You can use the `--json` flag to output JSON
instead, for consumption by other tools:
```bash
pledger --json expenses/ > monthly.json
```
## Ledger format
`pledger`'s ledgers are plain text files, with one entry per line. Debits begin with `D`,
credits with `C`, and the rest of the format is mostly self-explanatory:
```
C 130.00 #bonus
D 8.00 burger and fries #weekday #lunch
D 27.00 saturday drinks #weekend #alcohol
D 20,000.12 new car #essential
```
Everything after the currency amount is the _comment_. The _comment_ can include _tags_, which
begin with `#` and can be alphanumeric + symbolic. `pledger` uses your tags to provide expense
summaries; duplicate tags in a comment are removed.
Empty lines or lines that begin with `#` are ignored.