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.9.1  # Use the latest upstream tag (shim mirrors upstream)
    hooks:
      - id: rusty-todo-md
        args: ["--auto-add", "--markers", "TODO", "FIXME", "HACK", "--"]
        language_version: python3.11

• args customise the markers to scan for and enable --auto-add to stage TODO.md automatically.
• language_version forces the hook to run with a specific Python interpreter.

Example with exclusions:

repos:
  - repo: https://github.com/simone-viozzi/rusty-todo-md-pre-commit
    rev: v1.9.1
    hooks:
      - id: rusty-todo-md
        args:
          - "--auto-add"
          - "--markers"
          - "TODO"
          - "FIXME"
          - "HACK"
          - "--exclude-dir"
          - "node_modules"
          - "--exclude-dir"
          - "target"
          - "--exclude"
          - "**/*.test.js"
          - --
        language_version: python3.11

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 the files passed to it (typically staged files from pre-commit) 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.

7. Auto-stage Updated TODO.md With the --auto-add flag, the tool can automatically stage the TODO.md file after updates.

🧩 CLI usage

Scan staged files

rusty-todo-md

Use multiple markers

rusty-todo-md --markers TODO FIXME HACK

Specify files to process with markers

When using --markers as the last option before specifying files, use -- to separate markers from files:

rusty-todo-md --markers TODO FIXME HACK -- file1.rs file2.rs

Without the -- separator, the files would be incorrectly treated as additional markers.

Automatically stage TODO.md

rusty-todo-md --auto-add path/to/file.rs

Custom TODO.md path

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

Exclude files and directories

Rusty TODO.md supports glob-based exclusion patterns to filter out files and directories from TODO extraction.

Exclude specific files or patterns

# Exclude all log files
rusty-todo-md --exclude "*.log"

# Exclude specific file
rusty-todo-md --exclude "config.rs"

# Exclude files in a specific directory
rusty-todo-md --exclude "src/generated/*"

Exclude directories

# Exclude a directory (and all files within it)
rusty-todo-md --exclude-dir "build"

# Or use --exclude with trailing slash
rusty-todo-md --exclude "build/"

# Exclude multiple directories
rusty-todo-md --exclude-dir "node_modules" --exclude-dir "target"

Recursive exclusion with wildcards

# Exclude all files under src/ recursively
rusty-todo-md --exclude "src/**"

# Exclude all .test.js files anywhere in the tree
rusty-todo-md --exclude "**/*.test.js"

# Exclude all 'vendor' directories at any depth
rusty-todo-md --exclude-dir "**/vendor"

Multiple exclusion patterns

# Combine multiple exclusions
rusty-todo-md \
  --exclude "*.log" \
  --exclude "*.tmp" \
  --exclude-dir "build" \
  --exclude-dir "dist" \
  --markers TODO FIXME

Glob pattern syntax

• * — matches any sequence of characters within a single path component
• ? — matches any single character
• ** — matches zero or more path components (recursive)
• / suffix — indicates directory-only matching (when used with --exclude)

Note: Patterns are matched relative to the scan root. The --exclude-dir flag automatically ensures directory-only matching.

📝 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.