如何使用libgit2创建无提交记录的初始分支？

Git命令行中，刚初始化的空仓库可以直接创建unborn分支（无提交历史的分支），但libgit2的git_branch_create API要求基于已存在的提交对象，因此需要通过**直接操作引用（Reference）**来实现相同效果，具体方案如下：

核心原理 #

空仓库中创建的unborn分支本质是：HEAD符号引用指向一个尚未存在的分支引用（refs/heads/[分支名]），直到首次提交后该分支引用才会被实际创建并指向提交对象。因此我们不需要创建实际的分支引用，只需修改HEAD的指向即可。

具体实现步骤（C语言示例） #

1. 初始化本地仓库
   使用git_repository_init API创建并打开目标路径的仓库：

   git_repository *repo = NULL;
   int ret = git_repository_init(&repo, "/tmp/REPO/ROOT", 0);
   if (ret < 0) {
       // 错误处理：可通过git_error_last()获取错误信息
       git_repository_free(repo);
       return ret;
   }
   

2. 修改HEAD指向目标分支
   使用git_reference_symbolic_create API将HEAD符号引用指向新分支的路径（refs/heads/anyName），设置force标志为1以覆盖默认的HEAD指向：

   ret = git_reference_symbolic_create(
       NULL,                // 无需返回新创建的引用对象
       repo,                // 仓库实例
       "HEAD",              // 要创建的引用名称
       "refs/heads/anyName",// 目标分支的引用路径
       1,                   // force标志：覆盖已存在的HEAD引用
       NULL                 // 签名对象（无需签名时传NULL）
   );
   if (ret < 0) {
       // 错误处理
       git_repository_free(repo);
       return ret;
   }
   

3. 清理资源
   操作完成后释放仓库实例：

   git_repository_free(repo);
   

效果验证 #

完成上述操作后，仓库状态与命令行执行git init && git checkout -b anyName完全一致：

• 当前分支为anyName，属于unborn状态（无关联提交）
• 执行首次提交后，refs/heads/anyName引用会自动创建并指向该提交

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