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

   • Each run rescans the files being committed plus every tracked file TODO.md already lists, and rewrites TODO.md from that scan.
   • Removes entries when their corresponding TODOs (or files) 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.

🔀 Rebase conflicts in TODO.md

Why it happens

Each TODO.md bullet embeds the line number twice — once in the label and once in the link anchor (* [file:line](file#L<line>)). When two branches both shift the same TODO to different line numbers, git's line-by-line text merge sees the same physical TODO.md line edited differently on each side and produces a conflict — at every replayed commit during a rebase. The user did not meaningfully edit TODO.md; the line numbers just moved.

Fix: one line in .gitattributes

Commit this to your repository. If you use --todo-path, write that path instead of TODO.md, relative to the repository root (.gitattributes patterns are repository-relative); a path containing spaces or *, ?, [, #, ", \, or starting with !, needs gitattributes quoting/escaping:

/TODO.md merge=union

(The leading / anchors the rule to the root TODO.md; without it, it would also apply to any other file named TODO.md in a subdirectory.)

union is built into git, so there is nothing to install or configure per clone. Git then merges TODO.md by keeping the lines from both sides instead of stopping with a conflict, so rebases and merges never stop on TODO.md.

The merged TODO.md is temporarily wrong (old and new line numbers side by side, out of order), and that's expected. Each hook run rebuilds TODO.md from the files being committed plus every file TODO.md already lists, so the next normal commit replaces whatever the merge left, whatever files it touches. Commits replayed during the rebase keep the approximate TODO.md, because git doesn't run hooks during a rebase.

Without the .gitattributes line, resolve a TODO.md conflict by keeping both sides (leaving the conflict markers in is fine too); the next hook run rebuilds it the same way, and prints a hint with the exact merge=union line for your path (or points here when the path needs escaping). Don't resolve it by taking only one side (e.g. git checkout --ours TODO.md): the files listed only on the other side would no longer be listed, so their TODOs would not come back until those files change or you run --regenerate. To rebuild it right away:

rusty-todo-md --regenerate

This re-scans every tracked file and rewrites TODO.md from scratch. Source files that still contain conflict markers are skipped with a warning rather than producing garbled TODOs.

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

The file has a single # TODOs title, one ## section per marker and one ### subsection per file:

# TODOs

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

A TODO.md written by a version before 1.11 (markers as #, files as ##) is rebuilt automatically, from all tracked files, the first time the hook runs.

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