aboutsummaryrefslogtreecommitdiff
path: root/dijo.1
blob: 2058810f15a7747a025fc71a1b8d789f6042d8dd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
.TH DIJO 1 "January 26, 2021" dijo-0.2.7

.SH NAME
dijo \- digital journal

.SH SYNOPSIS
.B dijo
[\fBFLAGS\fR]
[\fBOPTIONS\fR]

.SH DESCRIPTION
.B dijo
is scriptable, curses-based and modal, much like \fIvim\fR, digital habit tracker

.SH FLAGS
.TP
.BR \-h ", " \-\-help
Prints help information
.TP
.BR \-l ", " \-\-list
List dijo habits
.TP
.BR \-V ", " \-\-version
Prints version information

.SH OPTIONS
.TP
.BR \-c ", " \-\-command " " \fIcommand
Run a dijo command

.SH FEATURES
.TP
\(bu \fBvim like motions\fR
Navigate with \fBhjkl\fR!
.TP
\(bu \fBdijo is modal\fR
Different modes to view different stats!
.TP
\(bu \fBvim like command mode\fR
Add with \fB:add\fR, delete with \fB:delete\fR and above all, quit with \fB:q!\fR.
.TP
\(bu \fBFully scriptable\fR
You can configure it to track your \fIgit\fR commits!

.SH GETTING STARTED
.PP
On running \fBdijo\fR at the command line, you are presented with a blank screen. This is the \fBDAY\fR mode, analogous to the \fBNORMAL\fR mode in Vim. In this mode, you may view stats for every day of the current month.
.PP
To start tracking habits, enter the command mode with \fB:.\fR Use the add command to add a habit to begin tracking.
.TP
Say, I would like to track the number of French lessons I took on Duolingo, and I aim to do 5 lessons each day:
.nf
\fB
:add french  5
       |     |
       `-----|----- habit name
              `---- goal (optional)
\fR
.fi
.TP
Go ahead and add a couple more habits the same way:
.nf
\fB
:add lifting 1   <-- a yes/no kind of habit (represented by a dot grid)
:add water       <-- no goal provided
\fR
.fi
.PP
To track your progress for the day:
.IP
\(bu focus the habit you want to track, (the focused habit is highlighted in bright white).
.IP
\(bu Hit \fBEnter\fR on the keyboard to increase the value, or \fBBackspace\fR to reduce it.
.IP
\(bu Once you reach your daily goal, the day is marked in green and the habit name is struck through with a line.
.PP
Check your weekly progress for a given habit by pressing \fBv\fR on the keyboard, this is \fBWEEK\fR mode, and press \fB<ESC>\fR to go back to \fBDAY\fR mode. \fB<Shift-v>\fR is a shortcut to display weekly progress for every habit. The current mode is indicated on the status line.
.PP
Review your progress for previous months by pressing \fB[\fR on the keyboard, sift through months with \fB[\fR and \fB]\fR.

.SH CUSTOMIZATION
.PP
\fBdijo (>= v0.2.7)\fR, can be configured via a configuration file. After its first run, \fBdijo\fR creates a configuration file. \fBdijo\fR must be restarted for changes in the configuration file to take effect.
.PP
This file is saved in different directories based on your operating system:

.nf
.IP
\(bu GNU/Linux: \fB$XDG_CONFIG_HOME/dijo/config.toml\fR
.IP
\(bu MacOS: \fB$HOME/Library/Application Support/rs.nerdypepper.dijo/config.toml\fR
.IP
\(bu Win10: \fB{FOLDERID_RoamingAppData}\[rs]nerdypepper\[rs]dijo\[rs]config\[rs]config.toml\fR
.fi

.PP
The default config file (created on first run) looks something like this, \fBconfig.toml\fR:
.IP
.nf
\fB
[look]
true_chr = \[dq]\[pc]\[dq]
false_chr = \[dq]\[pc]\[dq]
future_chr = \[dq]\[pc]\[dq]

[colors]
reached = \[dq]cyan\[dq]
todo = \[dq]magenta\[dq]
inactive = \[dq]light black\[dq]
\fR
.fi

.SS Look
.PP
Variables in this section define the characters \fBdijo\fR uses in \fBDAY\fR mode to represent days of the month. Every value in this section must span exactly 1 character in length.

.IP 
\(bu \fBtrue_chr\fR: The character to use in a Bit habit when the goal is \fBreached\fR
.IP 
\(bu \fBfalse_chr\fR: The character to use in a Bit habit when the goal is \fBnot reached\fR
.IP 
\(bu \fBfuture_chr\fR: The character to use in a Bit habit when the day is \fBuntracked\fR.

.SS Colors
.PP
Variables in this section define the colors \fBdijo\fR uses in all modes:

.IP 
\(bu \fBreached\fR: The color to use when the goal is \fBreached\fR for the day. This is also the color used in \fBWEEK\fR mode to fill the progress bar.
.IP 
\(bu \fBtodo\fR: The color to use when the goal is \fByet to be reached\fR.
.IP 
\(bu \fBinactive\fR: The color to use for \fBunfocused habits and untracked days\fR.

.PP
The values in this section are strings, and may be populated by one of the following:
.IP
.nf
\fB
 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\[aq]s background color
 #123456  -- any color in hex (supported only on true color terminals)
\fR
.fi

.PP
\fBNote\fR: These values have to be quoted (ex.: \fBreached = \[dq]black\[dq]\fR)

.SH AUTO HABITS
.PP
\fBdijo\fR supports auto-trackable habits, that is, habits that can be updated via scripts. Add an auto-habit to, say, track your git commits:
.IP
.nf
\fB
:add-auto commits 5
\fR
.fi
.PP
You can control \fBdijo\fR externally by calling it with the
\fB-c\fR flag:
.IP
.nf
\fB
dijo -c \[dq]track-up commits\[dq]   # a +1 on today\[aq]s count
dijo -c \[dq]track-down commits\[dq] # a -1 on today\[aq]s count
\fR
.fi
.PP
Firstly, point \fBgit\fR to your hooks directory
(\fB\[ti]/.hooks\fR in this case):
.IP
.nf
\fB
# contents of \[ti]/.gitconfig

[core]
hooksPath = \[dq]/home/\fIusername\fB/.hooks\[dq]
\fR
.fi
.PP
Create a file called \fBpost-commit\fR in the \fB\[ti]/.hooks\fR directory, with the following contents (you should run \fBmkdir \[ti]/.hooks\fR if it doesn\[cq]t exist):
.IP
.nf
\fB
#! /usr/bin/env bash

dijo -c \[dq]track-up commits\[dq]
\fR
.fi
.IP
.nf
\fB
# make the post-commit script an executable

chmod +x \[ti]/.hooks/post-commit
\fR
.fi
.PP
Voil\[`a]! Every time you make a commit, \fBdijo\fR will automatically track it under the \fBcommits\fR habit.

.SH MODES
.PP
Any habit in the interactive program can exist in one of two modes:
.IP
\(bu \fBDAY\fR: the default mode
.IP
\(bu \fBWEEK\fR: can be toggled on an off with \fBv\fR
.SS \fBDAY\fR mode

.PP
\fBDAY\fR 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 \fB\[pc]\fR (U+00B7 Middle Dot). Days whose goals have been reached are displayed in cyan and those that haven\[cq]t been reached are displayed in magenta. Days that haven\[cq]t been tracked are displayed in \[lq]light black\[rq].

.SS \fBWEEK\fR mode
.PP
\fBWEEK\fR mode can be triggered for a single habit via \fBv\fR,
and for every habit via \fBV\fR. \fBWEEK\fR mode will show you a summary of your progress for every week of the month. The current week\[cq]s percentage is indicated in white, other weeks are colored in \[lq]light black\[rq]. The progress for a given week is calculated as follows:
.IP "1." 3
if the goal is reached for a day of the week, the day contributes
exactly 14.28% (100/7) towards that week\[cq]s progress.
.IP "2." 3
if the goal is not reached for a day of the week, the day contributes
\fBprogress / goal * 100\fR towards that week\[cq]s progress.
.PP
That means, to achieve a 100% for a week, you have to reach your goal
\fIevery single day of the week\fR.

.SS The Command mode
.PP
The command mode is different from the other modes in that it is a \[lq]control\[rq] mode rather than an \[lq]observe\[rq] mode. One can enter the command mode by hitting \fB:\fR on the keyboard. You will notice a \fB:\fR pop up at the bottom of the screen. You may now begin typing a command, once you are done, press \fBEnter\fR on the keyboard to execute it.
.PP
The command mode may also be accessed without running the program interactively, by starting \fBdijo\fR with the \fB-c\fR flag and passing a string to it as a command:
.IP
.nf
\fB
$ dijo -c \[dq]track-up commits\[dq]
\fR
.fi
.PP
You can hit \fBTab\fR on the keyboard inside Command mode to
trigger completions. For example:
.IP
.nf
\fB
:d<Tab>
# completes to
:delete

:delete fr<Tab>
# completes to
:delete french
\fR
.fi

.SH COMMANDS
.SS Keybinds
.PP
These are key binds you can use at \fBDAY\fR or \fBWEEK\fR 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 \fB[f]\fR.
.IP \(bu 2
Motions:
.RS 2
.nf
.IP \(bu 2
\fBh\fR - move one cell to the left (aliases: \fB<Tab>\fR, \fB<Arrow-Left>\fR)
.IP \(bu 2
\fBj\fR - move one cell down (aliases: \fB<Arrow-Down>\fR)
.IP \(bu 2
\fBk\fR - move one cell up (alases: \fB<Arrow-Up>\fR)
.IP \(bu 2
\fBl\fR - move one cell to the right (aliases: \fB<Shift-Tab>\fR,
\fB<Arrow-Right>\fR)
.fi
.RE
.IP \(bu 2
Editing
.RS 2
.nf
.IP \(bu 2
\fB<Enter>\fR - increment the currently focused habit (aliases: \fBn\fR) \fB[f]\fR
.IP \(bu 2
\fB<Backspace>\fR - decrement the currently focused habit (aliases: \fBp\fR) \fB[f]\fR
.fi
.RE
.IP \(bu 2
Modes
.RS 2
.IP \(bu 2
\fBv\fR - enter \fBWEEK\fR mode for currently focused habit
\fB[f]\fR
.IP \(bu 2
\fBV\fR - enter \fBWEEK\fR mode for all habits
.IP \(bu 2
\fB<Esc>\fR - return to \fBDAY\fR mode
.RE
.IP \(bu 2
Time Travel
.RS 2
.IP \(bu 2
\fB[\fR - shift view port back by one month
.IP \(bu 2
\fB]\fR - shift view port forward by one month
.IP \(bu 2
\fB}\fR - return to present
.RE
.IP \(bu 2
Control
.RS 2
.IP \(bu 2
\fB<Ctrl-c>\fR - quit without saving (subject to change)
.RE
.SS Commandline
.PP
Enter the command mode with \fB:\fR. Type out a command and press \fB<Enter>\fR on the keyboard to execute it. Most commands have `aliases', or short forms. Command mode supports auto-complete also.
.IP \(bu 2
Help: show command syntax
.RS 2
.IP \(bu 2
Inputs: optional command or alias
.IP \(bu 2
Usage: \fBhelp [command]\fR
.IP \(bu 2
Example: \fB:help aa\fR
.IP \(bu 2
Aliases: \fBh\fR
.RE
.IP \(bu 2
Add: add a habit
.RS 2
.IP \(bu 2
Inputs: name of habit, optional daily goal
.IP \(bu 2
Usage: \fBadd <habit-name> [goal]\fR
.IP \(bu 2
Example: \fB:add french 5\fR
.IP \(bu 2
Aliases: \fBa\fR
.RE
.IP \(bu 2
Add Auto: add an auto-trackable habit
.RS 2
.IP \(bu 2
Inputs: name of habit, optional daily goal
.IP \(bu 2
Usage: \fBadd-auto <habit-name> [goal]\fR
.IP \(bu 2
Example: \fB:add-auto commits 5\fR
.IP \(bu 2
Aliases: \fBaa\fR
.RE
.IP \(bu 2
Delete: delete a habit
.RS 2
.IP \(bu 2
Inputs: name of habit to delete
.IP \(bu 2
Usage: \fBdelete <habit-name>\fR
.IP \(bu 2
Example: \fB:delete water\fR
.IP \(bu 2
Aliases: \fBd\fR
.RE
.IP \(bu 2
Month motions: stats from the past
.RS 2
.IP \(bu 2
Inputs: None
.IP \(bu 2
Usage: \fBmonth-prev\fR, \fBmonth-next\fR
.IP \(bu 2
Example: \fB:month-prev\fR
.IP \(bu 2
Aliases: \fBmprev\fR, \fBmnext\fR
.RE
.IP \(bu 2
Tracking: For use only with \fBdijo --command\fR, works only on
auto-habits
.RS 2
.IP \(bu 2
Inputs: name of habit to track up/down
.IP \(bu 2
Usage: \fBtrack-up <habit-name>\fR,
\fBtrack-down <habit-name>\fR
.IP \(bu 2
Example: \fB:track-up commits\fR
.IP \(bu 2
Aliases: \fBtup\fR, \fBtdown\fR
.RE
.IP \(bu 2
Write: write progress to disk
.RS 2
.IP \(bu 2
Inputs: None
.IP \(bu 2
Usage: \fBwrite\fR
.IP \(bu 2
Example: \fB:write\fR
.IP \(bu 2
Aliases: \fBw\fR
.RE
.IP \(bu 2
Quit: save and quit
.RS 2
.IP \(bu 2
Inputs: None
.IP \(bu 2
Usage: \fBquit\fR
.IP \(bu 2
Example: \fB:quit\fR
.IP \(bu 2
Aliases: \fBq\fR
.RE

.SH INTERNALS
.PP
This document delves into the internals of \fBdijo\fR.
.SS Files
.PP
After its first run, \fBdijo\fR creates three files on your file system, one to record habit data, \fBhabit_record.json\fR, one to record auto-habit data, \fBhabit_record[auto].json\fR, and one to store the default configuration in, \fBconfig.toml\fR. Data is saved in a human-readable format: JSON (a lot of work went into this). The config file is stored in TOML.

.SS Data files:
.PP
Making changes to these files while \fBdijo\fR is running, is not recommended (\fBdijo\fR will overwrite your changes on save).
.nf
.IP \(bu 2
GNU/Linux: \fB$XDG_DATA_HOME/dijo/*.json\fR
.IP \(bu 2
MacOS: \fB$HOME/Library/Application Support/rs.nerdypepper.dijo/*.json\fR
.IP \(bu 2
Win10: \fB{FOLDERID_RoamingAppData}\[rs]nerdypepper\[rs]dijo\[rs]data\[rs]*.json\fR
.fi

.SS Config files:
.PP
You can read more about configuring \fBdijo\fR at the Customization page.
.nf
.IP \(bu 2
GNU/Linux: \fB$XDG_CONFIG_HOME/dijo/config.toml\fR
.IP \(bu 2
MacOS: \fB$HOME/Library/Application Support/rs.nerdypepper.dijo/config.toml\fR
.IP \(bu 2
Win10: \fB{FOLDERID_RoamingAppData}\[rs]nerdypepper\[rs]dijo\[rs]config\[rs]config.toml\fR
.fi
.PP
\fBdijo\fR will not run on your computer if it can\[cq]t find your home directory.

.SS Data format
.PP
The general structure of a habit is as follows:
.IP
.nf
\fB
type  :: String,
name  :: String,
goal  :: HabitType,
auto  :: bool,
stats :: Map<Date, HabitType>
\fR
.fi
.PP
\fBHabitType\fR is the type of data to be tracked and it is a \fBbool\fR for bit-type habits and a \fBu32\fR for counting habits.

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

.SH AUTHOR
Akshay <[email protected]>

.SH SEE ALSO
.PP
\fIvi\fR(1), \fIvim\fR(1), \fInvim\fR(1), \fIjq\fR(1), \fIgit\fR(1)