A file-based task manager
ngp.computer
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 workspaces must be created on filesystems that support symlinking.
32
33Task-level metadata requires Linux's xattr(7) API and a filesystem that supports
34it. Patches that implement this for other operating systems are welcome.
35
36tsk expects to run on POSIX-like systems. Microsoft Windows and other
37non-UNIX-ey operating systems will never be directly supported.
38
39
40Installation
41------------
42
43```sh
44cargo install --locked tsk-cli
45```
46
47
48Building
49--------
50
51```sh
52cargo install --path .
53```
54
55Make sure ~/.cargo/bin is in your PATH.
56
57Overview
58--------
59
60A summary of commands and their functionality can be seen with:
61
62 tsk help
63
64tsk uses plain text files for all of its functionality. A workspace is a folder
65that contains a .tsk/ directory created with the `tsk init` command. The
66presence of a .tsk/ folder is searched recursively upwards until a filesystem
67boundary or root is encountered. This means you can nest workspaces and use
68folders to namespace tasks while also using tsk commands at any location within
69a workspace.
70
71New tasks are created with the `tsk push` command. A title is always required,
72but can be modified later. A unique identifier is selected automatically and a
73file with the title and any body contents supplied are stored in the
74.tsk/archive folder. A symlink is then created in the .tsk/tasks folder marking
75the task as "open." The task is then added to the top of the "stack" by having
76its tsk-ID and title added to the .tsk/index file.
77
78The contents of the stack may be printed using the `tsk list` command.
79
80Tasks are marked as "completed" and removed from the index with the `tsk drop`
81command. They will remain in the .tsk/archive folder, but are excluded from
82fuzzy searches by default.
83
84The priority of a task may be manipulated in any of several ways:
85
86`tsk swap` swaps the top two task on the stack
87
88 ┌─────────┐ ┌─────────┐
89 │ tsk-100 │ │ tsk-102 │
90 └─────────┘ └─┬─────▲─┘
91 │ │
92 ┌─────────┐ ┌─▼─────┴─┐
93 │ tsk-102 │ ───────► │ tsk-100 │
94 └─────────┘ └─────────┘
95
96 ┌─────────┐ ┌─────────┐
97 │ tsk-108 │ │ tsk-108 │
98 └─────────┘ └─────────┘
99
100`tsk rot` moves the 3rd task on the stack to the top of the stack and shifts
101the first and second down
102
103 ┌─────────┐ ┌─────────┐
104 │ tsk-100 │ │ tsk-108 ◄─┐
105 └─────────┘ └────┬────┘ │
106 │ │
107 ┌─────────┐ ┌────▼────┐ │
108 │ tsk-102 │ ───────► │ tsk-100 │ │
109 └─────────┘ └────┬────┘ │
110 │ │
111 ┌─────────┐ ┌────▼────┐ │
112 │ tsk-108 │ │ tsk-102 ├─┘
113 └─────────┘ └─────────┘
114
115`tsk tor` moves the task on the top of the stack behind the third, shifting the
116second and third tasks up.
117
118 ┌─────────┐ ┌─────────┐
119 │ tsk-100 │ │ tsk-102 ├─┐
120 └─────────┘ └────▲────┘ │
121 │ │
122 ┌─────────┐ ┌────┴────┐ │
123 │ tsk-102 │ ───────► │ tsk-108 │ │
124 └─────────┘ └────▲────┘ │
125 │ │
126 ┌─────────┐ ┌────┴────┐ │
127 │ tsk-108 │ │ tsk-100 ◄─┘
128 └─────────┘ └─────────┘
129
130`tsk prioritize` will take a selected task and move it to the top of the stack
131from any other position in the stack. It is selected either by ID or using fuzzy
132finding.
133
134`tsk deprioritize` moves a selected task to the bottom of the stack from any
135position.
136
137Roadmap
138-------
139
140- Configurable workspace-scoped prefix tags (tsk- vs example-)
141- Extended Attribute-based Metadata
142- Task Linking
143- IMAP4/SMTP-based synchronization and sharing
144- Export + sync with external task managers
145 - GitLab
146 - GitHub
147 - JIRA
148 - Obsidian
149 - More?
150- tsk -> html export
151- Editor plugins
152 - nvim-telescope
153 - nvim
154 - others?
155- Man page
156
157Format
158------
159
160The tsk text format can be thought of as a derivative of Markdown and scdoc, but
161not quite either. Markdown is a great baseline for rich-text while scdoc
162restricts itself to rich text formatting that can be displayed effectively in a
163terminal. As tsk's primary goal is to be a fast, terminal-centric task manager,
164this property is a *must.*
165
166Additionally, it should be similar enough to Markdown such that it is easy to
167export to other applications, as outlined above in the roadmap.
168
169Meanwhile, both Markdown and scdoc have some limitations and make choices that,
170while appropriate for their domain, are not appropriate for tsk. Some notable
171differences from both:
172
173- There is only one way to do any type of formatting
174- Hard line breaks are real, not imaginary
175- Inline formatting control characters must be surrounded by space, newline, or
176 common punctuation
177
178A core feature of the format is *linking*. That is, references to other tasks
179utilizing wiki-link style links: `[[]]`. The content within the link is mapped
180to the local workspace if the `tsk-` prefix is used, or a mapped non-local
181workspace if another prefix is used. These mappings are specified using a text
182file within the .tsk folder.
183
184A quick overview of the format:
185
186- \!Bolded\! text is surrounded by exclamation marks (!)
187- \*Italicized\* text is surrounded by single asterisks (*)
188- \_Underlined\_ text is surrounded by underscores (_)
189- \~Strikethrough\~ text is surrounded by tildes (~)
190- \=Highlighted\= text is surrounded by equals signs (=)
191- \`Inline code\` is surrounded by backticks (`)
192
193Links like in Markdown, along with the wiki-style links documented above.
194Raw links can also be written as \<https://example.com\>.
195
196Misc
197----
198
199tsk is heavily inspired by git. It mimics its folder structure and some
200commands. The concept of the stack is inspired by FORTH and the observation that
201most of the time, only the top 3 priorities at any given moment matter and tasks
202tend to be created when they are most important. This facilitates small,
203frequent creation of tasks that help both document problems and manage
204fast-paced work environments.
205
206tsk is not intended to be checked into git, however there is not a reason that it
207cannot be. This repository's development is managed using tsk itself.
208
209Git does *not* track extended filesystem attributes. If you wish to avoid constantly
210re-indexing, use something like metastore:
211
212 https://github.com/przemoc/metastore