Skip to content

README.md

Latest commit

 

History

History
176 lines (117 loc) · 3.42 KB

README.md

File metadata and controls

176 lines (117 loc) · 3.42 KB

src-todo

CLI tool for managing TODO comments in source code files.

Description

src-todo is a command-line interface written in Haskell (btw) that scans source files for TODO comments, allowing users to register new TODOs with

unique IDs, list existing TODOs, display details for a specific TODO by ID, replace TODO IDs, and unregister TODOs (removing their IDs). It supports TODO formats like "TODO: (id) description" or "TODO: description", where IDs are optional and now generated as UUIDs for uniqueness.

The tool operates on files or directories (default: current directory), parsing comments using Megaparsec and handling file updates in place.

Installation

  1. Ensure you have Haskell installed (GHC recommended) along with Cabal or Stack.

  2. Clone the repository:

    git clone https://github.com/LitFill/src-todo.git

  3. Navigate to the project directory:

    cd src-todo

  4. Build and install the executable:

    • Using Cabal:

      cabal build
cabal install

    • Using Stack:

      stack build
stack install

This will make the src-todo command available in your PATH.

Usage

Run the tool with:

src-todo <command> [options] [FILES...]

If no files are specified, it defaults to the current directory (.).

Commands

  • register: Scans for TODOs without IDs, assigns a new unique UUID-based ID, updates the files in place, and outputs the new IDs.

    src-todo register [FILES...]

    Example:

    src-todo register src/

    Output (if new TODOs are found):

    Registered new todos with these ids:
123e4567-e89b-12d3-a456-426614174000

  • unregister : Removes the ID and parenthesis from a TODO with the specified ID, restoring the line to its original, unregistered form.

    src-todo unregister <ID> [FILES...]

    Example:

    src-todo unregister 123e4567-e89b-12d3-a456-426614174000 src/

    Output:

    Unregistered id 123e4567-e89b-12d3-a456-426614174000 at src/module.hs:10

  • show : Displays details for a TODO with the specified ID, including note, ID, and location (file:line).

    src-todo show <ID> [FILES...]

    Example:

    src-todo show 20250914123456789012 src/

    Output:

    # Todo
  - note     : Implement feature X
  - id       : 20250914123456789012
  - location : src/module.hs:10

  • list: Lists all TODOs found in the specified files/directories, displaying each with note, ID (if present), and location.

    src-todo list [FILES...]

    Example:

    src-todo list .

    Output:

    # Todo
  - note     : Fix bug Y
  - id       : 20250914123456789012
  - location : src/file.hs:5

# Todo
  - note     : Optimize Z
  - id       :
  - location : src/another.hs:20

  • replace-id <OLD_ID> <NEW_ID>: Replaces the specified old ID with a new ID in matching TODOs and updates the files.

    src-todo replace-id <OLD_ID> <NEW_ID> [FILES...]

    Example:

    src-todo replace-id 20250914123456789012 new-custom-id src/

    Output:

    The id 20250914123456789012 is replaced with new-custom-id

Contributing

Contributions are welcome. Fork the repository, make changes, and submit a pull request. Ensure code adheres to my Haskell best practices.

License

MIT License. See LICENSE file for details.