简介：j2kt-commiter是一款面向Kotlin迁移场景的命令行工具，主要帮助开发者在将Java项目逐模块转换为Kotlin时，通过两次重命名与提交策略保留每个文件的Git历史记录，适合需要平滑迁移且关注代码溯源的中高级Android或JVM开发者。压缩包共24个文件，约3.82MB，其中包含3个Kotlin源代码文件、8个Jar依赖库（如JGit、SLF4J等）、10个用于IntelliJ IDEA工程配置的XML文件，以及README说明文档，结构清晰，可直接运行验证。该工具支持多仓库VCS映射，并提供空运行模式，可在不实际提交文件的情况下预先查看转换流程。其核心逻辑是先将Kotlin文件重命名为Java文件并提交，再将文件名改回Kotlin执行第二次提交，从而让Git历史保持连续可追溯；转换时仅提交被转换的文件，避免工作目录中的其他改动混入提交记录。目前已有225人学习下载，对于正在经历Java转Kotlin、又不想丢失提交历史的团队来说，这是一份可直接运行的辅助脚本，也是一套值得参考的迁移实践方案。
1. Kotlin 迁移总有一步绕不开：让 Git 记住 Java 文件的旧历史
接手过一个用 Java 写的跨平台系统，代码量不小，迁移到 Kotlin 时最头疼的居然不是语法差异，而是历史记录。以前每行代码的来龙去脉，git blame一敲就清清楚楚；文件改名、挪目录也基本能追到源头。可在 Java 转 Kotlin 后，blame 直接指向「整文件删除」，原来的提交信息、作者、改动人全成了黑匣子。j2kt-commiter这个命令行工具就是为这个场景设计的：它会在转换过程中自动生成特殊的双提交，利用 Git 自身的相似度检测机制，让 Kotlin 文件能关联回对应的 Java 历史。适合正在做 Kotlin 迁移、并且对代码追溯有硬性要求的团队，尤其是需要过审计或做长期维护的项目。
2. 为什么 Java 转 Kotlin 会切断 Git 历史：文件重命名检测机制与双提交策略
2.1 Git 靠什么判断文件被重命名或重写
Git 本身没有「重命名跟踪」这个功能。它比较提交前后的两棵树，靠文件名路径和内容 token 相似度来推断哪个文件可能是旧文件改过来的。git diff --find-renames和一个默认阈值有关：当两个路径的内容相似度超过阈值时，就会被判成 rename，从而把历史串起来。
Java 转 Kotlin 后，文件扩展名从.java变成.kt，路径基本不变，但内容几乎完全换血。方法签名一样，但函数体可能从命令式改成函数式，注释、可见性修饰符、空安全符号全变了。token 层面的相似度经常低于检测阈值，Git 就把它当成「删了旧文件、加了新文件」。git blame输出里所有行都指向删除提交，原来谁写的、什么时候改的，全断了。
2.2 双提交策略：先让 Git 找到「相似的」Kotlin 文件，再移除 Java
j2kt-commiter 的思路不是把两个 Git 仓库的 commit 链接起来，而是在一次转换里制造两次提交。第一次提交把 Java 文件删除，同时把对应的 Kotlin 文件加进来；第二次提交再正式删除剩余的 Java 文件。这样设计的核心意图，是让 Git 的相似度检测算法有机会把「新增的 Kotlin 文件源」识别成「被删除的 Java 文件源」的重命名结果。
实际跑起来是这个效果：第一次提交里，src/main/java/com/example/Foo.java被删掉，src/main/kotlin/com/example/Foo.kt被加入，因为路径目录名一致、文件基名一致，加上内容里保留了类名、方法名、字符串常量这些 token，Git 更可能判成 rename；第二次提交再把残留的 Java 文件清干净。这样执行完后，git log --follow能顺着 rename 找到 Java 时代的提交，blame 也能追溯到原始行。按目录批量迁移时，工具会为每个文件对生成两条提交记录。
2.3 主要参数与用法概览
| 参数 | 作用 | 典型值 |
|---|---|---|
-map | 建立 Java 旧路径与 Kotlin 新路径的映射关系 | -map src/main/java/com/example/Foo.java src/main/kotlin/com/example/Foo.kt |
-unmap | 在迁移后解除映射，常用于二次操作，确保手写映射不被覆盖 | -unmap |
--diff-ignore-whitespace | 让 Git 相似度检测时忽略空白差异 | 转换 Kotlin 后建议加上 |
--no-clobber | 检测到目标 Kotlin 文件已存在时直接报错，不覆盖 | 批量跑时强烈建议开启 |
--resume | 从上次失败的位置继续 | 大批量转换时备用 |
映射关系要么在命令行里逐条给，要么写成文件用@映射文件形式传入。批量场景下我一般会准备一份映射清单，每行一条「旧路径 新路径」，可读性好，也方便排查。
3. 把 j2kt-commiter 跑起来：环境准备、映射定义与一个可复现的命令
3.1 环境要求与安装
这个工具以 jar 包形式分发，要求本机装有 JDK 17 及以上版本。安装不需要全局写权限，把它放在一个固定目录下即可：
mkdir -p ~/tools/j2kt-commiter mv j2kt-commiter.jar ~/tools/j2kt-commiter/ java -jar ~/tools/j2kt-commiter.jar --version最后一条命令能正常输出版本号，说明环境就绪。注意：工具只负责 Git 提交生成，不负责 Java 到 Kotlin 的代码转换，转换动作本身还是要靠其它工具或人工完成。
3.2 初始化仓库与定义路径映射
进入要迁移的仓库根目录，先确认工作区是干净的，然后初始化工具的状态文件：
cd /path/to/project git status --porcelain # 必须没有任何输出，保证起点干净 java -jar ~/tools/j2kt-commiter.jar initinit会在.git目录旁边生成一个状态文件，记录哪些文件已映射、哪些还没处理。然后定义 Java 与 Kotlin 文件的对应关系：
java -jar ~/tools/j2kt-commiter.jar define \ -map src/main/java/com/example/Foo.java src/main/kotlin/com/example/Foo.kt \ -map src/main/java/com/example/Bar.java src/main/kotlin/com/example/Bar.ktdefine子命令就是「告诉工具这两个文件是一次转换的前后关系」。路径用相对仓库根目录的写法，不要带绝对路径，否则后面提交信息里会混入机器相关路径。映射条目多的话，把上面的写法整理成文件，再用@mapper.txt传入，可维护性更好。
3.3 执行第一次提交并验证 rename 关联
映射定义好之后，执行提交操作。这一阶段交给 j2kt-commiter 全权处理：
java -jar ~/tools/j2kt-commiter.jar commit --diff-ignore-whitespace这条命令做的事：对每个已定义映射的 Java 文件执行删除，并git add对应的 Kotlin 文件，然后生成提交。提交信息里会写明这是迁移转换提交。执行完可以用下面这条命令验证：
git log --oneline --follow -- src/main/kotlin/com/example/Foo.kt如果输出里能看到 Java 时代的提交记录，说明 rename 关联成功；如果只看到刚才那条迁移提交和更早的无关提交，说明相似度没被 Git 认可，需要检查内容改动幅度或者考虑拆分更细的映射。
3.4 移除残留 Java 文件并检查状态
第一次提交后，如果某些 Java 文件没有被任何映射覆盖，工具会把它们留在工作区。需要手动确认这些文件确实不再被构建脚本引用，然后发起第二次提交：
git rm src/main/java/com/example/OldUnmapped.java git commit -m "Remove Java sources after Kotlin conversion complete"这个第二步提交与 j2kt-commiter 生成的第一条提交是独立的，顺序不可颠倒。先删 Java 再补 Kotlin 的顺序会打断 rename 检测；先补 Kotlin，那些 Java 文件短暂存在也不会影响编译，只影响仓库体积，可接受。
4. 实践中的避坑记录：五个真实会踩的问题与排查方法
4.1 现象：--diff-ignore-whitespace没加，Kotlin 文件被判成新增而非重命名
原因：Kotlin 官方格式化风格与 Java 差异明显，缩进、空行、参数换行规则全不同。内容相似度本来就贴着检测阈值的边，空白差异一叠加就跌破线了。
解决：执行commit时务必加上--diff-ignore-whitespace。加了之后，Git 检测相似度时会先忽略空白 token，Kotlin 文件里大量「只改换行没改逻辑」的行就不会拖累整体相似度。
4.2 现象：Windows 环境迁移后，git log --follow追到一半断开
原因：Windows 上 Git 默认把换行符转成 CRLF，j2kt-commiter 生成的提交里，Kotlin 文件内容用的是 CRLF；而被删除的 Java 文件在仓库里可能是 LF。换行符差异会直接影响相似度计算，即使开了--diff-ignore-whitespace，某些 Git 版本在 CRLF/LF 混用时也会走不同的比较分支。
解决：迁移前先统一行尾。在仓库根目录加一个.gitattributes，把*.java text eol=lf和*.kt text eol=lf固定下来，然后跑一次重新规范化。之后再执行 j2kt-commiter 的操作，rename 检测就稳定很多。
4.3 现象：批量转换时，某个 Kotlin 文件原本就已存在，工具直接中断
原因：define里映射的目标路径如果已经存在同名 Kotlin 文件，工具默认会停下来，怕覆盖掉已有代码。没有开任何保护参数时，行为也不可预期。
解决：批量操作时加--no-clobber，让工具遇到目标文件存在就直接报错退出，而不是覆盖。中断后检查那个已存在的文件：如果是误放到目标路径的，先挪走；如果是之前迁移遗漏的，改映射路径绕开。再用--resume继续执行，不用把已跑完的映射重新跑一遍。
4.4 现象：define时写了-map，二次调整时旧映射总在干扰
原因：-map是「建立或更新映射」，不是「临时覆盖」。第二次执行时如果不显式解除旧映射，工具会把新旧映射混在一起，导致 Git 相似度检测出现多余的候选路径。
解决：需要调整映射前，先用-unmap解除对应条目，再重新-map。流程是「先解绑再绑新」，不要直接覆盖。映射文件建议纳入版本管理，每次调整都留痕，排查时能回溯哪一步改坏了关联。
4.5 现象：迁移后的提交信息里出现完整文件路径，PR 审查时被反复追问
原因：j2kt-commiter 生成的提交信息默认会带上被映射的文件路径列表，路径长了以后，PR 页面会被刷屏，审查者很难聚焦到真正的代码变更上。
解决：用--message-prefix或提交信息模板，把描述收敛为一句「Migrate Foo.java to Foo.kt」之类的简短说明，路径细节放到提交 body 里。PR 标题和第一行描述保持简洁，历史记录的完整性不受影响。
5. 进阶玩法：按目录粒度迁移、批量脚本化与 CI 里的历史保留
5.1 按包路径批量定义映射
模块化迁移时，通常按包结构分批处理。整包路径一次性定义，比逐个文件敲命令高效得多。先列出包下所有 Java 文件，再形成映射清单：
cd /path/to/project for java_file in $(find src/main/java/com/example/moduleA -name '*.java'); do kt_file="src/main/kotlin${java_file#src/main/java}" kt_file="${kt_file%.java}.kt" echo "$java_file $kt_file" >> mapping_moduleA.txt done java -jar ~/tools/j2kt-commiter.jar define @mapping_moduleA.txt脚本里kt_file的生成规则是：把src/main/java前缀替换成src/main/kotlin，扩展名改成.kt。如果你的项目不是这种标准布局，要先把目录映射关系梳理清楚，别让脚本生成的全是错误映射。跑完define后抽查几条，确认路径都真实存在，再执行commit。
5.2 写一个可重放的迁移脚本
一次性交互式的转换很难复现，出了岔子也没法回滚重来。把整个迁移流程固化成脚本，才能保证团队里的其他人拿到同样结果。下面是一个常见做法的框架，映射文件、命令参数全部从外部传入：
#!/usr/bin/env bash set -euo pipefail PROJECT_ROOT="${1:?usage: $0 <project-root>}" MAPPING_FILE="${2:?usage: $0 <project-root> <mapping-file>}" JAR="$HOME/tools/j2kt-commiter/j2kt-commiter.jar" cd "$PROJECT_ROOT" git status --porcelain | grep -q . && { echo "工作区不干净，先处理未提交的变更" exit 1 } java -jar "$JAR" init java -jar "$JAR" define "@$MAPPING_FILE" java -jar "$JAR" commit --diff-ignore-whitespace --no-clobber git status --porcelain脚本在commit前强制检查工作区是否干净，避免把无关改动混进迁移提交。set -euo pipefail保证任何一步出错都会立即中止，不会带着半成品状态继续往下跑。
5.3 与 CI 流程配合，避免主分支历史被反复改写
迁移最好不要直接在主分支上进行。常见做法是拉一条专门的分支，跑完整转换，确认构建和测试通过后，用常规合并（非 squash）合回主分支。squash 会把迁移提交压缩成一个，rename 关联虽然还在，但中间的提交粒度就丢了。
合并目标分支选好之后，确保 CI 里的代码扫描工具认得 Kotlin 文件的新路径，原来针对src/main/java路径的规则要同步更新。否则迁移完会出现一类诡异问题：本地git log一切正常，CI 却报覆盖率找不到文件，根源就是路径规则没跟上。
5.4 映射文件作为单一事实来源
映射文件是迁移过程的核心资产，建议和代码一起入库。它记录了「哪个 Java 文件对应哪个 Kotlin 文件」，以后做历史追溯、代码审计、甚至反向迁移时都能用。放在docs/migration/下，以日期命名，保留每次迁移的完整版本。
6. 迁移后的历史验证技巧：用 blame 与 diff 反查关联是否可靠
验证 rename 映射是否成功，最直接的方法是看git blame的原始输出。拿 Kotlin 文件里某一行代码试一下：
git blame src/main/kotlin/com/example/Foo.kt -L 10,20如果这十几行都指向迁移提交，说明映射可能没有生效；如果指向的是几周甚至几个月前的 Java 提交，说明 rename 关联建立成功。注意-L范围里如果有新增逻辑行，那些行指向迁移提交是正常的，不要误判。配合git diff <迁移前提交> <迁移后提交> --find-renames查看相似度得分，能看到每个文件对的分数，低于阈值的就是需要回头处理的漏网之鱼。
还有一个容易被忽略的点：确认 Git 的diff.renames配置没有被设置成false。某些自动化构建环境为了追求速度会关掉 rename 检测，导致历史记录在克隆仓库时就已经断了。
我曾有一次在迁移框架代码时图省事，跳过了--diff-ignore-whitespace，结果大量 Kotlin 文件被判成新增，历史全断。后来重新定义映射、批量补跑，前前后后花了几小时。从那以后我每次做 Java 到 Kotlin 的转换，都强制走完这套流程：先统一换行符，再小批量执行双提交，每一步都验证git log --follow能追到历史，最后才合并主分支。希望这些经验能帮你在迁移路上少踩几个坑，保住那份真正有价值的历史记录。
本文还有配套的精品资源，点击获取
