xaizek / dit (License: GPLv3) (since 2018-12-07)
Command-line task keeper that remembers all old values and is meant to combine several orthogonal features to be rather flexible in managing items.
Clone URLs: https://code.reversed.top/user/xaizek/dit ssh://rocketgit@code.reversed.top/user/xaizek/dit
v0.10 v0.11 master
Commit 1387feab628513102fa2bbb7a7669c40274149a8

Keep generated man page in the repository
To not require pandoc for an installation.
Author: xaizek
Author date (UTC): 2019-01-09 11:46
Committer name: xaizek
Committer date (UTC): 2019-01-09 11:46
Parent(s): 226a2d9cc4d7ced2cf4356d020fec43e45bb6c55
Signing key: 99DC5E4DB05F6BE2
Tree: ddd2e8530d56ad70d93e5942333edfb3f81a253d
File Lines added Lines deleted
.gitignore 0 1
INSTALL.md 4 8
Makefile 5 7
README.md 1 1
docs/dit.1 797 0
File .gitignore changed (mode: 100644) (index 403f35d..0554c7b)
6 6 *.o *.o
7 7 /dit /dit
8 8 /tests/tests /tests/tests
9 /docs/dit.1
File INSTALL.md changed (mode: 100644) (index 392853e..885ae6d)
... ... Builds debug version in `debug/`.
13 13 Builds release version in `release/`. Builds release version in `release/`.
14 14
15 15 * `man` * `man`
16 Builds manual page in `<out>/docs/dit.1`, requires `pandoc`.
16 Builds manual page in `docs/dit.1`, requires `pandoc`.
17 17
18 18 * `coverage` * `coverage`
19 19 Builds coverage in `coverage/` putting report in `coverage/data/`. Requires Builds coverage in `coverage/` putting report in `coverage/data/`. Requires
 
... ... Removes build artifacts for all configurations.
30 30 Builds the application in release mode (`release` target) and installs it. Builds the application in release mode (`release` target) and installs it.
31 31 `DESTDIR` can be set to point to root of the installation directory. `DESTDIR` can be set to point to root of the installation directory.
32 32
33 * `install-docs`
34 Builds man page (`man` target) and installs it.
35 `DESTDIR` can be set to point to root of the installation directory.
36
37 33 * `uninstall` * `uninstall`
38 34 Removes files installed by the `install` target. Make sure to specify the same Removes files installed by the `install` target. Make sure to specify the same
39 35 `DESTDIR` as for installation. `DESTDIR` as for installation.
40 36
41 37 #### Documentation #### #### Documentation ####
42 38
43 Building a man-page requires `pandoc` to be installed.
39 Rebuilding a man-page requires `pandoc` to be installed.
44 40
45 41 ### Installation ### ### Installation ###
46 42
47 43 A regular installation under `/usr/bin` can be done like this: A regular installation under `/usr/bin` can be done like this:
48 44
49 45 ``` ```
50 make install install-docs
46 make install
51 47 ``` ```
52 48
53 49 Installation into custom directory (e.g. to make a package): Installation into custom directory (e.g. to make a package):
54 50
55 51 ``` ```
56 make DESTDIR=$PWD/build install install-docs
52 make DESTDIR=$PWD/build install
57 53 ``` ```
58 54
59 55 ### Uninstallation ### ### Uninstallation ###
File Makefile changed (mode: 100644) (index 8b1886b..310bf20)
... ... out_dirs := $(sort $(dir $(bin_objects) $(tests_objects)))
77 77
78 78 .PHONY: check clean man debug release .PHONY: check clean man debug release
79 79 .PHONY: coverage reset-coverage .PHONY: coverage reset-coverage
80 .PHONY: install install-docs uninstall
80 .PHONY: install uninstall
81 81
82 82 debug release: $(out_dir)/$(bin) debug release: $(out_dir)/$(bin)
83 83
84 man: $(out_dir)/docs/dit.1
85 $(out_dir)/docs/dit.1: $(wildcard docs/*.md) | $(out_dir)/docs
84 man: docs/dit.1
85 docs/dit.1: $(wildcard docs/*.md) | $(out_dir)/docs
86 86 pandoc -V title=dit \ pandoc -V title=dit \
87 87 -V section=1 \ -V section=1 \
88 88 -V app=dit \ -V app=dit \
 
... ... install: release
111 111 $(INSTALL) $(out_dir)/$(bin) $(DESTDIR)/usr/bin/$(bin) $(INSTALL) $(out_dir)/$(bin) $(DESTDIR)/usr/bin/$(bin)
112 112 $(INSTALL) -m 644 scripts/bash-completion \ $(INSTALL) -m 644 scripts/bash-completion \
113 113 $(DESTDIR)/usr/share/bash-completion/completions/dit $(DESTDIR)/usr/share/bash-completion/completions/dit
114
115 install-docs: man
116 $(INSTALL) -m 644 $(out_dir)/docs/dit.1 $(DESTDIR)/usr/share/man/man1/dit.1
114 $(INSTALL) -m 644 docs/dit.1 $(DESTDIR)/usr/share/man/man1/dit.1
117 115
118 116 uninstall: uninstall:
119 117 $(RM) $(DESTDIR)/usr/bin/$(bin) $(DESTDIR)/usr/share/man/man1/dit.1 \ $(RM) $(DESTDIR)/usr/bin/$(bin) $(DESTDIR)/usr/share/man/man1/dit.1 \
 
... ... $(out_dirs) $(out_dir)/docs:
136 134 clean: clean:
137 135 -$(RM) -r coverage/ debug/ release/ -$(RM) -r coverage/ debug/ release/
138 136 -$(RM) $(bin_objects) $(bin_depends) $(tests_objects) $(tests_depends) \ -$(RM) $(bin_objects) $(bin_depends) $(tests_objects) $(tests_depends) \
139 $(out_dir)/$(bin) $(out_dir)/tests/tests $(out_dir)/docs/dit.1
137 $(out_dir)/$(bin) $(out_dir)/tests/tests
140 138
141 139 include $(wildcard $(bin_depends) $(tests_depends)) include $(wildcard $(bin_depends) $(tests_depends))
File README.md changed (mode: 100644) (index 58f655c..1bd0f7a)
... ... Expected to work in \*nix like environments.
59 59 * [GNU Make][3]; * [GNU Make][3];
60 60 * C++11 compatible compiler (e.g. GCC 4.9.3); * C++11 compatible compiler (e.g. GCC 4.9.3);
61 61 * [Boost][4], tested with 1.54, 1.58 and 1.59; * [Boost][4], tested with 1.54, 1.58 and 1.59;
62 * (optional) [pandoc][5] for building man page.
62 * (optional) [pandoc][5] for regenerating man page.
63 63
64 64 ### Interaction with Environment ### ### Interaction with Environment ###
65 65
File docs/dit.1 added (mode: 100644) (index 0000000..6d40458)
1 .\" Automatically generated by Pandoc 1.17.0.3
2 .\"
3 .TH "dit" "1" "January 09, 2019" "" ""
4 .hy
5 .SH NAME
6 .PP
7 dit \- command\-line task keeper.
8 .SH SYNOPSIS
9 .PP
10 \f[C]dit\ [.<project>]\ [key=value]\ [key+=value]\ [<command>]\ [args...]\f[]
11 .PP
12 Broken down structure of the command\-line:
13 .IP
14 .nf
15 \f[C]
16 \ \ dit\ [.<project>]\ [key=value]\ [key+=value]\ [<command>]\ [args...]
17 \ \ \ |\ \ \ \ \ \ \ \ \ |\ \ \ \ \ \\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ /\ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ |
18 command\ \ \ \ \ \ |\ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \ |\ \ \ \ \ sub\-command
19 \ name\ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ arguments
20 \ \ \ \ \ \ \ \ \ optional\ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ sub\-command
21 \ \ \ \ \ \ \ project\-name\ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ name
22 \ \ \ \ \ \ \ (.\ ==\ defprj)\ \ \ \ configuration
23 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ overrides
24 \f[]
25 .fi
26 .PP
27 \f[C]<command>\f[] in turn can be a composite of commands/aliases:
28 .IP
29 .nf
30 \f[C]
31 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <command>.\ ...\ .<command>.<command>
32 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ /\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \\
33 \ \ \ \ \ \ \ \ \ \ \ \ \ \ applied\ last\ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ applied\ first
34 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ applied\ second
35 \f[]
36 .fi
37 .SH DESCRIPTION
38 .SS Overview
39 .PP
40 The overall hierarchical structure of data is as follows:
41 .IP
42 .nf
43 \f[C]
44 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-\-\-+
45 |\ \ \ Project\ A\ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ |\ \ Project\ X\ \ |
46 |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ .\ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ |
47 |\ Item\ a\ \ \ \ Item\ b\ \ |\ \ \ \ \ \ \ \ \ |\ \ Item\ a\ \ \ \ \ |
48 |\ \-\-\-\-\-\-\ \ \ \ \-\-\-\-\-\-\ \ |\ \ \ \ .\ \ \ \ |\ \ \-\-\-\-\-\-\ \ \ \ \ |
49 |\ entry1\ \ \ \ entry1\ \ |\ \ \ \ \ \ \ \ \ |\ \ entry1\ \ \ \ \ |
50 |\ entry2\ \ \ \ entry2\ \ |\ \ \ \ .\ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ |
51 |\ \ \ \ \ \ \ \ \ \ \ entry3\ \ |\ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ |
52 |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ |
53 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-\-\-+
54 \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |
55 \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-+
56 \ \ \ \ |\ Project\ A\ |\-\-\-\-\-\-\-+\-\-\-\-\-\-\-|\ Project\ B\ |
57 \ \ \ \ |\ \ Config\ \ \ |\ \ \ \ \ \ \ |\ \ \ \ \ \ \ |\ \ Config\ \ \ |
58 \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-+\ \ \ \ \ \ \ |\ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-+
59 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |
60 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ v
61 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
62 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ Global\ config\ \ |
63 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
64 \f[]
65 .fi
66 .SS Projects
67 .PP
68 Projects define storage namespace for items and configuration settings.
69 Project\-specific settings can override almost any of the global ones.
70 .PP
71 Project manages distribution of unique identifies among items
72 constituting it.
73 .SS IDs
74 .PP
75 Identifies are three character strings picked in semi\-randomised way
76 that guarantees that they won\[aq]t repeat.
77 The space is picked at the moment of project creation.
78 Each character can be one of 26 lower case and 26 upper case letters of
79 Latin alphabet.
80 IDs start as at the length of three and then automatically extended.
81 .SS Items
82 .PP
83 Each item in a project is uniquely identified by its symbolic ID.
84 Items consist of entries, which are key\-value pairs.
85 Removing of an entry is performed by assigning empty value to it.
86 .SS Entries
87 .PP
88 Users\[aq] key names start with one of \f[C][a\-zA\-Z]\f[] characters
89 and are followed by any of \f[C][\-a\-zA\-Z_0\-9]\f[].
90 Builtin keys start with \f[C]_\f[].
91 .PP
92 Currently available builtin keys:
93 .IP \[bu] 2
94 \f[C]_id\f[] \-\- identifier of the item;
95 .IP \[bu] 2
96 \f[C]_created\f[] \-\- creation date and time of the item;
97 .IP \[bu] 2
98 \f[C]_changed\f[] \-\- date and time the item was last changed.
99 .PP
100 Values can contain arbitrary strings, which might include newline
101 characters.
102 .SS Changes
103 .PP
104 When a change is made to an entry, instead of actually overwriting an
105 old value with a new one, new one just hides old value keeping whole
106 history of item changes available for the future.
107 .SH COMMANDS
108 .SS Generic syntax elements
109 .PP
110 There are two big groups of commands:
111 .IP "1." 3
112 Commands that operate on elements.
113 .IP "2." 3
114 The rest of commands.
115 .PP
116 First group of commands usually accepts an item id and sometimes list of
117 fields to create or update.
118 Second group generally has less commonalities.
119 .SS List of fields
120 .PP
121 The list specifies operations on entries of an item.
122 There are two kinds of operations:
123 .IP \[bu] 2
124 assigning
125 .IP \[bu] 2
126 appending (added on a new line)
127 .PP
128 Where assigning to empty value means removal.
129 .PP
130 There are also two types of syntax which can be used simultaneously:
131 .IP \[bu] 2
132 key=value
133 .IP \[bu] 2
134 key: value
135 .PP
136 The first kind suits well for simple values without any special
137 characters or spaces, while the second one is great for all other cases.
138 Due to the way shell works, on completion the second syntax is used
139 (otherwise it\[aq]s not convenient to type the rest of the value after
140 completion because of an extra space).
141 .SS List of fields: "key=value" and "key+=value"
142 .PP
143 One can use shell parsing capabilities to insert values with spaces or
144 special symbols:
145 .IP
146 .nf
147 \f[C]
148 status=done
149 status=\[aq]in\ progress\[aq]
150 status=to\\\ be\\\ considered
151 title="Doesn\[aq]t\ work\ with\ \\$PATH\ =\ $PATH"
152 \f[]
153 .fi
154 .SS List of fields: "key: long value"
155 .PP
156 This form is easier to type as there is no quotes around values.
157 .IP
158 .nf
159 \f[C]
160 status:\ done
161 status:\ in\ progress
162 status:\ to\ be\ considered
163 title:\ Doesn\\\[aq]t\ work\ with\ \\$PATH\ =\ "$PATH"
164 \f[]
165 .fi
166 .PP
167 During parsing contiguous spaces are contracted into single one.
168 .SS List of fields: How ambiguity is resolved
169 .PP
170 If an argument includes \f[C]=\f[] character and what precedes it is a
171 valid key name, then it\[aq]s assumed to be "key=value" form of
172 argument.
173 Otherwise it must end with a colon to be key name or be preceded by such
174 argument.
175 .PP
176 Such rules help with parsing the following strings as values:
177 .IP
178 .nf
179 \f[C]
180 2+2=4
181 http://example.com/script?param=value
182 \f[]
183 .fi
184 .SS List of fields: Requesting spawning external editor
185 .PP
186 When assigning a value to a key, it\[aq]s possible to specify special
187 value of \f[B]\-\f[] (single dash character), which instructs the
188 application to spawn editor to update corresponding field.
189 .PP
190 On appending editor contains previous value of the field is used as
191 starting value.
192 Once editor is closed, contents of the file is read.
193 .PP
194 Example:
195 .IP
196 .nf
197 \f[C]
198 dit\ set\ abc\ assign=\-\ append+=\-\ assign_another_field:\ \-
199 \f[]
200 .fi
201 .SS List of conditions
202 .PP
203 This is list of arguments where each argument is a comparison expression
204 of the form:
205 .IP
206 .nf
207 \f[C]
208 key\ op\ value
209 \f[]
210 .fi
211 .PP
212 \f[I]key\f[] and \f[I]value\f[] are two parts of an entry.
213 \f[I]op\f[] is one of:
214 .IP \[bu] 2
215 \f[B]==\f[] \-\- \f[I]key\f[] is equal to the \f[I]value\f[]
216 .IP \[bu] 2
217 \f[B]!=\f[] \-\- \f[I]key\f[] is not equal to the \f[I]value\f[]
218 .IP \[bu] 2
219 \f[B]/\f[] or \f[B]=/\f[] \-\- \f[I]key\f[] contains \f[I]value\f[]
220 (case is ignored)
221 .IP \[bu] 2
222 \f[B]#\f[] or \f[B]!/\f[] \-\- \f[I]key\f[] doesn\[aq]t contain
223 \f[I]value\f[] (case is ignored)
224 .PP
225 Extra spaces are allowed, but don\[aq]t forget to escape them (with \\
226 or quotes).
227 .PP
228 Key in a condition can be a pseudo value "_any" which matches with any
229 existing field of an item.
230 .SS Command composition
231 .PP
232 When given command in the form of
233 \f[C]<command>.\ ...\ .<command>.<command>\f[] here\[aq]s what happens.
234 .PP
235 Components are processed from right to left with aliases being expanded
236 (commands are just expanded to themselve).
237 Each alias can be viewed as three components: configuration overrides,
238 command name and arguments.
239 For each alias its components are mixed into current command\-line as
240 follows:
241 .IP "1." 3
242 overrides = overrides + alias overrides (appended)
243 .IP "2." 3
244 Command name from an alias is new command name.
245 .IP "3." 3
246 arguments = expanded alias + extra arguments (prepended)
247 .PP
248 \f[C]expanded\ alias\f[] is created by applying alias to current
249 argument list.
250 \f[C]extra\ arguments\f[] are all arguments unused by the alias.
251 .PP
252 One of the commands can be empty (as in \f[C]\&.cmd\f[],
253 \f[C]cmd1..cmd2\f[] or \f[C]cmd.\f[]), in which case it designates
254 default command line, which is expanded at that point of processing.
255 Note that leading dot can be taken as indication of project name, and
256 thus should be used with project specified explicitly.
257 As a special case single dot as a command (\f[C]\&.\f[]) is expanded
258 into default command line (this is the same as empty command name
259 (\f[C]\[aq]\[aq]\f[]), but easier to type).
260 .PP
261 For example, the following aliases:
262 .IP
263 .nf
264 \f[C]
265 alias.recent\ =\ ui.ls.sort=_changed,title,_id
266 alias.dates\ =\ ui.ls.fmt+=,_created,_changed
267 alias.standout\ =\ ls\ status!=done
268 \f[]
269 .fi
270 .PP
271 combined as \f[C]recent.standout\f[] or \f[C]standout.recent\f[]
272 (doesn\[aq]t matter in this case) yield the following command\-line:
273 .IP
274 .nf
275 \f[C]
276 ui.ls.sort=_changed,title,_id\ alias.standout\ =\ ls\ status!=done
277 \f[]
278 .fi
279 .PP
280 \f[C]recent.dates.ls\f[] produces:
281 .IP
282 .nf
283 \f[C]
284 ui.ls.sort=_changed,title,_id\ ui.ls.fmt+=,_created,_changed\ ls
285 \f[]
286 .fi
287 .SH CONFIGURATION
288 .SS Hierarchy of configurations
289 .PP
290 The lookup is performed from left to right according to the following
291 diagram:
292 .IP
293 .nf
294 \f[C]
295 Overrides\ \-\->\ Project\ \-\->\ Global\ \-\->\ Application\ Default
296 \f[]
297 .fi
298 .PP
299 Thus options given on the command\-line are the most prioritized, then
300 project\-specific settings are queried, then global configuration and
301 defaults are used if nothing specifies the value.
302 .SS Accessing settings
303 .PP
304 \f[B]config\f[] command is there to view and change settings.
305 By default project\-specific settings are used, but \f[B]\-\-global\f[]
306 option switches to global configuration.
307 .SS Setting names
308 .PP
309 Settings starting with \f[B]!\f[] are reserved for internal purposes and
310 can\[aq]t be accessed via \f[B]config\f[].
311 .PP
312 Setting key is a dot\-separated sequence of section names.
313 It can\[aq]t be empty.
314 .SS Configuration overrides
315 .PP
316 These are command\-line arguments between project name and command (all
317 of these are optional, so they might go first and not be followed by
318 anything) of the form:
319 .IP \[bu] 2
320 \f[C]key=value\f[] \-\- sets new value
321 .IP \[bu] 2
322 \f[C]key+=value\f[] \-\- appends to existing value
323 .PP
324 Such settings are temporary and not saved anywhere, project\-specific or
325 global configurations should be used for persistent settings.
326 These are good for tests and use with aliases.
327 .SS Aliases
328 .PP
329 Aliases can only be set in global configuration, otherwise they are
330 ignored.
331 .PP
332 Alias name can match name of a builtin command.
333 .PP
334 Aliases must be defined in \f[I]alias\f[] section, e.g.
335 \f[I]alias.standout\f[].
336 .PP
337 Alias can consume arguments, their placeholders have the form:
338 \f[B]{}\f[], numbering starts with 1.
339 Unused arguments are appended.
340 .PP
341 Example:
342 .IP
343 .nf
344 \f[C]
345 dit\ config\ \-\-global\ alias.take\ =\ set\ ${1}\ status=\[aq]in\ progress\[aq]
346 dit\ take\ id\ comment+=\[aq]Done,\ finally.\[aq]
347 #\ equivalent\ to:\ dit\ set\ id\ status=\[aq]in\ progress\[aq]\ comment+=\[aq]Done,\ finally.\[aq]
348 \f[]
349 .fi
350 .SS Removing values
351 .PP
352 Removal is performed by reseting key to empty value, which will enable
353 use of application default value or value from the previous level if
354 such values exist.
355 .PP
356 Example:
357 .IP
358 .nf
359 \f[C]
360 dit\ config\ ui.lf.fmt=
361 \f[]
362 .fi
363 .SS List of all settings
364 .PP
365 \f[B]core.defcmd\f[] (global) (default: \f[C]ls\f[]) \-\- names command
366 to be used on invocation without arguments.
367 .PP
368 \f[B]core.defprj\f[] (global) (no default) \-\- names project to use if
369 none was specified.
370 .PP
371 \f[B]core.pager\f[] (global) (default: \f[C]$PAGER\f[] or
372 \f[C]less\ \-R\f[]) \-\- command to be used to start a pager when output
373 doesn\[aq]t fit on one screen.
374 .PP
375 \f[B]defaults.\f[]* (no defaults) \-\- default values for newly created
376 items.
377 Configuration on project level completely hides global one.
378 .PP
379 \f[B]guards.newitem\f[] (no default) \-\- condition ("List of
380 conditions" like for \f[B]ls\f[] command) evaluated for fields of a new
381 item.
382 If this condition is not satisfied, item creation aborts.
383 .PP
384 \f[B]prj.descr\f[] (no default) \-\- project description for
385 \f[B]projects\f[] command.
386 .PP
387 \f[B]ui.ls.fmt\f[] (default: \f[C]_id,title\f[]) \-\- column
388 specification for \f[B]ls\f[] command.
389 .PP
390 \f[B]ui.ls.sort\f[] (default: \f[C]title,_id\f[]) \-\- item sorting
391 specification for \f[B]ls\f[] command.
392 .PP
393 \f[B]ui.ls.color\f[] (default: \f[C]fg\-cyan\ inv\ bold\ !heading\f[])
394 \-\- item colorization rules for \f[B]ls\f[] command.
395 .PP
396 \f[B]ui.show.order\f[] (default: \f[C]title\f[]) \-\- entries ordering
397 specification for \f[B]show\f[] command.
398 .SS ui.ls.fmt syntax
399 .PP
400 Comma\-separated list of keys, which define columns of table printed out
401 by \f[B]ls\f[] command.
402 .SS ui.ls.sort syntax
403 .PP
404 Comma\-separated list of keys.
405 First key is the primary one, its subgroups are sorted by the second key
406 and so on (i.e., items are sorted by keys in right to left order
407 preserving relative ordering from previous sorts).
408 .SS ui.ls.color syntax
409 .PP
410 Semicolon\-separated list of colorization rules.
411 Each rule has the following structure:
412 .IP
413 .nf
414 \f[C]
415 attributes\ conditions
416 \f[]
417 .fi
418 .PP
419 Attributes can include:
420 .IP \[bu] 2
421 \f[B]bold\f[], \f[B]inv\f[], \f[B]def\f[];
422 .IP \[bu] 2
423 \f[B]fg\-black\f[], \f[B]fg\-red\f[], \f[B]fg\-green\f[],
424 \f[B]fg\-yellow\f[], \f[B]fg\-blue\f[], \f[B]fg\-magenta\f[],
425 \f[B]fg\-cyan\f[], \f[B]fg\-white\f[];
426 .IP \[bu] 2
427 \f[B]bg\-black\f[], \f[B]bg\-red\f[], \f[B]bg\-green\f[],
428 \f[B]bg\-yellow\f[], \f[B]bg\-blue\f[], \f[B]bg\-magenta\f[],
429 \f[B]bg\-cyan\f[], \f[B]bg\-white\f[].
430 .PP
431 Conditions are either of:
432 .IP \[bu] 2
433 \f[B]!heading\f[] \-\- header of the table;
434 .IP \[bu] 2
435 any condition as in list of conditions.
436 .SS ui.show.order syntax
437 .PP
438 Comma\-separated list of keys.
439 Keys mentioned in this option are displayed above any other keys and in
440 this order, the rest keys of an item follow in alphabetical order.
441 .SH LIST OF COMMANDS
442 .SS add
443 .PP
444 Adds new item.
445 .PP
446 \f[B]Usage: add <list of fields>\f[]
447 .PP
448 Creates new item filling it with specified entries.
449 .SS check
450 .PP
451 Verifies project state.
452 .PP
453 \f[B]Usage: check\f[]
454 .PP
455 Checks that storage files and their content are meaningful.
456 Prints out errors if something is wrong and exits with non\-zero exit
457 code.
458 .SS complete
459 .PP
460 Provides command\-line completion helper for shells.
461 .PP
462 \f[B]Usage: complete <regular args>\f[]
463 .PP
464 Takes normal command\-line with trailing \f[I]::cursor::\f[] designating
465 cursor position.
466 The marker is needed to complete empty argument, which otherwise might
467 be dropped by the shell on invocation.
468 .SS config
469 .PP
470 Displays/updates configuration.
471 .PP
472 \f[B]Usage: config [\-\-help|\-h] [\-\-global|\-g] <list of fields>\f[]
473 .PP
474 \f[B]\-\-help (\-h)\f[] causes option summary to be printed.
475 .PP
476 \f[B]\-\-global (\-g)\f[] switches operations to act on global
477 configuration, whereas by default project\-specific configuration is
478 processed.
479 .PP
480 When invoked without arguments, all values are displayed.
481 .PP
482 When invoked with at least one argument:
483 .IP \[bu] 2
484 Keys without values are displayed.
485 .IP \[bu] 2
486 Keys with values are updated.
487 Setting is removed on assigning it empty value.
488 .PP
489 Special value \f[B]\-\f[] can be used to request spawning external
490 editor.
491 .SS export
492 .PP
493 Invokes external script passing item data via argument list.
494 .PP
495 \f[B]Usage: export (\-|cmd) <list of conditions>\f[]
496 .PP
497 Invokes \f[B]cmd key1=value1 key2=value2\f[] for each item that matches
498 given list of conditions or prints out items to standard output with
499 \f[B]key=value\f[] fields terminated by null character and each item
500 also finished by null character.
501 Builtin key \f[C]_id\f[] is also printed.
502 .SS help
503 .PP
504 Provides help information.
505 .PP
506 \f[B]Usage: help [command]\f[]
507 .PP
508 Without arguments displays summary of available commands.
509 .PP
510 With argument displays summary on that command.
511 .SS log
512 .PP
513 Displays item changes.
514 .PP
515 \f[B]Usage: log [\-\-help|\-h] [\-\-timestamps|\-t] <item id>
516 [<key>...]\f[]
517 .PP
518 \f[B]\-\-help (\-h)\f[] causes option summary to be printed.
519 .PP
520 \f[B]\-\-timestamps (\-t)\f[] adds timestamp to each change printed.
521 .PP
522 Displays information about item changes (from oldest to newest) either
523 for all fields (if only item id is specified) or just for the specified
524 ones.
525 .SS ls
526 .PP
527 Lists items.
528 .PP
529 \f[B]Usage: ls <list of conditions>\f[]
530 .PP
531 Print table of items that match the list of conditions.
532 .PP
533 Affected by: \f[B]ui.ls.fmt\f[], \f[B]ui.ls.sort\f[],
534 \f[B]ui.ls.color\f[].
535 .SS new
536 .PP
537 Creates new project.
538 .PP
539 \f[B]Usage: new <project name>\f[]
540 .PP
541 Initializes new project.
542 .SS projects
543 .PP
544 Lists projects.
545 .PP
546 \f[B]Usage: projects\f[]
547 .PP
548 Lists projects along with their descriptions (\f[B]prj.descr\f[]).
549 Picked project is marked with a star (*).
550 .SS rename
551 .PP
552 Renames a project.
553 .PP
554 \f[B]Usage: rename <old name> <new name>\f[]
555 .PP
556 Renames existing project.
557 .SS set
558 .PP
559 Changes items.
560 .PP
561 \f[B]Usage: set <item id> <list of fields>\f[]
562 .PP
563 Updates entries of existing item.
564 .SS show
565 .PP
566 Displays items.
567 .PP
568 \f[B]Usage: show <item id> [<key>...]\f[]
569 .PP
570 Prints entries of specified item, either all fields (if only item id is
571 specified) or just for the specified ones.
572 .PP
573 Affected by: \f[B]ui.show.order\f[].
574 .SS values
575 .PP
576 Displays values of a key.
577 .PP
578 \f[B]Usage: values <key>\f[]
579 .PP
580 Prints all values that appear associated with the given key to at least
581 one item.
582 .SH TIPS
583 .SS Install and use bash completion
584 .PP
585 Bash completion script is installed in standard location and should work
586 automatically.
587 Lots of things are completed in a predictable and helpful manner, so be
588 sure to use the completion as it helps a great deal.
589 .SS Create aliases for frequently used projects
590 .PP
591 Example:
592 .IP
593 .nf
594 \f[C]
595 alias\ d.d=\[aq]dit\ .dit\[aq]
596 alias\ d.v=\[aq]dit\ .vifm\[aq]
597 \f[]
598 .fi
599 .PP
600 Using dot as a separated might be better for using \f[C]Ctrl\-W\f[] with
601 shell configuration that stops at a dot.
602 .PP
603 Creating an alias for \f[C]dit\f[] itself won\[aq]t hurt either:
604 .IP
605 .nf
606 \f[C]
607 alias\ d=\[aq]dit\[aq]
608 \f[]
609 .fi
610 .PP
611 Note that this can break completion if there are not workarounds like
612 the one mentioned in http://superuser.com/a/437508.
613 Another option is to define completion manually for the alias like this:
614 .IP
615 .nf
616 \f[C]
617 complete\ \-F\ _dit\ d
618 \f[]
619 .fi
620 .PP
621 This won\[aq]t work right away with \f[C]d.d\f[] and \f[C]d.v\f[] above
622 as they take project name argument.
623 .SH EXAMPLE
624 .PP
625 Below is an example sequence of commands that demonstrates basic usage.
626 .PP
627 Assuming absent configuration, there isn\[aq]t much one can do:
628 .IP
629 .nf
630 \f[C]
631 $\ dit
632 No\ project\ specified
633 $\ dit\ projects
634 \f[]
635 .fi
636 .PP
637 Create first project:
638 .IP
639 .nf
640 \f[C]
641 $\ dit\ new\ test
642 $\ dit
643 No\ project\ specified
644 $\ dit\ projects
645 \ test
646 $\ dit\ .test
647 ID\ \ TITLE
648 \f[]
649 .fi
650 .PP
651 Setup the \f[C]test\f[] project to be the default one to omit
652 \f[C]\&.test\f[] part:
653 .IP
654 .nf
655 \f[C]
656 $\ dit\ config\ \-\-global\ core.defprj:\ test
657 $\ dit
658 ID\ \ TITLE
659 \f[]
660 .fi
661 .PP
662 Now add simple task:
663 .IP
664 .nf
665 \f[C]
666 $\ dit\ add\ title:\ Explore\ dit.
667 Created\ item:\ fqH
668 $\ dit
669 ID\ \ \ TITLE
670 fqH\ \ Explore\ dit.
671 \f[]
672 .fi
673 .PP
674 Modify its field:
675 .IP
676 .nf
677 \f[C]
678 $\ dit\ set\ fqH\ status:\ in\ progress
679 \f[]
680 .fi
681 .PP
682 It\[aq]s not visible via \f[C]ls\f[] (the default subcommand), but
683 it\[aq]s there:
684 .IP
685 .nf
686 \f[C]
687 $\ dit
688 ID\ \ \ TITLE
689 fqH\ \ Explore\ dit.
690 $\ dit\ show\ fqH
691 title:\ Explore\ dit.
692 status:\ in\ progress
693 \f[]
694 .fi
695 .PP
696 To display it via \f[C]ls\f[], configuration must be altered a bit:
697 .IP
698 .nf
699 \f[C]
700 $\ dit\ config\ ui.ls.fmt:\ _id,title,status
701 $\ dit
702 ID\ \ \ TITLE\ \ \ \ \ \ \ \ \ STATUS
703 fqH\ \ Explore\ dit.\ \ in\ progress
704 \f[]
705 .fi
706 .PP
707 One might want to ease taking tasks and marking them as done later, this
708 is where aliases can be used:
709 .IP
710 .nf
711 \f[C]
712 $\ dit\ config\ \-\-global\ alias.done=\[aq]set\ ${1}\ status=done\[aq]
713 $\ dit\ config\ \-\-global\ alias.take=\[aq]set\ ${1}\ status="in\ progress"\[aq]
714 $\ dit\ done\ fqH
715 $\ dit
716 ID\ \ \ TITLE\ \ \ \ \ \ \ \ \ STATUS
717 fqH\ \ Explore\ dit.\ \ done
718 \f[]
719 .fi
720 .PP
721 Usually, there is no need to see tasks that are already done and
722 \f[C]ls\f[] command drops them from the output if asked:
723 .IP
724 .nf
725 \f[C]
726 $\ dit\ ls\ status!=done
727 ID\ \ TITLE\ \ STATUS
728 \f[]
729 .fi
730 .PP
731 Not very easy to type, so let\[aq]s make an alias and set it as new
732 default command:
733 .IP
734 .nf
735 \f[C]
736 $\ dit\ config\ \-\-global\ alias.standout=\[aq]ls\ status!=done\[aq]
737 $\ dit\ config\ \-\-global\ core.defcmd:\ standout
738 $\ dit
739 ID\ \ TITLE\ \ STATUS
740 $\ dit\ ls
741 ID\ \ \ TITLE\ \ \ \ \ \ \ \ \ STATUS
742 fqH\ \ Explore\ dit.\ \ done
743 \f[]
744 .fi
745 .PP
746 It\[aq]s sometimes handy to add additional columns to the table, aliases
747 can help here as well:
748 .IP
749 .nf
750 \f[C]
751 $\ dit\ config\ \-\-global\ alias.dates=\[aq]ui.ls.fmt+=,_created,_changed\[aq]
752 $\ dit\ ls.dates
753 ID\ \ \ TITLE\ \ \ \ \ \ \ \ \ STATUS\ \ CREATED\ \ \ \ \ \ \ \ \ \ \ \ \ \ CHANGED
754 fqH\ \ Explore\ dit.\ \ done\ \ \ \ 2016\-02\-05\ 12:31:25\ \ 2016\-02\-05\ 13:07:51
755 \f[]
756 .fi
757 .PP
758 If at some later moment one wants to view history of a task, use
759 \f[C]log\f[]:
760 .IP
761 .nf
762 \f[C]
763 $\ dit\ log\ fqH
764 title\ created:\ Explore\ dit.
765 status\ created:\ in\ progress
766 status\ changed:
767 \-in\ progress
768 +done
769 \f[]
770 .fi
771 .PP
772 And so on...
773 .PP
774 Combination of aliases and key\-value pairs allow for implementation of
775 wide range of possible workflows, one only needs to adjust them
776 accordingly.
777 .SH FILES
778 .PP
779 \f[B]$XDG_CONFIG_HOME/dit\f[] \-\- location of configuration/data
780 directory.
781 .PP
782 \f[B]~/.config/dit\f[] \-\- location used if \f[B]XDG_CONFIG_HOME\f[] is
783 invalid.
784 .SH ENVIRONMENT
785 .PP
786 \f[B]XDG_CONFIG_HOME\f[] \-\- checked first to determine location of
787 configuration/data.
788 .PP
789 \f[B]HOME\f[] \-\- checked second to determine location of
790 configuration/data.
791 .PP
792 \f[B]EDITOR\f[] \-\- used to perform external editing of values.
793 .PP
794 \f[B]PAGER\f[] \-\- used as a default for displaying output which
795 doesn\[aq]t fit on the screen.
796 .SH AUTHORS
797 xaizek <xaizek@posteo.net>.
Hints
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://code.reversed.top/user/xaizek/dit

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@code.reversed.top/user/xaizek/dit

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a pull request:
... clone the repository ...
... make some changes and some commits ...
git push origin master