{"id":13677317,"url":"https://github.com/narendraj9/hledger-mode","last_synced_at":"2025-04-29T11:30:27.376Z","repository":{"id":11813054,"uuid":"67365046","full_name":"narendraj9/hledger-mode","owner":"narendraj9","description":"An Emacs major mode for Hledger","archived":false,"fork":false,"pushed_at":"2024-04-15T18:12:16.000Z","size":4801,"stargazers_count":219,"open_issues_count":8,"forks_count":22,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-02T13:17:14.937Z","etag":null,"topics":["accounting","emacs","hledger","hledger-mode","ledger"],"latest_commit_sha":null,"homepage":null,"language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/narendraj9.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-04T19:48:09.000Z","updated_at":"2024-07-21T06:10:34.000Z","dependencies_parsed_at":"2023-01-11T20:17:08.177Z","dependency_job_id":"704ffce4-90fd-45d5-be55-3c0b10c338a6","html_url":"https://github.com/narendraj9/hledger-mode","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/narendraj9%2Fhledger-mode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narendraj9%2Fhledger-mode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narendraj9%2Fhledger-mode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narendraj9%2Fhledger-mode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/narendraj9","download_url":"https://codeload.github.com/narendraj9/hledger-mode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224163521,"owners_count":17266515,"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":["accounting","emacs","hledger","hledger-mode","ledger"],"created_at":"2024-08-02T13:00:40.381Z","updated_at":"2024-11-11T19:31:28.637Z","avatar_url":"https://github.com/narendraj9.png","language":"Emacs Lisp","funding_links":[],"categories":["Text Editor Tools","Emacs Lisp"],"sub_categories":[],"readme":"# hledger-mode\n\n[![MELPA](https://melpa.org/packages/hledger-mode-badge.svg)](https://melpa.org/#/hledger-mode)\n\nAn Emacs major mode for writing [hledger](https://hledger.org/) journals and\ngenerating useful accounting reports.\n\n![Sample Reports](_assets/new_demo.gif?raw=true \"Reports\")\n\n## Installation\n\nThe external `hledger` program should be installed first, or most of the report\nfeatures won't work.\n\nThis package is available on [MELPA](http://melpa.org/):\n\n    M-x package-install hledger-mode\n\nIf you are not installing from Melpa, to make `hledger-mode` available\nto your Emacs add it to `load-path`.\n\n    (add-to-list 'load-path \"/path/to/hledger-mode/dir/\")\n\n## Setup\n\n```elisp\n;;; Basic configuration\n(require 'hledger-mode)\n\n;; To open files with .journal extension in hledger-mode\n(add-to-list 'auto-mode-alist '(\"\\\\.journal\\\\'\" . hledger-mode))\n\n;; Provide the path to you journal file.\n;; The default location is too opinionated.\n(setq hledger-jfile \"/path/to/your/journal-file.journal\")\n\n;;; Auto-completion for account names\n;; For company-mode users,\n(add-to-list 'company-backends 'hledger-company)\n\n;; For auto-complete users,\n(add-to-list 'ac-modes 'hledger-mode)\n(add-hook 'hledger-mode-hook\n    (lambda ()\n        (setq-local ac-sources '(hledger-ac-source))))\n\n;; For easily adjusting dates.\n(define-key hledger-mode-map (kbd \"\u003ckp-add\u003e\") 'hledger-increment-entry-date)\n(define-key hledger-mode-map (kbd \"\u003ckp-subtract\u003e\") 'hledger-decrement-entry-date)\n```\n\n## Configuration\n\nFor configuring various parameters, e.g. the accounts used for\ncomputing ratios in the overall report, `M-x customize-group` and\ncustomize the `hledger` group. For example, the Emergency Fund Ratio\nis computed with expenses incurred in accounts listed in the variable\n`hledger-ratios-essential-expense-accounts`.\n\n## Usage\n\nI recommend the following key bindings:\n\n```elisp\n\n;; Personal Accounting\n(global-set-key (kbd \"C-c e\") 'hledger-jentry)\n(global-set-key (kbd \"C-c j\") 'hledger-run-command)\n\n```\n\nOnce you are in a report buffer after executing a command with\n`hledger-run-command`, press `h` to see the list of reports that you\ncan have a look at. Press `s` in the overall report to see the meaning\nof the personal finance ratios for your report.\n\nTo enable email reporting, you would need to setup your email api\ncredentials. You can set those up with `M-x customize-group hledger`.\n\nOnce you have done so, you can enable monthly email reporting on\n`hledger-reporting-day` with the following in your `init.el`:\n\n```elisp\n\n(hledger-enable-reporting)\n\n```\n\nHere is my configuration with `use-package' declarations:\n\n``` elisp\n(use-package hledger-mode\n  :pin manual\n  :after htmlize\n  :load-path \"packages/rest/hledger-mode/\"\n  :mode (\"\\\\.journal\\\\'\" \"\\\\.hledger\\\\'\")\n  :commands hledger-enable-reporting\n  :preface\n  (defun hledger/next-entry ()\n    \"Move to next entry and pulse.\"\n    (interactive)\n    (hledger-next-or-new-entry)\n    (hledger-pulse-momentary-current-entry))\n\n  (defface hledger-warning-face\n    '((((background dark))\n       :background \"Red\" :foreground \"White\")\n      (((background light))\n       :background \"Red\" :foreground \"White\")\n      (t :inverse-video t))\n    \"Face for warning\"\n    :group 'hledger)\n\n  (defun hledger/prev-entry ()\n    \"Move to last entry and pulse.\"\n    (interactive)\n    (hledger-backward-entry)\n    (hledger-pulse-momentary-current-entry))\n\n  :bind ((\"C-c j\" . hledger-run-command)\n         :map hledger-mode-map\n         (\"C-c e\" . hledger-jentry)\n         (\"M-p\" . hledger/prev-entry)\n         (\"M-n\" . hledger/next-entry))\n  :init\n  (setq hledger-jfile\n        (expand-file-name \"~/miscellany/personal/finance/accounting.journal\")\n        hledger-email-secrets-file (expand-file-name \"secrets.el\"\n                                                     emacs-assets-directory))\n  ;; Expanded account balances in the overall monthly report are\n  ;; mostly noise for me and do not convey any meaningful information.\n  (setq hledger-show-expanded-report nil)\n\n  (when (boundp 'my-hledger-service-fetch-url)\n    (setq hledger-service-fetch-url\n          my-hledger-service-fetch-url))\n\n  :config\n  (add-hook 'hledger-view-mode-hook #'hl-line-mode)\n  (add-hook 'hledger-view-mode-hook #'center-text-for-reading)\n\n  (add-hook 'hledger-view-mode-hook\n            (lambda ()\n              (run-with-timer 1\n                              nil\n                              (lambda ()\n                                (when (equal hledger-last-run-command\n                                             \"balancesheet\")\n                                  ;; highlight frequently changing accounts\n                                  (highlight-regexp \"^.*\\\\(savings\\\\|cash\\\\).*$\")\n                                  (highlight-regexp \"^.*credit-card.*$\"\n                                                    'hledger-warning-face))))))\n\n  (add-hook 'hledger-mode-hook\n            (lambda ()\n              (make-local-variable 'company-backends)\n              (add-to-list 'company-backends 'hledger-company))))\n\n(use-package hledger-input\n  :pin manual\n  :load-path \"packages/rest/hledger-mode/\"\n  :bind ((\"C-c e\" . hledger-capture)\n         :map hledger-input-mode-map\n         (\"C-c C-b\" . popup-balance-at-point))\n  :preface\n  (defun popup-balance-at-point ()\n    \"Show balance for account at point in a popup.\"\n    (interactive)\n    (if-let ((account (thing-at-point 'hledger-account)))\n        (message (hledger-shell-command-to-string (format \" balance -N %s \"\n                                                          account)))\n      (message \"No account at point\")))\n\n  :config\n  (setq hledger-input-buffer-height 20)\n  (add-hook 'hledger-input-post-commit-hook #'hledger-show-new-balances)\n  (add-hook 'hledger-input-mode-hook #'auto-fill-mode)\n  (add-hook 'hledger-input-mode-hook\n            (lambda ()\n              (make-local-variable 'company-idle-delay)\n              (setq-local company-idle-delay 0.1))))\n```\n\n## Auxiliary tools\n\nYou are welcome to use the web application hosted\nat [vicarie.in](https://services.vicarie.in) for logging data while\nyou are away from computer. You can use the command\n`hledger-fetch-entries` later on to get those entries into your\njournal file.\n\nIf you want real-time checking of your journal, you might want to\ninstall\n[flycheck-hledger](https://github.com/DamienCassou/flycheck-hledger/):\n\n![flycheck-hledger](_assets/flycheck-hledger.png?raw=true \"flycheck-hledger\")\n\n## Testing\n\n`hledger-mode` contains automated tests. You may run them by executing\n`cask exec ert-runner`.\n\nYou may need to install `cask` locally if you do not already have it\ninstalled, and run `cask install` to install any dependencies that you\nmay be missing.\n\n## Contributing\n\nThis project is new and improving. Please feel free to contribute to\nit. You might start with writing a document on contributing to the\nproject or by refactoring it a bit [See `hledger-reports.el`. It's a\nmess.].\n\nCheers!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarendraj9%2Fhledger-mode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnarendraj9%2Fhledger-mode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarendraj9%2Fhledger-mode/lists"}