Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/samwho/hmm

A small command-line note taking app written in Rust. Notes are written in plain text and indexed by the time they were written.
https://github.com/samwho/hmm

command-line journaling note-taking rust

Last synced: 4 days ago
JSON representation

A small command-line note taking app written in Rust. Notes are written in plain text and indexed by the time they were written.

Awesome Lists containing this project

README 

        
[![Build status](https://github.com/samwho/hmm/workflows/Build/badge.svg)](https://github.com/samwho/hmm/actions)

[![Crates.io](https://img.shields.io/crates/v/hmmcli.svg)](https://crates.io/crates/hmmcli)



`hmm` is a small command-line note taking app written in Rust. Entries are

written in plain text and indexed by the time they were written.



`hmm` is inspired by [jrnl][1], except with a different use-case in mind.

Where `jrnl` excels at a journaling use case, where users to can entries

with arbitrary times and the file format is human-readable, `hmm` only

allows you to add an entry at the current time and has a machine-readable

format that's optimised for fast time-based querying.



* [Comparison to jrnl](#comparison-to-jrnl)

* [Installation](#installation)

    * [Arch Linux (AUR)](#arch-linux-aur)

    * [Using cargo](#using-cargo)

    * [From source](#from-source)

* [Usage](#usage)

* [hmm](#hmm)

    * [Writing an entry from the CLI](#writing-an-entry-from-the-cli)

    * [Writing an entry to a different .hmm file](#writing-an-entry-to-a-different-hmm-file)

    * [Writing long-form entries in your EDITOR](#writing-long-form-entries-in-your-editor)

* [hmmq](#hmmq)

    * [Listing your entries](#listing-your-entries)

        * [Show the most recent 10 entries](#show-the-most-recent-10-entries)

        * [Show the frst 10 entries](#show-the-frst-10-entries)

        * [Show entries on a specific day](#show-entries-on-a-specific-day)

        * [Show entries on a given year](#show-entries-on-a-given-year)

        * [Count entries in a given year](#count-entries-in-a-given-year)

        * [Show all entries from a given date](#show-all-entries-from-a-given-date)

        * [Show a random entry](#show-a-random-entry)

    * [Formatting entries](#formatting-entries)

* [hmmp](#hmmp)

* [Benchmarking](#benchmarking)



# Comparison to `jrnl`



Features `jrnl` has that `hmm` doesn't:



- Encryption.

- Ability to add entries at arbitrary points in time.

- In-built notion of tags.

- In-built notion of starring.

- Ability to edit entries.

- Ability to parse English dates/times, e.g. "yesterday" and "2 weeks ago."



Features `hmm` has that `jrnl` doesn't:



- Unambigous date-format (RFC3339).

- File-format optimised for searching by time.

- Ability to format entries however you want.

- No external dependencies.

- Lots of flexibility.



If you need to add entries at times in the past, or you need encryption, or

you need your file format to be purely plain text, or you need to edit entries

after they're written, `hmm` isn't for you. Other than that, I believe `hmm`

can be made to work exactly how you want it to.



# Installation



No support for Homebrew yet, so Mac users will need to go down the `cargo`

route, but I plan to get it in to the Homebrew repos soon.



## Arch Linux (AUR)



`hmm` is in the AUR, and can be installed with an AUR helper such as `yay`:



    yay -S hmm-bin



## Using cargo



[Install Rust][2], then run:



    cargo install hmmcli



Now the `hmm` and `hmmq` binaries should be available in your terminal.



## From source



[Install Rust][2], [install git][3] then run:



    git clone https://github.com/samwho/hmm

    cd hmm

    cargo install



# Usage



`hmm` is split in to three binaries: `hmm`, `hmmq` and `hmmp`.



- `hmm` is for writing new entries via the CLI.

- `hmmq` is for querying entries by time and content.

- `hmmp` is for printing entries if you want to use tools other than

  `hmmq` to query them.



# `hmm`



## Writing an entry from the CLI



    hmm hello world



This will write an entry to the default `.hmm` file location, which is in

your home directory.



## Writing an entry to a different `.hmm` file



Your `.hmm` file can be located wherever you want, and named whatever you

want.



    hmm --path ~/.notes hello world



## Writing long-form entries in your `EDITOR`



    hmm



Invoked with no arguments, or just a `--path` argument, `hmm` will open your

default `EDITOR` to compose an entry. Saving and quitting that editor will

then write the note to your `.hmm` file. If you don't have an `EDITOR`

configured, you can also pass one as a flag:



    hmm --editor vim



The editor variable can be arbitrarily complex, the only thing to keep in mind

is that `hmm` will call it with a temporary file as the last argument. It will

read the contents of that temporary file after your editor command exits

successfully. If your editor does not exit successfully, nothing is written to

your `.hmm` file.



# `hmmq`



## Listing your entries



    hmmq



By default, this lists all of your entries in a default format in ascending

chronological order. This may not be desired, so there are a bunch of flags

to narrow down what is shown.



### Show the most recent 10 entries



    hmmq --last 10



### Show the frst 10 entries



    hmmq --first 10



### Show entries on a specific day



    hmmq --start 2020-01-01 --end 2020-01-02



The `--start` flag is inclusive and the `--end` flag is exclusive, so the

above command will show all entries that were created on the 1st of January

2020.



Dates follow the RFC3339/ISO8601 format, allowing you to omit parts you don't

need. All dates are in your local timezone.



### Show entries on a given year



    hmmq --start 2019 --end 2020



This will show all of your entries from 2019.



### Count entries in a given year



    hmmq --start 2019 --end 2020 --count



This will show you how many entries you made in 2019.



### Show all entries from a given date



    hmmq --start 2020-02-20



This will print all of your entries from the 20th of February 2020.



### Show a random entry



    hmmq --random



Prints out a random entry. The randomness comes from selecting a random byte

in your `.hmm` file, and as such longer entries are more likely to be picked.

This is a trade-off. Picking entries in a truly random fashion would require

reading the entire file, which is against the philosophy of `hmmq`.



## Formatting entries



`hmmq` makes use of the [Handlebars][4] templating format to determine how entries

are printed to the terminal. Here's an example of a really simple template:



    hmmq --format "{{ datetime }}: {{ message }}"



It's not much to look at, but it shows how the templates look and all of the

variables you have access to inside a template.



`hmmq` offers some helper functions to make your templates look nicer. Here's

the default output format specified explicitly:



    hmmq --format $'╭ {{ color "blue" (strftime "%Y-%m-%d %H:%M" datetime) }}\n{{ indent (markdown message) }}╰─────────────────"



The keen reader will notice the `$` before the format argument. This is a bash

quirk. Without it, the `\n` inside the format argument will print literally

instead of being interpreted as a newline.



# `hmmp`



If you want to use other tools to filter through your `.hmm` file, that's completely

file and even encouraged. The `hmmp` tool exists to let you pipe filtered `.hmm` file

contents and have it formatted how you want it.



The following two commands are equivalent:



    tail -n 10 ~/.hmm | hmmp

    hmmq --last 10



As are the following two:



    tail -n 10 ~/.hmm | hmmp --format "{{ message }}"

    hmmq --last 10 --format "{{ message }}"



# Benchmarking



There's a script in the repository root called `bench.sh` that shows the methodology

behind the following table if you're interested.



| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |

|:---|---:|---:|---:|---:|

| `target/release/hmmq --path /tmp/out --random` | 13.5 ± 0.8 | 11.9 | 15.4 | 1.00 |

| `target/release/hmmq --path /tmp/out --last 10` | 15.0 ± 0.8 | 12.8 | 17.1 | 1.11 ± 0.09 |

| `target/release/hmmq --path /tmp/out --first 10` | 13.6 ± 1.0 | 9.0 | 16.2 | 1.01 ± 0.09 |

| `target/release/hmmq --path /tmp/out --start 2019 --first 10` | 16.8 ± 0.8 | 15.3 | 19.2 | 1.24 ± 0.09 |

| `target/release/hmmq --path /tmp/out --end 2019 --last 10` | 18.8 ± 0.9 | 16.4 | 21.4 | 1.40 ± 0.10 |

| `target/release/hmmq --path /tmp/out --start 2019-01 --end 2019-02` | 325.6 ± 11.9 | 309.9 | 379.9 | 24.11 ± 1.65 |

| `target/release/hmmq --path /tmp/out --start 2019 --end 2020 --count` | 346.6 ± 13.6 | 336.7 | 427.6 | 25.67 ± 1.79 |

| `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 |

| `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 |



[1]: https://jrnl.sh/

[2]: https://rustup.rs/

[3]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

[4]: https://handlebarsjs.com/