返回首頁

先看懂歷史,再建立下一個 tag。

Tagsmith 的流程從本機檢視開始。規格清楚時再預覽;規格模糊時,由 maintainer 明確定義意圖。建立與發布各自是有意識的步驟。

開始前

在 Git repository 內執行,並使用 Node.js 22+。所有指令都可直接複製;示範不使用任何遠端狀態。

01

先讀本機已知的 tag 歷史。

從 list 開始。Tagsmith 會依語意排序,並標示不合規、無法解析或重複的 tag。發版前可再用 audit 檢查完整歷史、已設定的本機護欄,以及歷史 tag 對應的產物版本;它不會自動修正任何歷史。

安全試用

npx @carllee1983/tagsmith list

這個步驟只讀取與評估本機歷史,不會改動 repository。

02

歷史是否已經說清楚規格?

規格清楚

保留推論,前往預覽。

一致的 SemVer 式歷史可走零設定路徑。下一步只是計算,不會建立 tag。

前往預覽
規格模糊

由 maintainer 定義意圖。

混合、模糊或非 SemVer 的歷史不會被猜測或自動修正。先寫下團隊規格,再重新檢視。

設定規格

npx @carllee1983/tagsmith init

提交產生的 .tagsmith.json,然後再次執行 list。

查看設定格式
03

確認意圖後,再預覽下一個版本。

next 依目前規格與本機歷史計算下一個 tag。它不會建立 tag,也不會發出任何遠端請求。

只預覽

npx @carllee1983/tagsmith next

需要 minor 或 major 時,可在這一步與建立時一併加上相同的 --level。若採用 commit policy,使用 --from-commits 可讓建議列出命中的規則。

04

預覽符合意圖後,先確認 push: false,才在本機建立。

建立前,Tagsmith 會依明確規格與本機已知歷史再次驗證。若不符合,會停止而不是自行選擇解法。若啟用產物版本護欄,--enforce-policy 也會在目標 commit 的 package.json 缺失或版本不一致時停止建立。

新設定的預設是 push: false。create 會遵從選定 tag line 的設定:值為 false 時只建立本機 tag;值為 true 時,這個指令會發布它。

確認 push 後再建立

npx @carllee1983/tagsmith create

請先確認選定 tag line 維持 push: false,再複製這個指令。

05

遠端發布是另一個明確決定。

是否、何時與如何推送,都屬於團隊既有的 Git hosting 與 release workflow。Tagsmith 提供本機驗證與可預期的建立行為;它不取代 remote 的衝突處理、權限控管或 repository-wide enforcement。

把判斷結果交給周邊流程。

--json 讓 CI 和 script 讀取 Tagsmith 對規格的評估結果;後續該做什麼,仍由你的 automation 決定。

npx @carllee1983/tagsmith next --json

從一條 tag line 開始。

SemVer 是零設定評估的預設路徑。CalVer、build number、多條 tag line、產物版本檢查、commit policy 與選用的本機護欄,都在有明確需求後再加入。

閱讀完整設定參考