A file-based task manager
1tsk
2===
3
4A fast & simple CLI task manager
5--------------------------------
6
7The motivation for tsk is simple: make managing tasks as fast and easy as
8possible with a focus on small, ephemeral tasks.
9
10Secondary goals include:
11
12- Provide the minimum amount of features necessary to be usable by a team
13- Support local and non-local workspaces
14- Be adaptable to almost any environment, even employer-mandated JIRA use
15- Be flexible, within reason
16
17tsk takes inspiration from git and FORTH and is expected to be used alongside
18the former.
19
20Dependencies
21------------
22
23tsk is written in Rust. To compile from source, a recent Rust toolchain is
24required. As of now, it is developed using Rust 1.81.0.
25
26Additionally, for fuzzy-finding functionality, the fzf command must be installed
27and in the shell's PATH.
28
29 https://github.com/junegunn/fzf
30
31tsk stores its data in git refs (`refs/tsk/*`) inside a host git repository, so
32any filesystem git itself runs on will work. Use the `tsk git-pull` and
33`tsk git-push` commands to update/push these refs.
34
35
36Installation
37------------
38
39```sh
40cargo install --locked tsk-cli
41```
42
43
44Building
45--------
46
47```sh
48cargo install --path .
49```
50
51Make sure ~/.cargo/bin is in your PATH.
52
53Overview
54--------
55
56A summary of commands and their functionality can be seen with:
57
58 tsk help
59
60tsk uses virtual text files tracked by special refs in a git repo for its
61functionality. Any git repo can be made into a tsk workspace.
62
63New tasks are created with the `tsk push` command. A title is always required,
64but can be modified later. A unique, human-readable identifer is selected
65scoped to the namespace and may be used to as a stable reference within that
66namespace.
67
68The contents of the stack may be printed using the `tsk list` command.
69
70Tasks are marked as "completed" and removed from the index with the `tsk drop`
71command. They will remain in the .tsk/archive folder, but are excluded from
72fuzzy searches by default.
73
74The priority of a task may be manipulated in any of several ways:
75
76`tsk swap` swaps the top two task on the stack
77
78 ┌─────────┐ ┌─────────┐
79 │ tsk-100 │ │ tsk-102 │
80 └─────────┘ └─┬─────▲─┘
81 │ │
82 ┌─────────┐ ┌─▼─────┴─┐
83 │ tsk-102 │ ───────► │ tsk-100 │
84 └─────────┘ └─────────┘
85
86 ┌─────────┐ ┌─────────┐
87 │ tsk-108 │ │ tsk-108 │
88 └─────────┘ └─────────┘
89
90`tsk rot` moves the 3rd task on the stack to the top of the stack and shifts
91the first and second down
92
93 ┌─────────┐ ┌─────────┐
94 │ tsk-100 │ │ tsk-108 ◄─┐
95 └─────────┘ └────┬────┘ │
96 │ │
97 ┌─────────┐ ┌────▼────┐ │
98 │ tsk-102 │ ───────► │ tsk-100 │ │
99 └─────────┘ └────┬────┘ │
100 │ │
101 ┌─────────┐ ┌────▼────┐ │
102 │ tsk-108 │ │ tsk-102 ├─┘
103 └─────────┘ └─────────┘
104
105`tsk tor` moves the task on the top of the stack behind the third, shifting the
106second and third tasks up.
107
108 ┌─────────┐ ┌─────────┐
109 │ tsk-100 │ │ tsk-102 ├─┐
110 └─────────┘ └────▲────┘ │
111 │ │
112 ┌─────────┐ ┌────┴────┐ │
113 │ tsk-102 │ ───────► │ tsk-108 │ │
114 └─────────┘ └────▲────┘ │
115 │ │
116 ┌─────────┐ ┌────┴────┐ │
117 │ tsk-108 │ │ tsk-100 ◄─┘
118 └─────────┘ └─────────┘
119
120`tsk prioritize` will take a selected task and move it to the top of the stack
121from any other position in the stack. It is selected either by ID or using fuzzy
122finding.
123
124`tsk deprioritize` moves a selected task to the bottom of the stack from any
125position.
126
127Roadmap
128-------
129
130- Configurable workspace-scoped prefix tags (tsk- vs example-)
131- Extended Attribute-based Metadata
132- Task Linking
133- IMAP4/SMTP-based synchronization and sharing
134- Export + sync with external task managers
135 - GitLab
136 - GitHub
137 - JIRA
138 - Obsidian
139 - More?
140- tsk -> html export
141- Editor plugins
142 - nvim-telescope
143 - nvim
144 - others?
145- Man page
146
147Format
148------
149
150The tsk text format can be thought of as a derivative of Markdown and scdoc, but
151not quite either. Markdown is a great baseline for rich-text while scdoc
152restricts itself to rich text formatting that can be displayed effectively in a
153terminal. As tsk's primary goal is to be a fast, terminal-centric task manager,
154this property is a *must.*
155
156Additionally, it should be similar enough to Markdown such that it is easy to
157export to other applications, as outlined above in the roadmap.
158
159Meanwhile, both Markdown and scdoc have some limitations and make choices that,
160while appropriate for their domain, are not appropriate for tsk. Some notable
161differences from both:
162
163- There is only one way to do any type of formatting
164- Hard line breaks are real, not imaginary
165- Inline formatting control characters must be surrounded by space, newline, or
166 common punctuation
167
168A core feature of the format is *linking*. That is, references to other tasks
169utilizing wiki-link style links: `[[]]`. The content within the link is mapped
170to the local workspace if the `tsk-` prefix is used, or a mapped non-local
171workspace if another prefix is used. These mappings are specified using a text
172file within the .tsk folder.
173
174A quick overview of the format:
175
176- !Bolded! text is surrounded by exclamation marks (!)
177- *Italicized* text is surrounded by single asterisks (*)
178- _Underlined_ text is surrounded by underscores (_)
179- ~Strikethrough~ text is surrounded by tildes (~)
180- =Highlighted= text is surrounded by equals signs (=)
181- `Inline code` is surrounded by backticks (`)
182
183Links like in Markdown, along with the wiki-style links documented above.
184Raw links can also be written as \<https://example.com\>.
185
186Misc
187----
188
189tsk is heavily inspired by git. It mimics its folder structure and some
190commands. The concept of the stack is inspired by FORTH and the observation that
191most of the time, only the top 3 priorities at any given moment matter and tasks
192tend to be created when they are most important. This facilitates small,
193frequent creation of tasks that help both document problems and manage
194fast-paced work environments.
195
196tsk is not intended to be checked into git, however there is not a reason that it
197cannot be. This repository's development is managed using tsk itself.
198
199Git does *not* track extended filesystem attributes. If you wish to avoid constantly
200re-indexing, use something like metastore:
201
202 https://github.com/przemoc/metastore