hledger-forecast 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c025630ee2a5d379fcf9e27509c1c5cc5438e5b0a38fcc73c3277fab8e1a6e2e
-  data.tar.gz: 6d50f7774dbf3331328b9126392bad45aba281b00b4e93eb9060671b982560f6
+  metadata.gz: 33ae1c8b9a296f2420b87963e12ccc77a6a4b18cb5e9e977ed6e17f3d83b3c03
+  data.tar.gz: f4a4e1fa8df7a5d982036349903ce6a38b68edc59f2734be1ebc12a071ebf27f
 SHA512:
-  metadata.gz: 7a21eca09d0f5145a54e4acff809090179cc48e9aa060ed6117c5ef2d17f578aab93b6779396254c3ff0437ff29ecffecf92546622f0dc2f9d12ee61e2794dbd
-  data.tar.gz: 43509f84789f5dc0700924e22d3137eb4f07a11ee4cbbecef291770c4bdb2bbf83ef63c4aaecc7a87c0a4b77bc5ff29d578dc0e231cf68db85e76fc00f187ec7
+  metadata.gz: 1942ba18912517ceb70a6f2e4639632f5bccb6c98945d88509405c046e41c59631bebb099f15c89cc630ebca270360d5efd2c9eaea9fe7449eeb9be2fc5d9dee
+  data.tar.gz: d717115be6e73cf7277f29e01d4f465a63f1e03c88271a16ecd9df20600430b0d7483dc5f9a4c1831796a71413fb8bb2df9adb9f9dd5b3fd4c583c7e3e79a5fa

data/.github/workflows/{test.yml → ci.yml}

@@ -1,29 +1,37 @@
-name: Test
+name: Continuous Integration
 
 on:
-  pull_request:
-    branches: [main]
   push:
-    branches: [main]
+    branches:
+      - main
+  pull_request: ~
 
 jobs:
-  test:
+  tests:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.0', '3.1', '3.2']
+        ruby-version: ['3.3', '3.4']
 
     steps:
       - uses: actions/checkout@v4
-      - name: Update packages
+
+      - name: Update packages 📦️
         run: sudo apt-get update
-      - name: Install packages
+
+      - name: Install packages 📦️
         run: sudo apt-get -y install hledger
-      - name: Set up Ruby
+
+      - name: Set up Ruby env 💎️
         uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
           ruby-version: ${{ matrix.ruby-version }}
-      - name: Run tests
+
+      - name: Run tests 🧪
         run: |
           bundle exec rspec
+
+      - name: Build gem 💎️
+        run: gem build *.gemspec
+

data/.github/workflows/publish_ruby_gem.yml

@@ -0,0 +1,24 @@
+name: Publish Ruby Gem
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Publish Gem 💎️
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push *.gem
+        env:
+          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.github/workflows/release.yml

@@ -1,22 +1,21 @@
 name: Release
 
 on:
-  release:
-    types: [published]
+  push:
+    branches:
+      - main
 
 jobs:
   release:
     runs-on: ubuntu-latest
 
+    permissions:
+      contents: write
+      pull-requests: write
+
     steps:
-      - uses: actions/checkout@v4
-      - name: publish gem
-        run: |
-          mkdir -p $HOME/.gem
-          touch $HOME/.gem/credentials
-          chmod 0600 $HOME/.gem/credentials
-          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-          gem build *.gemspec
-          gem push *.gem
-        env:
-          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"
+      - name: Release 📦
+        uses: googleapis/release-please-action@v4
+        with:
+          release-type: ruby
+

data/.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = '3.4'

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [3.0.0](https://github.com/olimorris/hledger-forecast/compare/v2.0.1...v3.0.0) (2026-03-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* plugin rewrite and removal of tracking ([#9](https://github.com/olimorris/hledger-forecast/issues/9))
+
+### Features
+
+* add tag support ([#12](https://github.com/olimorris/hledger-forecast/issues/12)) ([2c341aa](https://github.com/olimorris/hledger-forecast/commit/2c341aa1270699d4bdd13431d5a1a7301169b7a0))
+
+
+### Code Refactoring
+
+* plugin rewrite and removal of tracking ([#9](https://github.com/olimorris/hledger-forecast/issues/9)) ([1fadce6](https://github.com/olimorris/hledger-forecast/commit/1fadce6c1db34a93f5700997fb39800e4716c967))

data/Gemfile

@@ -2,6 +2,7 @@
 
 source "https://rubygems.org"
 
+gem 'bigdecimal'
 gem 'colorize'
 gem 'money'
 gem 'terminal-table'

data/README.md

@@ -5,25 +5,48 @@
 <h1 align="center">hledger-forecast</h1>
 
 <p align="center">
-<a href="https://github.com/olimorris/hledger-forecast/stargazers"><img src="https://img.shields.io/github/stars/olimorris/hledger-forecast?color=c678dd&logoColor=e06c75&style=for-the-badge"></a>
-<a href="https://github.com/olimorris/hledger-forecast/issues"><img src="https://img.shields.io/github/issues/olimorris/hledger-forecast?color=%23d19a66&style=for-the-badge"></a>
-<a href="https://github.com/olimorris/hledger-forecast/blob/main/LICENSE"><img src="https://img.shields.io/github/license/olimorris/hledger-forecast?color=%2361afef&style=for-the-badge"></a>
-<a href="https://github.com/olimorris/hledger-forecast/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/olimorris/hledger-forecast/test.yml?branch=main&label=tests&style=for-the-badge"></a>
+<a href="https://github.com/olimorris/hledger-forecast/stargazers"><img src="https://img.shields.io/github/stars/olimorris/hledger-forecast?style=for-the-badge"></a>
+<a href="https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/olimorris/hledger-forecast/ci.yml?branch=main&label=tests&style=for-the-badge"></a>
+<a href="https://github.com/olimorris/hledger-forecast/releases"><img src="https://img.shields.io/github/v/release/olimorris/hledger-forecast?style=for-the-badge"</a>
 </p>
-
 **"Improved", you say?** Using a _CSV_ file, forecasts can be quickly generated into a _journal_ file ready to be fed into [hledger](https://github.com/simonmichael/hledger). **A 16 line [CSV file](https://github.com/olimorris/hledger-forecast/blob/main/example.csv) can generate a 46 line hledger [forecast file](https://github.com/olimorris/hledger-forecast/blob/main/example.journal)!**
 
-Forecasts can also be constrained between dates, inflated by modifiers, tracked until they appear in your bank statements and summarized into your own daily/weekly/monthly/yearly personal forecast income and expenditure statement.
-
 ## :sparkles: Features
 
-- :rocket: Uses a simple CSV file to generate forecasts which can be used with hledger
-- :calendar: Can smartly track forecasts against your bank statement
-- :dollar: Can automatically apply modifiers such as inflation/deflation to forecasts
-- :mag: Enables the use of maths in your forecasts (for amounts and dates)
-- :bar_chart: Display your forecasts as income and expenditure reports (e.g. daily, weekly, monthly)
-- :twisted_rightwards_arrows: Compare and display the difference between hledger outputs
-- :computer: Simple and easy to use CLI
+- :rocket: Simple CSV file drives the whole forecast
+- :mag: Supports maths in your amounts _and_ dates
+- :label: Apply tags to your transactions​
+- :bar_chart: Summarize forecasts as daily/weekly/monthly/yearly income and expenditure reports
+- :twisted_rightwards_arrows: Compare and highlight the difference between two hledger CSV outputs
+- :computer: Straightforward CLI
+
+## :brain: The problem statement
+
+Forecasting is essential to how I plan and budget with hledger. It enables me to know my financial position in 1 month, 10 months or even 100 months from now.
+
+But forecasting in hledger is verbose and unintelligent. Consider this scenario: you purchase a new $3,000 laptop on a 0% finance deal and spread it over 20 months. In hledger, this would be accounted for with:
+
+```ledger
+~ monthly from 2026-01-01 to 2027-08-31  * New Laptop
+    Expenses:General Expenses           $150.00
+    Assets:Checking
+```
+
+Except, you'd need to work out what 20 months from `2026-01-01` is and do $3000 \div 20$.
+
+In `hledger-forecast`, you add a single line to your CSV:
+
+```csv
+monthly,,Assets:Checking,01/01/2026,=20,New Laptop,Expenses:General Expenses,=3000/20,,,
+```
+
+The tool calculates the amount and the end date for you.
+
+Now the natural next question: _what does that $150/month do to your monthly surplus_? With `hledger-forecast`, that's one command:
+
+    hledger-forecast summarize -f forecast.csv -r monthly
+
+You get an [income statement](https://en.wikipedia.org/wiki/Income_statement) in your terminal  - income, expenses, totals, and savings rate.
 
 ## :camera_flash: Screenshots
 
@@ -31,194 +54,201 @@ Forecasts can also be constrained between dates, inflated by modifiers, tracked
 
 <img src="https://github.com/olimorris/hledger-forecast/assets/9512444/430503b5-f447-4972-b122-b48f8628aff9" alt="hledger-Forecast" />
 
-**The ouput from the `summarize` command**
+**The output from the `summarize` command**
 
 <img src="https://github.com/olimorris/hledger-forecast/assets/9512444/f5017ea2-9606-46ec-8b38-8840dc175e7b" alt="Summarize command" />
 
 ## :package: Installation
 
-Assuming you have Ruby and [Rubygems](http://rubygems.org/pages/download) installed on your system, simply run:
+Assuming you have Ruby and [RubyGems](http://rubygems.org/pages/download) installed:
 
-    gem install --user hledger-forecast
+    gem install hledger-forecast
 
 ## :rocket: Usage
 
-Run:
-
     hledger-forecast
-
-The available options are:
-
+    
     Usage: hledger-forecast [command] [options]
-
+    
     Commands:
-      generate    Generate a forecast from a file
+      generate    Generate a forecast from a CSV file
       summarize   Summarize the forecast file and output to the terminal
       compare     Compare and highlight the differences between two CSV files
-
+    
     Options:
         -h, --help                       Show this help message
         -v, --version                    Show version
 
-### Generate command
+### Generate
 
-The `hledger-forecast generate` command will generate a forecast _from_ a `CSV` file _to_ a journal file. You can see the output of this command in the [example.journal](https://github.com/olimorris/hledger-forecast/blob/main/example.journal) file.
-
-The available options are:
+Reads your CSV file and creates a journal file ready to use with hledger. See [example.journal](https://github.com/olimorris/hledger-forecast/blob/main/example.journal) for an example of the output.
 
+    hledger-forecast generate -f my_forecast.csv -o forecast.journal
+    
     Usage: hledger-forecast generate [options]
-
+    
       -f, --forecast FILE              The path to the FORECAST CSV file to generate from
       -o, --output-file FILE           The path to the OUTPUT file to create
-      -t, --transaction FILE           The path to the TRANSACTION journal file
+      -t, --tags TAGS                  Only include transactions with given tags (comma-separated)
       -v, --verbose                    Don't group transactions by type in the output file
           --force                      Force an overwrite of the output file
-          --no-track                   Don't track any transactions
       -h, --help                       Show this help message
 
-> **Note**: For the tracking of transactions you need to include the `-t` flag
-
-Running the command with no options will assume a `forecast.csv` file exists.
+Running with no options assumes a `forecast.csv` file exists in the current directory.
 
 ### Using with hledger
 
-To work with hledger, include the forecast file and use the `--forecast` flag:
+Include the generated journal file and use hledger's `--forecast` flag:
 
-    hledger -f bank_transactions.journal -f forecast.journal --forecast bal assets -e 2024-02
+    hledger -f bank_transactions.journal -f forecast.journal --forecast bal assets -e 2027-02
 
-The command will generate a forecast up to the end of Feb 2024, showing the balance for any asset accounts, overlaying some bank transactions with the forecast journal file. Forecasting in hledger can be complicated so be sure to refer to the [documentation](https://hledger.org/dev/hledger.html) or start a [discussion](https://github.com/olimorris/hledger-forecast/discussions/new?category=q-a).
+This will generate a forecast up to the end of Feb 2027, showing asset balances with your bank transactions overlaid. Forecasting in hledger has some nuance, so please refer to the [hledger docs](https://hledger.org/dev/hledger.html) or open a [discussion](https://github.com/olimorris/hledger-forecast/discussions/new?category=q-a) if you get stuck.
 
-If you use the `hledger-ui` tool, it may be helpful to use the `--verbose` flag. This ensures that transactions are not grouped together in the forecast journal file, making descriptions much easier to read.
+> **Tip:** If you use `hledger-ui`, the `--verbose` flag is worth using. It keeps each transaction as its own entry in the journal, making descriptions much easier to read in the UI.
 
-### Summarize command
+### Summarize
 
-As your forecast file grows, it can be helpful to sum up the total amounts and output them to the CLI. Think of this command as your own _profit and loss_ summarizer, generating a statement over a period you specify.
+As your forecast grows, it's useful to see the totals at a glance. Think of this as your income statement, rolled up to whatever period makes sense.
 
     hledger-forecast summarize -f my_forecast.csv
-
-The available options are:
-
+    
     Usage: hledger-forecast summarize [options]
+    
+      -f, --forecast FILE              The path to the FORECAST CSV file to summarize
+      -r, --roll-up PERIOD             The period to roll-up your forecasts into. One of:
+                                       [yearly], [half-yearly], [quarterly], [monthly], [weekly], [daily]
+      -t, --tags TAGS                  Only include transactions with given tags (comma-separated)
+      -v, --verbose                    Show additional information in the summary
+      -h, --help                       Show this help message
 
-    -f, --forecast FILE              The path to the FORECAST CSV file to summarize
-    -r, --roll-up PERIOD             The period to roll-up your forecasts into. One of:
-                                     [yearly], [half-yearly], [quarterly], [monthly], [weekly], [daily]
-    -v, --verbose                    Show additional information in the summary
-    -h, --help                       Show this help message
+### Compare
 
-### Compare command
+A core part of managing personal finances is comparing what you _expected_ to happen with what _actually_ happened. The `compare` command makes this easy:
 
-A core part of managing your personal finances is the comparison of what you _expected_ to happen versus what _actually_ happened. This can be challenging to accomplish with hledger so to make this easier, the app has a useful `compare` command:
+    hledger-forecast compare path/to/expected.csv path/to/actual.csv
 
-    hledger-forecast compare [path/to/file1.csv] [path/to/file2.csv]
+To generate CSV output from hledger, append `-O csv > output.csv` to any hledger command.
 
-To generate CSV output with hledger, append `-O csv > output.csv` to your desired command.
+For wide output, pipe through a pager like [most](https://en.wikipedia.org/wiki/Most_(Unix)):
 
-To make it easier to read horizontal output in the terminal, consider the use of a terminal pager like [most](https://en.wikipedia.org/wiki/Most_(Unix)) by appending `| most` to the compare command.
+    hledger-forecast compare file1.csv file2.csv | most
 
-> **Note:** The two CSV files being compared must have the same structure
+> **Note:** The two CSV files must have the same structure.
 
 ## :gear: Creating your forecast
 
-The app makes it easy to generate a comprehensive _journal_ file with very few lines of code, making it much easier to stay on top of your forecasting from month to month.
-
 ### Columns
 
-The _CSV_ file _should_ contain a header row with the following columns:
-
-- `type` - (string) - The type of forecast entry. One of `monthly`, `quarterly`, `half-yearly`, `yearly`, `once` or `custom`
-- `frequency` - (string) - The frequency that the type repeats with (only if `custom`). As per hledger's [periodic rule syntax](https://hledger.org/dev/hledger.html#periodic-transactions)
-- `account` - (string) - The account the transaction applies to e.g. _Expenses:Food_
-- `from` - (date) - The date the transaction should start from e.g. _2023-06-01_
-- `to` - (date) _(optional)_ - The date the transaction should end on e.g. _2023-12-31_
-- `description` - (string) - A description of the transaction
-- `category` - (string) - The classification or category of the transaction
-- `amount` - (integer/float) - The amount of the transaction
-- `roll-up` - (integer/float) _(optional)_ - For use with the summarizer, the value you need to multiply the amount by to get it into a yearly amount
-- `summary_exclude` - (boolean) _(optional)_ - Exclude the transaction from the summarizer?
-- `track` - (boolean) _(optional)_ - Track the transaction against your confirmed transactions?
+The CSV file should have a header row with these columns:
 
-### Example forecast
+| Column | Type | Required | Description |
+|---|---|---|---|
+| `type` | string | yes | One of: `monthly`, `quarterly`, `half-yearly`, `yearly`, `once`, `custom` |
+| `frequency` | string | `custom` only | Repeating frequency, using hledger's [periodic rule syntax](https://hledger.org/dev/hledger.html#periodic-transactions) |
+| `account` | string | yes | The account the transaction applies to, e.g. `Assets:Bank` |
+| `from` | date | yes | Start date, e.g. `01/03/2023` |
+| `to` | date | no | End date, e.g. `01/01/2025` |
+| `description` | string | yes | A description of the transaction |
+| `category` | string | yes | The category account, e.g. `Expenses:Food` |
+| `amount` | number | yes | The transaction amount. Supports `=` prefix for calculated values |
+| `roll-up` | number | no | Multiplier for the summarizer — use this for `custom` types to annualise them |
+| `summary_exclude` | boolean | no | Set to `TRUE` to exclude from the summarizer |
+| `tag` | string | no | Pipe-separated tags, e.g. `fixed|essential`. Outputs as native hledger tags |
 
-Putting it together, we end up with a CSV file like:
+### Example
 
 ```csv
-type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
-monthly,,Assets:Bank,01/03/2023,,Salary,Income:Salary,-3500,,,
-monthly,,Assets:Bank,01/03/2023,01/01/2025,Mortgage,Expenses:Mortgage,2000,,,
-monthly,,Assets:Bank,01/03/2023,,Bills,Expenses:Bills,175,,,
-monthly,,Assets:Bank,01/03/2023,,Food,Expenses:Food,500,,,
-monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,,
-monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,,
-monthly,,Assets:Bank,01/03/2023,01/03/2025,Rainy day fund,Assets:Savings,300,,,
-monthly,,Assets:Pension,01/01/2024,,Pension draw down,Income:Pension,-500,,,
-quarterly,,Assets:Bank,01/04/2023,,Quarterly bonus,Income:Bonus,-1000,,,
-half-yearly,,Assets:Bank,01/04/2023,,Top up holiday funds,Expenses:Holiday,500,,,
-yearly,,Assets:Bank,01/04/2023,,Annual bonus,Income:Bonus,-2000,,,
-once,,Assets:Bank,05/03/2023,,Refund for that damn laptop,Expenses:Shopping,-3000,,TRUE,TRUE
-custom,every 2 weeks,Assets:Bank,01/03/2023,,Hair and beauty,Expenses:Personal Care,80,26,,
-custom,every 5 weeks,Assets:Bank,01/03/2023,,Misc expenses,Expenses:General Expenses,30,10.4,,
+type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,tag
+monthly,,Assets:Bank,01/03/2023,,Salary,Income:Salary,-3500,,,fixed|essential
+monthly,,Assets:Bank,01/03/2023,01/01/2025,Mortgage,Expenses:Mortgage,2000,,,fixed|essential
+monthly,,Assets:Bank,01/03/2023,,Bills,Expenses:Bills,175,,,fixed|essential
+monthly,,Assets:Bank,01/03/2023,,Food,Expenses:Food,500,,,living|essential
+monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,,living
+monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,,living
+monthly,,Assets:Bank,01/03/2023,01/03/2025,Rainy day fund,Assets:Savings,300,,,saving
+monthly,,Assets:Pension,01/01/2024,,Pension draw down,Income:Pension,-500,,,fixed|essential
+quarterly,,Assets:Bank,01/04/2023,,Quarterly bonus,Income:Bonus,-1000,,,fixed
+half-yearly,,Assets:Bank,01/04/2023,,Top up holiday funds,Expenses:Holiday,500,,,living
+yearly,,Assets:Bank,01/04/2023,,Annual bonus,Income:Bonus,-2000,,,fixed
+once,,Assets:Bank,05/03/2023,,Refund for that damn laptop,Expenses:Shopping,-3000,TRUE,
+custom,every 2 weeks,Assets:Bank,01/03/2023,,Hair and beauty,Expenses:Personal Care,80,26,,living
+custom,every 5 weeks,Assets:Bank,01/03/2023,,Misc expenses,Expenses:General Expenses,30,10.4,,living
 settings,currency,USD,,,,,,,,
 ```
 
-### Additional features
+### Calculated amounts
+
+Prefix any `amount` with `=` and write it as a standard formula — the app will evaluate it for you. Great for spreading a lump sum across months:
 
-From the example above, there are a few additional features that may be useful.
+```csv
+monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,
+```
 
-#### Calculated amounts
+> Calculations are evaluated to two decimal places.
 
-> **Note**: Calculations will be determined up to two decimal places
+### Calculated dates
 
-It may be helpful to let the app calculate the forecasted amount in your transactions on your behalf. This can be especially useful if you're spreading a payment out over a number of months:
+The `to` column also supports calculated values. Use `=` followed by a number to mean "N months from the `from` date":
 
 ```csv
-type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
-monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,,
+monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,
 ```
 
-Simply start the `amount` column with a `=` sign and use standard Excel based math formatting.
+That sets the end date to 12 months after `01/03/2023`.
 
-#### Calculated dates
+### Tags
 
-It may also be helpful for `to` dates to be calculated:
+Add a `tag` column to your CSV to tag transactions. Tags are output as native [hledger tags](https://hledger.org/tags-tutorial.html), making them queryable in hledger itself. Multiple tags are separated by pipes (`|`):
 
 ```csv
-type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
-monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,,
+type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,tag
+monthly,,Assets:Bank,01/03/2023,,Salary,Income:Salary,-3500,,,fixed|essential
+monthly,,Assets:Bank,01/03/2023,,Food,Expenses:Food,500,,,living|essential
+monthly,,Assets:Bank,01/03/2023,,Netflix,Expenses:Subscriptions,15,,,living
 ```
 
-### Settings
-
-There are also additional settings that can be applied in the forecast. The defaults are:
+This generates journal entries with proper hledger tags on each posting:
 
-```csv
-type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
-settings,currency,USD,,,,,,,,
-settings,show_symbol,true,,,,,,,,
-settings,thousands_separator,true,,,,,,,,
+```
+~ monthly from 2023-03-01  * Salary, Food, Netflix
+    Income:Salary             £-3,500.00;  fixed:, essential:
+    Expenses:Food             £500.00   ;  living:, essential:
+    Expenses:Subscriptions    £15.00    ;  living:
+    Assets:Bank
 ```
 
-### Tracking
+**Filtering by tags** - both `generate` and `summarize` accept a `--tags` flag to include only transactions matching any of the given tags:
 
-> **Note**: Marking a transaction for tracking will ensure that it is only written into the forecast if it isn't found within a specified transaction file
+```bash
+# Generate a journal with only your fixed costs
+hledger-forecast generate -f forecast.csv -o fixed.journal --tags=fixed
 
-Sometimes it can be useful to track and monitor forecasted transactions to ensure that they are accounted for in any financial projections. If they are present, then these should be discarded from your forecast as this will create a double count against your actuals. However, if they can't be found then they should be carried forward into a future period to ensure accurate recording.
+# Summarize only essential spending
+hledger-forecast summarize -f forecast.csv --tags=essential
 
-To mark transactions as available for tracking you may use the `track` option in your config file:
+# Multiple tags use OR logic — matches any
+hledger-forecast summarize -f forecast.csv --tags=fixed,living
+```
 
-```csv
-type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
-once,,Assets:Bank,2023-03-05,,Refund for that damn laptop,Expenses:Shopping,-3000,,,TRUE
+**Querying in hledger** - because the tags are native hledger format, you can query them directly:
+
+```bash
+hledger bal tag:fixed -f forecast.journal
+hledger bal tag:essential not:tag:living -f forecast.journal
 ```
 
-> **Note**: This feature has been designed to work with `once` transaction types only
+### Settings
 
-To use this feature, ensure you pass a filepath to the `-t` flag, such as:
+Settings rows live in the same CSV file. The defaults are:
 
-    hledger-forecast generate -t [journal_file_to_search] -f [path_to_yaml_file] -o [path_to_output_journal]
+```csv
+settings,currency,USD,,,,,,,,
+settings,show_symbol,true,,,,,,,,
+settings,thousands_separator,true,,,,,,,,
+```
 
-The app will use a hledger query to determine if the combination of category and amount is present in the periods between the `from` key and the current date in the journal file you've specified. If not, then the app will include it as a forecast transaction in the output file.
+Override any of them by adding a `settings` row. Multiple settings rows are fine — they won't clobber each other.
 
 ## :pencil2: Contributing
 
-I am open to any pull requests that fix bugs but would ask that any new functionality is discussed before it could be accepted.
+I'm open to pull requests that fix bugs. For new functionality, please open a discussion first so we can figure out whether it's the right direction before any code is written.

data/example.csv

@@ -1,16 +1,16 @@
-type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,track
-monthly,,Assets:Bank,01/03/2023,,Salary,Income:Salary,-3500,,,
-monthly,,Assets:Bank,01/03/2023,01/01/2025,Mortgage,Expenses:Mortgage,2000,,,
-monthly,,Assets:Bank,01/03/2023,,Bills,Expenses:Bills,175,,,
-monthly,,Assets:Bank,01/03/2023,,Food,Expenses:Food,500,,,
-monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,,
-monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,,
-monthly,,Assets:Bank,01/03/2023,01/03/2025,Rainy day fund,Assets:Savings,300,,,
-monthly,,Assets:Pension,01/01/2024,,Pension draw down,Income:Pension,-500,,,
-quarterly,,Assets:Bank,01/04/2023,,Quarterly bonus,Income:Bonus,-1000,,,
-half-yearly,,Assets:Bank,01/04/2023,,Top up holiday funds,Expenses:Holiday,500,,,
-yearly,,Assets:Bank,01/04/2023,,Annual bonus,Income:Bonus,-2000,,,
-once,,Assets:Bank,05/03/2023,,Refund for that damn laptop,Expenses:Shopping,-3000,,TRUE,TRUE
-custom,every 2 weeks,Assets:Bank,01/03/2023,,Hair and beauty,Expenses:Personal Care,80,26,,
-custom,every 5 weeks,Assets:Bank,01/03/2023,,Misc expenses,Expenses:General Expenses,30,10.4,,
+type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude,tag
+monthly,,Assets:Bank,01/03/2023,,Salary,Income:Salary,-3500,,,fixed|essential
+monthly,,Assets:Bank,01/03/2023,01/01/2025,Mortgage,Expenses:Mortgage,2000,,,fixed|essential
+monthly,,Assets:Bank,01/03/2023,,Bills,Expenses:Bills,175,,,fixed|essential
+monthly,,Assets:Bank,01/03/2023,,Food,Expenses:Food,500,,,living|essential
+monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,,living
+monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,,living
+monthly,,Assets:Bank,01/03/2023,01/03/2025,Rainy day fund,Assets:Savings,300,,,saving
+monthly,,Assets:Pension,01/01/2024,,Pension draw down,Income:Pension,-500,,,fixed|essential
+quarterly,,Assets:Bank,01/04/2023,,Quarterly bonus,Income:Bonus,-1000,,,fixed
+half-yearly,,Assets:Bank,01/04/2023,,Top up holiday funds,Expenses:Holiday,500,,,living
+yearly,,Assets:Bank,01/04/2023,,Annual bonus,Income:Bonus,-2000,,,fixed
+once,,Assets:Bank,05/03/2023,,Refund for that damn laptop,Expenses:Shopping,-3000,TRUE,
+custom,every 2 weeks,Assets:Bank,01/03/2023,,Hair and beauty,Expenses:Personal Care,80,26,,living
+custom,every 5 weeks,Assets:Bank,01/03/2023,,Misc expenses,Expenses:General Expenses,30,10.4,,living
 settings,currency,USD,,,,,,,,

data/example.journal

@@ -1,47 +1,46 @@
 ~ monthly from 2023-03-01  * Salary, Bills, Food, New Kitchen
-    Income:Salary                $-3,500.00   ;  Salary
-    Expenses:Bills               $175.00      ;  Bills
-    Expenses:Food                $500.00      ;  Food
-    Expenses:House               $208.33      ;  New Kitchen
+    Income:Salary                $-3,500.00;  fixed:, essential:
+    Expenses:Bills               $175.00   ;  fixed:, essential:
+    Expenses:Food                $500.00   ;  living:, essential:
+    Expenses:House               $208.33   ;  living:
     Assets:Bank
 
 ~ monthly from 2023-03-01 to 2025-01-01  * Mortgage
-    Expenses:Mortgage            $2,000.00    ;  Mortgage
+    Expenses:Mortgage            $2,000.00 ;  fixed:, essential:
     Assets:Bank
 
 ~ monthly from 2023-03-01 to 2024-02-29  * Holiday
-    Expenses:Holiday             $125.00      ;  Holiday
+    Expenses:Holiday             $125.00   ;  living:
     Assets:Bank
 
 ~ monthly from 2023-03-01 to 2025-03-01  * Rainy day fund
-    Assets:Savings               $300.00      ;  Rainy day fund
+    Assets:Savings               $300.00   ;  saving:
     Assets:Bank
 
 ~ monthly from 2024-01-01  * Pension draw down
-    Income:Pension               $-500.00     ;  Pension draw down
+    Income:Pension               $-500.00  ;  fixed:, essential:
     Assets:Pension
 
 ~ every 3 months from 2023-04-01  * Quarterly bonus
-    Income:Bonus                 $-1,000.00   ;  Quarterly bonus
+    Income:Bonus                 $-1,000.00;  fixed:
     Assets:Bank
 
 ~ every 6 months from 2023-04-01  * Top up holiday funds
-    Expenses:Holiday             $500.00      ;  Top up holiday funds
+    Expenses:Holiday             $500.00   ;  living:
     Assets:Bank
 
 ~ yearly from 2023-04-01  * Annual bonus
-    Income:Bonus                 $-2,000.00   ;  Annual bonus
+    Income:Bonus                 $-2,000.00;  fixed:
     Assets:Bank
 
-~ every 2 weeks from 2023-03-01  * Hair and beauty
-    Expenses:Personal Care       $80.00       ;  Hair and beauty
+~ 2023-03-05  * Refund for that damn laptop
+    Expenses:Shopping            $-3,000.00
     Assets:Bank
 
-~ every 5 weeks from 2023-03-01  * Misc expenses
-    Expenses:General Expenses    $30.00       ;  Misc expenses
+~ every 2 weeks from 2023-03-01  * Hair and beauty
+    Expenses:Personal Care       $80.00    ;  living:
     Assets:Bank
 
-~ 2024-01-01  * [TRACKED] Refund for that damn laptop
-    Expenses:Shopping            $-3,000.00;  Refund for that damn laptop
+~ every 5 weeks from 2023-03-01  * Misc expenses
+    Expenses:General Expenses    $30.00    ;  living:
     Assets:Bank
-