tld
is a tool for people who want to do things, but who might also want a
bit of flexibility.
tld
(pronounced "told", based off of Steve Losh's t.py but with a LD
twist) is a simple command line tool that works like a (somewhat) minimal list
manager. Calling
$ python tld.py This is a message.
will create a file called tasks
in the current directory and put "This is a
message." (and some identifier) in that file. Calling it again will print
the contents of the file.
$ python tld.py
3 - This is a message.
The 3
at the start of the output is an identifier, and can be referenced.
Calling
$ python tld.py -f 3
will mark this message as "done" and move it to a file .tasks.done
in the
current directory.
For more options, call
$ python tld.py -h
or see the options description on the github page https://github.com/davidlowryduda/tld.
Steve Losh designed t.py to do the simplest thing that could possibly work: you can add, edit, remove, and finish elements from a list. It's simple, messy, and has almost no features to distract you from getting in the way of doing things. It's easy to say "I'll just organize my list a bit" and spend 15 minutes tagging, coloring, setting priorities, and so forth.
And if that works for you, great! Then t.py is enough.
tld
does everything t.py does, except with a few more features (and a bit less
purity). In particular, tld
supports simple date annotations, simple tagging,
and philosophically isn't against complete organization.
Where t.py encourages you to use different aliases to different tasklists for
different one level of organization, tld
allows one to use tags in fewer
lists.
Do you want to edit a bunch of items at once? Open the list in a text editor,
and tld
will handle the rest.
Do you want to view the list on a computer that doesn't have tld
installed?
Open the list in a text editor.
Do you want to synchronize your list across multiple computers? Keep your lists in a Dropbox folder or a github repository.
tld
follows the lead of other systems which keep lists in a plain text file.
This is a great idea.
tld
also follows t.py
's use of random IDs to order the items in the list.
When list managers append new items to the end of the list and multiple users
edit a list, then merge conflicts will occur and require manual handling.
If order really matters, then this makes sense. But if order really matters,
then you shouldn't be using tld
.
tld
uses random IDs (actually SHA1 hashes) to order the list. Once a list has
a couple of items in it, adding more is far less likely to cause merge
conflicts.
tld
requires Python 3.6+ and a bash-like shell. It works on Linux, OS X,
and Windows (with the linux subsystem).
Installing and setting up tld
will take about one minute.
First, download the newest version or clone the github repository
(git clone https://github.com/davidlowryduda/tld
).
You can also use pip through a command like
python3 -m pip install --user --upgrade tld-task
If you use pip, then you can replace 'python3 ~/path/to/tld.py
with
tld` in the examples below.
Next, decide where you want to keep your lists. I put mine in ~/notes/tasks
(I keep notes created from other note utilities in ~/notes/
too). Create that
directory (or whatever directory you plan on using).
mkdir -p ~/notes/tasks
Set up an alias to run tld
. Put something like this in your
~/.bashrc
file:
alias tld='python3 ~/path/to/tld.py --task-dir ~/notes/tasks --list tasks'
Make sure you run source ~/.bashrc
or restart your terminal window to make
the alias take effect. Now tld
is ready to use.
tld
is quick and easy to use, especially when used in combination with other
tools. Commandline usage is available through tld -h
or tld --help
, and is
a good reference once you grok the workflow.
To add an item, use tld [item description]
:
$ tld Tell my wife I love her.
$ tld Prove the Riemann Hypothesis.
$ tld "Read Steve Losh's .vimrc."
Listing your items is even easier -- just use tld
:
$ tld
1 - Read Steve Losh's .vimrc.
a - Tell my wife I love her.
b - Prove the Riemann Hypothesis.
tld
will list all of your unfinished items and their IDs. Do you not want to
see the IDs? Use the "quiet" option by using tld -q
or tld --quiet
.
After you're done with something, use tld -f ID
to finish it:
$ tld -f b
$ tld
1 - Read Steve Losh's .vimrc.
a - Tell my wife I love her.
You can use tld -r ID
to "remove" an item (which won't mark it as "finished".
Items marked "finished" can be listed. Items that are "removed" are just gone).
Sometimes you might want to change the wording of an item. You can use
tld -e ID [new description]
to do that:
$ tld -e 1 Clean my .vimrc.
$ tld
5 - Update my .vimrc.
a - Tell my wife I love her.
Yes, you can use sed-style substitution strings s/old/repl
.
$ tld -e 5 s/Update/Clean/
$ tld
a - Tell my wife I love her.
e - Clean my .vimrc.
Have you marked lots of items as "finished" and you want to review them?
You can view these items with tld --done
.
$ tld --done
b - Prove the Riemann Hypothesis.
Do you want to be able to remember when you added an item to the list? Use
tld --date [description]
when you add the item to the list.
$ tld --date Write README.
$ tld
1 - Write Readme.
5 - Update my .vimrc.
a - Tell my wife I love her.
tld
doesn't show these dates by default --- too much clutter. To see dates,
use tld --showdates
.
$ tld --showdates
2018-06-01 | 1 - Write README.
| 5 - Update my .vimrc
| a - Tell my wife I love her.
You can use --date
in your tld
alias, and this information will only affect
the output when used with --showdates
.
Use tld --tag [TAG] [description]
when you add an item to the list to add a
tag.
$ tld --tag shopping Buy milk.
$ tld
1 - Write README.
5 - Update my .vimrc
9 - Buy milk.
a - Tell my wife I love her.
To see the tags, use --showtags
.
$ tld --showtags
1 - Write README.
5 - Update my .vimrc
9 - Buy milk. | tags: shopping
a - Tell my wife I love her.
Why keep an empty list around? You can have the list delete itself automatically
if empty. You can use the --delete-if-empty
option in your alias:
alias tld='python3 ~/path/to/tld.py --task-dir ~/notes/tasks --list tasks --delete_if-empty'
tld
might be simple, but it can do a lot of interesting things.
Counting your item is simple using the wc
program:
$ tld | wc -l
4
If I have too many aliases, I forget them. I use tags and grep as a primary
level of organization. To remember what tags exist, just print them with
tld --showtags
or tld --showtags | grep tags
. Then print out the relevant
items through grep with tld --showtags | grep shopping
.
$ tld --showtags | grep shopping
9 - Buy milk. | tags: shopping
To make it look pretty, you can cut out the tag by showing evertying before '|' with something like awk.
$ tld --showtags | grep shopping | awk -F'|' '{print $1}'
9 - Buy milk.
If you have too many tags and too many items, then perhaps having multiple lists is a good idea for you. But you can list all the unique collections of tags relatively easily with classic tools and sed.
$ tld --tag shopping Buy chocolate syrup.
$ tld --tag music Buy Phoenix album.
$ tld --showtags | grep tags | sed -e's/.*tags: //' | sort | uniq
music
shopping
The given grep
option will print only tasks containing the word,
case-insensitively. This includes if the tags contain that word.
$ tld --grep Album
7 - Buy Phoenix album.
You can follow the t.py
philosophy of organizing tasks into different lists by
adding additional aliases. For example
alias g='python ~/path/to/tld.py --task-dir ~/notes/tasks --list groceries'
alias m='python ~/path/to/tld.py --task-dir ~/notes/tasks --list music-to-buy'
alias w='python ~/path/to/tld.py --task-dir ~/notes/tasks --list wines-to-try'
Like the idea of distributed bug trackers like [BugsEverywhere][], but don't
want to use such a heavyweight system? You can use tld
instead.
Add another alias to your ~/.bashrc
file:
alias b='python ~/path/to/tld.py --task-dir . --list bugs'
Now when you're in your project directory you can use b
to manage the list of
bugs/tasks for that project. Add the bugs
file to version control and you're
all set.
Even people without tld
installed can view the bug list, because it's plain
text.
tld
can read and operate on lists made with t.py
, but t.py
does not handle
the date and tag annotations from tld
. If you never use those, then they're
interoperable (and you're essentially using t.py
anyway).
In the future, additional metadata may be implemented in tld
, which may
further widen this gap.
I used Steve Losh's t.py
for a long time before deciding to make a few
changes. When I read through his code, I thought it was pretty elegant. So I
thought it would be a good learning experience to rebuild it in roughly the same
order, but with a few changes in mind.
So really, this project is an exercise in programming that I did over about a week to fit my whims and desires.
Those who find themselves here should really check out t.py
. By adding new
features, I satisfy my whims --- but more features ruin the simple purity of the
original t.py
.
If you happen to use it and find a bug, let me know.
For more featureful list managers, you might checko out todo.txt
and
TaskWarrior
. They have lots of features and lots of knobs that one can tweak
and prettify.
If you want to contribute code to tld
, that's great! Fork the
repo and send me a pull request.
But I've been doing this as a learning experience, and know that I might
experiment with contributed code too.