git-extras 实战：git fresh-branch 命令详解——一条命令创建干净的空分支

git fresh-branch 是 Git 扩展集 git-extras 中用于创建一个全新的空本地分支的实用命令。与常规 git branch 不同，fresh-branch 创建的分支不包含任何历史提交，它直接以裸分支的形式接管仓库，并清空工作区中所有未跟踪内容，常用于从零开始搭建文档目录、实验性代码或需要干净初始状态的场景。读完本文，你将掌握该命令的完整用法、参数含义、底层实现原理（基于 symbolic-ref 与 git clean 的机制），以及使用它之前必须注意的数据安全边界。

本文以官方手册 man/git-fresh-branch.md 为主体，并结合仓库内真实实现脚本 bin/git-fresh-branch 进行源码级剖析，同时给出 Commands.md 与 History.md 中的官方佐证。

命令总览（SYNOPSIS）

手册中对命令的定义非常简洁：

git-fresh-branch <branchname>

• 功能描述（DESCRIPTION）：创建名为 <branchname> 的空本地分支（creates empty local branch named <branchname>）。
• 参数（OPTIONS）：<branchname> —— 要创建的分支名称，必填。

需要注意的是，在 git-extras 中所有命令都可通过 git <命令名> 的形式调用，因此实际使用形式为 git fresh-branch <branchname>，而不是直接执行 git-fresh-branch。

快速上手：一个完整示例

手册中的官方示例（同样出现在 Commands.md）：

$ git fresh-branch docs

执行后，当前仓库会被切换到名为 docs 的新分支上，且该分支：

1. 不包含任何提交记录（是一个"空"分支）；
2. 工作区中被清理为最干净的状态；
3. 原有的未跟踪文件与未提交修改会全部丢失（命令会先弹出确认提示）。

典型使用场景是：你想在一个已有仓库里开启一个与历史完全无关的"白纸"分支，例如为项目搭建独立的中文文档目录、录制演示环境，或者验证从零初始化后的构建流程。

源码实现剖析：命令到底做了什么

git fresh-branch 的实现非常精炼，完整源码位于 bin/git-fresh-branch，全文仅 24 行，逐段解读如下：

#!/usr/bin/env bash

branch=$1

test -z "$branch" && echo "branch required." 1>&2 && exit 1

第一段：参数校验。脚本把第一个命令行参数赋给 branch，随后用 test -z 检查其是否为空。若用户未提供分支名，则向标准错误输出 branch required. 并以退出码 1 终止——这也印证了手册中 <branchname> 为必填参数的约束。

changes=$(git status --porcelain)

clean()
{
    git symbolic-ref HEAD "refs/heads/$branch"
    rm .git/index
    git clean -fdx
}

第二段：核心清理函数 clean()。这是整个命令的关键，它依次执行三步操作：

1. git symbolic-ref HEAD "refs/heads/$branch"：把 HEAD 直接指向 refs/heads/$branch 这个引用，而不经过任何 commit 对象——这正是"空分支"的本质。新分支上没有任何父提交，是一个从虚无中诞生的分支头；
2. rm .git/index：删除暂存区索引文件，使"已暂存"状态全部失效；
3. git clean -fdx：强制删除所有未跟踪文件与目录（-f 强制、-d 含目录、-x 连被 .gitignore 忽略的文件也一并清除）。

if [ -n "$changes" ]; then
    read -rp "All untracked changes will be lost. Continue [y/N]? " res
    case $res in
        [Yy]* ) ;;
        * ) exit 0;;
    esac
fi

clean

第三段：安全检查。如果 git status --porcelain 检测到工作区有未提交内容（changes 非空），命令会先弹出交互式确认：All untracked changes will be lost. Continue [y/N]?。只有输入 y（或 Y 开头的内容）才继续执行 clean；输入其他任何内容（包括直接回车，即默认的 N）都会以退出码 0 安全退出。

从源码结构可以推断出的行为细节

• 命令内部使用 git status --porcelain 作为"是否有改动"的判定依据，属于机器可读的稳定输出格式，适合在脚本中做条件判断；
• rm .git/index 直接操作 .git 内部文件，意味着该命令只适用于 Git 仓库根目录且使用标准 .git 目录布局的场景；
• 确认提示的措辞是 "All untracked changes will be lost"，但实际上丢失范围更广：暂存内容（index）与所有未跟踪内容都会消失，已提交到当前分支的历史则不受影响（HEAD 引用被改指新分支后，旧分支引用仍保留）。

版本演进：这段确认逻辑是怎么来的

从 History.md 的变更记录可以看到该命令的安全机制并非一开始就有：

• 早期版本直接执行清理，不询问用户；
• 后来因 Issue: #142 提出"在销毁前检查改动并弹出确认"的需求，引入了交互确认逻辑；
• 再之后一次修复（Merge pull request #600，对应 History.md 中 "git-fresh-branch: fix handling of 'yes' response when there are changes"）修正了 yes 应答的处理方式——现在的 case $res in [Yy]* 写法同时接受 y 和 yes 等以 y 开头的输入。

这段历史提醒使用者：该命令本质上是一个高危清理命令，它的安全提示是社区后来逐步加固的结果。

安装与启用方式

git fresh-branch 随 git-extras 整体分发。仓库根目录的 Makefile 表明默认安装路径为：

• 可执行脚本安装到 $(PREFIX)/bin（默认 /usr/local/bin）；
• 手册页安装到 man/man1 目录；
• 支持 DESTDIR 与 PREFIX 覆盖，便于打包与自定义安装位置。

标准安装流程为：

make install

装好后即可直接使用 git fresh-branch <branchname>。此外，仓库的 etc/ 目录提供了 bash、zsh、fish 三种 shell 的补全脚本（etc/bash_completion.sh、etc/git-extras-completion.zsh、etc/git-extras.fish），配置后输入 git fresh- 即可触发命令补全。更详细的安装说明见 Installation.md。

与原生 git 命令的对比

git fresh-branch 很容易被误解为 git branch <name> 的别名，实际上二者行为差异巨大：

命令	分支是否含历史	是否清空工作区	交互确认
git branch docs	含（从当前 HEAD 复制）	否，仅创建引用	无
git checkout -b docs	含（基于当前 HEAD）	否，切换并保留工作区	无
git fresh-branch docs	不含（空分支）	是（index + 未跟踪全清）	有改动时弹确认

简言之，git fresh-branch 是"把仓库重置为一块干净画布并挂上全新分支名"的命令，适合需要隔离历史、重新开始的场景；而普通 git branch/git checkout -b 只是基于现有提交创建新指针。

使用注意事项与安全边界

基于源码与手册，使用该命令前请务必确认以下几点：

1. 数据会永久丢失：未提交的修改、暂存内容、所有未跟踪文件（含被 .gitignore 忽略的文件，因 clean -fdx 中的 -x）都会被清除，且无撤销手段；
2. 仅限本地分支：命令只操作本地 refs/heads/ 引用，不会创建远程分支；
3. 分支名必填：省略参数会立即报错 branch required. 并退出；
4. 不适用于非标准仓库布局：直接依赖 .git/index 文件路径；
5. 请先确认再回车：默认回答是 N（回车即取消），输入 y 才真正执行清理。

参考文档

• 本命令官方手册（man page）：man/git-fresh-branch.md、man/git-fresh-branch.1
• 命令索引总览：man/index.txt、man/git-extras.md
• 官方命令速查：Commands.md
• 完整实现源码：bin/git-fresh-branch
• 变更历史：History.md