A simple and extensible shell script for managing your todo.txt file.
Read our contributing guide if you're looking to contribute (issues/PRs/etc).
I want to learn Go, so I decided to convert todo.sh to Go. This felt like a decent beginner project.
At this time, I'm not sure if I will support an actions directory. This project is intended for an audience of one (me). If I want something new, I would probably just add it in with Go. If this isn't a whole lot of work, I may do it to maintain feature parity.
I chose json for a config file because I want to minimize external dependencies and the config is quite small. If it grows I may explore toml.
Download the latest stable release for use on your desktop or server.
brew install todo-txt
cp -n $(brew --prefix)/opt/todo-txt/todo.cfg ~/.todo.cfgNote: The -n flag for cp makes sure you do not overwrite an existing file.
make
make install
make testNOTE: Makefile defaults to several default paths for installed files. Adjust to your system:
INSTALL_DIR: PATH for executables (default/usr/local/bin)CONFIG_DIR: PATH for thetodo/configconfiguration template (default/usr/local/etc)BASH_COMPLETION: PATH for autocompletion scripts (default to/usr/local/share/bash-completion/completions)
# Note: Showcasing config overrides for legacy locations; NOT recommended!
make install CONFIG_DIR=/etc INSTALL_DIR=/usr/bin BASH_COMPLETION=/etc/bash_completion.dhttps://aur.archlinux.org/packages/todotxt/
No configuration is required; however, most users tweak the default settings (e.g. relocating the todo.txt directory to a subdirectory of the user's home directory, or onto a cloud drive (via the TODO_DIR variable)), modify the colors, add additional highlighting of projects, contexts, dates, and so on. A configuration template with a commented-out list of all available options is included.
It is recommended to copy that template into one of the locations listed by todo.sh help on -d CONFIG_FILE, even if it is installed in the global configuration location (/etc/todo/config).
todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]For example, to add a todo item, you can do:
todo.sh add "THING I NEED TO DO +project @context"Replaces task on line NR with UPDATED TODO.
todo.sh replace NR "UPDATED TODO"Adds the number of open tasks and done tasks to report.txt.
todo.sh reportRead about all the possible commands in the USAGE file.
See CHANGELOG.md
Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
We welcome all contributions. First read our Contributor Code of Conduct and then get started contributing.
GNU General Public License v3.0 © todo.txt org
todo.txt README.md from GitHub
A complete primer on the whys and hows of todo.txt.
The first and most important rule of todo.txt:
A single line in your todo.txt text file represents a single task.
Plain text is software and operating system agnostic. It's searchable, portable, lightweight, and easily manipulated. It's unstructured. It works when someone else's web server is down or your Outlook .PST file is corrupt. There's no exporting and importing, no databases or tags or flags or stars or prioritizing or insert company name here-induced rules on what you can and can't do with it.
Using special notation in todo.txt, you can create a list that's sliceable by 3 key axes.
Your todo list should be able to tell you what's the next most important thing for you to get done - either by project or by context or overall. You can optionally assign tasks a priority that'll bubble them up to the top of the list.
The only way to move a big project forward is to tackle a small subtask associated with it. Your todo.txt should be able to list out all the tasks specific to a project.
In order to move along a project like "Cleaning out the garage," my task list should give me the next logical action to take in order to move that project along. "Clean out the garage" isn't a good todo item; but "Call Goodwill to schedule pickup" in the "Clean out garage" project is.
Getting Things Done author David Allen suggests splitting up your task lists by context - ie, the place and situation where you'll work on the job. Messages that you need to send go in the @email context; calls to be made @phone, household projects @home.
That way, when you've got a few minutes in the car with your cell phone, you can easily check your @phone tasks and make a call or two while you have the opportunity.
This is all possible inside todo.txt.
Your todo.txt is a plain text file. To take advantage of structured task metadata like priority, projects, context, creation, and completion date, there are a few simple but flexible file format rules.
Philosophically, the todo.txt file format has two goals:
- The file contents should be human-readable without requiring any tools other than a plain text viewer or editor.
- A user can manipulate the file contents in a plain text editor in sensible, expected ways. For example, a text editor that can sort lines alphabetically should be able to sort your task list in a meaningful way.
These two goals are why, for example, lines start with priority and/or dates, so that they are easily sorted by priority or time, and completed items are marked with an x, which both sorts at the bottom of an alphabetical list and looks like a filled-in checkbox.
Here are the rest.
The beauty of todo.txt is that it's completely unstructured; the fields you can attach to each task are only limited by your imagination. To get started, use special notation to indicate task context (e.g. @phone ), project (e.g. +GarageSale ) and priority (e.g. (A) ).
A todo.txt file might look like the following:
(A) Thank Mom for the meatballs @phone
(B) Schedule Goodwill pickup +GarageSale @phone
Post signs around the neighborhood +GarageSale
@GroceryStore pies
A search and filter for the @phone contextual items would output:
(A) Thank Mom for the meatballs @phone
(B) Schedule Goodwill pickup +GarageSale @phone
To just see the +GarageSale project items would output:
(B) Schedule Goodwill pickup +GarageSale @phone
Post signs around the neighborhood +GarageSale
There are three formatting rules for current todo's.
The priority is an uppercase character from A-Z enclosed in parentheses and followed by a space.
This task has a priority:
(A) Call Mom
These tasks do not have any priorities:
Really gotta call Mom (A) @phone @someday
(b) Get back to the boss
(B)->Submit TPS report
If there is no priority, the creation date appears first. If the creation date exists, it should be in the format YYYY-MM-DD.
These tasks have creation dates:
2011-03-02 Document +TodoTxt task format
(A) 2011-03-02 Call Mom
This task doesn't have a creation date:
(A) Call Mom 2011-03-02
- A context is preceded by a single space and an at-sign (
@). - A project is preceded by a single space and a plus-sign (
+). - A project or context contains any non-whitespace character.
- A task may have zero, one, or more than one projects and contexts included in it.
For example, this task is part of the +Family and +PeaceLoveAndHappiness projects as well as the @iphone and @phone contexts:
(A) Call Mom +Family +PeaceLoveAndHappiness @iphone @phone
This task has no contexts in it:
Email SoAndSo at soandso@example.com
This task has no projects in it:
Learn how to add 2+2
Two things indicate that a task has been completed.
If a task starts with an x (case-sensitive and lowercase) followed directly by a space, it is marked as complete.
This is a complete task:
x 2011-03-03 Call Mom
These are not complete tasks.
xylophone lesson
X 2012-01-01 Make resolutions
(A) x Find ticket prices
We use a lowercase x so that completed tasks sort to the bottom of the task list using standard sort tools.
For example:
x 2011-03-02 2011-03-01 Review Tim's pull request +TodoTxtTouch @github
If you’ve prepended the creation date to your task, on completion it will appear directly after the completion date. This is so your completed tasks sort by date using standard sort tools. Many Todo.txt clients discard priority on task completion. To preserve it, use the key:value format described below (e.g. pri:A)
With the completed date (required), if you've used the prepended date (optional), you can calculate how many days it took to complete a task.
Tool developers may define additional formatting rules for extra metadata.
Developers should use the format key:value to define additional metadata (e.g. due:2010-01-02 as a due date).
Both key and value must consist of non-whitespace characters, which are not colons. Only one colon separates the key and value.
- Add flags for some configs
- fix the default directory to point to ~/.config or $TODO_DIR env
- in args make it so that it isn't by string because wow would quoting be frustrating
- set defaults to all config values -- should there be a config check?
- add help to run? and add the help string to the like cmd list thing? TODO_DIR TODO_FILE DONE_FILE REPORT_FILE
CONFIG:
INBOX_FILE?
"TODO_DIR": "$HOME/Projects/todo.txt-cli", "TODO_FILE": "$TODO_DIR/todo.txt", "DONE_FILE": "$TODO_DIR/done.txt", "REPORT_FILE": "$HOME/.local/state/todo/report.txt"