[![构建和测试](https://github.com/actions/checkout/actions/workflows/test.yml/badge.svg)](https://github.com/actions/checkout/actions/workflows/test.yml)

# Checkout V4

此操作将您的仓库检出到 `$GITHUB_WORKSPACE` 下，以便您的工作流可以访问它。

默认情况下，仅获取触发工作流的 ref/SHA 的单个提交。设置 `fetch-depth: 0` 可以获取所有分支和标签的所有历史记录。请参考 [这里](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows) 了解不同事件中 `$GITHUB_SHA` 指向的提交。

认证令牌会持久化到本地 git 配置中。这使得您的脚本可以运行经过身份验证的 git 命令。该令牌会在作业后清理步骤中被移除。设置 `persist-credentials: false` 可以选择不保留。

当 Git 2.18 或更高版本不在您的 PATH 中时，将回退到 REST API 来下载文件。

# 新特性

请参考 [发布页面](https://github.com/actions/checkout/releases/latest) 获取最新的发布说明。

# 使用方法

<!-- start usage -->
```yaml
• uses: actions/checkout@v4

  with:
    # 仓库名称及所有者。例如，actions/checkout
    # 默认值: ${{ github.repository }}
    repository: ''

    # 要检出的分支、标签或 SHA。当检出触发工作流的仓库时，默认为该事件的引用或 SHA。
    # 否则，使用默认分支。
    ref: ''

    # 用于获取仓库的个人访问令牌 (PAT)。该 PAT 会配置到本地 git 配置中，使您的脚本可以运行经过身份验证的 git 命令。
    # 作业后步骤会移除该 PAT。
    #
    # 我们建议使用具有最低必要权限的服务账户。此外，在生成新的 PAT 时，请选择最低必要的范围。
    #
    # [了解有关创建和使用加密机密的更多信息](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    #
    # 默认值: ${{ github.token }}
    token: ''

    # 用于获取仓库的 SSH 密钥。该 SSH 密钥会配置到本地 git 配置中，使您的脚本可以运行经过身份验证的 git 命令。
    # 作业后步骤会移除该 SSH 密钥。
    #
    # 我们建议使用具有最低必要权限的服务账户。
    #
    # [了解有关创建和使用加密机密的更多信息](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    ssh-key: ''

    # 除用户和全局主机密钥数据库之外的已知主机。可以使用 `ssh-keyscan` 工具获取主机的公共 SSH 密钥。例如，`ssh-keyscan github.com`。
    # github.com 的公钥始终会隐式添加。
    ssh-known-hosts: ''

    # 是否执行严格的主机密钥检查。当为 true 时，会在 SSH 命令行中添加 `StrictHostKeyChecking=yes` 和 `CheckHostIP=no` 选项。
    # 使用 `ssh-known-hosts` 输入来配置其他主机。
    # 默认值: true
    ssh-strict: ''

    # 连接到远程 SSH 主机时使用的用户。默认值为 'git'。
    # 默认值: git
    ssh-user: ''

    # 是否将令牌或 SSH 密钥配置到本地 git 配置中
    # 默认值: true
    persist-credentials: ''

    # 在 $GITHUB_WORKSPACE 下放置仓库的相对路径
    path: ''

    # 是否在获取前执行 `git clean -ffdx && git reset --hard HEAD`
    # 默认值: true
    clean: ''

    # 针对给定过滤器进行部分克隆。如果设置了此选项，则会覆盖 sparse-checkout。
    # 默认值: null
    filter: ''

    # 对给定模式进行稀疏检出。每个模式应以换行符分隔。
    # 默认值: null
    sparse-checkout: ''

    # 指定在执行稀疏检出时是否使用 cone 模式。
    # 默认值: true
    sparse-checkout-cone-mode: ''

    # 要获取的提交数量。0 表示所有分支和标签的所有历史记录。
    # 默认值: 1
    fetch-depth: ''

    # 是否获取标签，即使 fetch-depth > 0。
    # 默认值: false
    fetch-tags: ''

    # 获取时是否显示进度状态输出。
    # 默认值: true
    show-progress: ''

    # 是否下载 Git-LFS 文件
    # 默认值: false
    lfs: ''

    # 是否检出子模块：`true` 表示检出子模块，`recursive` 表示递归检出子模块。
    #
    # 当未提供 `ssh-key` 输入时，以 `git@github.com:` 开头的 SSH URL 会被转换为 HTTPS。
    #
    # 默认值: false
    submodules: ''

    # 通过运行 `git config --global --add safe.directory <path>` 将仓库路径添加为 Git 全局配置的安全目录。
    # 默认值: true
    set-safe-directory: ''

    # 尝试克隆的 GitHub 实例的基本 URL，将使用环境默认值从工作流运行的同一实例获取，除非指定。示例 URL 包括 https://github.com 或 https://my-ghes-server.example.com
    github-server-url: ''
```
<!-- end usage -->

# 场景

- [仅获取根文件](#Fetch-only-the-root-files)
- [仅获取根文件和 `.github` 及 `src` 文件夹](#Fetch-only-the-root-files-and-github-and-src-folder)
- [仅获取单个文件](#Fetch-only-a-single-file)
- [获取所有标签和分支的所有历史记录](#Fetch-all-history-for-all-tags-and-branches)
- [检出不同分支](#Checkout-a-different-branch)
- [检出 HEAD^](#Checkout-HEAD)
- [并行检出多个仓库](#Checkout-multiple-repos-side-by-side)
- [嵌套检出多个仓库](#Checkout-multiple-repos-nested)
- [检出多个私有仓库](#Checkout-multiple-repos-private)
- [检出拉取请求的 HEAD 提交而不是合并提交](#Checkout-pull-request-HEAD-commit-instead-of-merge-commit)
- [在关闭事件上检出拉取请求](#Checkout-pull-request-on-closed-event)
- [使用内置令牌推送提交](#Push-a-commit-using-the-built-in-token)
- [使用内置令牌向拉取请求推送提交](#Push-a-commit-to-a-PR-using-the-built-in-token)

## 仅获取根文件

```yaml
• uses: actions/checkout@v4

  with:
    sparse-checkout: .
```

## 仅获取根文件和 `.github` 及 `src` 文件夹

```yaml
• uses: actions/checkout@v4

  with:
    sparse-checkout: |
      .github
      src
```

## 仅获取单个文件

```yaml
• uses: actions/checkout@v4

  with:
    sparse-checkout: |
      README.md
    sparse-checkout-cone-mode: false
```

## 获取所有标签和分支的所有历史记录

```yaml
• uses: actions/checkout@v4

  with:
    fetch-depth: 0
```

## 检出不同分支

```yaml
• uses: actions/checkout@v4

  with:
    ref: my-branch
```

## 检出 HEAD^

```yaml
• uses: actions/checkout@v4

  with:
    fetch-depth: 2
• run: git checkout HEAD^

```

## 并行检出多个仓库

```yaml
• name: Checkout

  uses: actions/checkout@v4
  with:
    path: main

• name: Checkout tools repo

  uses: actions/checkout@v4
  with:
    repository: my-org/my-tools
    path: my-tools
```
> - 如果您的次要仓库是私有或内部的，您需要添加 [Checkout multiple repos (private)](#Checkout-multiple-repos-private) 中提到的选项

## 嵌套检出多个仓库

```yaml
• name: Checkout

  uses: actions/checkout@v4

• name: Checkout tools repo

  uses: actions/checkout@v4
  with:
    repository: my-org/my-tools
    path: my-tools
```
> - 如果您的次要仓库是私有或内部的，您需要添加 [Checkout multiple repos (private)](#Checkout-multiple-repos-private) 中提到的选项

## 检出多个私有仓库

```yaml
• name: Checkout

  uses: actions/checkout@v4
  with:
    path: main

• name: Checkout private tools

  uses: actions/checkout@v4
  with:
    repository: my-org/my-private-tools
    token: ${{ secrets.GH_PAT }} # `GH_PAT` 是包含您 PAT 的机密
    path: my-tools
```
> - `${{ github.token }}` 的范围限定在当前仓库，因此如果您想检出其他私有仓库，则需要提供您自己的 [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)。

## 检出拉取请求的 HEAD 提交而不是合并提交

```yaml
• uses: actions/checkout@v4

  with:
    ref: ${{ github.event.pull_request.head.sha }}
```

## 在关闭事件上检出拉取请求

```yaml
on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, closed]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      ◦ uses: actions/checkout@v4

```

## 使用内置令牌推送提交

```yaml
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      ◦ uses: actions/checkout@v4

      ◦ run: |

          date > generated.txt
          # 注意：以下账户信息在 GHES 上不起作用
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "generated"
          git push
```
*注意:* 用户邮箱为 `{user.id}+{user.login}@users.noreply.github.com`。请参阅用户 API: https://api.github.com/users/github-actions%5Bbot%5D

## 使用内置令牌向拉取请求推送提交

在拉取请求触发器中，需要指定 `ref`，因为 GitHub Actions 默认以分离的 HEAD 模式检出，这意味着它不会默认检出您的分支。

```yaml
on: pull_request
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      ◦ uses: actions/checkout@v4

        with:
          ref: ${{ github.head_ref }}
      ◦ run: |

          date > generated.txt
          # 注意：以下账户信息在 GHES 上不起作用
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "generated"
          git push
```
*注意:* 用户邮箱为 `{user.id}+{user.login}@users.noreply.github.com`。请参阅用户 API: https://api.github.com/users/github-actions%5Bbot%5D

# 推荐权限

在 GitHub Actions 工作流中使用 `checkout` 操作时，建议设置以下 `GITHUB_TOKEN` 权限以确保正常功能，除非通过 `token` 或 `ssh-key` 输入提供了替代身份验证：

```yaml
permissions:
  contents: read
```

# 许可证

此项目中的脚本和文档均根据 [MIT 许可证](LICENSE) 发布