jot

jot is a minimal, command-line note-taking program written in Bash.

It integrates seamlessly with your text editor and terminal and supports the minimum number of features, getting out of your way.

Design goals

• Small source size (~250 LOC: grep -v '^#' jot | grep -v '^$' | wc -l)
• Easy installation
• Plain text note files edited with a text editor
• Few commands with sensible defaults and aliases for less typing
• Seamless integration with external programs through custom commands
• Extensibility and automation with custom command hooks

Check out some usage examples.

Installation

wget -qO - 'https://raw.githubusercontent.com/agorf/jot/master/jot' | sudo tee /usr/local/bin/jot >/dev/null

If wget is not available in your system, you can use curl:

curl -sS 'https://raw.githubusercontent.com/agorf/jot/master/jot' | sudo tee /usr/local/bin/jot >/dev/null

Finally, make jot executable:

sudo chmod +x /usr/local/bin/jot

Notes

Notes are plain text files:

• With a YYYY-MM-DD filename
• A $JOT_EXT extension
• Kept under $JOT_HOME

Dates

Commands accept one or more dates and map them to note file names.

For example, if:

• Today is the 15th of April, 2020
• $JOT_HOME is /home/agorf/jot/
• $JOT_EXT is txt

Then today is mapped to /home/agorf/jot/2020-04-15.txt

The following date aliases are supported:

today

Alias: td

Self-explanatory.

This is the default date if you don't provide one.

yesterday

Alias: yd

Self-explanatory.

tomorrow

Alias: tm

Self-explanatory.

prev

Previous day with notes.

pwd

Previous working day.

It returns previous Friday's date when ran on Saturday, Sunday or Monday.

nwd

Next working day.

It returns next Monday's date when ran on Friday, Saturday or Sunday.

all

Targets all dates.

This makes it possible to execute custom commands targeting all note files.

For example, the following lists all note files:

jot ls -l -- all

Custom dates

Any date not matching the above is passed as the value of the --date option to the system's date command (man 1 date).

Example: 2020-04-15 for the 15th of April, 2020

Example: "3 days ago"

Example: "1 day" (ahead)

dir

This is not a date and does not map to note files. It can be used to issue commands against the $JOT_HOME directory.

For example, the following lists all $JOT_HOME directory contents:

jot ls -l -- dir

Contrast this with the following which lists all note files:

jot ls -l -- all

And this which lists only today's note file:

jot ls -l

Commands

edit

Alias: e

Edit note file with $JOT_EDITOR

This is the default if you don't provide one.

Examples:

jot edit today
jot e td
jot e
jot e yd
jot e yd td
jot e td tm
jot e all

copy

Alias: c

Copy note file contents to the clipboard with $JOT_COPY

Lines beginning with # are considered comments and are not copied. This can be used to keep note lines private when copy-pasting.

Examples:

jot copy today
jot c td
jot c
jot c yd

list

Alias: l

List all note files in ascending date order (most recent, last)

For each file, the following is displayed:

• Optional > marker to signify today's note file
• Date
• Number of lines
• Path

Example output (truncated):

  Fri, 24 Apr 2020 ( 7) /home/agorf/jot/2020-04-24.txt
  Mon, 27 Apr 2020 ( 3) /home/agorf/jot/2020-04-27.txt
  Tue, 28 Apr 2020 ( 8) /home/agorf/jot/2020-04-28.txt
  Wed, 29 Apr 2020 ( 8) /home/agorf/jot/2020-04-29.txt
  Thu, 30 Apr 2020 ( 8) /home/agorf/jot/2020-04-30.txt
> Mon, 04 May 2020 ( 7) /home/agorf/jot/2020-05-04.txt
  Tue, 05 May 2020 ( 4) /home/agorf/jot/2020-05-05.txt

help

Aliases: -h, --help

Print usage help text.

version

Show jot version.

update

Update jot to latest version.

Needs wget or curl to be installed.

Custom commands

If the command is not one of the above, jot will execute it, passing to it as arguments any dates after -- mapped to note file names.

This makes it possible to call arbitrary commands with note files!

For example, to delete yesterday's and tomorrow's note files:

jot rm -- yd tm

To ask for confirmation before deleting:

jot rm -i -- yd tm

Check out the usage examples.

Command hooks

The edit and custom commands support "pre" and "post" hooks with $JOT_HOOKS/pre and $JOT_HOOKS/post respectively. Hooks are custom scripts marked as executable (chmod +x) that are executed before and/or after the command.

For example, the execution order for the edit command is:

• $JOT_HOOKS/pre
• edit command
• $JOT_HOOKS/post

The following post hook adds changes to a Git repository and pushes them to the remote, so that note files are backed up and synchronized:

# Place this under $JOT_HOOKS/post and make it executable with chmod +x

[[ -z "$(git status -s)" ]] && exit

git add --all
git commit -m "$(date)"
git push

Environment variables

The following environment variables are supported:

JOT_HOME

Default: $HOME/jot

Where note files are stored.

JOT_HOOKS

Default: $JOT_HOME/hooks

Where hook scripts are stored.

JOT_EDITOR

Default: $EDITOR

Text editor to edit note files with.

JOT_EDITOR_OPTS

Default: (empty)

Options passed to the $JOT_EDITOR command.

Here's what I use for Vim:

export EDITOR=vim
export JOT_EDITOR_OPTS='"+normal G" -O'

This ensures each file is opened in a vertical split window and the cursor is placed at the end of the file.

JOT_COPY

Default: (none)

Note file paths will be passed as parameters to this command to be copied to the clipboard.

jot will auto-detect the existence of the following X selection manipulation programs (in this order):

• xclip
• xsel
• xcut
• sselp

JOT_DATE_FMT

Default: %a, %d %b %Y

Example: Wed, 15 Apr 2020

How note file dates are displayed with the list command.

JOT_EXT

Default: txt

File extension used for note files.

Usage examples

Edit today's notes:

jot edit today

edit is aliased as e and today as td, so the following is equivalent:

jot e td

Since edit and today are the defaults, you can simply execute jot instead:

jot

Edit yesterday's (yd or yesterday) and today's notes:

jot e yd td

Edit all notes:

jot e all

Copy today's notes to the clipboard:

jot copy today

Shortened:

jot c td

Since today is the default:

jot c

List all notes:

jot list

Shortened:

jot l

Remove tomorrow's notes, asking for confirmation:

jot rm -iv -- tm

Open today's notes with less pager:

jot less -- td

Since today is the default:

jot less

Show file information for today's notes:

jot ls -lh

Concatenate yesterday's and today's notes:

jot cat -- yd td

Search all notes for @agorf, colorizing matches:

jot grep --color @agorf -- all

Display number of lines for all notes:

jot wc -l -- all

Display Git directory status in $JOT_HOME:

jot git status -- dir

Acknowledgements

I was inspired to start working on jot from iridakos who wrote stup.

License

The MIT License

Author

Angelos Orfanakos, https://angelos.dev