settle

Settle is a Zettelkasten note manager. All notes are written in Markdown and are stored locally.

Note that settle does not edit the files it handles directly. Therefore, you're probably going to want to use (or write) a plugin for your favourite editor, such as settle.vim for Vim and Neovim.

Table of contents

Synopsis

settle [--help | -h | --version | -v]
settle {sync | -S} [-p | -c | -u | -g | -m | -n]
settle {query | -Q} [-t | -p | -g | -x | -l | -b | -o | -f | -s | --graph]
settle ls ['tags' | 'projects' | 'ghosts' | 'path']

Options

Commands

All warnings and errors are printed to stderr, so you can suppress them (e.g. 2>/dev/null).

A short briefing on regular expressions (REGEX)

Regex is a useful tool that settle has support for, because it provides wildcards and patterns which allow matching multiple strings. See this regular expression specification for all supported patterns. But here are a few of the most useful characters you're going to use:

If you wanted to match a literal ., * or +, you'd have to escape them with a backslash: \., \* and \+ respectively.

Here are some examples:

The query command

The query command is used for getting information related to the notes in the Zettelkasten - most of the time, by returning those that match a given set of criteria.

Note that the various options listed here all compound - that is to say, every option acts as a criteria for querying. settle query --title "Foo.*" --tag "bar" will only return notes whose titles starts with Foo AND have the tag bar, not notes whose titles start with Foo OR have the tag bar. By default, when no filter parameter is applied (that is to say, settle query is ran without options), all notes are returned.

Here are the query flags:

Examples of the query command

The sync command

The sync command is used for changing things related to notes - be it creating new ones, updating their metadata in the database, moving them from a project to another project, or renaming them.

Note that, unlike the query command, the options that do take arguments here don't work with regex (except --move). Matches here need to be exact, since we're dealing with more or less precise database changes. Also, unless specified otherwise, most/all options are mutually exclusive.

Here are the options for this command:

Examples of the sync command

Configuration

The location of the configuration file may be influenced by environment variables:

  1. if $SETTLE_CONFIG is set: $SETTLE_CONFIG
  2. if $XDG_CONFIG_HOME is set: $XDG_CONFIG_HOME/settle/settle.yaml
  3. default: $HOME/.config/settle/settle.yaml

A generic configuration file is automatically created when settle is ran with any command (except compl), if it doesn't already exist.

Configuration properties

Templates

Template files are used when creating new Zettel. The text they contain gets put inside said new note, replacing variables.

Template placeholders

Example template

# ${TITLE}



### References

- ${DATE}:

Shell autocompletion

Shell completions can be generated by the user at runtime, by using the compl subcommand. In most cases, you'll need to create a directory for user-defined completions, then add settle's output to it.

If you want XDG compliance, you probably know what you're doing, so just replace a few things here and there.

bash

Add the following text to the ~/.bash_completion file:

for comp_file in ~/.bash_completion.d/*; do
    [[ -f "${comp_file}" ]] && . "${comp_file}"
done

And then run the following commands:

mkdir ~/.bash_completion.d
settle compl bash >~/.bash_completion.d/settle

zsh

In your terminal, run:

mkdir ~/.zsh_completion.d
settle compl zsh >~/.zsh_completion.d/_settle

Then add this line in your zshrc:

fpath=(${HOME}/.zsh_completion.d $fpath)

fish

Run the following commands:

mkdir -p ~/.config/fish/completions
settle compl fish >~/.config/fish/completions/settle.fish

nushell

From inside nushell, you can generate the completion file by running:

settle compl nu | save ~/.config/nushell/settle.nu

(Note that settle compl nushell also works; nushell is just an alias for nu)

And then you'll need to add the following line to your config.nu, so that the completions are sourced on every shell startup:

source ~/.config/nushell/settle.nu

License & Credits

Licensed under MIT

Written by xylous <xylous.e@gmail.com>