{"id":16929445,"url":"https://github.com/samwho/hmm","last_synced_at":"2025-08-02T09:15:39.242Z","repository":{"id":62440159,"uuid":"245717100","full_name":"samwho/hmm","owner":"samwho","description":"A small command-line note taking app written in Rust. Notes are written in plain text and indexed by the time they were written.","archived":false,"fork":false,"pushed_at":"2024-09-03T21:34:11.000Z","size":106,"stargazers_count":96,"open_issues_count":5,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-28T17:30:21.091Z","etag":null,"topics":["command-line","journaling","note-taking","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samwho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2020-03-07T22:48:44.000Z","updated_at":"2025-05-18T06:55:03.000Z","dependencies_parsed_at":"2024-10-25T18:44:49.116Z","dependency_job_id":"bf4f6c55-5864-4704-8f3d-68bcaf968b9b","html_url":"https://github.com/samwho/hmm","commit_stats":{"total_commits":108,"total_committers":4,"mean_commits":27.0,"dds":"0.12962962962962965","last_synced_commit":"8894296e98ab43e6937adbfe88af413c7edee881"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/samwho/hmm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samwho%2Fhmm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samwho%2Fhmm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samwho%2Fhmm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samwho%2Fhmm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samwho","download_url":"https://codeload.github.com/samwho/hmm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samwho%2Fhmm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268362012,"owners_count":24238533,"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","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["command-line","journaling","note-taking","rust"],"created_at":"2024-10-13T20:39:20.666Z","updated_at":"2025-08-02T09:15:39.218Z","avatar_url":"https://github.com/samwho.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build status](https://github.com/samwho/hmm/workflows/Build/badge.svg)](https://github.com/samwho/hmm/actions)\n[![Crates.io](https://img.shields.io/crates/v/hmmcli.svg)](https://crates.io/crates/hmmcli)\n\n`hmm` is a small command-line note taking app written in Rust. Entries are\nwritten in plain text and indexed by the time they were written.\n\n`hmm` is inspired by [jrnl][1], except with a different use-case in mind.\nWhere `jrnl` excels at a journaling use case, where users to can entries\nwith arbitrary times and the file format is human-readable, `hmm` only\nallows you to add an entry at the current time and has a machine-readable\nformat that's optimised for fast time-based querying.\n\n* [Comparison to jrnl](#comparison-to-jrnl)\n* [Installation](#installation)\n    * [Arch Linux (AUR)](#arch-linux-aur)\n    * [Using cargo](#using-cargo)\n    * [From source](#from-source)\n* [Usage](#usage)\n* [hmm](#hmm)\n    * [Writing an entry from the CLI](#writing-an-entry-from-the-cli)\n    * [Writing an entry to a different .hmm file](#writing-an-entry-to-a-different-hmm-file)\n    * [Writing long-form entries in your EDITOR](#writing-long-form-entries-in-your-editor)\n* [hmmq](#hmmq)\n    * [Listing your entries](#listing-your-entries)\n        * [Show the most recent 10 entries](#show-the-most-recent-10-entries)\n        * [Show the frst 10 entries](#show-the-frst-10-entries)\n        * [Show entries on a specific day](#show-entries-on-a-specific-day)\n        * [Show entries on a given year](#show-entries-on-a-given-year)\n        * [Count entries in a given year](#count-entries-in-a-given-year)\n        * [Show all entries from a given date](#show-all-entries-from-a-given-date)\n        * [Show a random entry](#show-a-random-entry)\n    * [Formatting entries](#formatting-entries)\n* [hmmp](#hmmp)\n* [Benchmarking](#benchmarking)\n\n# Comparison to `jrnl`\n\nFeatures `jrnl` has that `hmm` doesn't:\n\n- Encryption.\n- Ability to add entries at arbitrary points in time.\n- In-built notion of tags.\n- In-built notion of starring.\n- Ability to edit entries.\n- Ability to parse English dates/times, e.g. \"yesterday\" and \"2 weeks ago.\"\n\nFeatures `hmm` has that `jrnl` doesn't:\n\n- Unambigous date-format (RFC3339).\n- File-format optimised for searching by time.\n- Ability to format entries however you want.\n- No external dependencies.\n- Lots of flexibility.\n\nIf you need to add entries at times in the past, or you need encryption, or\nyou need your file format to be purely plain text, or you need to edit entries\nafter they're written, `hmm` isn't for you. Other than that, I believe `hmm`\ncan be made to work exactly how you want it to.\n\n# Installation\n\nNo support for Homebrew yet, so Mac users will need to go down the `cargo`\nroute, but I plan to get it in to the Homebrew repos soon.\n\n## Arch Linux (AUR)\n\n`hmm` is in the AUR, and can be installed with an AUR helper such as `yay`:\n\n    yay -S hmm-bin\n\n## Using cargo\n\n[Install Rust][2], then run:\n\n    cargo install hmmcli\n\nNow the `hmm` and `hmmq` binaries should be available in your terminal.\n\n## From source\n\n[Install Rust][2], [install git][3] then run:\n\n    git clone https://github.com/samwho/hmm\n    cd hmm\n    cargo install\n\n# Usage\n\n`hmm` is split in to three binaries: `hmm`, `hmmq` and `hmmp`.\n\n- `hmm` is for writing new entries via the CLI.\n- `hmmq` is for querying entries by time and content.\n- `hmmp` is for printing entries if you want to use tools other than\n  `hmmq` to query them.\n\n# `hmm`\n\n## Writing an entry from the CLI\n\n    hmm hello world\n\nThis will write an entry to the default `.hmm` file location, which is in\nyour home directory.\n\n## Writing an entry to a different `.hmm` file\n\nYour `.hmm` file can be located wherever you want, and named whatever you\nwant.\n\n    hmm --path ~/.notes hello world\n\n## Writing long-form entries in your `EDITOR`\n\n    hmm\n\nInvoked with no arguments, or just a `--path` argument, `hmm` will open your\ndefault `EDITOR` to compose an entry. Saving and quitting that editor will\nthen write the note to your `.hmm` file. If you don't have an `EDITOR`\nconfigured, you can also pass one as a flag:\n\n    hmm --editor vim\n\nThe editor variable can be arbitrarily complex, the only thing to keep in mind\nis that `hmm` will call it with a temporary file as the last argument. It will\nread the contents of that temporary file after your editor command exits\nsuccessfully. If your editor does not exit successfully, nothing is written to\nyour `.hmm` file.\n\n# `hmmq`\n\n## Listing your entries\n\n    hmmq\n\nBy default, this lists all of your entries in a default format in ascending\nchronological order. This may not be desired, so there are a bunch of flags\nto narrow down what is shown.\n\n### Show the most recent 10 entries\n\n    hmmq --last 10\n\n### Show the frst 10 entries\n\n    hmmq --first 10\n\n### Show entries on a specific day\n\n    hmmq --start 2020-01-01 --end 2020-01-02\n\nThe `--start` flag is inclusive and the `--end` flag is exclusive, so the\nabove command will show all entries that were created on the 1st of January\n2020.\n\nDates follow the RFC3339/ISO8601 format, allowing you to omit parts you don't\nneed. All dates are in your local timezone.\n\n### Show entries on a given year\n\n    hmmq --start 2019 --end 2020\n\nThis will show all of your entries from 2019.\n\n### Count entries in a given year\n\n    hmmq --start 2019 --end 2020 --count\n\nThis will show you how many entries you made in 2019.\n\n### Show all entries from a given date\n\n    hmmq --start 2020-02-20\n\nThis will print all of your entries from the 20th of February 2020.\n\n### Show a random entry\n\n    hmmq --random\n\nPrints out a random entry. The randomness comes from selecting a random byte\nin your `.hmm` file, and as such longer entries are more likely to be picked.\nThis is a trade-off. Picking entries in a truly random fashion would require\nreading the entire file, which is against the philosophy of `hmmq`.\n\n## Formatting entries\n\n`hmmq` makes use of the [Handlebars][4] templating format to determine how entries\nare printed to the terminal. Here's an example of a really simple template:\n\n    hmmq --format \"{{ datetime }}: {{ message }}\"\n\nIt's not much to look at, but it shows how the templates look and all of the\nvariables you have access to inside a template.\n\n`hmmq` offers some helper functions to make your templates look nicer. Here's\nthe default output format specified explicitly:\n\n    hmmq --format $'╭ {{ color \"blue\" (strftime \"%Y-%m-%d %H:%M\" datetime) }}\\n{{ indent (markdown message) }}╰─────────────────\"\n\nThe keen reader will notice the `$` before the format argument. This is a bash\nquirk. Without it, the `\\n` inside the format argument will print literally\ninstead of being interpreted as a newline.\n\n# `hmmp`\n\nIf you want to use other tools to filter through your `.hmm` file, that's completely\nfile and even encouraged. The `hmmp` tool exists to let you pipe filtered `.hmm` file\ncontents and have it formatted how you want it.\n\nThe following two commands are equivalent:\n\n    tail -n 10 ~/.hmm | hmmp\n    hmmq --last 10\n\nAs are the following two:\n\n    tail -n 10 ~/.hmm | hmmp --format \"{{ message }}\"\n    hmmq --last 10 --format \"{{ message }}\"\n\n# Benchmarking\n\nThere's a script in the repository root called `bench.sh` that shows the methodology\nbehind the following table if you're interested.\n\n| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |\n|:---|---:|---:|---:|---:|\n| `target/release/hmmq --path /tmp/out --random` | 13.5 ± 0.8 | 11.9 | 15.4 | 1.00 |\n| `target/release/hmmq --path /tmp/out --last 10` | 15.0 ± 0.8 | 12.8 | 17.1 | 1.11 ± 0.09 |\n| `target/release/hmmq --path /tmp/out --first 10` | 13.6 ± 1.0 | 9.0 | 16.2 | 1.01 ± 0.09 |\n| `target/release/hmmq --path /tmp/out --start 2019 --first 10` | 16.8 ± 0.8 | 15.3 | 19.2 | 1.24 ± 0.09 |\n| `target/release/hmmq --path /tmp/out --end 2019 --last 10` | 18.8 ± 0.9 | 16.4 | 21.4 | 1.40 ± 0.10 |\n| `target/release/hmmq --path /tmp/out --start 2019-01 --end 2019-02` | 325.6 ± 11.9 | 309.9 | 379.9 | 24.11 ± 1.65 |\n| `target/release/hmmq --path /tmp/out --start 2019 --end 2020 --count` | 346.6 ± 13.6 | 336.7 | 427.6 | 25.67 ± 1.79 |\n| `target/release/hmmq --path /tmp/out --start 2019-01 --end 2019-06 --contains lorum` | 232.3 ± 5.2 | 226.4 | 262.7 | 17.21 ± 1.07 |\n| `target/release/hmmq --path /tmp/out --start 2019 --end 2020 --regex \"(lorum\\|ipsum)\"` | 565.3 ± 13.3 | 548.1 | 622.1 | 41.87 ± 2.62 |\n\n[1]: https://jrnl.sh/\n[2]: https://rustup.rs/\n[3]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git\n[4]: https://handlebarsjs.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamwho%2Fhmm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamwho%2Fhmm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamwho%2Fhmm/lists"}