如何使用JGit将Git父仓库与子模块的变更一同推送到远程？

你遇到的这个问题很常见——子模块提交成功但推送失败，核心原因基本是子模块处于游离HEAD状态，或者本地分支未与远程分支建立跟踪关系，导致JGit不知道该把变更推送到哪个远程分支。下面是一步步的解决方案：

1. 确保子模块在可推送的分支上 #

子模块默认克隆后通常处于游离的HEAD状态（指向某个具体commit，而非分支），这种情况下提交的变更没有对应的远程分支可以接收。首先要把它切换到一个本地分支，并关联远程分支：

// 获取子模块仓库实例
Repository submoduleRepo = ...; // 你的子模块Repository对象
Git submoduleGit = new Git(submoduleRepo);

// 检查当前是否处于分支上
Ref headRef = submoduleRepo.getRef("HEAD");
String targetBranch = "main"; // 根据你的远程分支名调整，比如master

if (!headRef.isSymbolic()) {
    // 处于游离HEAD状态，切换到远程对应的分支（如果本地没有则创建）
    submoduleGit.checkout()
        .setCreateBranch(true)
        .setName(targetBranch)
        .setStartPoint("origin/" + targetBranch)
        .call();
}

2. 提交子模块的变更（确保已添加修改） #

你的提交代码里用了setAll(false)，这意味着只有已经通过add命令暂存的文件会被提交。如果之前没暂存修改，需要先执行添加操作：

// 暂存子模块中所有修改的文件
submoduleGit.add()
    .addFilepattern(".")
    .call();

// 提交子模块变更
submoduleGit.commit()
    .setAuthor("testUser", "testUser@gmail.com")
    .setMessage(commitMessage)
    .call();

3. 推送子模块（明确指定分支或建立跟踪） #

推送时需要明确告诉JGit要推送到哪个远程分支，或者先建立本地分支与远程分支的跟踪关系：

方案一：直接指定推送的分支 #

// 推送本地main分支到远程origin的main分支
submoduleGit.push()
    .setRemote("origin")
    .setCredentialsProvider(credentialsProvider)
    .setRefSpecs(new RefSpec(targetBranch + ":" + targetBranch))
    .call();

方案二：建立跟踪关系后推送（后续可直接push） #

// 建立本地分支与远程分支的跟踪关系
submoduleGit.branchCreate()
    .setName(targetBranch)
    .setTrack(true)
    .setStartPoint("origin/" + targetBranch)
    .call();

// 之后可以直接推送，无需指定refspec
submoduleGit.push()
    .setRemote("origin")
    .setCredentialsProvider(credentialsProvider)
    .call();

4. 提交并推送父仓库的变更 #

子模块推送成功后，父仓库需要记录子模块的最新commit引用，否则远程父仓库还是指向旧的子模块版本：

// 获取父仓库实例
Git parentGit = new Git(parentRepository);
String submodulePath = "path/to/your/submodule"; // 子模块在父仓库中的相对路径

// 暂存父仓库中子模块的引用变更
parentGit.add()
    .addFilepattern(submodulePath)
    .call();

// 提交父仓库的变更
parentGit.commit()
    .setAuthor("testUser", "testUser@gmail.com")
    .setMessage("Update submodule to latest commit: " + commitMessage)
    .call();

// 推送父仓库
parentGit.push()
    .setRemote("origin")
    .setCredentialsProvider(credentialsProvider)
    .call();

关键注意点 #

• 游离HEAD状态是罪魁祸首：如果子模块不在分支上，提交的变更属于"无主"commit，远程没有对应的分支接收，必然会提示"Nothing to push"。
• 父仓库必须更新子模块引用：子模块推送后，父仓库的子模块目录对应的commit哈希会变化，一定要提交这个变更并推送到远程，否则父仓库的远程版本不会同步子模块的最新状态。

内容的提问来源于stack exchange，提问作者karthick ravichandran