DIJO(1)

NAME
dijo - digital journal

SYNOPSIS
dijo [FLAGS] [OPTIONS]

DESCRIPTION
dijo is scriptable, curses-based and modal, much like vim, digital habit tracker

FLAGS

-h, --help
    Prints help information

-l, --list
    List dijo habits

-V, --version
    Prints version information

OPTIONS

-c, --command command
    Run a dijo command

FEATURES

• vim like motions
    Navigate with hjkl!

• dijo is modal
    Different modes to view different stats!

• vim like command mode
    Add with :add, delete with :delete and above all, quit with :q!.

• Fully scriptable
    You can configure it to track your git commits!

GETTING STARTED

On running dijo at the command line, you are presented with a blank screen. This is the DAY mode, analogous to the NORMAL mode in Vim. In this mode, you may view stats for every day of the current month.

To start tracking habits, enter the command mode with :. Use the add command to add a habit to begin tracking.

Say, I would like to track the number of French lessons I took on Duolingo, and I aim to do 5 lessons each day:

    :add french  5
           |     |
           `-----|----- habit name
                  `---- goal (optional)

Go ahead and add a couple more habits the same way:

    :add lifting 1   <-- a yes/no kind of habit (represented by a dot grid)
    :add water       <-- no goal provided

To track your progress for the day:

    • focus the habit you want to track, (the focused habit is highlighted in bright white).

    • Hit Enter on the keyboard to increase the value, or Backspace to reduce it.

    • Once you reach your daily goal, the day is marked in green and the habit name is struck through with a line.

Check your weekly progress for a given habit by pressing v on the keyboard, this is WEEK mode, and press <ESC> to go back to DAY mode. <Shift-v> is a shortcut to display weekly progress for every habit. The current mode is indicated on the status line.

Review your progress for previous months by pressing [ on the keyboard, sift through months with [ and ].

CUSTOMIZATION

dijo (>= v0.2.7), can be configured via a configuration file. After its first run, dijo creates a configuration file. dijo must be restarted for changes in the configuration file to take effect.

This file is saved in different directories based on your operating system:

    • GNU/Linux: $XDG_CONFIG_HOME/dijo/config.toml

    • MacOS: $HOME/Library/Application Support/rs.nerdypepper.dijo/config.toml

    • Win10: {FOLDERID_RoamingAppData}\nerdypepper\dijo\config\config.toml

The default config file (created on first run) looks something like this, config.toml:

    [look]
    true_chr = "·"
    false_chr = "·"
    future_chr = "·"
    [colors]
    reached = "cyan"
    todo = "magenta"
    inactive = "light black"

  Look

Variables in this section define the characters dijo uses in DAY mode to represent days of the month. Every value in this section must span exactly 1 character in length.

    • true_chr: The character to use in a Bit habit when the goal is reached

    • false_chr: The character to use in a Bit habit when the goal is not reached

    • future_chr: The character to use in a Bit habit when the day is untracked.

  Colors

Variables in this section define the colors dijo uses in all modes:

    • reached: The color to use when the goal is reached for the day. This is also the color used in WEEK mode to fill the progress bar.

    • todo: The color to use when the goal is yet to be reached.

    • inactive: The color to use for unfocused habits and untracked days.

The values in this section are strings, and may be populated by one of the following:

     black               light black
     red                 light red
     green               light green
     yellow              light yellow
     blue                light blue
     magenta             light magenta
     cyan                light cyan
     white               light white
     default  -- uses your terminal's background color
     #123456  -- any color in hex (supported only on true color terminals)

Note: These values have to be quoted (ex.: reached = "black")

AUTO HABITS

dijo supports auto-trackable habits, that is, habits that can be updated via scripts. Add an auto-habit to, say, track your git commits:

    :add-auto commits 5

You can control dijo externally by calling it with the -c flag:

    dijo -c "track-up commits"   # a +1 on today's count
    dijo -c "track-down commits" # a -1 on today's count

Firstly, point git to your hooks directory (~/.hooks in this case):

    # contents of ~/.gitconfig
    [core]
    hooksPath = "/home/username/.hooks"

Create a file called post-commit in the ~/.hooks directory, with the following contents (you should run mkdir ~/.hooks if it doesn’t exist):

    #! /usr/bin/env bash
    dijo -c "track-up commits"

    # make the post-commit script an executable
    chmod +x ~/.hooks/post-commit

Voilà! Every time you make a commit, dijo will automatically track it under the commits habit.

MODES

Any habit in the interactive program can exist in one of two modes:

    • DAY: the default mode

    • WEEK: can be toggled on an off with v

  DAY mode

DAY mode is the default mode for every habit. It shows you every day of the current month. In this mode, counting-type habits display their counts for each day of the month. Bit-type habits (yes/no) display their bits in the form of a · (U+00B7 Middle Dot). Days whose goals have been reached are displayed in cyan and those that haven’t been reached are displayed in magenta. Days that haven’t been tracked are displayed in “light black”.

  WEEK mode

WEEK mode can be triggered for a single habit via v, and for every habit via V. WEEK mode will show you a summary of your progress for every week of the month. The current week’s percentage is indicated in white, other weeks are colored in “light black”. The progress for a given week is calculated as follows:

1.  if the goal is reached for a day of the week, the day contributes exactly 14.28% (100/7) towards that week’s progress.

2.  if the goal is not reached for a day of the week, the day contributes progress / goal * 100 towards that week’s progress.

That means, to achieve a 100% for a week, you have to reach your goal every single day of the week.

  The Command mode

The command mode is different from the other modes in that it is a “control” mode rather than an “observe” mode. One can enter the command mode by hitting : on the keyboard. You will notice a : pop up at the bottom of the screen. You may now begin typing a command, once you are done, press Enter on the keyboard to execute it.

The command mode may also be accessed without running the program interactively, by starting dijo with the -c flag and passing a string to it as a command:

    $ dijo -c "track-up commits"

You can hit Tab on the keyboard inside Command mode to trigger completions. For example:

    :d<Tab>
    # completes to
    :delete
    :delete fr<Tab>
    # completes to
    :delete french

COMMANDS

  Keybinds

These are key binds you can use at DAY or WEEK modes. Some of them are dependent on the currently focused habit and some are global. Those that are dependent on the currently focused habit are marked with a [f].

•   Motions:

    •   h - move one cell to the left (aliases: <Tab>, <Arrow-Left>)

    •   j - move one cell down (aliases: <Arrow-Down>)

    •   k - move one cell up (alases: <Arrow-Up>)

    •   l - move one cell to the right (aliases: <Shift-Tab>,
        <Arrow-Right>)

•   Editing

    •   <Enter> - increment the currently focused habit (aliases: n) [f]

    •   <Backspace> - decrement the currently focused habit (aliases: p) [f]

•   Modes

    •   v - enter WEEK mode for currently focused habit [f]

    •   V - enter WEEK mode for all habits

    •   <Esc> - return to DAY mode

•   Time Travel

    •   [ - shift view port back by one month

    •   ] - shift view port forward by one month

    •   } - return to present

•   Control

    •   <Ctrl-c> - quit without saving (subject to change)

  Commandline

Enter the command mode with :. Type out a command and press <Enter> on the keyboard to execute it. Most commands have `aliases', or short forms. Command mode supports auto-complete also.

•   Help: show command syntax

    •   Inputs: optional command or alias

    •   Usage: help [command]

    •   Example: :help aa

    •   Aliases: h

•   Add: add a habit

    •   Inputs: name of habit, optional daily goal

    •   Usage: add <habit-name> [goal]

    •   Example: :add french 5

    •   Aliases: a

•   Add Auto: add an auto-trackable habit

    •   Inputs: name of habit, optional daily goal

    •   Usage: add-auto <habit-name> [goal]

    •   Example: :add-auto commits 5

    •   Aliases: aa

•   Delete: delete a habit

    •   Inputs: name of habit to delete

    •   Usage: delete <habit-name>

    •   Example: :delete water

    •   Aliases: d

•   Month motions: stats from the past

    •   Inputs: None

    •   Usage: month-prev, month-next

    •   Example: :month-prev

    •   Aliases: mprev, mnext

•   Tracking: For use only with dijo --command, works only on auto-habits

    •   Inputs: name of habit to track up/down

    •   Usage: track-up <habit-name>, track-down <habit-name>

    •   Example: :track-up commits

    •   Aliases: tup, tdown

•   Write: write progress to disk

    •   Inputs: None

    •   Usage: write

    •   Example: :write

    •   Aliases: w

•   Quit: save and quit

    •   Inputs: None

    •   Usage: quit

    •   Example: :quit

    •   Aliases: q

INTERNALS

This document delves into the internals of dijo.

  Files

After its first run, dijo creates three files on your file system, one to record habit data, habit_record.json, one to record auto-habit data, habit_record[auto].json, and one to store the default configuration in, config.toml. Data is saved in a human-readable format: JSON (a lot of work went into this). The config file is stored in TOML.

  Data files:

Making changes to these files while dijo is running, is not recommended (dijo will overwrite your changes on save).

•   GNU/Linux: $XDG_DATA_HOME/dijo/*.json

•   MacOS: $HOME/Library/Application Support/rs.nerdypepper.dijo/*.json

•   Win10: {FOLDERID_RoamingAppData}\nerdypepper\dijo\data\*.json

  Config files:

You can read more about configuring dijo at the Customization page.

•   GNU/Linux: $XDG_CONFIG_HOME/dijo/config.toml

•   MacOS: $HOME/Library/Application Support/rs.nerdypepper.dijo/config.toml

•   Win10: {FOLDERID_RoamingAppData}\nerdypepper\dijo\config\config.toml

dijo will not run on your computer if it can’t find your home directory.

  Data format

The general structure of a habit is as follows:

    type  :: String,
    name  :: String,
    goal  :: HabitType,
    auto  :: bool,
    stats :: Map<Date, HabitType>

HabitType is the type of data to be tracked and it is a bool for bit-type habits and a u32 for counting habits.

  File watchers

dijo sets up a file watcher (in the interactive mode), and watches habit_record[auto].json for changes. When changes are made to this file via dijo -c or equivalent, the interactive mode receives an update. However, the change is not reflected immediately because of dijo’s event based redrawing. You may force a redraw, and thereby update auto habits by pressing any button on the keyboard.

AUTHOR
Akshay <nerdy@peppe.rs>

SEE ALSO

vi(1), vim(1), nvim(1), jq(1), git(1)