简介：这是一款面向Kotlin迁移场景的辅助工具，专为需要将Java代码转换为Kotlin、同时希望保留Git提交历史的开发者设计。它通过重命名与两次提交的巧妙方式，让转换后的文件在版本库中延续原有历史记录，并支持多仓库的VCS映射，还提供空运行模式便于先行验证。资源包共24个文件，包含8个jar依赖（如JGit、slf4j、jansi等）、10个xml配置、3个kt源码及iml、mf、md等辅助文件，压缩包约3.82MB，结构紧凑、开箱即用。目前已有225人学习下载。借助其中的可执行脚本与依赖库，读者可快速完成Java到Kotlin的批量转换并保留提交轨迹，同时通过日志与空运行机制排查问题，适合正在推进Kotlin迁移的中高级开发者参考使用。
1. 从 Java 到 Kotlin 的迁移，为什么历史记录总在提交那一刻断档
做过 Java 到 Kotlin 迁移的人大概都有过这种体验：代码改完了，编译也过了，可一旦执行git log，之前那条清晰的演进线就像被人从中间剪断了一样——最后一次 Java 提交和第一次 Kotlin 提交之间，Git 认不出它们是同一个文件的延续。这不是玄学，是 Git 的 rename detection 在跨语言重写场景下的天然盲区。
j2kt-commiter 这个工具要解决的就是这件事。它面向的是正在做 Java 到 Kotlin 渐进式迁移的团队，核心诉求只有一个：在把.java文件转换成.kt文件的过程中，让 Git 历史记录保持可追溯，git blame能一路追到 Java 时代的原始作者和提交，而不是在转换点戛然而止。如果你正在维护一个存量大、提交历史长、多人协作的 Java 项目，并且打算分批迁移到 Kotlin，这个工具值得花时间拆一拆。
它的思路不是去改 Git 的底层对象，而是在提交策略上做文章——通过控制转换和提交的粒度，让 Git 的相似度检测算法能够识别出「这个.kt文件就是原来那个.java文件」。听起来简单，但实际操作里有一堆细节会让这个目标落空。
2. 历史保留的底层逻辑：Git 怎么判断两个文件是同一个
2.1 Git 的 rename detection 到底在看什么
Git 并不存储「重命名」这个动作本身。它存储的是每次提交的完整树对象快照，然后在需要的时候（比如git log --follow、git blame、git diff -M）通过相似度算法去推断两个文件之间是否存在重命名关系。默认的相似度阈值是 50%，可以通过-M参数调整，比如-M90%表示要求 90% 以上的相似度才认定为重命名。
这个机制对 Java 转 Kotlin 来说是把双刃剑。一方面，如果转换后的 Kotlin 代码和原 Java 代码在结构上足够相似，Git 有可能自动识别出重命名；另一方面，Java 和 Kotlin 的语法差异——分号消失、类型声明顺序变化、public变成默认可见性、getter/setter 变成属性——会让文本相似度骤降，经常跌破 50% 的阈值。
常见做法是先用git diff -M --stat看看 Git 自己能不能识别出来。如果识别不了，就需要在提交策略上做干预。
2.2 j2kt-commiter 的干预策略
这个工具的核心操作可以概括为三步：先做纯重命名提交，再做内容转换提交。第一步把Foo.java重命名为Foo.kt，但内容保持 Java 语法不变（或者只做最小改动），单独提交一次。第二步再把文件内容真正转换成 Kotlin 语法，再提交一次。
这样做的原因是：第一步的提交里，Git 看到的是一个 100% 相似度的重命名（文件内容没变，只是扩展名变了），rename detection 必然命中。第二步的提交里，Git 看到的是同一个.kt文件的内容修改，不涉及重命名判断，历史自然延续。
听起来是个笨办法，但笨办法在 Git 这种基于快照的版本控制里往往最可靠。关键在于执行时的细节控制——哪些文件一起处理、提交信息怎么写、什么时候该拆什么时候该合。
2.3 为什么不能一次性批量转换再提交
我见过最常见的翻车方式就是：用 IDE 的自动转换功能把几十个 Java 文件一次性转成 Kotlin，然后一个提交推上去。结果就是git log --follow完全失效，git blame显示所有行都是「本次提交」，之前几年的作者信息全部丢失。
原因在于批量转换后，Git 面对的是一个巨大的 diff，里面既有文件删除又有文件新增，还有大量内容修改。rename detection 在这种混乱的 diff 里基本不可能正确匹配。而且一旦这个提交推到了远端，再想修复历史就非常麻烦了——你不可能去 rewrite 已经共享的提交历史。
所以正确的做法是控制每次提交的范围。j2kt-commiter 一般建议每次处理一个文件或一组紧密相关的文件，确保每个转换都有对应的重命名提交和内容提交。
3. 实操：用 j2kt-commiter 完成一次可追溯的转换
3.1 环境准备与工具获取
这个工具本身是一个命令行程序，运行需要 JDK 17 或以上版本，以及 Git 2.30+（因为用到了一些较新的 diff 参数）。获取方式通常是从项目的 release 页面下载可执行 jar 包，或者从源码构建。
# 确认环境版本 java -version # 期望输出：openjdk version "17.x.x" 或更高 git --version # 期望输出：git version 2.30.x 或更高 # 从源码构建（如果选择这条路） git clone <repo-url> cd j2kt-commiter ./gradlew shadowJar # 构建产物在 build/libs/ 目录下构建完成后会得到一个可执行的 fat jar。我一般会把它放到一个固定路径，比如~/tools/j2kt-commiter.jar，然后写一个简单的 shell alias 方便调用。
注意：如果你的项目用的是 Gradle 或 Maven 多模块结构，建议先在单个模块上验证流程，确认历史保留效果符合预期后再推广到整个项目。
3.2 单文件转换的完整流程
假设你要把src/main/java/com/example/service/UserService.java转换成 Kotlin。整个流程分四步：重命名提交、内容转换、验证、推送。
# 第一步：纯重命名，内容不动 git mv src/main/java/com/example/service/UserService.java \ src/main/java/com/example/service/UserService.kt git commit -m "rename: UserService.java -> UserService.kt (step 1/2)" # 第二步：用 j2kt-commiter 做内容转换 java -jar ~/tools/j2kt-commiter.jar \ --input src/main/java/com/example/service/UserService.kt \ --output src/main/java/com/example/service/UserService.kt \ --mode convert \ --report ./conversion-report.json # 查看转换报告，确认没有严重问题 cat ./conversion-report.json | python3 -m json.tool | head -50 # 第三步：提交转换后的内容 git add src/main/java/com/example/service/UserService.kt git commit -m "convert: UserService to Kotlin syntax (step 2/2)" # 第四步：验证历史是否保留 git log --follow --oneline src/main/java/com/example/service/UserService.kt这里的关键参数是--mode convert，它告诉工具执行实际的语法转换而不是只做分析。--report参数会生成一个 JSON 格式的转换报告，里面记录了哪些地方做了自动转换、哪些地方需要人工确认、哪些地方转换失败。这个报告非常重要，后面会详细说怎么看。
git log --follow是验证历史保留的核心命令。如果输出里能看到 Java 时代的提交记录，说明重命名被正确识别了。如果只看到最近两条提交，说明 rename detection 没命中，需要检查相似度阈值或者调整提交策略。
3.3 批量转换时的分组策略
实际项目里不可能一个一个文件手动转。j2kt-commiter 支持通过配置文件批量处理，但批量不等于一次性全转。我的经验是按依赖关系分组，每组 5 到 10 个文件，组内文件之间有调用关系，组间依赖尽量少。
# conversion-plan.yaml groups: - name: "user-service-layer" files: - src/main/java/com/example/service/UserService.java - src/main/java/com/example/service/UserValidator.java - src/main/java/com/example/service/UserMapper.java commit_prefix: "user-svc" - name: "order-service-layer" files: - src/main/java/com/example/service/OrderService.java - src/main/java/com/example/service/OrderValidator.java commit_prefix: "order-svc"# 按分组执行转换 java -jar ~/tools/j2kt-commiter.jar \ --plan conversion-plan.yaml \ --repo . \ --auto-commit \ --similarity-threshold 50--auto-commit会让工具自动完成「重命名提交 + 内容提交」的两步操作，省去手动 commit 的麻烦。--similarity-threshold对应 Git 的-M参数，默认 50%，如果发现某些文件历史丢失，可以适当降低这个值再试。
分组的原则是：同一组内的文件一起提交，组与组之间分开提交。这样即使某一组的历史保留出了问题，影响范围也可控，不会污染整个迁移过程。
3.4 转换报告的解读与人工介入
自动转换不可能 100% 正确。Java 里的一些模式——比如复杂的泛型嵌套、注解处理器的生成代码、反射相关的字符串引用——Kotlin 没有直接对应物，工具只能标记出来让人工处理。
转换报告里一般会把问题分成三个等级：auto表示自动转换成功，review表示转换了但需要人工确认，manual表示无法自动转换需要手动改写。我一般会先把所有manual的条目过一遍，这些是必须处理的；然后抽查review的条目，确认转换结果符合预期。
# 提取所有需要人工处理的条目 cat conversion-report.json | \ python3 -c " import json, sys report = json.load(sys.stdin) for item in report.get('issues', []): if item['level'] in ('manual', 'review'): print(f\"[{item['level']}] {item['file']}:{item['line']} - {item['message']}\") "这个脚本会列出所有需要关注的转换问题。manual级别的必须逐个处理，review级别的可以批量确认。处理完之后再提交，确保每次提交的代码都是可编译、可测试的。
4. 避坑指南：历史保留失败的五个典型场景
4.1 git log --follow 看不到 Java 时代的提交
现象：转换完成后执行git log --follow，只显示最近两条提交，之前的 Java 提交记录全部消失。
原因：最常见的原因是重命名提交和内容提交被合并成了一个提交。有些团队为了「提交历史干净」，会把两步操作 squash 成一步，结果 Git 看到的是一个文件被删除、另一个文件被新增，rename detection 直接失效。
解决：确保重命名和内容转换是两个独立的提交。如果已经合并了，在推送之前可以用git rebase -i拆开。已经推送的话，如果分支是共享的，不建议 rewrite 历史，只能接受这个文件的历史丢失，后续文件严格按两步走。
4.2 相似度阈值过高导致部分文件匹配失败
现象：大部分文件的历史都保留了，但有几个文件git log --follow就是看不到旧记录。
原因：这些文件的 Java 和 Kotlin 版本差异太大，比如 Java 里用了大量静态工具方法，转成 Kotlin 后变成了扩展函数或者顶层函数，文本相似度跌破了 50% 的默认阈值。
解决：对这些文件单独处理，在重命名提交时尽量保持内容不变（只改扩展名），把语法转换全部放到第二个提交里。如果还是不行，可以在git log --follow -M40%里降低阈值试试，确认是阈值问题而不是提交策略问题。
4.3 IDE 自动格式化污染了重命名提交
现象：重命名提交里除了文件扩展名变化，还有大量空格、换行、import 顺序的改动。
原因：IDE 的 save action 或者 pre-commit hook 在git mv之后自动格式化了文件，导致重命名提交的 diff 不再「纯净」。
解决：在执行重命名提交之前，临时关闭 IDE 的自动格式化和 pre-commit hook。或者用git commit --no-verify跳过 hook。重命名提交的 diff 应该只有一行：similarity index 100%和rename from ... rename to ...。
4.4 跨模块迁移时包路径变化导致匹配失败
现象：文件从src/main/java/迁移到src/main/kotlin/时，历史记录丢失。
原因：Git 的 rename detection 是基于文件内容的，路径变化本身不影响。但如果迁移过程中同时改了包声明（package com.example变成package com.example.kotlin），内容相似度会下降。
解决：把路径迁移和包声明修改也拆成独立提交。先git mv到新路径，提交；再改包声明，提交；再做语法转换，提交。三步走虽然提交数多了，但每一步的 diff 都足够小，rename detection 更容易命中。
4.5 转换后编译失败导致提交被回滚
现象：转换提交推上去之后 CI 挂了，回滚之后发现历史记录乱了。
原因：自动转换没有覆盖所有语法点，比如 Java 的 checked exception 在 Kotlin 里没有对应概念，转换后编译不过。
解决：在本地先跑一遍完整编译和测试再提交。j2kt-commiter 的转换报告里manual级别的条目必须全部处理完。如果项目有 CI，建议在转换分支上先跑一次 pipeline，确认通过后再合并到主分支。
5. 进阶技巧：用 git replace 修复已经丢失的历史
如果有些文件在早期迁移时已经丢失了历史记录，又不想 rewrite 整个仓库的历史，git replace是一个后悔药级别的工具。它允许你在不修改原始提交对象的前提下，用一个替换对象来「覆盖」某个提交的视图。
# 假设 abc123 是转换后的提交，def456 是转换前的 Java 提交 # 创建一个替换对象，让 Git 在遍历历史时把 abc123 的父提交指向 def456 git replace --graft abc123 def456 # 验证替换效果 git log --follow --oneline src/main/kotlin/com/example/UserService.kt # 如果确认没问题，把替换对象推送到远端 git push origin refs/replace/abc123--graft参数的作用是修改提交的父指针。原本abc123的父提交可能是转换前的某个中间提交，通过 graft 把它直接指向 Java 时代的def456，这样git log --follow就能沿着新的父指针一路追溯到 Java 时代。
这个操作的妙处在于它是非破坏性的——原始提交对象还在，只是 Git 在遍历时用了替换后的视图。如果发现替换错了，git replace -d abc123就能撤销。但要注意，refs/replace/下的引用默认不会被git push --all推送，需要显式指定。
我一般会在两种情况下用这个技巧：一是修复早期迁移时遗漏的文件，二是处理那些因为相似度阈值问题导致历史断裂的顽固文件。用完之后，git log --follow和git blame都能正常工作，团队成员不需要做任何额外操作。
从那以后我每次做跨语言迁移，都会先在单个文件上完整走一遍「重命名 → 转换 → 验证」的流程，确认git log --follow能看到旧记录之后，再按分组批量推进。这个习惯帮我省掉了好几次回滚重来的麻烦。希望帮到你。
本文还有配套的精品资源，点击获取
