zk/docs/config-alias.md

Command aliases

A command alias is a custom zk command which can run another zk command or an external program.

Declaring your own aliases is a great way to make your experience with zk easier and more familiar. With aliases, zk becomes a hub capable of launching all the programs you need to manage your notebook.

Configuring aliases

Command aliases are declared in your configuration file, under the [alias] section. They are executed with $SHELL -c, which allows you to:

• expand arguments with $@ or $*
• expand environment variables
• run several commands with &&
• pipe several commands with |

An alias can call other aliases but cannot call itself. This enables you to override the default options of native commands, for example:

[alias]
edit = "zk edit --interactive $@"

When running an alias, the ZK_NOTEBOOK_DIR environment variable is set to the absolute path of the current notebook. You can use it to run commands working no matter the location of the working directory.

journal = 'zk new "$ZK_NOTEBOOK_DIR/journal"'

If you need to surround the path with quotes, make sure you use double quotes, otherwise environment variables will not be expanded.

xargs formula

Calling an external program with a list of note paths using xargs is such a common use case that we can extract a reusable alias pattern.

alias = "zk list --quiet --format path --delimiter0 $@ | xargs -0 <EXTERNAL COMMAND>"

Find more details about these options in Send notes for processing by other programs.

Collection of useful aliases

Here are a few aliases to get you started writing your own.

Shortcuts for native commands

ls = "zk list $@"
ed = "zk edit $@"
n = "zk new $@"

Edit the last modified note

Suffixing the modified sort criterion with - orders the notes by descendent modification date.

edlast = "zk edit --limit 1 --sort modified- $@"

Edit the notes created during the last two weeks

This command uses --interactive to let the user select which notes to actually edit among the recent ones. Note the use of human friendly language for --created-after's argument.

In this case, additional arguments do not necessarily make sense, so we omit the trailing $@.

recent = "zk edit --sort created- --created-after 'last two weeks' --interactive"

This kind of alias might be more useful as a named filter.

Edit the configuration file

Here's a concrete example using environment variables, in particular ZK_NOTEBOOK_DIR. Note the double quotes around the path.

conf = '$EDITOR "$ZK_NOTEBOOK_DIR/.zk/config.toml"'

List paths in a command-line friendly fashion

Use this alias to send a list of space-separated file paths matching the given filtering criteria to another program. See send notes for processing by other programs for more details.

paths = "zk list --quiet --format \"'{{path}}'\" --delimiter ' ' $@"

List paths to be used in a parent zk command

Similarly, use this alias to expand filtered note paths inside a parent zk command taking a comma-separated paths list.

inline = "zk list --quiet --format {{path}} --delimiter , $@"

Examples of use:

# List the notes which have at least one link pointing to them (i.e. not orphans).
$ zk list --exclude "`zk inline --orphan`"

# List the notes which are linked by at least one note from the journal/ directory.
$ zk list --linked-by "`zk inline journal`"

Print a random note

Increasing serendipity while using your notebook is important to spark new ideas. The random sort criterion is the key to this alias.

lucky = "zk list --quiet --format full --sort random --limit 1"

Create a note from a free title

If you often create notes with zk new --title "An interesting concept", you will like this alias. Using "$*", you do not need to quote the arguments anymore.

nt = 'zk new --title "$*"'

Usage: zk nt An interesting concept

No more forgotten quotes!

Create a note and save its path into the clipboard (macOS)

Build upon the previous alias, but instead of editing the created note it will copy the created note's path into the macOS clipboard.

ntc = 'zk new --print-path --title "$*" | pbcopy'

Print and sort the word count of selected notes

This will list the notes and their word count sorted by increasing word count. It is useful to spot flimsy notes that you could flesh out.

wc = "zk list --format '{{word-count}}\t{{title}}' --sort word-count $@"

Usage:

$ zk wc
4       Integration with fzf
5       Searching and filtering notes
63      Setting your default editor
86      Anatomy of a notebook
...

Print the backlinks of a note

This is such a useful command, that an alias might be helpful.

bl = "zk list --link-to $@"

Locate unlinked mentions in a note

This alias can help you look for potential new links to establish, by listing every note whose title is mentioned in the note you are working on but which are not already linked to it.

Note that we are using a single argument $1 which is repeated for both options.

unlinked-mentions = "zk list --mentioned-by $1 --no-linked-by $1"

Browse the Git history of selected notes

This example showcases the "xargs formula" with a concrete example.

log = "zk list --quiet --format path --delimiter0 $@ | xargs -0 git log --patch --"

Saving the changes in the Git repository

This alias does not call zk at all! This shows how you can use zk as a hub for everything related to your notes.

save = 'git add . && git commit -m "$*"'

Usage: zk save Expand the note on command aliases

Copy/backup selected notes

A more complex example backing up the notes matching the given filtering criteria in a target directory. It creates intermediate directories if needed.

$1 and ${@:2} are used to split the arguments between the first one which will be the destination directory, and the remaining arguments which will be used as filtering options.

# macOS
cp = 'zk list --quiet --format path --delimiter0 ${@:2} | xargs -t -0 -I % ditto "%" "$1/%"'

# Linux
cp = 'mkdir -p "$1" && zk list --quiet --format path --delimiter0 ${@:2} | xargs -t -0 -I % cp --parents "%" "$1"'

Usage: zk cp output/ --created-after 'last two weeks'