使用GitPython推送代码时遇‘fatal: You are not currently on a branch.’错误

我尝试用GitPython检出Git分支，生成文件后推送到该分支，代码如下：

repo = git.Repo(build_agent_artifact_directory)

branch_name =  source_branch_name.split('/')[-1]
if branch_name in repo.branches:
   repo.git.checkout(branch_name)

# 生成文件的代码（此处替换为实际文件生成逻辑）
# Python code to generate files and add it to the remote location

repo.git.add('--all')
repo.index.commit("pushing generated files")
origin = repo.remote(name='origin')
origin.push()

执行脚本时出现如下错误：

git.exc.GitCommandError: Cmd('git') failed due to: exit code(128)
cmdline: git push --porcelain origin
stderr: 'fatal: You are not currently on a branch.'

问题原因 #

错误核心是仓库处于 detached HEAD 状态——你的代码仅在本地分支存在时执行checkout操作，若目标分支不存在，代码会跳过分支切换，此时仓库停留在某个孤立提交节点上，而非合法分支，这种状态无法直接推送提交。

修复方案 #

必须确保无论分支是否存在，最终都处于已命名的分支上。修改后的代码如下：

repo = git.Repo(build_agent_artifact_directory)

branch_name = source_branch_name.split('/')[-1]
remote_branch_ref = f"origin/{branch_name}"

# 处理本地分支不存在的情况：从远程拉取并创建本地分支
if branch_name not in repo.branches:
    # 基于远程分支创建本地分支并切换
    repo.git.checkout('-b', branch_name, remote_branch_ref)
else:
    # 本地分支存在，直接切换
    repo.git.checkout(branch_name)

# 此处插入你的文件生成代码
# Python code to generate files and add it to the remote location

repo.git.add('--all')
repo.index.commit("pushing generated files")
origin = repo.remote(name='origin')
origin.push()

补充说明 #

• 如果远程也不存在目标分支，需先创建远程分支，或添加额外逻辑处理（比如创建全新本地分支后推送到远程）
• 提交和推送前，务必确认仓库处于已命名分支上，避免detached HEAD状态引发的推送失败

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