Skip to content
Back to search

uncomment

MarketplaceWorks with Claude CodeGitHub

Uncomment skills for AST-based source comment cleanup

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/goldziher--uncomment/badge.svg)](/listings/goldziher--uncomment)

HTML

<a href="/listings/goldziher--uncomment"><img src="/api/listings/goldziher--uncomment/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| Channel | Command | | ---------------------- | ----------------------------------------------------------------------------------------------- | | Homebrew (macOS/Linux) | `brew install polylint/tap/uncomment` | | Scoop (Windows) | `scoop bucket add polylint https://github.com/polylint/scoop-bucket && scoop install uncomment` | | Cargo (Rust) | `cargo install uncomment` | | npm (Node.js) | `npm i -g @polylint/uncomment` | | pip (Python) | `pip install uncomment` |

The npm and pip packages install the prebuilt binary from a per-platform package (npm `optionalDependencies`, platform wheels on PyPI), so nothing is downloaded at install time on macOS, glibc Linux and Windows x64. Only when no platform package matches the host do they fall back to downloading the release archive from GitHub.

Prefer prebuilt binaries? [`cargo binstall uncomment`](https://github.com/cargo-bins/cargo-binstall) downloads a release archive instead of compiling from source.

Run without installing:

npx @polylint/uncomment .
uvx uncomment .

Add `--dry-run` to preview changes before writing.

<details> <summary><b>Build from source</b></summary>

git clone https://github.com/polylint/uncomment.git
cd uncomment
cargo install --path .

Requires Rust 1.99+.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "uncomment",
  3. "description": "Uncomment skills for AST-based source comment cleanup",
  4. "owner": {
  5. "name": "polylint"
  6. },
  7. "plugins": [
  8. {
  9. "name": "uncomment",
  10. "description": "Inventory, preserve and remove source comments with AST parsing. Skills only; install the Uncomment CLI separately.",
  11. "source": "./plugin"
  12. }
  13. ]
  14. }
README.md · README · 803 lines
  1. <div align="center">
  2. <img src="assets/banner.svg" alt="uncomment — strip the noise, keep the code" width="820">
  3. **Strip the noise. Keep the code. Lint what's left.**
  4. uncomment is a comment remover and a comment linter, both built on tree-sitter's AST — so both are
  5. 100% accurate and **never** touch comment-like text inside strings. Removal keeps what matters by
  6. default (TODO/FIXME, docs, and linting directives) across **300+ languages**; linting checks that
  7. tag comments (TODO, FIXME, HACK, XXX) carry a real issue key instead of going stale. Either one can
  8. gate a commit or a pull request — scoped to a whole tree, to what a branch changed, or line by
  9. line — with parallel processing and a safe dry-run mode.
  10. AST-accurate&nbsp;·&nbsp;306 languages&nbsp;·&nbsp;zero false positives&nbsp;·&nbsp;tag-comment linting&nbsp;·&nbsp;changed-lines scoping&nbsp;·&nbsp;parallel&nbsp;·&nbsp;dry-run
  11. [![crates.io](https://img.shields.io/crates/v/uncomment?style=flat-square&color=2dd4bf)](https://crates.io/crates/uncomment)
  12. [![npm](https://img.shields.io/npm/v/@polylint/uncomment?style=flat-square&color=2dd4bf&label=npm)](https://www.npmjs.com/package/@polylint/uncomment)
  13. [![PyPI](https://img.shields.io/pypi/v/uncomment?style=flat-square&color=2dd4bf)](https://pypi.org/project/uncomment/)
  14. [![CI](https://img.shields.io/github/actions/workflow/status/polylint/uncomment/ci.yml?style=flat-square&label=CI)](https://github.com/polylint/uncomment/actions)
  15. [![License: MIT](https://img.shields.io/badge/License-MIT-2dd4bf?style=flat-square)](./LICENSE)
  16. [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-2dd4bf?style=flat-square&logo=github-sponsors)](https://github.com/sponsors/Goldziher)
  17. [Install](#installation)&nbsp;·&nbsp;[Features](#features)&nbsp;·&nbsp;[Usage](#usage)&nbsp;·&nbsp;[Linting](#subcommands)&nbsp;·&nbsp;[GitHub Action](#github-action)&nbsp;·&nbsp;[Configuration](#configuration)&nbsp;·&nbsp;[How it works](#how-it-works)&nbsp;·&nbsp;[Contributing](#contributing)
  18. </div>
  19. ---
  20. ## Why uncomment
  21. Regex-based comment strippers guess. They delete a `//` inside a string literal, mangle a URL in a
  22. docstring, or leave a linting directive your CI depends on. uncomment doesn't guess: it parses your
  23. code into a real syntax tree and acts only on the nodes that are genuinely comments.
  24. Originally built to clean up AI-generated code drowning in explanatory comments, it now works on
  25. anything with a tree-sitter grammar — and it grew a second job alongside the first. Deleting
  26. comments and keeping the ones that track work are the same problem seen from two sides: both need
  27. to know, precisely, which comments exist and what they say. `uncomment` removes; `uncomment lint`
  28. checks that a TODO or FIXME still points at a live issue key instead of quietly rotting; `uncomment
  29. --check` gates a commit or a pull request on either policy without writing anything.
  30. ## Features
  31. - **100% accurate** — tree-sitter AST parsing identifies comments structurally, not by pattern matching
  32. - **No false positives** — never removes or misreads comment-like content inside strings
  33. - **Smart preservation** — keeps TODO/FIXME, docs, and language-specific linting directives by default
  34. - **Tag-comment linting** — `uncomment lint` checks TODO/FIXME/HACK/XXX for a canonical form and a real issue key, with `--fix` and a baseline for adopting it on an existing codebase
  35. - **Gate-ready** — `--check` and `lint` both exit non-zero on a violation, scoped to a whole tree, `--changed-only`/`--changed-lines` against a base ref, or `--staged`
  36. - **306 languages** — powered by [tree-sitter-language-pack](https://github.com/kreuzberg-dev/tree-sitter-language-pack), every grammar compiled into the binary
  37. - **Parallel** — multi-threaded processing that scales across cores
  38. - **Safe** — dry-run mode with line-by-line diffs previews every change before you write
  39. - **Configurable** — hierarchical TOML config with a smart `init` command
  40. - **Built-in benchmarking** — optional performance analysis and profiling tools
  41. ## Installation
  42. | Channel | Command |
  43. | ---------------------- | ----------------------------------------------------------------------------------------------- |
  44. | Homebrew (macOS/Linux) | `brew install polylint/tap/uncomment` |
  45. | Scoop (Windows) | `scoop bucket add polylint https://github.com/polylint/scoop-bucket && scoop install uncomment` |
  46. | Cargo (Rust) | `cargo install uncomment` |
  47. | npm (Node.js) | `npm i -g @polylint/uncomment` |
  48. | pip (Python) | `pip install uncomment` |
  49. The npm and pip packages install the prebuilt binary from a per-platform package (npm
  50. `optionalDependencies`, platform wheels on PyPI), so nothing is downloaded at install time on
  51. macOS, glibc Linux and Windows x64. Only when no platform package matches the host do they fall
  52. back to downloading the release archive from GitHub.
  53. Prefer prebuilt binaries? [`cargo binstall uncomment`](https://github.com/cargo-bins/cargo-binstall) downloads a
  54. release archive instead of compiling from source.
  55. Run without installing:
  56. ```bash
  57. npx @polylint/uncomment .
  58. uvx uncomment .
  59. ```
  60. Add `--dry-run` to preview changes before writing.
  61. <details>
  62. <summary><b>Build from source</b></summary>
  63. ```bash
  64. git clone https://github.com/polylint/uncomment.git
  65. cd uncomment
  66. cargo install --path .
  67. ```
  68. Requires Rust 1.99+.
  69. </details>
  70. ## Quick Start
  71. ```bash
  72. # Generate a configuration file tuned to your project
  73. uncomment init
  74. # Remove comments from a directory
  75. uncomment src/
  76. # Preview changes as a diff, write nothing
  77. uncomment src/ --dry-run --diff
  78. ```
  79. ## Usage
  80. ```bash
  81. # Single file
  82. uncomment file.py
  83. # Multiple files / globs
  84. uncomment src/*.py
  85. # Also strip doc comments and docstrings
  86. uncomment --remove-doc file.py
  87. # Also remove TODO and FIXME comments (preserved by default)
  88. uncomment --remove-todo --remove-fixme file.py
  89. # Add custom patterns to preserve
  90. uncomment --ignore "HACK" --ignore "WARNING" file.py
  91. # Skip paths entirely, whatever the comments in them
  92. uncomment . --exclude "playground/**" --exclude "thirdparty/**"
  93. # Process an entire tree with all CPU cores
  94. uncomment . -j 0
  95. # Fail (exit 1) if any comment would be removed, writing nothing
  96. uncomment --check src/
  97. ```
  98. Run `uncomment --help` for the full, grouped list of options.
  99. <details>
  100. <summary><b>Configuring with <code>init</code></b></summary>
  101. The `init` command detects the languages in your project and writes a matching `.uncomment.toml`:
  102. ```bash
  103. # Smart detection — includes only the languages it finds
  104. uncomment init
  105. # Every global and pattern option, fully commented
  106. uncomment init --comprehensive
  107. # Interactive selection
  108. uncomment init --interactive
  109. # Custom output location / overwrite
  110. uncomment init --output config/uncomment-rules.toml --force
  111. ```
  112. </details>
  113. <details>
  114. <summary><b>Optional benchmarking tools</b></summary>
  115. Development binaries for benchmarking and profiling are gated behind the `bench-tools` feature so
  116. they are not installed for regular users:
  117. ```bash
  118. # Install with extras
  119. cargo install uncomment --features bench-tools
  120. # Or run locally
  121. cargo run --release --features bench-tools --bin benchmark -- --target /path/to/repo --iterations 3
  122. cargo run --release --features bench-tools --bin profile -- /path/to/repo
  123. ```
  124. </details>
  125. <details>
  126. <summary><b>Using uncomment as a library</b></summary>
  127. The command-line front end (binary, argument parsing, directory walk and its `rayon` parallelism,
  128. and the `lint`, `scan`, `keep`, `check` and `init` subcommands) sits behind the default-on `cli`
  129. feature. Library consumers that only need the per-file `Processor` API opt out:
  130. ```toml
  131. uncomment = { version = "3", default-features = false }
  132. ```
  133. `Processor::plan_removals` and `Processor::inspect` parse the file themselves. A host that already holds a
  134. tree-sitter tree for the same content passes it in through `plan_removals_with` / `inspect_with`: the closure gets
  135. the grammar uncomment resolved from the path and uncomment's own parser (already set to that grammar), and returns
  136. the tree, either one it holds or `parser.parse(content, Some(&old_tree))` for an incremental reparse. Name the types
  137. through `uncomment::tree_sitter` so both sides use the same tree-sitter version.
  138. ```rust
  139. let removals = processor.plan_removals_with(content, path, &config, |_language, _parser| Some(tree))?;
  140. ```
  141. </details>
  142. ## Supported Languages
  143. uncomment ships with 55 built-in language configurations and can process any of the **306 languages**
  144. in [tree-sitter-language-pack](https://github.com/kreuzberg-dev/tree-sitter-language-pack) — every
  145. grammar is compiled into the binary, so nothing is downloaded, built or cached at runtime, and any
  146. language can be added via configuration.
  147. <details>
  148. <summary><b>55 built-in languages</b></summary>
  149. Python (`.py`, `.pyw`, `.pyi`, `.pyx`, `.pxd`) · JavaScript (`.js`, `.jsx`, `.mjs`, `.cjs`) ·
  150. TypeScript (`.ts`, `.mts`, `.cts`, `.d.ts`, `.d.mts`, `.d.cts`) · TSX (`.tsx`) · Rust (`.rs`) ·
  151. Go (`.go`) · Go templates (`.tpl`, `.tmpl`, `.gotmpl`, `.gohtml`) · Java (`.java`) ·
  152. C (`.c`, `.h`) · C++ (`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`) · C# (`.cs`) ·
  153. Ruby (`.rb`, `.rake`, `.gemspec`) · PHP (`.php`, `.phtml`) · Elixir (`.ex`, `.exs`) · TOML (`.toml`) ·
  154. JSON (`.json`) · JSON with Comments (`.jsonc`) · YAML (`.yml`, `.yaml`) ·
  155. HCL/Terraform (`.hcl`, `.tf`, `.tfvars`) · Makefile (`Makefile`, `makefile`, `GNUmakefile`, `.mk`) ·
  156. Shell/Bash (`.sh`, `.bash`, `.zsh`, `.bashrc`, `.zshrc`, `.zshenv`) · Haskell (`.hs`, `.lhs`) · HTML (`.html`, `.htm`, `.xhtml`) ·
  157. CSS (`.css`) · XML (`.xml`, `.xsd`, `.xsl`, `.xslt`, `.svg`) · SQL (`.sql`) · Kotlin (`.kt`, `.kts`) ·
  158. Objective-C (`.m`) · Swift (`.swift`) · Lua (`.lua`) · Nix (`.nix`) · PowerShell (`.ps1`, `.psm1`, `.psd1`) ·
  159. Protobuf (`.proto`) · INI-like configs (`.ini`, `.cfg`, `.conf`) · Dockerfile (`Dockerfile`, `Dockerfile.*`) ·
  160. Starlark/Bazel (`BUILD`, `BUILD.bazel`, `WORKSPACE`, `WORKSPACE.bazel`, `WORKSPACE.bzlmod`, `MODULE.bazel`, `.bzl`, `.bazel`, `.star`) ·
  161. Java properties (`.properties`) ·
  162. Markdown (`.md`, `.markdown`, `.mdown`, `.mkd`) ·
  163. Scala (`.scala`, `.sc`) · Dart (`.dart`) · R (`.r`, `.R`) · Julia (`.jl`) · Zig (`.zig`) ·
  164. Clojure (`.clj`, `.cljs`, `.cljc`, `.edn`) · Elm (`.elm`) · Erlang (`.erl`, `.hrl`) · Vue (`.vue`) ·
  165. Svelte (`.svelte`) · SCSS (`.scss`) · LaTeX (`.tex`, `.sty`, `.cls`) · Fish (`.fish`) ·
  166. Perl (`.pl`, `.pm`) · Groovy (`.groovy`, `.gradle`) · OCaml (`.ml`, `.mli`) ·
  167. Fortran (`.f90`, `.f95`, `.f03`, `.f08`)
  168. </details>
  169. Objective-C uses the `objc` grammar. The `.m` extension is also used by MATLAB;
  170. Uncomment treats it as Objective-C by default. When processing a mixed project,
  171. pass only the Objective-C paths. Headers (`.h`) retain the C configuration;
  172. Objective-C++ (`.mm`) is not included in built-in support.
  173. Markdown has no comment of its own — `<!-- … -->` is raw HTML to CommonMark, and the grammar reports
  174. it as the same `html_block` that carries a `<div align="center">` badge row. A block is treated as a
  175. comment only when it is _nothing but_ one comment, so embedded HTML, a `<!DOCTYPE>`, an unterminated
  176. `<!--` (which runs to the end of the document) and `<!-- x --><div>kept</div>` are all left alone. A
  177. comment inside a paragraph or a table cell is inline content rather than an `html_block`, so it is
  178. out of reach; `.mdx` is not supported at all, because no grammar in the pack parses `{/* … */}`.
  179. In a Go template a comment is only a comment inside an action, so a bare `/* … */` is literal output
  180. text and `{{/* … */}}` is the only form. The grammar models the `{{` and `}}` as _siblings_ of the
  181. comment rather than as part of it, so the whole action is removed — deleting only the comment would
  182. leave `{{}}`, which Helm refuses to render. One spacing caveat: `{{ /* spaced */ }}` and `{{-/* x */-}}`
  183. produce no comment node at all and are left alone. A comment with code on _both_ sides keeps the
  184. spaces around it (`hello {{/* x */}} world` → `hello world`), because in a template that whitespace is
  185. rendered output. One that ends the line does not: `hello {{/* x */}}` leaves `hello`, since a trailing
  186. comment takes its separator with it like any other language's.
  187. ## Preservation Rules
  188. Certain comments are **never removed by default** — uncomment protects the ones your tooling and
  189. teammates rely on.
  190. **Always preserved:**
  191. - Comments containing `~keep`
  192. - `TODO` (unless `--remove-todo`), `FIXME` (unless `--remove-fixme`)
  193. - Documentation comments (unless `--remove-doc`)
  194. ### The `~keep` marker
  195. Put `~keep` on a `//`-style comment, not on a `///` or `/** */` doc comment. `~keep` is
  196. plain comment text, so a marker written inside a doc comment is republished by every tool
  197. that consumes doc comments — rustdoc, OpenAPI schemas, generated API clients, editor
  198. hover text.
  199. A marker on its own line protects the comment directly beneath it, which keeps it out of
  200. anything rendered:
  201. ```rust
  202. // ~keep
  203. /// Parent element ID for hierarchical relationships.
  204. pub parent_id: Option<String>,
  205. ```
  206. The marker also extends across a contiguous run of comments, so one `~keep` protects a
  207. whole multi-line block. A blank line or any code between comments ends the run.
  208. Inside a doc comment the marker is usually redundant, since doc comments are preserved
  209. anyway unless `--remove-doc` is set. uncomment strips such a marker from the doc text and
  210. reports it (`stripped 2 redundant ~keep markers`), leaving the comment itself untouched.
  211. Two cases are left alone: a marker is kept when `--remove-doc` is set, because there it is
  212. the only thing protecting that doc comment, and prose _about_ the marker is never rewritten
  213. — a line containing backticks, or a commented-out code sample, is read as documentation
  214. rather than as a directive.
  215. <details>
  216. <summary><b>Linting &amp; formatter directives (always preserved)</b></summary>
  217. | Language | Directives |
  218. | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  219. | Go | `//nolint`, `//golangci-lint`, `//staticcheck`, `//go:generate` |
  220. | Python | `# noqa`, `# type: ignore`, `# mypy:`, `# pyright:`, `# ruff:`, `# pylint:`, `# flake8:`, `# fmt: off/on`, `# black:`, `# isort:`, `# bandit:`, `# nosec`, `# pyre-ignore` |
  221. | JS/TS | `eslint-disable*`, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `/// <reference`, `prettier-ignore`, `biome-ignore`, `deno-lint-ignore`, `v8/c8/istanbul ignore` |
  222. | Rust | `#[allow]`, `#[deny]`, `#[warn]`, `#[forbid]`, `#[cfg]`, `clippy::`, `#[rustfmt::skip]` |
  223. | Java | `@SuppressWarnings`, `@SuppressFBWarnings`, `//noinspection`, `// checkstyle:` |
  224. | C/C++ | `// NOLINT`, `// NOLINTNEXTLINE`, `#pragma`, `// clang-format off/on` |
  225. | Shell | `# shellcheck disable`, `# hadolint ignore` |
  226. | YAML | `# yamllint disable/enable` |
  227. | HCL/Terraform | `# tfsec:ignore`, `# checkov:skip`, `# trivy:ignore`, `# tflint-ignore` |
  228. | Ruby | `# rubocop:disable/enable`, `# reek:`, `# standard:disable/enable` |
  229. | Markdown | `<!-- markdownlint-* -->`, `<!-- prettier-ignore -->`, `<!-- vale off/on -->`, `<!-- START/END doctoc -->` |
  230. </details>
  231. ## Subcommands
  232. ### `uncomment scan` — comment inventory
  233. Reports every comment in the tree with the verdict a real run would reach, as JSONL, JSON or text. Each comment gets a stable id that survives edits elsewhere in the file.
  234. ```bash
  235. # Inventory everything
  236. uncomment scan src/ --format jsonl -o scan.jsonl
  237. # Only the comments a run would remove
  238. uncomment scan src/ --only removable
  239. # Collapse identical comments into groups, sorted by frequency
  240. uncomment scan src/ --group-identical --only removable
  241. ```
  242. **Flags:**
  243. - `--format jsonl|json|text` — output format (default: jsonl)
  244. - `--only removable|preserved|all` — filter by verdict (default: all)
  245. - `--group-identical` — collapse equivalent comments into one record per distinct text, with a site count and list
  246. - `-o FILE` — write report to FILE instead of stdout
  247. **ID scheme:** IDs are derived from the file path, comment bytes, and occurrence index within the file — no line numbers, so an id survives edits above the comment. Collisions within a file are widened to the full 32-hex identifier; cross-file collisions widen the later claimant.
  248. ### `uncomment keep` — write `~keep` markers
  249. Applies `~keep` markers to comments selected by id, substring, or verdict. A line comment gets `~keep` appended; a block, doc or docstring comment gets a marker line directly above it, written with the language's plain line-comment token — or with its block pair (`/* ~keep */`, `<!-- ~keep -->`) when the language has no line form. A block, doc or docstring comment sharing its line with code cannot be marked at all: a marker line above it would attach to the line of code, so the comment is reported as unmarkable instead.
  250. ```bash
  251. # Mark everything a scan reported as removable
  252. uncomment keep src/ --from scan.jsonl
  253. # Mark specific comments by id
  254. uncomment keep src/ --id a3f9c1d2ab --id b7e4f8a1cd
  255. # Mark every comment whose text contains a substring
  256. uncomment keep src/ --match "legacy shim"
  257. # Mark everything that would be removed
  258. uncomment keep src/ --all-removable
  259. ```
  260. **Flags:**
  261. - `--from FILE` — read comment ids from a scan output file (JSONL or JSON; every field but `id` is ignored)
  262. - `--id ID` — mark the comment with this id (repeatable)
  263. - `--match SUBSTRING` — mark every comment whose text contains SUBSTRING
  264. - `--all-removable` — mark every comment a default run would remove
  265. - `--skip-missing` — warn about ids that no longer resolve instead of failing
  266. **Why a marker line above for docstrings:** A Python docstring is the `string` node that becomes `__doc__` at runtime, so editing its bytes changes what the program reports about itself. A marker line written above the docstring is a plain comment that uncomment reads but the runtime ignores.
  267. ### `uncomment --check` — fail when a comment would be removed
  268. Runs exactly as `--dry-run` does and writes nothing, but reports every comment the run would remove as a violation and exits non-zero, so the policy "every comment is either kept on purpose or gone" can gate a commit or a pull request. A comment passes when uncomment's own rules keep it: a `~keep` marker, a linting directive, a documentation comment, a configured preserve pattern, or TODO/FIXME while those are preserved.
  269. ```bash
  270. # Everything under src/
  271. uncomment --check src/
  272. # Only files a branch changed, or only the lines it changed
  273. uncomment --check --changed-only --base origin/main .
  274. uncomment --check --changed-lines --base origin/main .
  275. # Only what the next commit changes, line by line (for a pre-commit hook)
  276. uncomment --check --staged --changed-lines .
  277. ```
  278. Each violation is one line, sorted by path, then line:
  279. ```text
  280. src/main.rs:2:5: // strip me
  281. src/main.rs:3:16: // trailing note
  282. ✗ 2 removable comment(s) in 1 file(s) (1 file(s) checked)
  283. ```
  284. **Exit codes:** `0` nothing would be removed, `1` something would, `2` the check could not be completed — bad arguments, a rejected config, a file that could not be read, or a failed `git diff` — so a broken gate never reads as a pass.
  285. **Flags:**
  286. - `--check` — report instead of rewrite; rejects `--diff`, and makes `--dry-run` redundant
  287. - `--format text|json` — output format; JSON has the same `violations` / `notes` / `summary` shape as `uncomment lint`
  288. - `--changed-only` — check only files changed against `--base` (default: `origin/HEAD`, else `main`)
  289. - `--changed-lines` — report only comments on lines the diff added or rewrote (implies `--changed-only`); this is what makes the gate adoptable on a codebase that already has comments, because editing a legacy file does not make its old comments your problem
  290. - `--staged` — diff the index against `HEAD` instead of `--base`
  291. - `--base REF` — base ref for `--changed-only` and `--changed-lines`
  292. Excluded paths and files of unsupported types are skipped without a word, so a hook can pass every staged file. `--quiet` prints only the summary. See [Git Hooks](#git-hooks) for a lefthook and a GitHub Actions setup.
  293. ### `uncomment lint` — tag comment linting
  294. Checks tag comments (TODO, FIXME, HACK, XXX) against the convention configured under `[lint]`: that the tag is canonical, that it carries an issue key, and that the key is not the issue the current branch is working on. Removes nothing, exits 1 on violations, and works as a pre-commit hook.
  295. ```bash
  296. # Check comments, report violations, write nothing
  297. uncomment lint src/
  298. # Fix what can be fixed (canonical tags, injecting --todo-key)
  299. uncomment lint src/ --fix --todo-key PROJ-1234
  300. # Check only what the branch touched
  301. uncomment lint src/ --changed-only
  302. # Record current violations; future runs treat them as informational
  303. uncomment lint src/ --baseline .lint-baseline.json --write-baseline
  304. uncomment lint src/ --baseline .lint-baseline.json
  305. ```
  306. **Flags:**
  307. - `--fix` — rewrite what can be rewritten (canonical tag form, injecting `--todo-key` where missing)
  308. - `--todo-key KEY` — issue key to insert into tag comments that have none (with `--fix`)
  309. - `--changed-only` — lint only files changed against `--base`'s merge-base with `HEAD` (default:
  310. `origin/HEAD`, else `main`), comparing against the working tree — staged, unstaged and untracked
  311. (but not ignored) edits included, not just what has been committed
  312. - `--changed-lines` — report only violations on lines changed against `--base` (implies
  313. `--changed-only`, and the same working-tree comparison — an untracked file counts every line)
  314. - `--staged` — diff the index against `HEAD` instead of `--base`
  315. - `--base REF` — base ref for `--changed-only` and `--changed-lines`
  316. - `--baseline FILE` — treat violations recorded here as informational
  317. - `--write-baseline` — record every current violation in the baseline file and exit 0
  318. - `--format text|json` — output format (default: text)
  319. **Five rules:**
  320. 1. `tag-not-canonical` — a tag not written the way `canonical_tag` is written. That covers two defects and the message says which: a different spelling, reported as _`FIXME` should be written as `TODO`_, and the canonical spelling in the wrong casing, reported as _`todo` is `TODO` written with the wrong casing_. `--fix` rewrites both.
  321. 2. `todo-missing-key` — no issue key at all: not in a group, not spelled out nearby
  322. 3. `todo-key-not-upper-case` — a key was found but is not upper case, reported as _issue key `amvp-12` must be upper case_. `--fix` recases it in place.
  323. 4. `tag-form-not-canonical` — a key was found near the tag, but the tag is not written as `TAG(KEY):` around it: the key sits bare in the text (`TODO AMVP-12: x`, `TODO: AMVP-12 x`), in brackets (`TODO [AMVP-12] x`), or the tag itself is wrapped in its own `(...)`. `--fix` rewrites the whole form — the wrap, any bracket, and a key already in the leading text — into the single `TAG(KEY):` prefix, reusing the key that was already there rather than inserting a second one from `--todo-key`. A leftover from an earlier, careless rewrite, such as `(TODO(AMVP-1):):`, is reported and cleaned up the same way.
  324. 5. `todo-self-reference` — the key must not be the issue the current branch is for (that issue closes when the branch merges, leaving the TODO pointing at a dead ticket)
  325. **Casing:** tags are matched regardless of casing, so `fixme`, `Todo` and `xXx` are tags and each is a `tag-not-canonical` violation whose `--fix` normalises it to `canonical_tag`. A key is recognised the same way: `TODO(amvp-1)` and `todo(amvp-1)` both count as keyed, but a lower-case key is still wrong — it is `todo-key-not-upper-case`, not `todo-missing-key`, and `--fix` recases it without touching anything else. `key_pattern` governs this canonical `TAG(KEY):` group and can be replaced with a custom pattern; the bare-key forms `tag-form-not-canonical` also recognises (`TODO AMVP-12: x`, `TODO: AMVP-12 x`, `TODO [AMVP-12] x`) always use the default `AMVP-12`-shaped key, regardless of a custom `key_pattern`. Set `case_sensitive_tags = true` to go back to matching only the literal casing in `tags`, where `todo:` is not a tag at all.
  326. **Tag position:** a tag word counts only where a tag is written, not where a sentence mentions one. It is a tag when it opens its comment — everything before it on the line is delimiter or decoration (`//`, `#`, `/*`, `{/*`, a `*` continuation, a `-` bullet) — or when it opens a trailing segment of the comment, as in `# noqa: T201 # TODO: fix`. In that head position any casing counts, so `# todo: fix` and `* Hack: works around the driver` are tags. Further into a comment, only the exact spelling in `tags` can be a tag, and only when it reads as one: followed by `:`, `(` or a spaced dash (`# Socks handling - TODO: add a failure type`), or opening a clause after a label or punctuation (`# Note: TODO later`, `// biome-ignore lint/x: TODO remove`, `# fine for now, TODO revisit`). Everything else is prose and is neither reported nor touched by `--fix`: `# Line contains TODO`, `# Missing author in TODO`, `?tenant_id=XXX`, `{"uuid": XXX}`, and any tag word in backticks or quotes (`` `TODO` ``, `'hack'`). The cost is a tag written as a bare trailing word — `# remove later TODO` — which reads exactly like `# Line contains TODO` and is not reported.
  327. **Doc comments:** docstrings and doc comments (`///`, `//!`, `/** */`, Python docstrings) are not inspected by default. They describe an interface, and a tag word in one — "Returns the TODO list", `{"uuid": XXX} will be returned` — is far more often part of that description than tracked work. A plain comment that a language handler files as documentation only by position, such as Go's `// TODO` directly above a `func`, is still linted, and so is a `## TODO:` comment, which in Python, YAML and shell is emphasis rather than Doxygen. Set `include_doc_comments = true` to lint documentation too; the tag-position rule still applies inside it.
  328. A sigil is a separate question from casing and always has been: `\b` sits between `@` and the tag, so `# @TODO: x` is a tag today and `# @todo: x` becomes one now. `--fix` rewrites the tag token alone and leaves the sigil, giving `# @TODO: x`. If `@todo` is prose you do not want linted, `case_sensitive_tags = true` is not the lever — drop `TODO` from `tags` or baseline the occurrences.
  329. **Opt-in:** Linting is off by default. Enable it per file tree with `[lint]` in `.uncomment.toml`:
  330. ```toml
  331. [lint]
  332. enabled = true
  333. key_pattern = '^\s*(?:TODO|FIXME|HACK|XXX)\((?<key>[A-Z][A-Z0-9]+-\d+)\)\s*:'
  334. # Optional, default false. With `true`, only the literal casing in `tags` is a tag,
  335. # so `todo:` and `Fixme:` are not flagged at all.
  336. case_sensitive_tags = true
  337. # Optional, default false. With `true`, docstrings and doc comments are linted too.
  338. include_doc_comments = true
  339. ```
  340. Note what `enabled = true` alone commits you to: with the default `tags` and `canonical_tag`, every existing `FIXME`, `HACK` and `XXX` in the tree becomes two violations — one for the tag, one for the missing key — and `--fix` rewrites the tag to `TODO`. Every miscased tag counts too, `todo:` and `Fixme:` included. On an existing codebase, reach for `--changed-only` or `--write-baseline` first.
  341. ### Large-repo workflow
  342. On a large codebase, deciding which comments to keep is a batch process: scan once, filter the report, then mark what the filter selected.
  343. Two scans, because the two reports answer different questions. A grouped report is for _deciding_ — one judgement per distinct wording instead of hundreds. `keep` cannot act on it: a grouped record's `id` is a group id derived from the normalized text, with no path and no occurrence index, so it resolves to no single comment and the run fails with every id unresolved (`--skip-missing` downgrades that to a warning). Feed `keep --from` the ungrouped report.
  344. ```bash
  345. # 1. Read the decision surface: one record per distinct comment, by frequency
  346. uncomment scan . --group-identical --only removable
  347. # 2. Inventory every site, which is what keep consumes
  348. uncomment scan . --only removable --format jsonl -o scan.jsonl
  349. # 3. Filter scan.jsonl — delete the lines for comments that should be removed,
  350. # keep the lines for comments that should be kept. Any JSON-aware tool works;
  351. # the only field `keep` reads is `id`.
  352. # 4. Apply markers to the comments the filtered report selected
  353. uncomment keep . --from scan.jsonl
  354. # 5. Run the real removal
  355. uncomment .
  356. # 6. Verify: a second scan reports 0 removable comments
  357. uncomment scan . --only removable
  358. ```
  359. ## Configuration
  360. uncomment reads hierarchical TOML configuration. Precedence, lowest to highest:
  361. 1. Built-in defaults
  362. 2. Global config at `uncomment/config.toml` under the platform config directory (`dirs::config_dir()`) — `$XDG_CONFIG_HOME` or `~/.config` on Linux, `~/Library/Application Support` on macOS, `%APPDATA%` on Windows
  363. 3. Local `.uncomment.toml` files (from repository root toward the file; inner beats outer)
  364. 4. Pattern matches (`[patterns."glob"]`) within those configs, last match wins
  365. 5. Language-specific settings (`[languages.name]`)
  366. 6. Command-line flags
  367. A directory's config file is named `.uncomment.toml`. Two earlier names are still read — `.uncommentrc.toml`, then `uncomment.toml` — so an existing config keeps working, but each is deprecated and a run that loads one says so once on stderr. A directory holding more than one of the three uses the highest-precedence name outright; the others are ignored rather than merged.
  368. `[lint]` layers differently from the rest: a nested table amends the one above it key by key, each severity in `[lint.rules]` included, so a subdirectory can switch one rule off and still inherit `enabled`, `tags` and `key_pattern` from above.
  369. `[languages.*]` does not follow step 3 either. The language registry is built once, before any file is read, from the configs in the invocation directory and its ancestors plus every config found under the paths being processed — deepest declaration wins. (`--config FILE` replaces that discovery entirely.) A config reached only later, during per-file resolution, comes too late: its `[languages]` section is ignored, with a warning naming the directory.
  370. CLI flags are one-directional: `--remove-doc` sets `remove_docs = true` but an unset flag never clobbers a config-file value back to false.
  371. `exclude` does not layer like the rest either — it is a union. A file matching any `exclude` glob in force is not collected by any subcommand, and a nested config can add an exclusion but never withdraw one. Repeating `--exclude GLOB` adds to the configured list rather than replacing it, and naming an excluded path on the command line does not override it: the setting says which paths the project never wants read, not which ones this invocation skips. Globs use the same dialect as `[patterns."<glob>"]` keys — `*` does not cross a `/`, `**` does — and are anchored the same way, relative to the directory holding the config file that declared them (relative to the invocation directory for `--exclude`, and for a `--config FILE` config). `exclude = ["vendor/**"]` also keeps the directory walk out of `vendor` rather than descending it and discarding the results. Like `[languages.*]`, `exclude` has to be known before collection, so it is read from the same set of configs: the invocation directory and its ancestors plus every config found under the paths being processed.
  372. Every table rejects unknown keys, and a project config that does not parse stops the run instead of degrading to built-in defaults — so a typo such as `enable` for `enabled` in `[lint]` fails every subcommand, not just `lint`.
  373. A JSON Schema for the file is published at [`schema/uncomment.schema.json`](https://github.com/polylint/uncomment/blob/main/schema/uncomment.schema.json). `uncomment init` writes a `#:schema` directive at the top of every config it generates, which is what [Taplo](https://taplo.tamasfe.dev/) and the editors built on it read to complete and validate the file as you type. Add the same line to a hand-written config:
  374. ```toml
  375. #:schema https://raw.githubusercontent.com/polylint/uncomment/main/schema/uncomment.schema.json
  376. [global]
  377. remove_todos = true
  378. ```
  379. The directive is a comment rather than data, so uncomment itself never sees it. A `$schema` key, by contrast, is rejected as an unknown key, like any other.
  380. ```toml
  381. [global]
  382. remove_todos = false
  383. remove_fixme = false
  384. remove_docs = false
  385. preserve_patterns = ["IMPORTANT", "NOTE", "WARNING"]
  386. exclude = ["playground/**", "thirdparty/**"]
  387. use_default_ignores = true
  388. respect_gitignore = true
  389. [languages.python]
  390. name = "Python"
  391. extensions = ["py", "pyw", "pyi"]
  392. comment_nodes = ["comment"]
  393. doc_comment_nodes = ["string"]
  394. preserve_patterns = ["noqa", "type:", "pragma:", "pylint:"]
  395. [patterns."tests/**/*.py"]
  396. # Keep all comments in test files
  397. remove_todos = false
  398. remove_fixme = false
  399. remove_docs = false
  400. ```
  401. <details>
  402. <summary><b>Adding a language via configuration</b></summary>
  403. Any of the 306 tree-sitter-language-pack languages works. The grammar is already in the binary, so
  404. there is no grammar to fetch or build. The grammar is looked up by the `name` field lowercased — not
  405. by the section key — so `name` has to be the pack's own name for the language, or the name of a
  406. built-in you are overriding. A `name` that matches neither is reported on stderr rather than
  407. silently ignored:
  408. ```toml
  409. [languages.hare]
  410. name = "Hare"
  411. extensions = ["ha"]
  412. comment_nodes = ["comment"]
  413. preserve_patterns = ["TODO", "FIXME"]
  414. ```
  415. A language can claim whole filenames instead of, or as well as, extensions — the only way to reach a
  416. file that has no extension at all:
  417. ```toml
  418. [languages.starlark]
  419. name = "Starlark"
  420. extensions = ["bzl", "bazel", "star"]
  421. filenames = ["BUILD", "BUILD.bazel", "WORKSPACE", "MODULE.bazel", "Tiltfile"]
  422. comment_nodes = ["comment"]
  423. ```
  424. `filenames` is matched case-sensitively and consulted **before** any extension rule, so a claim on
  425. `BUILD.bazel` decides that file regardless of what else claims `.bazel`. Case matters because
  426. `BUILD` and `build` are different files to Bazel, and folding the key would hand a `build` shell
  427. script to a Starlark parser. An entry ending in `.*` claims every name starting with the part before
  428. the `*` — `filenames = ["Dockerfile.*"]` reaches `Dockerfile.prod` — and where two such prefixes
  429. overlap the longer one wins, never whichever was registered first. A `[languages.*]` section needs at
  430. least one `extensions` or `filenames` entry; with neither it claims no file at all and is rejected
  431. rather than silently doing nothing.
  432. </details>
  433. ## How It Works
  434. Unlike regex-based tools, uncomment builds a proper Abstract Syntax Tree of your code with
  435. tree-sitter, so it distinguishes:
  436. - Real comments vs comment-like content in strings
  437. - Documentation comments vs regular comments
  438. - Inline comments vs standalone comments
  439. - Language-specific metadata that must be preserved
  440. The pipeline is modular: a **language registry** (51 built-ins, plus any other compiled-in grammar
  441. named in config) feeds an **AST visitor** that finds comment nodes, a **preservation engine** decides
  442. what to keep, and an **output generator** emits clean code.
  443. ## Git Hooks
  444. <details>
  445. <summary><b>pre-commit</b></summary>
  446. ```yaml
  447. repos:
  448. - repo: https://github.com/polylint/uncomment
  449. rev: v3.5.0
  450. hooks:
  451. - id: uncomment
  452. ```
  453. Use `id: uncomment-check` instead to fail the commit on any comment a staged change adds that uncomment would remove, rewriting nothing.
  454. </details>
  455. <details>
  456. <summary><b>Lefthook</b></summary>
  457. ```yaml
  458. pre-commit:
  459. commands:
  460. uncomment:
  461. run: uncomment {staged_files}
  462. stage_fixed: true
  463. ```
  464. To block the commit instead of rewriting the files, check them. `--changed-lines --staged` asks only about the lines the commit changes, so touching a legacy file does not fail on the comments already in it:
  465. ```yaml
  466. pre-commit:
  467. commands:
  468. uncomment-check:
  469. run: uncomment --check --staged --changed-lines {staged_files}
  470. ```
  471. Drop `--staged --changed-lines` to hold every staged file to the policy in full.
  472. </details>
  473. <details>
  474. <summary><b>GitHub Actions</b></summary>
  475. Use the [GitHub Action](#github-action) below instead of installing the CLI by hand — it downloads
  476. and caches a matching release binary and turns violations into inline PR annotations.
  477. </details>
  478. ## GitHub Action
  479. `polylint/uncomment` ships a composite action that installs a release binary — cached, checksum-verified,
  480. no compilation — and runs it, with violations reported as inline PR annotations via a
  481. [problem matcher](https://docs.github.com/en/actions/using-workflows/adding-scripts#adding-a-problem-matcher).
  482. The binary is self-contained (every tree-sitter grammar is compiled in statically), so nothing about
  483. it touches the network beyond the one release download.
  484. ```yaml
  485. - uses: polylint/uncomment@v3
  486. with:
  487. args: "lint ." # or "--check .", or plain removal args
  488. ```
  489. `@v3` is a floating tag that tracks the newest 3.x release; pin an exact release (`@v3.10.1`)
  490. where reproducibility matters.
  491. **Lint an entire repository, failing the build on a violation:**
  492. ```yaml
  493. jobs:
  494. lint:
  495. runs-on: ubuntu-latest
  496. steps:
  497. - uses: actions/checkout@v7
  498. - uses: polylint/uncomment@v3
  499. with:
  500. args: "lint ."
  501. ```
  502. **Lint (or check) only the lines a pull request changed:** `--changed-lines` diffs against the
  503. merge base, so the checkout needs history back to it — `fetch-depth: 0` is the simple way to
  504. guarantee that. The action passes the pull request's base SHA to `--base` for you.
  505. ```yaml
  506. on: pull_request
  507. jobs:
  508. lint-changed:
  509. runs-on: ubuntu-latest
  510. steps:
  511. - uses: actions/checkout@v7
  512. with:
  513. fetch-depth: 0
  514. - uses: polylint/uncomment@v3
  515. with:
  516. args: "lint ."
  517. changed-lines: "true"
  518. ```
  519. Set `changed-only: "true"` instead to scope by whole file rather than by line, or add
  520. `args: "--check ."` to gate removable comments instead of (or alongside, as a second step) tag
  521. lint.
  522. **Install only, and run uncomment yourself:**
  523. ```yaml
  524. - uses: polylint/uncomment@v3
  525. id: uncomment
  526. with:
  527. install-only: "true"
  528. - run: uncomment --version # ${{ steps.uncomment.outputs.version }} is also available
  529. ```
  530. **Inputs** (all optional):
  531. | Input | Default | Description |
  532. | ------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
  533. | `version` | resolved from the tag the action is pinned to (`@v3` resolves the newest 3.x release), else `latest` | uncomment version to install, with or without a leading `v` |
  534. | `args` | `lint .` | Arguments passed to `uncomment`, as one space-separated string |
  535. | `working-directory` | `.` | Directory to run uncomment in |
  536. | `install-only` | `false` | Install and put uncomment on `PATH`, but don't run it |
  537. | `changed-only` | `false` | Append `--changed-only` |
  538. | `changed-lines` | `false` | Append `--changed-lines` (implies `changed-only`) |
  539. | `staged` | `false` | Append `--staged` |
  540. | `base` | PR base SHA on `pull_request`, else uncomment's own default | Base ref/SHA for `--changed-only`/`--changed-lines` |
  541. | `token` | `${{ github.token }}` | Token used to resolve `latest` and download the release asset |
  542. **Outputs:** `version` (the version installed) and `path` (absolute path to the binary).
  543. The action is a plain composite action (no bundled JavaScript) that resolves the right release
  544. asset for the runner's OS/arch, verifies its published checksum, caches it with `actions/cache`
  545. keyed by version, OS and arch, and adds it to `PATH`.
  546. ## Performance
  547. AST parsing costs a little more than regex, but the tool is fast and scales well with threads.
  548. - Small files (<1000 lines): ~20-30ms
  549. - Large files (>10000 lines): ~100-200ms
  550. | Threads | Files/second | Speedup |
  551. | ------- | ------------ | ------- |
  552. | 1 | 1,500 | 1.0× |
  553. | 4 | 3,900 | 2.6× |
  554. | 8 | 5,100 | 3.4× |
  555. _Benchmarked on a large enterprise codebase of ~5,000 mixed-language files._ Measure your own with
  556. the built-in `benchmark` and `profile` tools (see [optional benchmarking tools](#usage)).
  557. ## Coding-agent plugins
  558. The repository includes skills-only plugins for Claude Code, Codex, Cursor,
  559. Gemini CLI, Kimi CLI, OpenCode, Factory, Hermes, Pi, Agent Plugins and Copilot.
  560. Install the Uncomment CLI separately; these plugins provide no MCP server.
  561. For Claude Code, add this repository as a marketplace and install its plugin:
  562. ```bash
  563. claude plugin marketplace add polylint/uncomment
  564. claude plugin install uncomment@uncomment
  565. ```
  566. For Codex:
  567. ```bash
  568. codex plugin marketplace add polylint/uncomment
  569. codex plugin add uncomment@uncomment
  570. ```
  571. Portable Agent Skills are available in [`skills/uncomment`](skills/uncomment).
  572. Native runtime packages and installation details are in
  573. [`plugin/README.md`](plugin/README.md). Releases attach deterministic plugin
  574. archives, marketplace indexes and checksums. See [contributor instructions](CONTRIBUTING.md#ai-governance-and-public-plugins)
  575. for generation and verification.
  576. ## Development
  577. ```bash
  578. cargo build # Debug build
  579. cargo test # Run the test suite
  580. cargo test -- --ignored # Include network-dependent tests
  581. cargo clippy # Lint
  582. cargo fmt --all # Format
  583. ```
  584. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for local development, automation hooks, and release
  585. procedures.
  586. ## Contributing
  587. Issues and pull requests are welcome. If uncomment is useful to you, consider
  588. [sponsoring development](https://github.com/sponsors/Goldziher) — it helps keep the project
  589. maintained for the community.
  590. ## polylint organization
  591. uncomment is part of [polylint](https://github.com/polylint), high-performance Rust linters and formatters built for agentic workflows. Sibling tools: [polylint](https://github.com/polylint/polylint) (one linter and formatter for every language; it can run uncomment as an engine), [skif](https://github.com/polylint/skif) (JS/TS dependency linter), [adrlint](https://github.com/polylint/adrlint) (MADR decision records). Install any of them from the Homebrew tap (`brew tap polylint/tap`) or the Scoop bucket.
  592. ## License
  593. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.