git-extras 之 git create-branch：一条命令完成本地分支创建与远程跟踪分支设置

本篇技术指南围绕 git-extras 项目中 man/git-create-branch.md 所定义的 git create-branch 命令展开，讲解其全部命令行参数、远程跟踪分支的设置方式、基于 git config 的默认远程偏好配置，并结合仓库内 bin/git-create-branch 源码逐一还原其底层执行流程。读完本文，你将能熟练地用一条命令在本地创建分支、同步推送到指定远程并建立 --track 跟踪关系，同时理解 -r/--remote、--from 与偏好配置三者之间的优先级关系。

命令概览与适用场景

git create-branch 是 git-extras 提供的分支管理增强命令，核心能力是：创建名为 <branchname> 的本地分支，并在需要时顺带设置远程跟踪分支。原生 Git 完成同样动作通常需要串联 git checkout -b、git push -u origin 两到三步，而本命令把整个过程收敛为一条指令，尤其适合以下场景：

• 日常功能开发时快速从当前分支拉出新分支；
• 需要同时把新分支推送到 origin、upstream 或其他自定义远程，并让本地分支跟踪该远程分支；
• 从指定 start_point（如某个 tag、commit 或远程分支）创建分支并同步推送。

该命令的官方语法（见 man/git-create-branch.md）为：

git-create-branch [-r|--remote [remote_name]] <branchname>

其中 branchname 为必填参数，若缺失，脚本会直接报错退出（见下文"参数校验"一节）。

参数详解：-r/--remote、--from 与 branchname

-r | --remote [remote_name]

设置远程跟踪分支。remote_name 指定远程仓库名称；若省略 remote_name，则默认使用 origin。

# 在默认远程 origin 上创建远程跟踪分支
$ git create-branch -r integration

从 bin/git-create-branch 的源码可见其解析逻辑：

-r|--remote)
    if [[ -n $2 ]]
    then
        REMOTE=$2
        shift
    else
        REMOTE=origin
    fi
    ;;

即：-r 后紧跟参数时取该参数为远程名，否则回退为 origin。此外源码专门处理了"歧义 -r 参数"的情况——当用户写成 git create-branch -r integration 这种省略远程名、直接把分支名跟在 -r 之后的形式时，解析器会把 integration 先当作 REMOTE，随后通过如下兜底逻辑纠正（bin/git-create-branch）：

if [[ -z $BRANCH ]] && [[ -n $REMOTE ]]
then
    BRANCH=$REMOTE
    REMOTE=origin
fi

也就是说 git create-branch -r integration 等价于 git create-branch -r origin integration，这与 Commands.md 中 git create-branch 一节给出的官方示例行为完全一致。

--from [start_point]

指定分支创建的起点（start point）。若省略，默认以当前分支为起点。用法示例：

# 以某个 tag 为起点创建分支
$ git create-branch -r upstream hotfix --from v1.2.0

源码中的解析片段（bin/git-create-branch）：

--from)
    if [[ -n $2 ]]; then
        START_POINT=$2
        shift
    fi
    ;;

<branchname>

要创建的分支名称，必填。源码在入口处即做了校验（bin/git-create-branch）：

test $# -eq 0 && echo "branch argument required." 1>&2 && exit 1

参数解析结束后还会二次校验（bin/git-create-branch）：若 BRANCH 仍为空，同样输出 branch argument required. 并退出码 1。

偏好配置：用 git config 固化默认远程

如果希望"不写 -r 也能自动推送远程分支"，可以通过 git config 保存默认远程偏好。配置键为 git-extras.create-branch.remote，值即默认远程名：

$ git config git-extras.create-branch.remote lucinda

设置后，未显式指定 -r|--remote 时，命令将自动使用该偏好值作为远程。命令行选项 -r|--remote 的优先级高于该偏好配置，即显式传参时会覆盖配置。

源码中的优先级实现（bin/git-create-branch）非常直观——偏好值只作为最低优先级的兜底：

# preference takes lowest priority; look for remote from prefs first
REMOTE_PREF=$(git config git-extras.create-branch.remote)
if [ -n "$REMOTE_PREF" ]; then
    REMOTE=$REMOTE_PREF
fi

随后 -r/--remote 解析逻辑会覆盖 REMOTE 变量。因此三种写法的优先级从低到高为：git config 偏好 < -r（默认 origin）< -r remote_name（显式远程名）。

完整示例：从零到远程跟踪分支

未设置偏好配置时

# 仅创建本地分支 'integration'（基于当前分支）
$ git create-branch integration

# 创建本地分支，并在默认远程 'origin' 上建立远程跟踪分支
$ git create-branch -r integration

# 创建本地分支，并在 'upstream' 远程上建立远程跟踪分支
$ git create-branch -r upstream integration

已设置 git-extras.create-branch.remote=lucinda 时

# 创建本地分支，并在偏好远程 'lucinda' 上建立远程跟踪分支
$ git create-branch integration

# 用显式 `-r` 覆盖偏好，在默认 'origin' 上建立远程跟踪分支
$ git create-branch -r integration

# 用显式 `-r` 覆盖偏好，在指定 'upstream' 上建立远程跟踪分支
$ git create-branch -r upstream integration

指定起点

# 以 start_point 为起点创建本地分支并推送远程
$ git create-branch --from <start_point> <branchname>
# 例如：以远程 develop 为起点，同时推送到 origin
$ git create-branch -r origin feature/x --from origin/develop

源码级原理：底层到底执行了哪些 Git 命令

git create-branch 的全部行为都在 bin/git-create-branch 这一个 bash 脚本中实现，下面按两条执行路径拆解。

路径一：带远程（REMOTE 非空）

脚本先借助 helper 工具库 helper/git-extra-utility 中定义的 git_extra_mktemp()（内部基于 mktemp -t）创建临时文件，再执行连通性探测：

git ls-remote --exit-code "$REMOTE" 1>/dev/null 2>"$stderr"

• 若远程可达（退出码为 0），继续创建流程；
• 若不可达，则打印 Error connecting to remote '$REMOTE': ... 并以远程探测的退出码结束（bin/git-create-branch）。

远程可达时，是否指定 --from 会走两条不同的子流程（bin/git-create-branch）：

指定 --from <start_point>：

git fetch "$REMOTE"
git checkout --track -b "$BRANCH" "$START_POINT"
git push "$REMOTE" "HEAD:refs/heads/$BRANCH"

未指定 --from（默认以当前分支为起点）：

git push "$REMOTE" "HEAD:refs/heads/$BRANCH"
git fetch "$REMOTE"
git checkout --track -b "$BRANCH" "$REMOTE/$BRANCH"

注意两条子流程的顺序差异：未指定 --from 时先 push 再 fetch，然后基于 REMOTE/BRANCH 执行 checkout --track -b，从而让本地分支自动跟踪刚推送的远程分支；指定 --from 时则先 fetch，再基于 START_POINT 建立跟踪分支，最后 push 同步到远程。最终整个脚本以最后一条命令的退出码作为命令整体退出码。

路径二：仅本地（REMOTE 为空）

当既没有 -r/--remote 参数，也没有配置偏好时，行为退化为纯本地操作（bin/git-create-branch）：

if [[ -n $START_POINT ]]
then
    git checkout -b "$BRANCH" "$START_POINT"
else
    git checkout -b "$BRANCH"
fi

等价于原生 git checkout -b <branchname> [<start_point>]，不会触碰任何远程。

行为变更记录与版本注意事项

man/git-create-branch.md 的 NOTES 一节明确记录了两条重要的行为变更，使用旧版本时需特别注意：

• 自 4.4.0 起，默认行为已改变：git create-branch 不再自动设置远程跟踪分支，除非显式指定 -r|--remote 选项。也就是说，如果沿用旧版习惯"只写分支名就默认推送远程"，在 4.4.0 及之后会得到纯本地分支。
• 自 4.8.0-dev 起，remote 选项可通过 git config 偏好进行设置，即上文所述的 git-extras.create-branch.remote 配置键，详见偏好配置一节。

上述行为均与当前仓库源码实现一致：只有 REMOTE 变量非空时才会执行推送与跟踪逻辑，而 REMOTE 仅来自 -r/--remote 参数或偏好配置。

安装与快速上手

git create-branch 随 git-extras 一起安装，安装方式参见仓库根目录的 Installation.md（Linux/macOS 可通过 make install，Windows 可使用 install.cmd）。安装后命令以 git create-branch 形式直接可用，其手册页同时提供了 roff 格式（man/git-create-branch.1）与 HTML 格式（man/git-create-branch.html），而 Commands.md 的命令速查清单也收录了该命令的三种典型用法，可作为日常速查参考。

总结

git create-branch 用极其克制的参数设计覆盖了分支创建的核心诉求：默认纯本地、-r 一键远程跟踪、--from 自定义起点、git config 固化偏好。其实现完全由 bin/git-create-branch 单一 bash 脚本完成，逻辑清晰、优先级明确（偏好 < -r < -r 远程名），且针对"省略远程名"的歧义写法做了兼容处理。对于频繁切换多远程协作的开发者，这条命令能显著减少重复的 push + track 操作步骤，是 git-extras 工具箱中性价比极高的一员。