Git 如何配置本地分支自动追踪远程 origin 同名分支

Git 本地分支追踪远程分支是日常开发的高频操作。最稳妥的方式是在首次推送时使用 -u 参数，若希望长期自动关联，需 Git 2.37 及以上版本并开启 push.autoSetupRemote 配置。

先说结论：手动关联最可靠，自动配置需版本支持，不要盲目修改全局配置。

命令速用版

如果只是想解决当前分支的追踪问题，直接执行：

git push -u origin <branch-name>

如果希望以后新建分支推送时自动建立追踪（需 Git 2.37+）：

git config `--global` push.autoSetupRemote true

Git 的本地分支和远程分支默认是独立的。所谓“追踪”（upstream），就是告诉 Git 本地分支默认对应哪个远程分支，这样后续执行 git pull 或 git push 时就不需要再指定远程仓库和分支名。

早期版本 Git 为了安全，默认不会自动建立这种关联，需要用户显式指定。较新的版本引入了配置项，允许在推送时自动补全这个关系，但前提是版本够新且配置正确。

1. 确认 Git 版本

自动追踪配置依赖较新的 Git 版本，先检查版本号：

git `--version`

如果版本低于 2.37，建议仅使用手动方式，不要强行配置自动选项，否则命令会报错或无效。

2. 手动建立追踪（通用方法）

在当前分支执行推送并设置上游：

git push -u origin 当前分支名

或者分支已存在，仅设置追踪关系：

git branch `--set-upstream-to`=origin/当前分支名

3. 开启自动追踪（可选，需新版本）

确认版本满足要求后，执行全局配置：

git config `--global` push.autoSetupRemote true

同时确保 push.default 设置为 simple 或 current（2.0 版本后默认即为 simple）：

git config `--global` push.default simple

如果开启自动追踪后遇到兼容性问题，或希望恢复默认行为，可以取消全局配置：

git config `--global` `--unset` push.autoSetupRemote

执行后，Git 将不再尝试自动设置上游分支，恢复为需要手动指定 -u 参数的行为。

执行以下命令查看分支详细信息：

git branch -vv

观察输出结果，当前分支后面应该会有方括号标注远程追踪信息，例如：

* feature-log [origin/feature-log] commit message

如果方括号内显示 origin/分支名，说明追踪已建立。如果只显示本地 commit 信息而没有 origin 标识，说明未追踪。

此外，直接输入 git status 也可以看到提示，如果有追踪，会显示“您的分支与 'origin/xxx' 一致”或类似字样。

1. 版本不支持配置项

在旧版 Git 中使用 push.autoSetupRemote 会无效或被忽略，公开资料中没有看到可靠的量化数据说明旧版本的具体表现，但通常是不会生效且不会报错，导致用户以为配置成功。务必先检查版本。

2. 全局配置影响范围

使用 `--global` 参数会将配置应用到当前用户的所有仓库。如果在某些特殊仓库（如裸仓库或特定工作流仓库）中不需要此行为，可能会产生预期外影响。建议先在一个测试仓库中验证。

3. 远程分支名不一致

自动追踪通常假设本地分支名与远程一致。如果远程分支名不同，自动配置可能无法正确关联，仍需手动指定。

4. push.default 设置冲突

如果之前修改过 push.default 为 matching 等其他值，可能会影响自动追踪的行为。建议保持默认的 simple 模式，除非清楚其差异。