{"id":18005571,"url":"https://github.com/eikek/org-expenses","last_synced_at":"2025-04-04T10:43:15.321Z","repository":{"id":20959376,"uuid":"24248067","full_name":"eikek/org-expenses","owner":"eikek","description":"track expenses with org","archived":false,"fork":false,"pushed_at":"2016-06-12T12:41:03.000Z","size":135,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-02-09T20:45:22.981Z","etag":null,"topics":["emacs-lisp","expense-tracker","org-mode"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eikek.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-19T22:55:47.000Z","updated_at":"2024-07-23T23:50:02.000Z","dependencies_parsed_at":"2022-07-23T15:32:20.445Z","dependency_job_id":null,"html_url":"https://github.com/eikek/org-expenses","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eikek%2Forg-expenses","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eikek%2Forg-expenses/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eikek%2Forg-expenses/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eikek%2Forg-expenses/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eikek","download_url":"https://codeload.github.com/eikek/org-expenses/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247166094,"owners_count":20894652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emacs-lisp","expense-tracker","org-mode"],"created_at":"2024-10-30T00:20:18.482Z","updated_at":"2025-04-04T10:43:15.302Z","avatar_url":"https://github.com/eikek.png","language":"Emacs Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"* org-expenses.el\n\nTracking expenses in [[http://orgmode.org][org]] files works very well. The org capture\nmechanism can be used to quickly insert them. This library provides\nutility functions to generate basic statistics from expense lists.\n\nIt assumes the following conventions:\n\n- expense items are headings, to be able to apply tags and\n- properties where one is a currency code - price pair\n- a ~:date:~ property or a date string somewhere undere the headline\n  (not really required, but used to search expenses by date)\n\nAn expense item is a headline that complies to those points. Expense\nitems can have one category, which is by default the name of the\nparent headline. This can be overriden by the ~CATEGORY~ property.\n\nThe date of the expense item is either given by the ~:date:~ property\nor the first date that is found underneath the headline.\n\nThe following example shows two expense items that are organized below\na \"food\" headline, which serves as their default category. The second\nitem overrides this category to \"restaurant\".\n\n#+begin_example\n* food\n** groceries\n   :PROPERTIES:\n   :usd:   25.49\n   :date:  [2014-08-14 Do]\n   :END:\n** pizza\n   :PROPERTIES:\n   :usd:       18.99\n   :date:      [2014-08-25 Mo]\n   :CATEGORY:  restaurant\n   :END:\n#+end_example\n\nAll those items are gathered from some org files and tables are\ngenerated to show an overview of the data.\n\nThe standard overview for the last example would look like this:\n\n#+begin_example\n#+TITLE: Expenses [2014-08-14 Do] - [2014-08-25 Mo]\n#+STARTUP: showeverything\n\nSearch: ~(:date \"2014-08\")~\nShowing *2* items\n\n* Overview\n** Summary\n| Curr. |   sum |   max |   min | count |   avg |\n|-------+-------+-------+-------+-------+-------|\n| USD   | 44.48 | 25.49 | 18.99 |     2 | 22.24 |\n\n\n** Categories\n|                |   sum |   max |   min | count |   avg |\n|----------------+-------+-------+-------+-------+-------|\n| restaurant USD | 18.99 | 18.99 | 18.99 |     1 | 18.99 |\n| food USD       | 25.49 | 25.49 | 25.49 |     1 | 25.49 |\n\n\n** Monthly\n|             |   sum |   max |   min | count |   avg |\n|-------------+-------+-------+-------+-------+-------|\n| 2014/08 USD | 44.48 | 25.49 | 18.99 |     2 | 22.24 |\n\n\n* Items\n| item      | category   | date            |   USD |\n|-----------+------------+-----------------+-------|\n| pizza     | restaurant | [2014-08-25 Mo] | 18.99 |\n| groceries | food       | [2014-08-14 Do] | 25.49 |\n#+end_example\n\n\n** Installation\n\nClone this repository and add it to emacs load path. Then ~require~\nthe file:\n\n#+begin_src emacs-lisp :tangle yes\n  (require 'org-expenses)\n#+end_src\n\n** Configuration\n\nIf you have files with expense items, you can set them in your init\nfile. Either specify a list of files or just a string which then\nshould be a directory containing org files. All of them are\nconsidered.\n\n#+begin_src emacs-lisp :tangle yes\n  (setq org-expenses/files \"~/org/expenses\")\n#+end_src\n\nThen it might be convenient to assign a key to the\n~org-expenses/expense-view~ function. It shows the summary to those\nfiles.\n\nSince these files can grow quickly but usually don't change often,\nthere is a cache mechanism provided. It uses [[https://sqlite.org/][sqlite3]] and stores\nexpense items in a database file. If a file changes, it is simply\nre-added. You can set the sqlite3 executable if it differs from\n~/usr/bin/sqlite3~. Then you must provide a file location for the\ndatabase file, otherwise the cache is disabled.\n\n#+begin_src emacs-lisp :tangle yes\n  (setq org-expenses/sqlite-cmd \"/usr/local/bin/sqlite3\")\n  (setq org-expenses/sqlite-db-file \"~/.expenses.db\")\n#+end_src\n\nAs described above, only headlines with a currency-price property are\nconsidered. The list ~org-expenses/currency-list~ names all known\ncurrencies.\n\n** Expense View Mode\n\nThe function ~org-expense/expense-view~ reads the org files and\ndisplays a buffer with summary information of the expenses. It is set\nto \"epxense-view-mode\" that is org mode but with a custom keymap that\nmakes more sense for this buffer:\n\n| Key    | Binding                                          |\n|--------+--------------------------------------------------|\n| RET    | org-expenses/expense-view-jump-to-entry          |\n| C-n    | org-expenses/expense-view-move-next              |\n| C-p    | org-expenses/expense-view-move-prev              |\n| C-t    | org-expenses/expense-view-toggle-table           |\n| +      | org-expenses/expense-view-widen-date             |\n| -      | org-expenses/expense-view-narrow-date            |\n| .      | org-expenses/expense-view-goto-this-month        |\n| /      | org-expenses/expense-view-search-item            |\n| C      | org-expenses/expense-view-search-remove-category |\n| F      | org-expenses/expense-view-toggle-follow-entries  |\n| T      | org-expenses/expense-view-search-remove-tag      |\n| b      | org-expenses/expense-view-prev-date              |\n| c      | org-expenses/expense-view-search-add-category    |\n| d      | org-expenses/expense-view-search-date            |\n| f      | org-expenses/expense-view-next-date              |\n| g      | org-expenses/expense-view-update-view            |\n| l      | org-expenses/expense-view-last-search            |\n| n      | org-expenses/expense-view-move-next              |\n| p      | org-expenses/expense-view-move-prev              |\n| q      | org-expenses/expense-view-quit-window            |\n| t      | org-expenses/expense-view-search-add-tag         |\n| v      | org-expenses/expense-view-focus-item             |\n| \u003cdown\u003e | org-expenses/expense-view-move-next              |\n| \u003cup\u003e   | org-expenses/expense-view-move-prev              |\n|--------+--------------------------------------------------|\n\nIf this function is invoked with one prefix argument, it will clear\nthe sqlite db first (if it is used). With two prefix arguments the\nexpense view is generated for the current buffer (which must be in org\nmode).\n\nThis buffer is divided in two parts: the first shows a list of tables\nwith summary information, and the second is the item table. Both can\nbe configured a little. The variable ~org-expenses/overview-table~ is\nbound to an alist with headline - function pairs. Each function is\nexpected to take a result list and return a summary table to\ndisplay. The headline and table is inserted into the buffer. And\n~org-expenses/item-columns~ is a list containing property keys of an\nexpense item that are used as columns. It defaults to\n~(:item :category :date)~.\n\nSelecting expense items in the view is done via a plist that contains\n4 things: a date range (key ~:date~), an item name (key ~:item~), a\ntag list (key ~:tags~) and a category list (key ~:category~). A date\nrange can be an org date range like ~[2014-05-10]--[2014-05-20]~ or an\nabbreviated one like ~2014-05~. The latter is the short version for\n~[2014-05-01]--[2014-05-31]~. And likewise, ~2014~ is short for\n~[2014-01-01]--[2014-12-31]~. Items must match to all given\ncriteria. Tags and categories can be included by specifying them and\nexecluded by prefixing the names with a ~-~. Item names are substring\nmatches. For example ~(:date 2014-08 :tags (\"-train\" \"journey\"))~\nwould find all items from august 2014 that are tagged with \"journey\"\nbut not with \"train\".\n\n** Other interactive things\n\nThere are two functions\n\n- ~org-expense/insert-item-table~ that asks for a search plist and\n  inserts a table with all matching items\n- ~org-expense/insert-summary-table~ same as above but inserting a\n  summary table of the result. If a grouping function is specified,\n  the result is grouped first. There are some predefined\n  ~org-expenses/group-by…~ functions that can be used.\n\n\n** License\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either version 3, or (at your option)\nany later version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feikek%2Forg-expenses","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feikek%2Forg-expenses","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feikek%2Forg-expenses/lists"}