utagai/jot

WIP. Minimalism + scribbling.

jot

WIP. Minimalism + scribbling.

The entirety of jot's documentation can be found in its help output:

jot
Write notes.

Jot is a _very thin_ wrapper around the local filesystem and git. It makes use of these things to
store, as well as track and distribute notes. Jot is really just a thin API around the two and does
not do anything all that special.

Jot has no configuration file. It only has CLI flags and such. Jot commands and command-specific
arguments come at the end of its usage, so jot is meant to be aliased.

Jot is based on top of git. The base-dir containining all the notes is just a git repository. This
also means that you are able to go into that repository and mess with it as you see fit. This can
make jot fail, so mess with it at your own risk. In fact, jot is remarkably stupid. All it does to
sync your notes is to pull from upstream, add any changes in the repository, commit them, and then
push back to upstream. It fails pretty much immediately the moment anything goes wrong.

For arguments that take a command invocation, only the output from stdout is used for execution. An
invocation is only considered an error if it returns with a non-zero exit code. There is also no
restriction placed on the invocation itself. Invocations can be quite literally anything, from
/bin/ls to fzf to a custom Python script.

Note that custom invocations are executed by passing the invocation to the user's $SHELL. This means
your invocation can actually be written in a shell's scripting language, and make use of things like
environment variable substitution (jot passes its environment down to its child processes). Note
that there may be differences in how different shells support command execution, for example, in
bash, one uses `-c`:

bash -c 'echo foo'

If your shell differs, please set the shell_cmd_flag flag.

Standard streams stdin & stderr are inherited by the the child process. This is done to support
applications like fzf, which need stdin and stderr for their UI. This means that if your application
uses stderr to log error information, you should either:

* Set the capture_std flag.

* Use stdout and return a non-zero exit code.

* Roll out your own logging.

Finally, note that custom invocations _do not include_ invoking $EDITOR or git. When invoking
$EDITOR, the standard streams stdout and stdin are inherited by the editor process, but stderr is
piped. When invoking git, all standard streams are inherited.

USAGE:
    jot [OPTIONS] --base-dir <BASE_DIR> --finder <FINDER> --lister <LISTER> [SUBCOMMAND]

OPTIONS:
    -b, --base-dir <BASE_DIR>
            Base directory under which all notes handled by jot must reside. This must be a git
            repository

    -c, --capture-std
            Capture stderr/stdin for custom invocations. If not captured, the child process inherits
            stderr from the parent. Note that if this value is false, invocations that print things
            like error diagnostics to stderr will not be propagated directly by jot. Default: false

    -e, --edit-syncs
            Editing should finish with a sync automatically. Default: true

    -f, --finder <FINDER>
            Specifies a command invocation that prints a single filepath to stdout upon completion

    -h, --help
            Print help information

    -l, --lister <LISTER>
            Specifies a command invocation that, given a path (relative to base-dir) as a positional
            argument, prints a listing to stdout

    -m, --git-custom-commit-msg
            Prompt for a custom git commit message when syncing. This will default to whatever
            behavior your git config suggests for a bare `git commit`

    -q, --quiet-on-ctrl-c
            Do not print any error information if an invocation fails due to exit code 130 (CTRL+C).
            Likely only valid on unix/*nix-like OSes. Default: true

    -r, --git-remote-name <GIT_REMOTE_NAME>
            Specifies the name of the remote to push/pull to/from

            [default: origin]

    -s, --shell-cmd-flag <SHELL_CMD_FLAG>
            Specifies the flag for the user's $SHELL that allows for command execution. e.g. bash
            uses `-c`

            [default: -c]

    -u, --git-upstream-branch <GIT_UPSTREAM_BRANCH>
            Specifies the name of the remote branch to push/pull to/from

            [default: main]

SUBCOMMANDS:
    edit
            Dispatch to a program that outputs a filepath to open in $EDITOR. Edit mode need not be
            explicitly called. Calling jot without any subcommand defaults to edit mode. Note that
            the finder program need not return a filepath that exists. If the filepath does not
            exist, $EDITOR will be called nevertheless on the path. Most editors will open a blank
            page, and then create the file on save. This makes Edit roughly equivalent to New, the
            primary difference being that New creates the file prior to opening it in $EDITOR
    help
            Print this message or the help of the given subcommand(s)
    list
            Dispatch to a program (e.g. tree) that outputs a listing of all notes
    new
            Creates a new note at the specified path and opens it in $EDITOR. If a file exists at
            the path already, this command behaves similarly to Edit if its dispatched program had
            returned the given path
    sync
            'Synchronize' the notes. This is really just an attempt to git pull, git add -A, git
            commit, then finally, git push. If an error (namely a merge conflict) occurs, an error
            is propagated to stderr. If you want to be prompted for a custom commit message, specify
            the git-custom-commit-msg flag, otherwise, jot will set the message to the current local
            system time in RFC3339 format

Dependencies

Just a few.

• rustc to compile jot
• git

p.s.

This README was unfortunately not written with jot.

jot's Issues

Consider _only_ supporting Markdown

There are some benefits here. For example, issue #3 becomes 'easier' in the sense that we don't really need to support an option, we just always run a known formatter/linter/etc. It reduces the number of unknowns.

Furthermore, issue #4 could become easier. The main reason we are not only committing the edited file is because there could be other files, namely image files, that were added and referenced in the edited file that should be committed as well. However, if we could assume that the file is Markdown, it isn't too difficult to find image references in the diff and make sure they are committed.

Post-process script/command option

Having something run after $EDITOR, e.g., some kind of linter or compiler pass could make sense. One immediate use case is catching invalid/dangling image references in Markdown, or maybe compiling LaTeX to check for errors, or even to just to render things to .pdf and syncing that as well/instead.

Exiting $EDITOR without any changes causes an error

This is due to jot attempting to commit no changes, which gives a non-zero exit code from git since we aren't using --allow-empty. We probably shouldn't even be trying to commit unless the repository is dirty.

Potentially support multiple instances of `jot` simultaneously

Right now, if you are editing one document via jot and wish to open another one jot will complain about the directory being dirty:

Error: base-dir (/home/bob/foo/bar) is not clean, please fix the issue and run jot again

This can be annoying, but it isn't clear how to approach this, since if we don't enforce this, edits for both documents will get committed. It is possible that we made the wrong design choice initially -- we shouldn't stage everything for commit, but just the file you opened with $EDITOR. The problem with this of course is that you may have added other things as well, like an image file referenced in Markdown which wouldn't be captured.

Syncing after each write can be slow/blocking

This can be a bad UX, since after finishing jotting something down, you have to wait for the sync to go through. We could try asynchronously doing this by forking off a child, connecting its stderr to ours and let it do the work, but this can cause some weird behavior.

Probably the best is to point this out in the --help output and note that an alias can handle this by avoiding sync-on-write and instead running jot sync in the the bg.

Or see if we can come up with something better. At the very least, logging something to suggest we are syncing (instead of staying quiet) is better than nothing.