.\" Automatically generated by Pandoc 1.17.0.3
.\"
.TH "dit" "1" "January 09, 2019" "" ""
.hy
.SH NAME
.PP
dit \- command\-line task keeper.
.SH SYNOPSIS
.PP
\f[C]dit\ [.<project>]\ [key=value]\ [key+=value]\ [<command>]\ [args...]\f[]
.PP
Broken down structure of the command\-line:
.IP
.nf
\f[C]
\ \ dit\ [.<project>]\ [key=value]\ [key+=value]\ [<command>]\ [args...]
\ \ \ |\ \ \ \ \ \ \ \ \ |\ \ \ \ \ \\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ /\ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ |
command\ \ \ \ \ \ |\ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \ |\ \ \ \ \ sub\-command
\ name\ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ arguments
\ \ \ \ \ \ \ \ \ optional\ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ sub\-command
\ \ \ \ \ \ \ project\-name\ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ name
\ \ \ \ \ \ \ (.\ ==\ defprj)\ \ \ \ configuration
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ overrides
\f[]
.fi
.PP
\f[C]<command>\f[] in turn can be a composite of commands/aliases:
.IP
.nf
\f[C]
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <command>.\ ...\ .<command>.<command>
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ /\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \\
\ \ \ \ \ \ \ \ \ \ \ \ \ \ applied\ last\ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ applied\ first
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ applied\ second
\f[]
.fi
.SH DESCRIPTION
.SS Overview
.PP
The overall hierarchical structure of data is as follows:
.IP
.nf
\f[C]
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-\-\-+
|\ \ \ Project\ A\ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ |\ \ Project\ X\ \ |
|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ .\ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ |
|\ Item\ a\ \ \ \ Item\ b\ \ |\ \ \ \ \ \ \ \ \ |\ \ Item\ a\ \ \ \ \ |
|\ \-\-\-\-\-\-\ \ \ \ \-\-\-\-\-\-\ \ |\ \ \ \ .\ \ \ \ |\ \ \-\-\-\-\-\-\ \ \ \ \ |
|\ entry1\ \ \ \ entry1\ \ |\ \ \ \ \ \ \ \ \ |\ \ entry1\ \ \ \ \ |
|\ entry2\ \ \ \ entry2\ \ |\ \ \ \ .\ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ |
|\ \ \ \ \ \ \ \ \ \ \ entry3\ \ |\ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ |
|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-\-\-+
\ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |
\ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-+
\ \ \ \ |\ Project\ A\ |\-\-\-\-\-\-\-+\-\-\-\-\-\-\-|\ Project\ B\ |
\ \ \ \ |\ \ Config\ \ \ |\ \ \ \ \ \ \ |\ \ \ \ \ \ \ |\ \ Config\ \ \ |
\ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-+\ \ \ \ \ \ \ |\ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-+
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ v
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ Global\ config\ \ |
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\f[]
.fi
.SS Projects
.PP
Projects define storage namespace for items and configuration settings.
Project\-specific settings can override almost any of the global ones.
.PP
Project manages distribution of unique identifies among items
constituting it.
.SS IDs
.PP
Identifies are three character strings picked in semi\-randomised way
that guarantees that they won\[aq]t repeat.
The space is picked at the moment of project creation.
Each character can be one of 26 lower case and 26 upper case letters of
Latin alphabet.
IDs start as at the length of three and then automatically extended.
.SS Items
.PP
Each item in a project is uniquely identified by its symbolic ID.
Items consist of entries, which are key\-value pairs.
Removing of an entry is performed by assigning empty value to it.
.SS Entries
.PP
Users\[aq] key names start with one of \f[C][a\-zA\-Z]\f[] characters
and are followed by any of \f[C][\-a\-zA\-Z_0\-9]\f[].
Builtin keys start with \f[C]_\f[].
.PP
Currently available builtin keys:
.IP \[bu] 2
\f[C]_id\f[] \-\- identifier of the item;
.IP \[bu] 2
\f[C]_created\f[] \-\- creation date and time of the item;
.IP \[bu] 2
\f[C]_changed\f[] \-\- date and time the item was last changed.
.PP
Values can contain arbitrary strings, which might include newline
characters.
.SS Changes
.PP
When a change is made to an entry, instead of actually overwriting an
old value with a new one, new one just hides old value keeping whole
history of item changes available for the future.
.SH COMMANDS
.SS Generic syntax elements
.PP
There are two big groups of commands:
.IP "1." 3
Commands that operate on elements.
.IP "2." 3
The rest of commands.
.PP
First group of commands usually accepts an item id and sometimes list of
fields to create or update.
Second group generally has less commonalities.
.SS List of fields
.PP
The list specifies operations on entries of an item.
There are two kinds of operations:
.IP \[bu] 2
assigning
.IP \[bu] 2
appending (added on a new line)
.PP
Where assigning to empty value means removal.
.PP
There are also two types of syntax which can be used simultaneously:
.IP \[bu] 2
key=value
.IP \[bu] 2
key: value
.PP
The first kind suits well for simple values without any special
characters or spaces, while the second one is great for all other cases.
Due to the way shell works, on completion the second syntax is used
(otherwise it\[aq]s not convenient to type the rest of the value after
completion because of an extra space).
.SS List of fields: "key=value" and "key+=value"
.PP
One can use shell parsing capabilities to insert values with spaces or
special symbols:
.IP
.nf
\f[C]
status=done
status=\[aq]in\ progress\[aq]
status=to\\\ be\\\ considered
title="Doesn\[aq]t\ work\ with\ \\$PATH\ =\ $PATH"
\f[]
.fi
.SS List of fields: "key: long value"
.PP
This form is easier to type as there is no quotes around values.
.IP
.nf
\f[C]
status:\ done
status:\ in\ progress
status:\ to\ be\ considered
title:\ Doesn\\\[aq]t\ work\ with\ \\$PATH\ =\ "$PATH"
\f[]
.fi
.PP
During parsing contiguous spaces are contracted into single one.
.SS List of fields: How ambiguity is resolved
.PP
If an argument includes \f[C]=\f[] character and what precedes it is a
valid key name, then it\[aq]s assumed to be "key=value" form of
argument.
Otherwise it must end with a colon to be key name or be preceded by such
argument.
.PP
Such rules help with parsing the following strings as values:
.IP
.nf
\f[C]
2+2=4
http://example.com/script?param=value
\f[]
.fi
.SS List of fields: Requesting spawning external editor
.PP
When assigning a value to a key, it\[aq]s possible to specify special
value of \f[B]\-\f[] (single dash character), which instructs the
application to spawn editor to update corresponding field.
.PP
On appending editor contains previous value of the field is used as
starting value.
Once editor is closed, contents of the file is read.
.PP
Example:
.IP
.nf
\f[C]
dit\ set\ abc\ assign=\-\ append+=\-\ assign_another_field:\ \-
\f[]
.fi
.SS List of conditions
.PP
This is list of arguments where each argument is a comparison expression
of the form:
.IP
.nf
\f[C]
key\ op\ value
\f[]
.fi
.PP
\f[I]key\f[] and \f[I]value\f[] are two parts of an entry.
\f[I]op\f[] is one of:
.IP \[bu] 2
\f[B]==\f[] \-\- \f[I]key\f[] is equal to the \f[I]value\f[]
.IP \[bu] 2
\f[B]!=\f[] \-\- \f[I]key\f[] is not equal to the \f[I]value\f[]
.IP \[bu] 2
\f[B]/\f[] or \f[B]=/\f[] \-\- \f[I]key\f[] contains \f[I]value\f[]
(case is ignored)
.IP \[bu] 2
\f[B]#\f[] or \f[B]!/\f[] \-\- \f[I]key\f[] doesn\[aq]t contain
\f[I]value\f[] (case is ignored)
.PP
Extra spaces are allowed, but don\[aq]t forget to escape them (with \\
or quotes).
.PP
Key in a condition can be a pseudo value "_any" which matches with any
existing field of an item.
.SS Command composition
.PP
When given command in the form of
\f[C]<command>.\ ...\ .<command>.<command>\f[] here\[aq]s what happens.
.PP
Components are processed from right to left with aliases being expanded
(commands are just expanded to themselve).
Each alias can be viewed as three components: configuration overrides,
command name and arguments.
For each alias its components are mixed into current command\-line as
follows:
.IP "1." 3
overrides = overrides + alias overrides (appended)
.IP "2." 3
Command name from an alias is new command name.
.IP "3." 3
arguments = expanded alias + extra arguments (prepended)
.PP
\f[C]expanded\ alias\f[] is created by applying alias to current
argument list.
\f[C]extra\ arguments\f[] are all arguments unused by the alias.
.PP
One of the commands can be empty (as in \f[C]\&.cmd\f[],
\f[C]cmd1..cmd2\f[] or \f[C]cmd.\f[]), in which case it designates
default command line, which is expanded at that point of processing.
Note that leading dot can be taken as indication of project name, and
thus should be used with project specified explicitly.
As a special case single dot as a command (\f[C]\&.\f[]) is expanded
into default command line (this is the same as empty command name
(\f[C]\[aq]\[aq]\f[]), but easier to type).
.PP
For example, the following aliases:
.IP
.nf
\f[C]
alias.recent\ =\ ui.ls.sort=_changed,title,_id
alias.dates\ =\ ui.ls.fmt+=,_created,_changed
alias.standout\ =\ ls\ status!=done
\f[]
.fi
.PP
combined as \f[C]recent.standout\f[] or \f[C]standout.recent\f[]
(doesn\[aq]t matter in this case) yield the following command\-line:
.IP
.nf
\f[C]
ui.ls.sort=_changed,title,_id\ alias.standout\ =\ ls\ status!=done
\f[]
.fi
.PP
\f[C]recent.dates.ls\f[] produces:
.IP
.nf
\f[C]
ui.ls.sort=_changed,title,_id\ ui.ls.fmt+=,_created,_changed\ ls
\f[]
.fi
.SH CONFIGURATION
.SS Hierarchy of configurations
.PP
The lookup is performed from left to right according to the following
diagram:
.IP
.nf
\f[C]
Overrides\ \-\->\ Project\ \-\->\ Global\ \-\->\ Application\ Default
\f[]
.fi
.PP
Thus options given on the command\-line are the most prioritized, then
project\-specific settings are queried, then global configuration and
defaults are used if nothing specifies the value.
.SS Accessing settings
.PP
\f[B]config\f[] command is there to view and change settings.
By default project\-specific settings are used, but \f[B]\-\-global\f[]
option switches to global configuration.
.SS Setting names
.PP
Settings starting with \f[B]!\f[] are reserved for internal purposes and
can\[aq]t be accessed via \f[B]config\f[].
.PP
Setting key is a dot\-separated sequence of section names.
It can\[aq]t be empty.
.SS Configuration overrides
.PP
These are command\-line arguments between project name and command (all
of these are optional, so they might go first and not be followed by
anything) of the form:
.IP \[bu] 2
\f[C]key=value\f[] \-\- sets new value
.IP \[bu] 2
\f[C]key+=value\f[] \-\- appends to existing value
.PP
Such settings are temporary and not saved anywhere, project\-specific or
global configurations should be used for persistent settings.
These are good for tests and use with aliases.
.SS Aliases
.PP
Aliases can only be set in global configuration, otherwise they are
ignored.
.PP
Alias name can match name of a builtin command.
.PP
Aliases must be defined in \f[I]alias\f[] section, e.g.
\f[I]alias.standout\f[].
.PP
Alias can consume arguments, their placeholders have the form:
\f[B]{}\f[], numbering starts with 1.
Unused arguments are appended.
.PP
Example:
.IP
.nf
\f[C]
dit\ config\ \-\-global\ alias.take\ =\ set\ ${1}\ status=\[aq]in\ progress\[aq]
dit\ take\ id\ comment+=\[aq]Done,\ finally.\[aq]
#\ equivalent\ to:\ dit\ set\ id\ status=\[aq]in\ progress\[aq]\ comment+=\[aq]Done,\ finally.\[aq]
\f[]
.fi
.SS Removing values
.PP
Removal is performed by reseting key to empty value, which will enable
use of application default value or value from the previous level if
such values exist.
.PP
Example:
.IP
.nf
\f[C]
dit\ config\ ui.lf.fmt=
\f[]
.fi
.SS List of all settings
.PP
\f[B]core.defcmd\f[] (global) (default: \f[C]ls\f[]) \-\- names command
to be used on invocation without arguments.
.PP
\f[B]core.defprj\f[] (global) (no default) \-\- names project to use if
none was specified.
.PP
\f[B]core.pager\f[] (global) (default: \f[C]$PAGER\f[] or
\f[C]less\ \-R\f[]) \-\- command to be used to start a pager when output
doesn\[aq]t fit on one screen.
.PP
\f[B]defaults.\f[]* (no defaults) \-\- default values for newly created
items.
Configuration on project level completely hides global one.
.PP
\f[B]guards.newitem\f[] (no default) \-\- condition ("List of
conditions" like for \f[B]ls\f[] command) evaluated for fields of a new
item.
If this condition is not satisfied, item creation aborts.
.PP
\f[B]prj.descr\f[] (no default) \-\- project description for
\f[B]projects\f[] command.
.PP
\f[B]ui.ls.fmt\f[] (default: \f[C]_id,title\f[]) \-\- column
specification for \f[B]ls\f[] command.
.PP
\f[B]ui.ls.sort\f[] (default: \f[C]title,_id\f[]) \-\- item sorting
specification for \f[B]ls\f[] command.
.PP
\f[B]ui.ls.color\f[] (default: \f[C]fg\-cyan\ inv\ bold\ !heading\f[])
\-\- item colorization rules for \f[B]ls\f[] command.
.PP
\f[B]ui.show.order\f[] (default: \f[C]title\f[]) \-\- entries ordering
specification for \f[B]show\f[] command.
.SS ui.ls.fmt syntax
.PP
Comma\-separated list of keys, which define columns of table printed out
by \f[B]ls\f[] command.
.SS ui.ls.sort syntax
.PP
Comma\-separated list of keys.
First key is the primary one, its subgroups are sorted by the second key
and so on (i.e., items are sorted by keys in right to left order
preserving relative ordering from previous sorts).
.SS ui.ls.color syntax
.PP
Semicolon\-separated list of colorization rules.
Each rule has the following structure:
.IP
.nf
\f[C]
attributes\ conditions
\f[]
.fi
.PP
Attributes can include:
.IP \[bu] 2
\f[B]bold\f[], \f[B]inv\f[], \f[B]def\f[];
.IP \[bu] 2
\f[B]fg\-black\f[], \f[B]fg\-red\f[], \f[B]fg\-green\f[],
\f[B]fg\-yellow\f[], \f[B]fg\-blue\f[], \f[B]fg\-magenta\f[],
\f[B]fg\-cyan\f[], \f[B]fg\-white\f[];
.IP \[bu] 2
\f[B]bg\-black\f[], \f[B]bg\-red\f[], \f[B]bg\-green\f[],
\f[B]bg\-yellow\f[], \f[B]bg\-blue\f[], \f[B]bg\-magenta\f[],
\f[B]bg\-cyan\f[], \f[B]bg\-white\f[].
.PP
Conditions are either of:
.IP \[bu] 2
\f[B]!heading\f[] \-\- header of the table;
.IP \[bu] 2
any condition as in list of conditions.
.SS ui.show.order syntax
.PP
Comma\-separated list of keys.
Keys mentioned in this option are displayed above any other keys and in
this order, the rest keys of an item follow in alphabetical order.
.SH LIST OF COMMANDS
.SS add
.PP
Adds new item.
.PP
\f[B]Usage: add <list of fields>\f[]
.PP
Creates new item filling it with specified entries.
.SS check
.PP
Verifies project state.
.PP
\f[B]Usage: check\f[]
.PP
Checks that storage files and their content are meaningful.
Prints out errors if something is wrong and exits with non\-zero exit
code.
.SS complete
.PP
Provides command\-line completion helper for shells.
.PP
\f[B]Usage: complete <regular args>\f[]
.PP
Takes normal command\-line with trailing \f[I]::cursor::\f[] designating
cursor position.
The marker is needed to complete empty argument, which otherwise might
be dropped by the shell on invocation.
.SS config
.PP
Displays/updates configuration.
.PP
\f[B]Usage: config [\-\-help|\-h] [\-\-global|\-g] <list of fields>\f[]
.PP
\f[B]\-\-help (\-h)\f[] causes option summary to be printed.
.PP
\f[B]\-\-global (\-g)\f[] switches operations to act on global
configuration, whereas by default project\-specific configuration is
processed.
.PP
When invoked without arguments, all values are displayed.
.PP
When invoked with at least one argument:
.IP \[bu] 2
Keys without values are displayed.
.IP \[bu] 2
Keys with values are updated.
Setting is removed on assigning it empty value.
.PP
Special value \f[B]\-\f[] can be used to request spawning external
editor.
.SS export
.PP
Invokes external script passing item data via argument list.
.PP
\f[B]Usage: export (\-|cmd) <list of conditions>\f[]
.PP
Invokes \f[B]cmd key1=value1 key2=value2\f[] for each item that matches
given list of conditions or prints out items to standard output with
\f[B]key=value\f[] fields terminated by null character and each item
also finished by null character.
Builtin key \f[C]_id\f[] is also printed.
.SS help
.PP
Provides help information.
.PP
\f[B]Usage: help [command]\f[]
.PP
Without arguments displays summary of available commands.
.PP
With argument displays summary on that command.
.SS log
.PP
Displays item changes.
.PP
\f[B]Usage: log [\-\-help|\-h] [\-\-timestamps|\-t] <item id>
[<key>...]\f[]
.PP
\f[B]\-\-help (\-h)\f[] causes option summary to be printed.
.PP
\f[B]\-\-timestamps (\-t)\f[] adds timestamp to each change printed.
.PP
Displays information about item changes (from oldest to newest) either
for all fields (if only item id is specified) or just for the specified
ones.
.SS ls
.PP
Lists items.
.PP
\f[B]Usage: ls <list of conditions>\f[]
.PP
Print table of items that match the list of conditions.
.PP
Affected by: \f[B]ui.ls.fmt\f[], \f[B]ui.ls.sort\f[],
\f[B]ui.ls.color\f[].
.SS new
.PP
Creates new project.
.PP
\f[B]Usage: new <project name>\f[]
.PP
Initializes new project.
.SS projects
.PP
Lists projects.
.PP
\f[B]Usage: projects\f[]
.PP
Lists projects along with their descriptions (\f[B]prj.descr\f[]).
Picked project is marked with a star (*).
.SS rename
.PP
Renames a project.
.PP
\f[B]Usage: rename <old name> <new name>\f[]
.PP
Renames existing project.
.SS set
.PP
Changes items.
.PP
\f[B]Usage: set <item id> <list of fields>\f[]
.PP
Updates entries of existing item.
.SS show
.PP
Displays items.
.PP
\f[B]Usage: show <item id> [<key>...]\f[]
.PP
Prints entries of specified item, either all fields (if only item id is
specified) or just for the specified ones.
.PP
Affected by: \f[B]ui.show.order\f[].
.SS values
.PP
Displays values of a key.
.PP
\f[B]Usage: values <key>\f[]
.PP
Prints all values that appear associated with the given key to at least
one item.
.SH TIPS
.SS Install and use bash completion
.PP
Bash completion script is installed in standard location and should work
automatically.
Lots of things are completed in a predictable and helpful manner, so be
sure to use the completion as it helps a great deal.
.SS Create aliases for frequently used projects
.PP
Example:
.IP
.nf
\f[C]
alias\ d.d=\[aq]dit\ .dit\[aq]
alias\ d.v=\[aq]dit\ .vifm\[aq]
\f[]
.fi
.PP
Using dot as a separated might be better for using \f[C]Ctrl\-W\f[] with
shell configuration that stops at a dot.
.PP
Creating an alias for \f[C]dit\f[] itself won\[aq]t hurt either:
.IP
.nf
\f[C]
alias\ d=\[aq]dit\[aq]
\f[]
.fi
.PP
Note that this can break completion if there are not workarounds like
the one mentioned in http://superuser.com/a/437508.
Another option is to define completion manually for the alias like this:
.IP
.nf
\f[C]
complete\ \-F\ _dit\ d
\f[]
.fi
.PP
This won\[aq]t work right away with \f[C]d.d\f[] and \f[C]d.v\f[] above
as they take project name argument.
.SH EXAMPLE
.PP
Below is an example sequence of commands that demonstrates basic usage.
.PP
Assuming absent configuration, there isn\[aq]t much one can do:
.IP
.nf
\f[C]
$\ dit
No\ project\ specified
$\ dit\ projects
\f[]
.fi
.PP
Create first project:
.IP
.nf
\f[C]
$\ dit\ new\ test
$\ dit
No\ project\ specified
$\ dit\ projects
\ test
$\ dit\ .test
ID\ \ TITLE
\f[]
.fi
.PP
Setup the \f[C]test\f[] project to be the default one to omit
\f[C]\&.test\f[] part:
.IP
.nf
\f[C]
$\ dit\ config\ \-\-global\ core.defprj:\ test
$\ dit
ID\ \ TITLE
\f[]
.fi
.PP
Now add simple task:
.IP
.nf
\f[C]
$\ dit\ add\ title:\ Explore\ dit.
Created\ item:\ fqH
$\ dit
ID\ \ \ TITLE
fqH\ \ Explore\ dit.
\f[]
.fi
.PP
Modify its field:
.IP
.nf
\f[C]
$\ dit\ set\ fqH\ status:\ in\ progress
\f[]
.fi
.PP
It\[aq]s not visible via \f[C]ls\f[] (the default subcommand), but
it\[aq]s there:
.IP
.nf
\f[C]
$\ dit
ID\ \ \ TITLE
fqH\ \ Explore\ dit.
$\ dit\ show\ fqH
title:\ Explore\ dit.
status:\ in\ progress
\f[]
.fi
.PP
To display it via \f[C]ls\f[], configuration must be altered a bit:
.IP
.nf
\f[C]
$\ dit\ config\ ui.ls.fmt:\ _id,title,status
$\ dit
ID\ \ \ TITLE\ \ \ \ \ \ \ \ \ STATUS
fqH\ \ Explore\ dit.\ \ in\ progress
\f[]
.fi
.PP
One might want to ease taking tasks and marking them as done later, this
is where aliases can be used:
.IP
.nf
\f[C]
$\ dit\ config\ \-\-global\ alias.done=\[aq]set\ ${1}\ status=done\[aq]
$\ dit\ config\ \-\-global\ alias.take=\[aq]set\ ${1}\ status="in\ progress"\[aq]
$\ dit\ done\ fqH
$\ dit
ID\ \ \ TITLE\ \ \ \ \ \ \ \ \ STATUS
fqH\ \ Explore\ dit.\ \ done
\f[]
.fi
.PP
Usually, there is no need to see tasks that are already done and
\f[C]ls\f[] command drops them from the output if asked:
.IP
.nf
\f[C]
$\ dit\ ls\ status!=done
ID\ \ TITLE\ \ STATUS
\f[]
.fi
.PP
Not very easy to type, so let\[aq]s make an alias and set it as new
default command:
.IP
.nf
\f[C]
$\ dit\ config\ \-\-global\ alias.standout=\[aq]ls\ status!=done\[aq]
$\ dit\ config\ \-\-global\ core.defcmd:\ standout
$\ dit
ID\ \ TITLE\ \ STATUS
$\ dit\ ls
ID\ \ \ TITLE\ \ \ \ \ \ \ \ \ STATUS
fqH\ \ Explore\ dit.\ \ done
\f[]
.fi
.PP
It\[aq]s sometimes handy to add additional columns to the table, aliases
can help here as well:
.IP
.nf
\f[C]
$\ dit\ config\ \-\-global\ alias.dates=\[aq]ui.ls.fmt+=,_created,_changed\[aq]
$\ dit\ ls.dates
ID\ \ \ TITLE\ \ \ \ \ \ \ \ \ STATUS\ \ CREATED\ \ \ \ \ \ \ \ \ \ \ \ \ \ CHANGED
fqH\ \ Explore\ dit.\ \ done\ \ \ \ 2016\-02\-05\ 12:31:25\ \ 2016\-02\-05\ 13:07:51
\f[]
.fi
.PP
If at some later moment one wants to view history of a task, use
\f[C]log\f[]:
.IP
.nf
\f[C]
$\ dit\ log\ fqH
title\ created:\ Explore\ dit.
status\ created:\ in\ progress
status\ changed:
\-in\ progress
+done
\f[]
.fi
.PP
And so on...
.PP
Combination of aliases and key\-value pairs allow for implementation of
wide range of possible workflows, one only needs to adjust them
accordingly.
.SH FILES
.PP
\f[B]$XDG_CONFIG_HOME/dit\f[] \-\- location of configuration/data
directory.
.PP
\f[B]~/.config/dit\f[] \-\- location used if \f[B]XDG_CONFIG_HOME\f[] is
invalid.
.SH ENVIRONMENT
.PP
\f[B]XDG_CONFIG_HOME\f[] \-\- checked first to determine location of
configuration/data.
.PP
\f[B]HOME\f[] \-\- checked second to determine location of
configuration/data.
.PP
\f[B]EDITOR\f[] \-\- used to perform external editing of values.
.PP
\f[B]PAGER\f[] \-\- used as a default for displaying output which
doesn\[aq]t fit on the screen.
.SH AUTHORS
xaizek <xaizek@posteo.net>.