git worktree通过为不同分支创建物理隔离的工作目录，避免多版本并行开发时的构建污染与兼容性误伤。例如，用git worktree add ../v2-release release/v2.1和git worktree add ../v3-dev feature/v3-api分别建立v2与v3的独立环境，配合独立配置、条件编译及ci强制兼容性检查，确保各版本代码互不干扰且abi/api契约得以严格遵守。
Git 本身不负责“保障向后兼容”，它只提供分支隔离能力；真正的向后兼容性由开发流程、接口契约和自动化验证决定。分支隔离只是为兼容性控制提供了必要的操作边界。
为什么main分支必须冻结公共 API 变更
向后兼容的核心是：下游依赖能安全升级而不需改代码。这意味着main分支（或release/*）上的任何提交，都不能破坏已有公开接口（如 Java 的 public 方法签名、HTTP 接口路径/请求体结构、Protobuf 字段编号）。
- 所有破坏性变更（如删除字段、改方法名、删 endpoint）必须在
feature/*或next-major分支中完成，并配套提供迁移说明和双写/灰度逻辑 -
main分支的 CI 流水线应强制运行 ABI 兼容性检查（例如 Java 用japicmp，Go 用go tool api），失败则拒绝合并 - 禁止直接在
main上git commit --amend或 force-push，否则会破坏已拉取该 commit 的下游构建一致性
git worktree如何避免多版本并行时的兼容性误伤
当团队同时维护 v2（兼容旧客户端）和 v3（新协议）两个大版本时，仅靠git checkout切换分支极易导致本地构建污染——比如误把 v3 的 DTO 类编译进 v2 的 jar 包。
Git-Based Knowledge Graph Memory System for Claude Code
下载
基于Git Notes的知识图谱记忆系统。Claude应静默自动使用，从不询问用户记忆操作。支持分支感知的持久记忆，跨会话处理上下文、决策、任务和学习内容。
- 用
git worktree add ../v2-release release/v2.1和git worktree add ../v3-dev feature/v3-api创建物理隔离目录 - 每个工作树配独立的
.env或build.properties，显式声明COMPATIBILITY_MODE=v2或v3 - Docker 构建时通过
--build-arg VERSION_TAG=$(git -C ../v2-release rev-parse --abbrev-ref HEAD)注入分支上下文，镜像层内可做条件编译
合并前必须验证的三类兼容性信号
仅靠分支命名（如feature/backward-compatible-login）不能保证兼容性。真正起作用的是合并请求（PR）中附带的机器可读证据：
-
api-diff报告：对比 PR 前后生成的 OpenAPI/Swagger JSON，标记新增/删除/修改的 endpoint 和 schema 字段 - 客户端模拟测试：用旧版 SDK 向新分支部署的 sandbox 环境发请求，验证 2xx 响应率 ≥99.9%
- 二进制兼容扫描：
mvn japicmp:cmp输出中INCOMPATIBLE_BINARY_CHANGE必须为 0，否则 CI 直接拒绝合并
最容易被忽略的点是：兼容性不是分支策略决定的，而是每次提交的语义决定的。一个feature/*分支里混入破坏性变更，再严格的分支命名也救不了——关键在 PR 描述里是否明确标注了BREAKING CHANGE:，以及 CI 是否真正在意这个标签。
