Rusty TODO MD — A Pre-Commit Hook & CLI for Managing TODOs

Rusty TODO MD helps you find, centralize, and maintain all your TODO comments across your codebase. It can run as a pre-commit hook or from the CLI, automatically extracting TODO-style comments into a structured TODO.md file.

Supports a wide range of languages and file types, with sectioned formatting, multi-line support, and smart sync.

📌 Recommended usage: Pre-commit via shim repo

When pre-commit installs a hook from a Git repo, it runs pip install . from that repo — which would normally build Rusty TODO MD from source (requiring a Rust toolchain).

The shim repository (rusty-todo-md-pre-commit) solves this by depending on the rusty_todo_md PyPI package, ensuring prebuilt wheels are used.

Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/simone-viozzi/rusty-todo-md-pre-commit
    rev: v1.7.5  # Use the latest upstream tag (shim mirrors upstream)
    hooks:
      - id: rusty-todo-md

Then install the hook:

pre-commit install

✅ No Rust toolchain is required when using the shim and a supported platform.

⚙️ CLI installation

You can also install Rusty TODO MD directly for manual CLI use:

pip install rusty_todo_md

Then run:

rusty-todo-md --help

✨ Key Features

1. Automatic TODO Collection By default, Rusty TODO MD scans your staged files (or all tracked files using the --all-files flag) for markers like TODO and FIXME, and updates your TODO.md with any new entries.

2. Sectioned TODO.md Format The TODO.md file is now organized into sections, grouped first by marker (e.g., # TODO, # FIXME), then by file. Each marker section begins with a header (# <MARKER>), each file with a sub-header (## <file-path>), followed by a list of extracted TODO items.

3. Multi-line TODO Support Handles multi-line and indented TODO comments, merging them into a single entry.

4. Sync Mechanism

   • Automatically merges new TODO entries with existing ones, using an internal representation.
   • Removes entries when their corresponding TODOs are no longer present in the source code.

5. Language-Aware Parsing Supports precise parsing for Python, Rust, JavaScript, and Go out-of-the-box, with plans for additional languages such as TypeScript, PHP, and Java.

6. Seamless Pre-Commit Integration Easily integrate Rusty TODO MD into your workflow by adding it to your .pre-commit-config.yaml.

🧩 CLI usage

Scan staged files

rusty-todo-md

Scan all tracked files

rusty-todo-md --all-files

Use multiple markers

rusty-todo-md --markers TODO FIXME HACK

Custom TODO.md path

rusty-todo-md --todo-path docs/TODOS.md

📝 Supported languages & extensions

Rusty TODO MD detects comment syntax based on file extension:

Many extensions share the same parser (e.g., JS-style comment parsing for TS, Java, C-like languages).

🔍 Output format (stable)

Entries in TODO.md use this format:

* [path/to/file.ext:LINE](path/to/file.ext#L{LINE}): MESSAGE

This format is stable and designed for easy linking to code in hosted repos.

Example:

# TODO
## src/main.rs
* [src/main.rs:10](src/main.rs#L10): Refactor initialization logic

📦 Requirements & Supported Platforms

• Python ≥ 3.10
• No Rust toolchain needed if using the shim or PyPI wheels

Prebuilt wheels are published for:

🛠 Troubleshooting

• If no wheel is available for your platform, pip will try to build from source — which requires a Rust toolchain.
• If you encounter build errors, please:
  1. Check the latest releases to confirm wheel availability.
  2. Open an issue with your OS/arch details.

👩‍💻 Development

If you want to run Rusty TODO MD directly from the main repo via pre-commit (building from source):

repos:
  - repo: https://github.com/simone-viozzi/rusty-todo-md
    rev: v1.7.5
    hooks:
      - id: rusty-todo-md

⚠️ This will compile the Rust source and requires a working Rust toolchain.

🤝 Contributing

Contributions are welcome!

• Open an issue for bug reports or feature requests.
• Submit a pull request with improvements, new parsers, or fixes.

📚 Links

• Shim repo (recommended for pre-commit): rusty-todo-md-pre-commit
• PyPI package: rusty_todo_md
• Releases: GitHub Releases

⚖️ License

Licensed under the MIT License.

❤️ Support

If you find Rusty TODO MD helpful, please consider giving it a ⭐ on GitHub to help others discover the project.