na: per-project todos in Terminal

As I’ve mentioned before, I keep todo.taskpaper files in my web and code project folders. These allow me to keep track of bugs, ideas, notes, etc., and the archive it creates helps me remember what I did, when I did it and how it worked. I like having them separated per project; it’s the way my one-track mind works. I like the plain-text format because I can use any variety of methods (including TaskPaper itself) to manipulate and quickly update the files. This gave me the idea to have Terminal just notify me of current todos whenever I switched to a project. Thus, na was born. Whether or not it’s useful to anyone else remains to be seen, but I figured I’d share it anyway.

Yesterday at 5:30pm, this little project was working fine with about eight lines of code. Then I had an idea or two, and by morning it was 160 lines of code. It definitely got out of hand, but I rather like the final product. The bulk of the script is straight bash and UN*X commands, but I shelled a lot of the more complex string handling out to Ruby. I’m too lazy to deal with awk and sed past a certain point.

Feel free to skip to the na GitHub repo, peek at the readme.md file and start playing. I welcome any revisions/iterations of this, so feel free to fork and let me know what you do with it!

Meet “na”

na is a bash function designed to make it easy to see what your next actions are for any project, right from the command line. It works with TaskPaper-format files (but any plain text format will do), looking for @na tags (or whatever you specify) in todo files in your current folder. It can also auto-display next actions when you enter a project directory, automatically locating any todo files and listing their next actions when you cd to the project (optionally recursive).

Features

You can list next actions in files in the current directory by typing na. By default, na looks for “.taskpaper” files and extracts items tagged “@na” and not “@done”. All of these can be changed in the configuration.

Easy matching

na features intelligent project matching. Every time it locates a todo file, it adds the project to the database. Once a project is recorded, you can list its actions by using any portion of the parent directories names. If your project is in “~/Sites/dev/markedapp,” you could quickly list its next actions by typing na dev mark. It will always look for the shortest match.

Recursion

na can also recurse subdirectories to find all todo files in child folders as well. Use the -r switch to do a recursive search on the current directory. na -r with no arguments will recurse from your current location, looking for todo files in all subdirectories. Maximum depth for recursion can be controlled in the config (default is 4). na -r can take a path or project title fragments as arguments as well, and will recurse from the matched directory. A configuration option allows you to have the auto-display recurse by default.

Adding todos

You can also quickly add todo items from the command line with the -a switch. The script will look for a file in the current directory called todo.taskpaper (or whatever extension you’ve set). If found, it will try to locate an “Inbox:” project, or create one if it doesn’t exist. Any arguments after -a will be combined to create a new task in TaskPaper format. They will automatically be assigned as next actions (tagged “@na”) and will show up when na lists the tasks for the project.

More details and usage examples (as well as the download) on the GitHub page.