Git分支自动补全默认不生效，是因为Git自带的补全脚本未被Shell显式加载；需手动下载并source官方git-completion.bash脚本，或通过bash-completion包加载对应路径的补全文件，才能启用对git checkout、git switch等命令的分支名上下文感知补全。
Git分支自动补全为什么默认不生效
Git自带的自动补全脚本不会自动加载，终端启动时根本不知道git checkout或git switch后面能接哪些分支名。这不是你的Shell配置问题，而是你没显式启用Git提供的补全逻辑——它藏在Git安装目录里，需要手动载入。
macOS上启用Git分支补全（Homebrew安装）
Homebrew装的Git，补全脚本通常在/usr/local/etc/bash_completion.d/git-completion.bash或/opt/homebrew/etc/bash_completion.d/git-completion.bash（Apple Silicon）。把它source进你的shell配置：
编辑~/.zshrc（macOS Catalina+默认用zsh）：
echo "source /opt/homebrew/etc/bash_completion.d/git-completion.bash" >> ~/.zshrc source ~/.zshrc
如果报错“command not found: __git_complete”，说明还缺bash-completion依赖，先运行：brew install bash-completion，再重试。
Linux（Bash/Zsh）和Windows WSL通用做法
不管什么发行版，最稳妥的方式是直接下载官方补全脚本：
本地项目发布到GitHub的完整工作流助手。自动执行：安全检查（.gitignore、排除敏感.env/凭据文件）、补齐开源文件（LICENSE、.gitignore）、git init/commit/branch、创建远程仓库、首次推送、可选打tag。支持git filter-repo历史敏感信息重写、force push、tag管理。Windows下走Credential Manager自动认证。触发词："发布到GitHub"、"上传到github"、"
- 运行
curl -o ~/.git-completion.bash https://raw.githubusercontent.com/git/git/master/contrib/completion/git-completion.bash - 在
~/.bashrc或~/.zshrc末尾加一行：source ~/.git-completion.bash - 重新加载：
source ~/.zshrc（或source ~/.bashrc）
注意：这个脚本对git checkout和git switch都生效，但git switch补全更干净（只列本地分支），而git checkout还会把远程分支、tag甚至文件路径混在一起补全，容易误选。
补全后切换分支的实际操作与常见陷阱
补全生效后，输入git switch空格，按TAB就能列出所有本地分支；输入前缀如git switch feat/再按TAB，会精准匹配feat/login、feat/api-v2这类分支。
容易踩的坑：
- 补全不触发？检查是否拼错了命令——
git swtich或git chckout这种typo会让补全彻底失效 - 远程分支不显示？正常。Git默认只补全本地分支。要补远程分支，得用
git checkout -b local-name origin/remote-branch，但此时补全只作用于origin/之后的部分 - Zsh用户如果用了oh-my-zsh，可能已自带git插件，但默认禁用补全——确认
~/.zshrc里的plugins=(git)存在，且没被注释掉
补全本身不改变Git行为，但它依赖git ls-remote和git for-each-ref实时查询，所以刚fetch完新分支，要等1–2秒再按TAB才看到——不是卡，是它在后台扫引用。
