cargo-todox

Ensure source files in a cargo project do not contain TODOX issues.

Installing

To install:

cargo install cargo-todox

Running

To run on a cargo project in the current working directory:

cargo todox

This will list all (case insensitive) occurrences of the string TODOX anywhere in any of the project source files (taken from git ls-files). It will succeed if and only if there are no such occurrences.

Supported command line flags are:

• Run cargo todox DIRECTORY to only check files in a specific directory.
• Run cargo todox --output FILE to redirect the output to a file.
• Run cargo todox --version to report the version number.
• Run cargo todox --help to get a help message listing the options.

Why use TODOX?

Using TODOX allows making temporary changes to the code which must be addressed before checking the code in. This can for any of several reasons: debugging, getting something quick-and-dirty running, investigating alternatives, or just noting an issue which must be addressed.

Whatever the reason, using TODOX allows marking the issue and moving on without having to worry about it. Before completing the work, all such markers need to be removed, either by converting them into a TODO for later work or by fixing the issue. This is where cargo todox comes in - it emits a nicely formatted list of all the locations of this marker anywhere in the project, and only exits with a zero status only if no such markers are found. It is therefore easy to include cargo todox in the pre-commit checks, and/or in CI builds.

This is a generalization of using report_fixme = "Always" in rustfmt, a feature which seems on its way to be removed. The differences between report_fixme and cargo todox are:

• It looks everywhere in all source files, rather than only in comments in .rs files. This allows using todox as a part of the name of a variable, inside comments, inside printed debugging messages, inside .toml files, inside .yaml files, in the README files, etc. In contrast, FIXME is only detected in comments in rust files, which allows for most, but not all, of the useful cases for such a marker.

• It allows for exempting lines by saying ALLOW TODOX (typically in a comment). This allows configuration files to specify running cargo todox without being reported themselved.

• It looks for the (case insensitive) string TODOX, rather than the string FIXME.

License

cargo-todox is distributed under the GNU General Public License (Version 3.0). See the LICENSE for details.