husky v8 原理分析

cover.png

husky v8 原理分析

Features

1. 零依赖和轻量级(6kB)
2. 由现代的新 Git 特性(core.hooksPath)驱动
3. 遵循 npm 和 yarn 关于自动安装的最佳实践
4. 多环境支持
   1. macOS, Linux and Windows
   2. Git GUIs
   3. Monorepos
   4. Custom directories(自定义目录)

Usage

1. 添加初始化脚本 package.json => scirpts.prepare

npm set-script prepare "husky install"
npm run prepare

prepare hook 执行时机有两个：

1. 安装依赖(yarn install)时
2. 发布包(yarn publish || yarn pack)时

2. 添加钩子

npx husky add .husky/pre-commit "npm test"
git add .husky/pre-commit

3. 创建一个提交，测试 pre-commit 钩子

git commit -m "test my commit"
# 每次提交将自动帮你运行 `npm test`

分析

install

初始化完成后，我们得到了一个 .husky 文件夹。

husky-dir.png

Husky 通过 install 命令告诉 Git 使用 .husky/ 作为 Git Hooks 目录。

// https://github.com/typicode/husky/blob/main/src/index.ts#L49
export function install(dir = ".husky"): void {
  // install 方法主要是用于初始化配置，设置Git Hooks目录，创建 .husky 文件夹，生成husky.sh文件
  // ...
  const { error } = git(["config", "core.hooksPath", dir]);
  if (error) {
    throw error;
  }
  // ...
}

add

Husky 通过 add 命令，生成生成 githook 文件。

// https://github.com/typicode/husky/blob/main/src/index.ts#L82

// 新增 or 更新githook文件，并添加cmd
export function add(file: string, cmd: string): void {
  // githook文件已存在，则进行 append
  if (fs.existsSync(file)) {
    fs.appendFileSync(file, `${cmd}\n`);
    l(`updated ${file}`);
  } else {
    // githook文件不存在，则调用 set 命令
    set(file, cmd);
  }
}

// 新增githook文件，并设置cmd
export function set(file: string, cmd: string): void {
  const dir = p.dirname(file);
  if (!fs.existsSync(dir)) {
    throw new Error(
      `can't create hook, ${dir} directory doesn't exist (try running husky install)`
    );
  }
  fs.writeFileSync(
    file,
    `#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
${cmd}
`,
    { mode: 0o0755 }
  );
  l(`created ${file}`);
}

Test pre-commit

当我们使用 Git 进行提交时会执行 .husky/pre-commit 文件。

我们打开 pre-commit 文件：

# pre-commit

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm test
# npx --no-install lint-staged

首先执行了 husky.sh 文件：

# husky.sh
#!/usr/bin/env sh
# 判断环境变量 husky_skip_init 长度是否为0，为0则执行下面的内容
if [ -z "$husky_skip_init" ]; then
  # 声明 debug 函数，用来打印错误日志
  debug() {
    # "$HUSKY_DEBUG" = "1" 时打印
    echo "husky (debug) - $1"
    if [ "$HUSKY_DEBUG" = "1" ]; then
      echo "husky (debug) - $1"
    fi
  }

  # 声明一个只读参数，内容为 basename + hookname
  readonly hook_name="$(basename -- "$0")"
  debug "starting $hook_name..."

  # 判断环境变量 "$HUSKY" = "0" 是否成立，是则直接退出 (exit 0)
  if [ "$HUSKY" = "0" ]; then
    debug "HUSKY env variable is set to 0, skipping hook"
    exit 0
  fi

  # 判断 ~/.huskyrc 是否存在，存在的话直接执行
  if [ -f ~/.huskyrc ]; then
    debug "sourcing ~/.huskyrc"
    . ~/.huskyrc
  fi

  # 声明只读变量 husky_skip_init 并设置值为 1
  # sh -e "$0" "$@" => $0: shell文件名 $@: 所有参数列表 $?: 最后运行的命令的结束代码 => 再用 sh 执行一边当前脚本
  readonly husky_skip_init=1
  export husky_skip_init
  # debug "log $0" => .husky/pre-commit
  # debug "log $@" =>
  # debug "log $?" => 0
  sh -e "$0" "$@"
  exitCode="$?"

  # 当用户脚本返回错误时($exitCode != 0)，打印当前的 hook 名称 + 退出码
  if [ $exitCode != 0 ]; then
    echo "husky - $hook_name hook exited with code $exitCode (error)"
  fi

  # 当退出码为 127 时，环境变量 PATH 配置有误，打印 command not found in PATH 提示
  if [ $exitCode = 127 ]; then
    echo "husky - command not found in PATH=$PATH"
  fi

  exit $exitCode
fi

可以看出 husky.sh 文件主要是完善报错机制，辅助后面的脚本运行的。

当我们进行 Git 提交的时候会运行我们配置的 .husky/pre-commit 钩子。

**至此，我们便可以很方便的在项目中添加/修改 githook，完成个性化配置。

结论

Husky 主要是帮助我们对 Git 命令进行封装，处理了多平台的差异，完善了报错机制，方便开发者使用。

彩蛋

1. No verify
   You can bypass pre-commit and commit-msg hooks using Git -n/--no-verify option:

    git commit -m "yolo!" --no-verify
   

   For Git commands that don't have a --no-verify option, you can use HUSKY environment variable:

    HUSKY=0 git push # yolo!
   

2. If you want to prevent husky from installing completely

    npm ci --omit=dev --ignore-scripts
    
    npm set-script prepare ""
    npm ci --omit=dev
   
    
    # .husky/pre-commit
    # ...
    [ -n "$CI" ] && exit 0
   

3. test hooks

        # .husky/pre-commit
        # ...
        exit 1 # Commit will be aborted

4. reset git hooks

        git config gitflow.path.hooks .git/hooks

5. nvm，node，rbenv，pyenv... PATH not found

        # ~/.huskyrc
        # This loads nvm.sh and sets the correct PATH before running hook
        export NVM_DIR="$HOME/.nvm"
        [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

其他

husky docs
github
Why husky has dropped conventional JS config
lint-staged github