简介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 文件再移除 Javaj2kt-commiter 的思路不是把两个 Git 仓库的 commit 链接起来而是在一次转换里制造两次提交。第一次提交把 Java 文件删除同时把对应的 Kotlin 文件加进来第二次提交再正式删除剩余的 Java 文件。这样设计的核心意图是让 Git 的相似度检测算法有机会把「新增的 Kotlin 文件源」识别成「被删除的 Java 文件源」的重命名结果。实际跑起来是这个效果第一次提交里src/main/java/com/example/Foo.java被删掉src/main/kotlin/com/example/Foo.kt被加入因为路径目录名一致、文件基名一致加上内容里保留了类名、方法名、字符串常量这些 tokenGit 更可能判成 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 检测相似度时会先忽略空白 tokenKotlin 文件里大量「只改换行没改逻辑」的行就不会拖累整体相似度。4.2 现象Windows 环境迁移后git log --follow追到一半断开原因Windows 上 Git 默认把换行符转成 CRLFj2kt-commiter 生成的提交里Kotlin 文件内容用的是 CRLF而被删除的 Java 文件在仓库里可能是 LF。换行符差异会直接影响相似度计算即使开了--diff-ignore-whitespace某些 Git 版本在 CRLF/LF 混用时也会走不同的比较分支。解决迁移前先统一行尾。在仓库根目录加一个.gitattributes把*.java text eollf和*.kt text eollf固定下来然后跑一次重新规范化。之后再执行 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_filesrc/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能追到历史最后才合并主分支。希望这些经验能帮你在迁移路上少踩几个坑保住那份真正有价值的历史记录。本文还有配套的精品资源点击获取