todo-tree 0.3.0

# Todo Tree

A command-line tool to find and display TODO-style comments in your codebase, similar to the VS Code "Todo Tree" extension.

![Demo of Todo Tree](./assets/todo-tree.gif)

## Features

- 🔍 **Recursive directory scanning** - Respects `.gitignore` rules automatically
- 🏷️ **Configurable tags** - TODO, FIXME, BUG, NOTE, HACK, WARN, PERF, and more (and custom tags)
- 🌳 **Tree view output** - Beautiful hierarchical display grouped by file
- 📋 **Multiple output formats** - Tree, flat list, and JSON
- ⚙️ **Configuration file support** - `.todorc` in JSON or YAML format
- 🎨 **Colored output** - Priority-based coloring for different tag types
- 🔗 **Clickable links** - Terminal hyperlinks to file locations (where supported)
- 🧩 **Editor extensions** - Integrates with Zed
- 🤖 **GitHub Action** - Automatically scan PRs and post TODO summaries as comments

## Installation

### Using Homebrew (macOS/Linux)

```bash
brew tap alexandretrotel/todo-tree
brew install todo-tree
```

### Using Cargo

```bash
cargo install todo-tree
```

### NixOS (Flakes)

#### Try before you install

```bash
# runs the default todo-tree command
nix run github:alexandretrotel/todo-tree

# create a shell with the command available (with nix-output-monitor)
nom shell github:alexandretrotel/todo-tree
tt tags

# or, just normal nix
nix shell github:alexandretrotel/todo-tree
tt scan ~/projects/todo-tree --tags FIXME
```

**Note:** If you haven't enabled the experimental Nix command and flakes features, you need to pass `--extra-experimental-features "nix-command flakes"` to the command. See the [Nix command wiki](https://nixos.wiki/wiki/Nix_command) for more details.

#### Install for your system

```nix
# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    todo-tree.url = "github:alexandretrotel/todo-tree";
  };

  outputs = { self, nixpkgs, todo-tree, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [ ./configuration.nix ];
      specialArgs = { inherit todo-tree; };
    };
  };
}

# configuration.nix
{ pkgs, todo-tree, ... }:

{
  environment.systemPackages = [
    todo-tree.packages.${pkgs.stdenv.hostPlatform.system}.todo-tree
  ];
}
```

### From Source

```bash
# Clone the repository
git clone https://github.com/alexandretrotel/todo-tree.git
cd todo-tree

# Build and install
cargo install --path .
```

## Usage

The tool provides two binary names: `todo-tree` and `tt` (alias for quick access).

### Basic Commands

```bash
# Scan current directory (default command)
tt

# Scan a specific directory
tt scan ./src

# Scan with specific tags
tt scan --tags TODO,FIXME,BUG

# List all TODOs in flat format
tt list

# Show configured tags
tt tags

# Show statistics
tt stats
```

## Configuration

Create a `.todorc.json` or `.todorc.yaml` file in your project root:

### JSON Format (`.todorc.json`)

```json
{
  "tags": ["TODO", "FIXME", "BUG", "NOTE", "HACK", "XXX", "WARN", "PERF"],
  "include": ["*.rs", "*.py", "*.js", "*.ts"],
  "exclude": ["target/**", "node_modules/**", "dist/**"],
  "json": false,
  "flat": false,
  "no_color": false,
  "ignore_case": false,
  "require_colon": true
}
```

### YAML Format (`.todorc.yaml`)

```yaml
tags:
  - TODO
  - FIXME
  - BUG
  - NOTE
  - HACK

include:
  - "*.rs"
  - "*.py"

exclude:
  - "target/**"
  - "node_modules/**"

json: false
flat: false
no_color: false
```

### Configuration Search Order

1. `.todorc` in the current directory
2. `.todorc.json` in the current directory
3. `.todorc.yaml` or `.todorc.yml` in the current directory
4. Parent directories (recursive)
5. `~/.config/todo-tree/config.json` (global config)

## Supported Comment Styles

The tool recognizes TODO-style tags in various comment formats:

| Language | Comment Styles |
|----------|---------------|
| C, C++, Rust, Go, Java, JavaScript, TypeScript | `//`, `/* */` |
| Python, Ruby, Shell, YAML | `#` |
| HTML, XML | `<!-- -->` |
| SQL | `--`, `/* */` |
| Lisp, Clojure | `;` |
| Lua | `--` |

### Tag Formats Recognized

By default, todo-tree requires tags to be **UPPERCASE** and followed by a **colon**:

```rust
// TODO: This will be found ✓
// FIXME: This will be found ✓
// BUG: This will be found ✓

// todo: This will NOT be found (lowercase) ✗
// TODO This will NOT be found (no colon) ✗
// Todo: This will NOT be found (mixed case) ✗
```

**Optional author/assignee syntax** (still works with colon):
```rust
// TODO(john): Assigned to john ✓
// FIXME(team): Needs team review ✓
```

#### Flexible Matching Options

You can customize the matching behavior with CLI flags:

```bash
# Ignore case when matching (matches TODO, todo, Todo, etc.)
tt scan --ignore-case

# Allow tags without colon (matches "TODO something")
tt scan --no-require-colon

# Use both options together (most flexible, like v0.2.x behavior)
tt scan --ignore-case --no-require-colon
```

Or set these options in your `.todorc.json`:

```json
{
  "ignore_case": true,
  "require_colon": false
}
```

#### Why These Defaults?

The strict defaults (uppercase + colon required) significantly reduce false positives:
- Code like `std::io::Error` in Rust/C++ won't match
- Variable names like `ERROR_CODE` won't match
- Prose like "this is an error" won't match
- Type definitions like `Result<T, Error>` won't match

These defaults align with most coding conventions and help you find **intentional TODO comments**, not accidental matches.

## Priority Levels

Tags are assigned priority levels for sorting and coloring:

| Priority | Tags | Color |
|----------|------|-------|
| Critical | BUG, FIXME, ERROR | Red |
| High | HACK, WARN, WARNING, FIX | Yellow |
| Medium | TODO, WIP, MAYBE | Cyan |
| Low | NOTE, XXX, INFO, DOCS, PERF, TEST, IDEA | Green |

## Terminal Support

### Clickable Links

The tool generates clickable hyperlinks (OSC 8) in supported terminals:

- iTerm2
- WezTerm
- Hyper
- VS Code Terminal
- GNOME Terminal (VTE 0.50+)
- Konsole
- Alacritty

### Color Support

Colors are automatically enabled when outputting to a terminal. Use `--no-color` or set the `NO_COLOR` environment variable to disable.

## Related Projects

### [todo-tree-action](https://github.com/alexandretrotel/todo-tree-action)

A GitHub Action that automatically scans your pull requests for TODO comments and posts a summary as a PR comment. Features include:
- Scan only changed files in PRs
- Filter to show only NEW TODOs (not in base branch)
- Automatic PR comment with formatted results
- Full configuration support

### [zed-todo-tree](https://github.com/alexandretrotel/zed-todo-tree)

A Zed Editor extension that integrates TODO scanning directly into Zed. Features include:
- Interactive results in the assistant panel
- Full configuration support
- Seamless editor integration

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feat/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feat/amazing-feature`)
5. Open a Pull Request

## Acknowledgments

- Inspired by the [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) VS Code extension
- Built with [clap](https://github.com/clap-rs/clap), [ignore](https://github.com/BurntSushi/ripgrep/tree/master/crates/ignore), and [regex](https://github.com/rust-lang/regex)

## License

MIT License - see [LICENSE](LICENSE) for details.