cloc 工具使用教學

cloc 是一個用來統計程式碼行數的工具

cloc 可以做什麼？

cloc 主要會統計這幾種資訊：

• 使用了哪些程式語言
• 每種語言有幾個檔案
• 空白行數
• 註解行數
• 程式碼行數

例如執行：

cloc .

可能會看到類似下面的結果：

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
TypeScript                      12            320            110           1850
Markdown                         8            120              0            900
CSS                              4             80             20            500
-------------------------------------------------------------------------------
SUM:                            24            520            130           3250
-------------------------------------------------------------------------------

這樣就可以很快知道目前專案主要由哪些語言組成，以及大概有多少程式碼。

安裝 cloc

Windows

winget install AlDanial.Cloc

choco install cloc

macOS

brew install cloc

Linux

Ubuntu / Debian：

sudo apt install cloc

基本用法

最常用的方式是在專案根目錄執行：

cloc .

如果只想統計某個資料夾，例如 src：

cloc src

如果只想統計單一檔案：

cloc src/main.ts

也可以一次統計多個路徑：

cloc src components pages

排除不想統計的資料夾

實際專案裡通常會有一些不想計算的資料夾，例如：

• node_modules
• .git
• dist
• build

可以用 --exclude-dir 排除：

cloc . --exclude-dir=node_modules,.git,dist,build

我通常會這樣處理前端

cloc . --exclude-dir=node_modules,.git,dist,build,.svelte-kit

這樣統計結果會比較接近自己實際寫的程式碼，不會把套件或編譯輸出也算進去。

只統計特定語言

如果只想看 JavaScript 和 TypeScript：

cloc . --include-lang=JavaScript,TypeScript

如果想排除 Markdown：

cloc . --exclude-lang=Markdown

依照檔案顯示統計

預設的 cloc 是依照語言分類，如果想看每個檔案各自的行數，可以加上 --by-file：

cloc src --by-file

如果想同時依語言和檔案顯示，可以用：

cloc src --by-file-by-lang

排除特定檔案

有時候不只資料夾要排除，某些檔案也不想算，例如 lock file 或自動產生的檔案。

可以使用 --not-match-f，它會用 regular expression 比對檔案名稱：

cloc . --not-match-f="(package-lock.json|pnpm-lock.yaml|yarn.lock)"

如果要排除測試快照檔：

cloc . --not-match-f="\\.snap$"

如果要排除產生出來的 .min.js：

cloc . --not-match-f="\\.min\\.js$"

輸出成 JSON 或 CSV

輸出 JSON：

cloc . --json --out=cloc.json

輸出 CSV：

cloc . --csv --out=cloc.csv

輸出 Markdown：

cloc . --md --out=cloc.md

比較兩個版本的差異

cloc 也可以比較兩個資料夾或兩個版本之間的差異。

例如有兩個資料夾：

cloc --diff old-version new-version

它會顯示新舊版本之間增加、刪除或修改的程式碼行數。

如果你想比較兩個 Git commit，也可以先把不同版本匯出成資料夾後再比對：

git archive old-commit -o old.zip
git archive new-commit -o new.zip

解壓縮後再執行：

cloc --diff old new

這種方式適合用在版本重構後，檢查整體程式碼量是變多還是變少。

統計 Git 專案

如果專案本身有使用 Git，cloc 有幾個 Git 相關參數可以用。

使用 —vcs git 統計目前 repository

一般的：

cloc .

會掃描目前資料夾底下的檔案。

如果改用：

cloc --vcs git

cloc 會透過 Git 取得檔案清單，效果比較接近：

git ls-files

這樣可以避免把一些沒有被 Git 管理的檔案一起算進去，例如暫存檔、輸出檔或被 .gitignore 排除的檔案。

如果只是想統計目前 repo 裡實際有被 Git 管理的程式碼，我會比較推薦這個：

cloc --vcs git

使用 —git 統計 commit、branch 或 tag

--git 可以讓 cloc 把輸入當成 Git 的 commit、branch 或 tag。

統計目前 HEAD：

cloc --git HEAD

統計某個 branch：

cloc --git main

統計某個 commit：

cloc --git a1b2c3d

統計某個 tag：

cloc --git v1.0.0

cloc . 看的是目前工作目錄，cloc --git HEAD 看的是 Git 裡 HEAD 這個版本。

所以如果你有還沒 commit 的修改，這兩個指令算出來的結果可能會不一樣。

直接比較兩個 Git 版本

--git 最常搭配 --diff 使用，用來比較兩個 commit、branch 或 tag 的差異。

比較目前版本和上一個 commit：

cloc --git --diff HEAD~1 HEAD

比較兩個 branch：

cloc --git --diff main feature/login

比較兩個 tag：

cloc --git --diff v1.0.0 v1.1.0

—git-diff-rel 和 —git-diff-all

cloc 另外有兩個比較 Git 版本的參數。

只比較兩個版本中有變動的檔案：

cloc --git-diff-rel HEAD~1 HEAD

比較兩個版本中整個 repository 的所有檔案：

cloc --git-diff-all HEAD~1 HEAD

查看支援的語言和副檔名

查看 cloc 支援哪些語言：

cloc --show-lang

查看特定語言資訊：

cloc --show-lang=TypeScript

查看某個副檔名會被判斷成什麼：

cloc --show-ext=ts

如果遇到比較冷門的副檔名，這幾個指令很好用。

依副檔名過濾

只統計 ts 和 tsx：

cloc . --include-ext=ts,tsx

排除 json 和 md：

cloc . --exclude-ext=json,md

使用檔案清單統計

如果已經有一份檔案清單，可以用 --list-file 讓 cloc 只統計清單裡的檔案。

例如 files.txt：

src/main.ts
src/App.tsx
README.md

然後執行：

cloc --list-file=files.txt

如果有一份不想統計的清單，可以用：

cloc . --exclude-list-file=ignore-files.txt

這適合用在 CI 或固定報告流程中。

查看哪些檔案被統計或忽略

如果統計結果看起來怪怪的，可以把 cloc 實際看到的檔案輸出出來。

列出找到的所有檔案：

cloc . --found=found.txt

列出被成功統計的檔案：

cloc . --counted=counted.txt

列出被忽略的檔案和原因：

cloc . --ignored=ignored.txt

其他實用參數

忽略空白差異進行 diff：

cloc --diff old-version new-version --ignore-whitespace

忽略大小寫差異進行 diff：

cloc --diff old-version new-version --ignore-case

限制最大檔案大小，例如跳過超過 5 MB 的檔案：

cloc . --max-file-size=5

調整 diff timeout，例如每個檔案最多比較 30 秒：

cloc --diff old-version new-version --diff-timeout=30

顯示比較詳細的執行資訊：

cloc --git --diff HEAD~1 HEAD -v

常用指令整理

統計目前專案：

cloc .

統計 src 資料夾：

cloc src

排除常見產物資料夾：

cloc . --exclude-dir=node_modules,.git,dist,build

統計 Git 管理中的檔案：

cloc --vcs git

統計目前 Git commit：

cloc --git HEAD

比較兩個 Git commit：

cloc --git --diff HEAD~1 HEAD

只比較兩個 Git 版本中有變動的檔案：

cloc --git-diff-rel HEAD~1 HEAD

只統計 TypeScript：

cloc . --include-lang=TypeScript

只統計 ts 和 tsx：

cloc . --include-ext=ts,tsx

依檔案顯示：

cloc src --by-file

查看支援語言：

cloc --show-lang

列出被忽略的檔案：

cloc . --ignored=ignored.txt

輸出成 JSON：

cloc . --json --out=cloc.json

比較兩個資料夾：

cloc --diff old-version new-version

完整的前端指令：

cloc . --exclude-dir=node_modules,.git,dist,build --not-match-f="(package-lock.json|pnpm-lock.yaml|yarn.lock)"