环境变量IGNORE_NORMALISATION_GIT_HEAD_MOVE的作用及设置副作用是什么？

错误根因与环境变量作用 #

GitVersion在计算版本号前会先执行仓库归一化逻辑，会自动拉取全部分支引用、清理本地未提交变更、切换到构建指定的目标提交，确保所有环境下版本计算的基础状态一致。该报错是归一化完成后，GitVersion检测到HEAD指针的位置和预期提交哈希不一致，默认判定为内部逻辑错误直接中断构建。

IGNORE_NORMALISATION_GIT_HEAD_MOVE=1的作用就是直接跳过这个HEAD一致性校验，不管归一化后HEAD是否发生偏移，都强制继续执行版本计算流程。

设置为1的副作用 #

• 版本号计算结果不可控：如果HEAD偏移是真实发生的（比如构建环境有其他并行脚本修改了仓库状态、归一化逻辑真的出现错误），GitVersion会基于偏移后的提交计算版本，可能出现特性分支错用master的版本规则、版本号跳变、重复版本号等问题，完全不符合预期。
• 掩盖真实问题：该校验原本的作用是暴露GitVersion内部bug、构建环境的操作冲突问题，开启变量后这类问题会被直接屏蔽，后续出现版本异常时排查成本会大幅提升。
• 构建产物追溯风险：如果不同提交的构建因为HEAD偏移算出了相同的版本号，后续发布、回滚时会出现产物和代码提交匹配错误的问题，难以追溯问题根因。

更推荐的规避方案 #

不建议直接开启该环境变量，优先用以下方式解决报错：

• Jenkins构建任务配置「每次构建前清理工作空间」，拉取代码时使用完整克隆而非浅克隆、增量拉取，避免本地仓库状态混乱触发校验失败。
• 升级GitVersion.MsBuild到最新稳定版，该报错的大部分触发场景已经在后续版本的归一化逻辑优化中被修复。
• 特性分支构建前先rebase到最新的master分支，既可以规避该报错，也能提前发现代码合并冲突。

内容的提问来源于stack exchange，提问作者Claus Appel