zm

zm is a command line tool for managing zettelkasten-style notes. Create, find, view, and edit zets.

• Portable: zm is written in POSIX sh and does not use any utility extensions
• Minimal dependencies: fzf and a text editor set as EDITOR

Description

The core functionality of zm involves searching and filtering zets.

When zm is invoked with no arguments, it lists all zets in ZM_DIR (default $HOME/Documents/zm) in a fzf selector configured with a file previewer. Selecting a zet will open it with EDITOR in read-only mode (or in edit mode if option "-e" is set).

zm provides two ways to filter zets before selection, supporting any combination of the following:

• tag matching
• regular expression matching on zet contents

Usage Examples

zm
    Choose from a list of all zets.

zm n
    Create a new zet with EDITOR.

zm foo bar
    Choose from a list of zets that are tagged both "#foo" and "#bar".

zm -er '^baz'
    Choose from a list of zets that have content matching the regular
    expression "^baz", and open the selected zet in edit mode.

zm -r 'Colo[u]\{0,1\}r' alpha bravo charlie
    Choose from a list of zets that are tagged "#alpha" and "#bravo" and
    "#charlie" with content that matches the regular expression
    "Colo[u]\{0,1\}r".

Notes Format

[START EXAMPLE 19700101000000.md]------------------------------------------
# This is a very important zet
#important #foo #bar #some_other_tag

Today I will explain why this is a very important zet.
...
[END EXAMPLE 19700101000000.md]--------------------------------------------

zm recognizes zets as CommonMark (.md) files at the root of ZM_DIR with a timestamp as the filename (format: "YYYYMMDDHHMMSS")

zm assumes the second line of a zet is a space-separated sequence of tags that are associated with it. Each tag must be prefixed with a hash '#' symbol. For example, zm associates the tags "#important", "#foo", "#bar", and "#some_other_tag" with the example above.

Usage

SYNOPSIS
    zm [COMMAND]
    zm [OPTIONS...]
    zm [TAG_FILTER...]
    zm [OPTIONS...] [TAG_FILTER...]

POSITIONAL PARAMETERS
    <TAG>
        List zets that are tagged <TAG>. You can list zero or more tags.
        Prefixing tags with a hash '#' symbol is not required, but still valid
        input.

        For example, this will list zets that are tagged both "#linux" and
        "#shell":

            zm '#linux' shell

COMMANDS:
    zm treats the following single letters as commands if provided as the
    first positional argument, and will exit after invocation.

    n
        Create a new zet with EDITOR. The filename will be a timestamp with the
        format "YYYYMMDDHHMMSS".

    u
        Update the tags file (ZM_DIR/tags), which lists all the unique tags
        that appear in ZM_DIR. Tags are updated after a zet is created/updated,
        so this command isn't usually needed.

    t
        List all unique tags in ZM_DIR.

    h
        Print the help output for zm.

OPTIONS:
    -r PATTERN
        Filter zets by a regular expression pattern PATTERN.

    -e
        Edit the selected zet. By default, zm opens the zet in read-only
        mode.

    -h
        Print the help output for zm.

Dependencies

Required:

• fzf
• a text editor set as EDITOR

Optional:

• bat for fzf file previews (using cat as a fallback)

License

MIT