SidneyZhang
c2f914307d
`quicommit ginit`（别名 `gi`）离线完成仓库起步：用 git2 建库并确立初始分支、 写最简 README.md、按根目录标志文件装配 .gitignore、按 --add 添加远程， `--profile` 可选套用已有 Git 配置。在已有仓库上重复执行只补齐缺失项：绝不覆盖 既有的 README.md/.gitignore、绝不改动已有 remote 的地址、不提供 --force、 不创建首个提交。边界取舍见 ADR 0006，命令命名见 ADR 0005。 实现落在新的 src/git/init.rs（9 个 git 层函数）与 src/commands/ginit.rs， 命令层不直接引用 git2，GitRepo 公开接口未改动，其余命令行为不变。 测试：src/git/init.rs 11 条单元测试、tests/ginit_tests.rs 18 条集成测试； 新增 35 个 ginit_* 消息覆盖 7 种语言。 另将 CONTEXT.md 与 docs/adr/ 纳入版本跟踪（.gitignore 放开 adr/ 与 CONTEXT.md 两条忽略规则）；RAODMAP.md 除 ginit 条目外还包含此前未提交的 规划条目更新。
66 lines
4.5 KiB
Markdown
66 lines
4.5 KiB
Markdown
# QuiCommit
|
||
|
||
AI 辅助的 Git 提交、Tag 和 Changelog 管理 CLI 工具。
|
||
|
||
## Language
|
||
|
||
**Remote**:
|
||
Git 远程仓库配置名。QuiCommit 推送 commit/tag 的默认目标是 `origin`。仓库一个远程都没有时，创建后不询问推送、直接跳过并说明。`--select-remote` 开启后，在多远程仓库中弹出多选列表，可一次推送其中部分或全部远程。
|
||
_Avoid_: 远端、远程仓库地址
|
||
|
||
**Tag message**:
|
||
Tag 对象的注释消息。annotated tag 时写入，lightweight tag 时为空。QuiCommit 默认创建 annotated tag。
|
||
_Avoid_: Tag 消息、标签说明
|
||
|
||
**Changelog entry**:
|
||
一条版本发布记录，包含该版本所有变更按类别（Added / Changed / Fixed 等）分组。多个 entry 组成一个完整的 CHANGELOG.md 文件。
|
||
_Avoid_: 更新日志条目、发布说明
|
||
|
||
**Keep a Changelog**:
|
||
CHANGELOG.md 的标准格式。以 `# Changelog` 开头，版本章节按 `## [x.y.z] - YYYY-MM-DD` 排列，变更按 Added / Changed / Deprecated / Removed / Fixed / Security 分组。
|
||
_Avoid_: 标准 changelog
|
||
|
||
**Version bump**:
|
||
根据提交类型推断下一个版本号的操作。feat → Minor, fix → Patch, breaking change → Major。
|
||
_Avoid_: 版本升级、版本号递增
|
||
|
||
**--auto mode**:
|
||
从项目根目录的主流包管理器配置文件（Cargo.toml、package.json、pyproject.toml、pom.xml 等）中读取当前版本作为新 tag。若同时存在多个配置文件，列出所有发现的版本让用户选择。读取失败则回退到 commit 分析自动建议版本并提示用户确认。读取到的版本直接用作 tag name，不做自动 bump——假定用户已在配置文件中手动更新了版本号。
|
||
|
||
支持的项目配置文件：Cargo.toml、package.json、pyproject.toml、pom.xml、.gemspec、pubspec.yaml、build.sbt、project.clj、mix.exs、package.yaml（Haskell Stack）、Project.toml（Julia）、composer.json、.csproj、CMakeLists.txt、meson.build。
|
||
|
||
`go.mod` 存在时跳过配置文件读取，直接走 commit 分析——Go 项目约定以 git tag 为版本依据，go.mod 不含 version 字段。
|
||
_Avoid_: 自动模式
|
||
|
||
**Annotated tag**:
|
||
Git 中带有独立对象（包含 message、作者、时间戳）的 tag。`git tag -a` 或 `git2::Repository::tag()` 传入 message 时创建。
|
||
_Avoid_: 注释标签、带消息的 tag
|
||
|
||
**Lightweight tag**:
|
||
Git 中仅为一个 commit 指针的 tag，无独立对象。`git tag` 不带 `-a` 创建。
|
||
_Avoid_: 轻量标签
|
||
|
||
**Thinking mode**:
|
||
生成 commit/tag/changelog 内容时启用模型思考（reasoning）的生成模式，终端显示 "thinking..." 状态直到正文开始输出；仅部分 LLM provider 支持，不支持时自动降级为普通生成。通过 `--think/-t` 或配置 `thinking_enabled` 启用。
|
||
_Avoid_: 推理模式、reasoning mode
|
||
|
||
**Project config file**:
|
||
项目根目录下由包管理器/构建系统使用的配置文件，其中的 `version` 字段反映项目当前版本。结构化的（JSON/TOML/YAML/XML）用对应解析器读取，代码即配置的（.gemspec/build.sbt/project.clj/mix.exs）用正则提取。仅检查项目根目录，不递归子目录。解析失败静默跳过。
|
||
_Avoid_: 项目配置文件、版本文件
|
||
|
||
**Ecosystem marker**:
|
||
只凭「存在与否」就能判定目录属于哪个语言生态的根目录标志文件，不要求其内容可解析。与 Project config file 的区别是职责不同：后者要读出 version，前者只要认出生态，因此 versionless 的 package.json、workspace 继承版本的 Cargo.toml、go.mod 都是有效的 Ecosystem marker。仅检查项目根目录，不递归子目录。
|
||
_Avoid_: 语言检测文件、生态标志（口头可用，书面统一用 Ecosystem marker）
|
||
|
||
**Repo init**:
|
||
把一个普通目录变成 Git 仓库并备好起步内容的操作——建库、定 Initial branch、补 README 与忽略规则、按需挂 Remote。由 `ginit` 承担。
|
||
_Avoid_: 项目初始化、建仓、git 初始化
|
||
|
||
**Config init**:
|
||
创建或重置 QuiCommit 自身配置文件（LLM provider 与首个 Git Profile）的操作，由 `init` 承担。不创建 Git 仓库，也不写入工作目录任何文件。
|
||
_Avoid_: 初始化（单独使用时有歧义，必须区分 Config init 与 Repo init）
|
||
|
||
**Initial branch**:
|
||
新仓库里 HEAD 指向、尚无任何 commit 的第一个分支。QuiCommit 认定它是一次 Repo init 的产物，只能在尚不存在任何分支时确立，不得用于重命名已有仓库的当前分支。
|
||
_Avoid_: 默认分支、主分支、master 分支
|