Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Uniform todo listing from Github, Redmine, Files...
Branch: master

Implement a Todofile that may define what's a project's root

If a project does not use neither Mercurial nor Git all Provider can
only use the current working directory as project root (and thereby
project name etc.).
Now an existing "Todofile" file will be used as an hint that the containing
directory is the project root.
latest commit d55e1c48e8
@cmur2 authored


ctodo provides combined listing of "issues" or "todos" from different Issue Providers (like a Github or Google Code project) with color output support.

The intended use case is that you as e.g. a developer have the source code of a software project (maybe under version control with Mercurial or Git) located in a single root directory and that you want to have an quick overview from the command line which issues you have to face in your software.

Another example would be somebody with some documents that belong to a larger (maybe academic) project with some "issues" in these documents that he wants an overview of via cli.

ctodo is written in Ruby.


  • LocalFS -- grep-like local file system provider
  • Github -- issues from identically named repo
  • Google Project Hosting -- issues from identically named project
  • Redmine -- issues from identically named project on instance


gem install ctodo

Basic Usage

You are supposed to run ctodo from cli simply via ctodo.

Now ctodo will search and list all found issues for your current project.

How ctodo knows what your "current project" is

There are several automatisms currently built in:

If from the current working directory on any of the parent directories contains a .git or .hg directory this is taken as an indicator that this containing directory is the root directory of your project.

If you're not in a Mercurial or Git repository, the current working directory is assumed to be the root directory of your project.

The name of the root directory is assumed to be your project's name or an appropriate identifier for your project.

Issue Providers

Without further configuration ctodo will simply search all files and directories beneath the root directory recursively line by line for strings like

TODO: something


XXX fix bug

etc. by using the most basic Issue Provider called localfs.

If you decide to give ctodo some hints about where you usually share your project's (version controlled) files like your Github account name or the credentials to some Redmine instance ctodo will be capable to locate and display more issues than from local files: e.g. when you have created a Github repository "blub" with attached issues ctodo will assume that these issues belong to a project "blub" (located in the root directory "blub") on your hard disk and display them accordingly.

Template for ~/.todo

# config for ctodo
# If you don't want to use some of these services just
# remove the corresponding lines below:
:gh_user: <github-user>
:red_uri: <redmine-base-uri>
:red_key: <redmine-api-key>
:red2_uri: <another-redmine-base-uri>
:red2_key: <another-redmine-api-key>


Something went wrong with that request. Please try again.