Uniform todo listing from Github, Redmine, Files...
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



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 github.com/<gh_user> repo
  • Google Project Hosting -- issues from identically named code.google.com/p/ project
  • Redmine -- issues from identically named project on your.redmine.com 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>