# Comment-Stripper-RS
A production-grade CLI that strips comments from Rust source trees using
[`ra-ap-rustc_lexer`](https://crates.io/crates/ra-ap-rustc_lexer) — the same
lexer Rust Analyzer is built on.
## Why a Rust-dedicated comment-stripping tool?
### `ra-ap-rustc_lexer` (what we use)
**Pros**
- Matches Rust syntax rules closely.
- Rust Analyzer aligned behavior.
- Lexical tasks, like stripping comments, are handled at the tokenization layer.
- Simpler and lighter than a full parser stack.
### Tree-sitter (why we don't use it)
**Cons**
- More complex than a lexer for stripping comments.
- A grammar can be imperfect or behave differently across bindings/languages.
- It's broader than needed for a Rust-only, comment-stripping tool.
## Installation
```sh
cargo install --path .
# or build a release binary
cargo build --release # -> target/release/comment-stripper-rs
```
## Usage
```sh
# Strip comments from the current directory (recursively)
comment-stripper-rs
# A single file or specific directories
comment-stripper-rs src/main.rs
comment-stripper-rs crate_a/ crate_b/
# Preview what would change without writing anything (exits non-zero if any would)
comment-stripper-rs --check
# Also strip rustdoc comments
comment-stripper-rs --strip-docs
```
`--include` globs are matched against each file's path relative to the root, its
raw walked path, and its canonical absolute path — so both relative globs and
absolute paths work:
```sh
comment-stripper-rs -i 'src/**/*.rs'
comment-stripper-rs -i /abs/path/to/file.rs
```
Each rewritten file gets a `.bak` backup next to it by default. Use
`--no-backup` to skip backups, `--restore-backups` to undo a run, or
`--clean-backups` to delete the backups once you're happy.
## Options
| `[PATH]...` | | One or more files or directories to process (defaults to `.`). |
| `--check` | `-c` | Report files that would change without rewriting them; exit non-zero if any would. |
| `--verbose` | `-v` | Print changed file paths. |
| `--no-backup` | `-n` | Do not create `.bak` backup files when rewriting. |
| `--strip-docs` | `-d` | Also strip rustdoc comments (`///`, `//!`, `/** */`, `/*! */`). |
| `--hidden` | | Include hidden files and directories. |
| `--follow-links` | | Follow symlinks. |
| `--clean-backups` | | Delete backup files (matching `--backup-suffix`) instead of stripping comments. |
| `--restore-backups` | | Restore backup files over their originals instead of stripping comments. |
| `--backup-suffix <SUFFIX>` | | Suffix appended to backup files (default `.bak`; also matched by `--clean-backups`/`--restore-backups`). |
| `--exclude-dirs <NAMES>` | `-e` | Comma-separated directory names to skip (`target` and `.git` are always excluded). |
| `--include <GLOBS>` | `-i` | Comma-separated glob patterns; only matching files are stripped (e.g. `src/**/*.rs`). Use `**` to cross directories. Excluded dirs still win. |
## Behavior notes
- **Rustdoc comments are preserved** unless `--strip-docs` is given.
- **Whole-line comments are removed line and all.** A comment that is the only
content on its line (e.g. a `///` doc line under `--strip-docs`, or an indented
`// note`) is removed along with its blank line, rather than left behind as an
empty line. Blank lines that were already in the source are preserved.
- **Inline comments preserve line numbers.** A comment that follows code on the
same line (including multi-line block comments mid-code) keeps the line intact,
so line numbers don't shift.
- **Trailing whitespace** left after removing a comment is stripped, except
inside string literals, raw strings, frontmatter, and preserved doc comments.
- `target` and `.git` are always excluded from traversal.