A file-based task manager
ngp.computer
Move tsk.txt to readme, add docs
+175
readme
+175
readme
···
1
+
tsk
2
+
===
3
+
4
+
A fast & simple CLI task manager
5
+
--------------------------------
6
+
7
+
The motivation for tsk is simple: make managing tasks as fast and easy as
8
+
possible with a focus on small, ephemeral tasks.
9
+
10
+
Secondary 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
+
17
+
tsk takes inspiration from git and FORTH and is expected to be used alongside
18
+
the former.
19
+
20
+
Dependencies
21
+
------------
22
+
23
+
tsk is written in Rust. To compile from source, a recent Rust toolchain is
24
+
required. As of now, it is developed using Rust 1.81.0.
25
+
26
+
Additionally, for fuzzy-finding functionality, the fzf command must be installed
27
+
and in the shell's PATH.
28
+
29
+
https://github.com/junegunn/fzf
30
+
31
+
tsk workspaces must be created on filesystems that support hard linking.
32
+
33
+
Task-level metadata requires Linux's xattr(7) API and a filesystem that supports
34
+
it. Patches that implement this for other operating systems are welcome.
35
+
36
+
Building
37
+
--------
38
+
39
+
```shell
40
+
cargo install --path .
41
+
```
42
+
43
+
Make sure ~/.cargo/bin is in your PATH.
44
+
45
+
Overview
46
+
--------
47
+
48
+
A summary of commands and their functionality can be seen with:
49
+
50
+
tsk help
51
+
52
+
tsk uses plain text files for all of its functionality. A workspace is a folder
53
+
that contains a .tsk/ directory created with the `tsk init` command. The
54
+
presence of a .tsk/ folder is searched recursively upwards until a filesystem
55
+
boundary or root is encountered. This means you can nest workspaces and use
56
+
folders to namespace tasks while also using tsk commands at any location within
57
+
a workspace.
58
+
59
+
New tasks are created with the `tsk push` command. A title is always required,
60
+
but can be modified later. A unique identifier is selected automatically and a
61
+
file with the title and any body contents supplied are stored in the
62
+
.tsk/archive folder. A hardlink is then created in the .tsk/tasks folder marking
63
+
the task is "open." The task is then added to the top of the "stack" by having
64
+
its tsk-ID and title added to the .tsk/index file.
65
+
66
+
The contents of the stack may be printed using the `tsk list` command.
67
+
68
+
Tasks are marked as "completed" and removed from the index with the `tsk drop`
69
+
command. They will remain in the .tsk/archive folder, but are excluded from
70
+
fuzzy searches by default.
71
+
72
+
The priority of a task may be manipulated in any of several ways:
73
+
74
+
`tsk swap` swaps the top two task on the stack
75
+
76
+
┌─────────┐ ┌─────────┐
77
+
│ tsk-100 │ │ tsk-102 │
78
+
└─────────┘ └─┬─────▲─┘
79
+
│ │
80
+
┌─────────┐ ┌─▼─────┴─┐
81
+
│ tsk-102 │ ───────► │ tsk-100 │
82
+
└─────────┘ └─────────┘
83
+
84
+
┌─────────┐ ┌─────────┐
85
+
│ tsk-108 │ │ tsk-108 │
86
+
└─────────┘ └─────────┘
87
+
88
+
`tsk rot` moves the 3rd task on the stack to the top of the stack and shifts
89
+
the first and second down
90
+
91
+
┌─────────┐ ┌─────────┐
92
+
│ tsk-100 │ │ tsk-108 ◄─┐
93
+
└─────────┘ └────┬────┘ │
94
+
│ │
95
+
┌─────────┐ ┌────▼────┐ │
96
+
│ tsk-102 │ ───────► │ tsk-100 │ │
97
+
└─────────┘ └────┬────┘ │
98
+
│ │
99
+
┌─────────┐ ┌────▼────┐ │
100
+
│ tsk-108 │ │ tsk-102 ├─┘
101
+
└─────────┘ └─────────┘
102
+
103
+
`tsk tor` moves the task on the top of the stack behind the third, shifting the
104
+
second and third tasks up.
105
+
106
+
┌─────────┐ ┌─────────┐
107
+
│ tsk-100 │ │ tsk-102 ├─┐
108
+
└─────────┘ └────▲────┘ │
109
+
│ │
110
+
┌─────────┐ ┌────┴────┐ │
111
+
│ tsk-102 │ ───────► │ tsk-108 │ │
112
+
└─────────┘ └────▲────┘ │
113
+
│ │
114
+
┌─────────┐ ┌────┴────┐ │
115
+
│ tsk-108 │ │ tsk-100 ◄─┘
116
+
└─────────┘ └─────────┘
117
+
118
+
`tsk prioritize` will take a selected task and move it to the top of the stack
119
+
from any other position in the stack. It is selected either by ID or using fuzzy
120
+
finding.
121
+
122
+
`tsk deprioritize` moves a selected task to the bottom of the stack from any
123
+
position.
124
+
125
+
Roadmap
126
+
-------
127
+
128
+
- Configurable workspace-scoped prefix tags (tsk- vs example-)
129
+
- Extended Attribute-based Metadata
130
+
- Task Linking
131
+
- IMAP4/SMTP-based synchronization
132
+
- Text format with rich-text terminal display
133
+
- Export + sync with external task managers
134
+
- GitLab
135
+
- GitHub
136
+
- JIRA
137
+
- Obsidian
138
+
- More?
139
+
- tsk -> html export
140
+
- Editor plugins
141
+
- nvim-telescope
142
+
- nvim
143
+
- others?
144
+
- Man page
145
+
146
+
Format
147
+
------
148
+
149
+
The tsk text format can be thought of as a derivative of Markdown and scdoc, but
150
+
not quite either. Markdown is a great baseline for rich-text while scdoc
151
+
restricts itself to rich text formatting that can be displayed effectively in a
152
+
terminal. As tsk's primary goal is to be a fast, terminal-centric task manager,
153
+
this property is a *must.*
154
+
155
+
Additionally, it should be similar enough to Markdown such that it is easy to
156
+
export to other applications, as outlined above in the roadmap.
157
+
158
+
A core feature of the format is *linking*. That is, references to other tasks
159
+
utilizing wiki-link style links: `[[]]`. The content within the link is mapped
160
+
to the local workspace if the `tsk-` prefix is used, or a mapped non-local
161
+
workspace if another prefix is used. These mappings are specified using a text
162
+
file within the .tsk folder.
163
+
164
+
Misc
165
+
----
166
+
167
+
tsk is heavily inspired by git. It mimics its folder structure and some
168
+
commands. The concept of the stack is inspired by FORTH and the observation that
169
+
most of the time, only the top 3 priorities at any given moment matter and tasks
170
+
tend to be created when they are most important. This facilitates small,
171
+
frequent creation of tasks that help both document problems and manage
172
+
fast-paced work environments.
173
+
174
+
tsk is not intended to be checked into git, however there is not reason that it
175
+
cannot be. This repository's development is managed using tsk itself.
-38
tsk.txt
-38
tsk.txt
···
1
-
tsk
2
-
===
3
-
4
-
A simple command line task manager with exporting and syncing capabilities
5
-
--------------------------------------------------------------------------
6
-
7
-
The motivation for tsk is simple: make managing tasks as easy as possible with a focus
8
-
on small, ephemeral tasks.
9
-
10
-
Roadmap
11
-
-------
12
-
13
-
- Extended Attribute-based Metadata
14
-
- Task Linking
15
-
- IMAP4/SMTP-based synchronization
16
-
- Text format with rich-text
17
-
- Export + sync with external task managers
18
-
- GitLab
19
-
- GitHub
20
-
- JIRA
21
-
- Obsidian
22
-
- More?
23
-
- Neovim Plugin?
24
-
- nvim-telescope plugin?
25
-
26
-
Format
27
-
------
28
-
29
-
The tsk text format can be thought of as a derivative of Markdown and scdoc, but not
30
-
quite either. Markdown is a great baseline for rich-text while scdoc restricts itself to
31
-
rich text formatting that can be displayed effectively in a terminal. As tsk's primary
32
-
goal is to be a fast, terminal-centric task manager, this property is a *must.*
33
-
34
-
Additionally, it should be similar enough to Markdown such that it is easy to export to
35
-
other applications, as outlined above in the roadmap.
36
-
37
-
A core feature of the format is *linking*. That is, references to tasks within a given
38
-
workspace utilizing wiki-link style links: `[[]]`.