EndBug/add-and-commit
GitHub: EndBug/add-and-commit
一个 GitHub Action，让用户能在工作流运行期间将代码或文件变更自动提交并推送回仓库，省去手写复杂 git 脚本的麻烦。
Stars: 1283 | Forks: 122
# 添加与提交 (Add & Commit)
你可以使用这个 GitHub Action 将工作流运行期间所做的更改直接提交到你的仓库中：例如，你可以用它来 lint 你的代码、更新文档、提交更新后的构建产物等等。
## 目录
- [输入参数](#inputs)
- [输出参数](#outputs)
- [常见问题](#faqs)
- [示例](#examples)
- [贡献者](#contributors-)
- [相关文章](#articles)
## 输入参数
在你的工作流中添加一个如下所示的步骤：
```
- uses: EndBug/add-and-commit@v10 # You can change this to use a specific version.
with:
# The arguments for the `git add` command (see the paragraph below for more info)
# Default: '.'
add: 'src'
# The name of the user that will be displayed as the author of the commit.
# Default: depends on the default_author input
author_name: Author Name
# The email of the user that will be displayed as the author of the commit.
# Default: depends on the default_author input
author_email: mail@example.com
# Additional arguments for the git commit command. The --message argument is already set by the message input.
# Default: ''
commit: --signoff
# The name of the custom committer you want to use, if different from the author of the commit.
# Default: the name of the author (set with either author_name or default_author)
committer_name: Committer Name
# The email of the custom committer you want to use, if different from the author of the commit.
# Default: the email of the author (set with either author_email or default_author)
committer_email: mail@example.com
# The local path to the directory where your repository is located. You should use actions/checkout first to set it up.
# Default: '.'
cwd: './path/to/the/repo'
# Determines the way the action fills missing author name and email. Three options are available:
# - github_actor -> UserName
# - user_info -> Your Display Name
# - github_actions -> github-actions
# Default: github_actor
default_author: github_actor
# Arguments for the git fetch command. If set to false, the action won't fetch the repo.
# For more info as to why fetching is usually recommended, please see the "Performance on large repos" FAQ.
# Default: --tags --force
fetch: false
# The message for the commit.
# Default: 'Commit from GitHub Actions (name of the workflow)'
message: 'Your commit message'
# If this input is set, the action will push the commit to a new branch with this name.
# Default: ''
new_branch: custom-new-branch
# The way the action should handle pathspec errors from the add and remove commands. Three options are available:
# - ignore -> errors will be logged but the step won't fail
# - exitImmediately -> the action will stop right away, and the step will fail
# - exitAtEnd -> the action will go on, every pathspec error will be logged at the end, the step will fail.
# Default: ignore
pathspec_error_handling: ignore
# Arguments for the git pull command. By default, the action does not pull.
# Default: ''
pull: '--rebase --autostash ...'
# Whether to push the commit and, if any, its tags to the repo. It can also be used to set the git push arguments (see the paragraph below for more info)
# Default: true
push: false
# The arguments for the `git rm` command (see the paragraph below for more info)
# Default: ''
remove: './dir/old_file.js'
# Arguments for the git tag command (the tag name always needs to be the first word not preceded by an hyphen)
# Default: ''
tag: 'v1.0.0 --force'
# Arguments for the git push --tags command (any additional argument will be added after --tags)
# Default: ''
tag_push: '--force'
```
### Git 参数
多个选项允许你提供希望该 action 使用的 `git` 参数。需要注意的是，这些参数**实际上并不会通过 CLI 命令来使用**，而是由一个名为 [`string-argv`](https://npm.im/string-argv) 的包进行解析，然后与 [`simple-git`](https://npm.im/simple-git) 一起使用。
这对你来说意味着什么呢？这意味着包含大量嵌套引号的字符串可能会被错误地解析，并且特定的参数声明方式可能不受这些库支持。如果你在参数字符串上遇到问题，可以通过为你的工作流运行[启用调试日志](https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging)或直接使用 `string-argv` 进行测试（[RunKit 演示](https://npm.runkit.com/string-argv)）来检查它们是否被正确解析：如果每个参数和选项都被正确解析，你将会看到一个数组，其中每个字符串都是一个选项或值。
### 添加文件
该 action 使用常规的 `git add` 命令来添加文件，因此你可以在 `add` 选项中放入各种类型的参数。例如，如果你想强制添加一个文件：`./path/to/file.txt --force`。
如果其中一个 git 命令没有匹配到任何文件，脚本也不会停止。例如：如果你的命令显示“fatal: pathspec 'yourFile' did not match any files”错误，该 action 会继续执行，除非通过 `pathspec_error_handling` 另行指定。
你也可以使用 JSON 或 YAML 数组（例如 `'["first", "second"]'`、`"['first', 'second']"`）来让该 action 运行多个 `git add` 命令：该 action 会记录你的输入是如何被解析的。请注意，由于 GitHub Actions 处理输入的方式，你的输入仍然需要是一个字符串：只需将你的数组写在字符串内，action 稍后会对其进行解析。
### 删除文件
如果需要删除预定义的文件列表，可以使用 `remove` 选项。它运行的是 `git rm` 命令，因此你可以向其传递各种类型的参数。与 [`add` 输入](#adding-files)类似，你也可以使用 JSON 或 YAML 数组来让该 action 运行多个 `git rm` 命令。
如果你希望自动检测并提交已删除的文件，你可以使用 [`--no-ignore-removal`/`-A`](https://git-scm.com/docs/git-add#Documentation/git-add.txt--A) git 参数。
### 推送
默认情况下，该 action 会运行以下命令：`git push origin ${new_branch input} --set-upstream`。你可以使用 `push` 输入来修改此行为，以下是你可以设置的值：
- `true`：这是默认值，它将像往常一样运行。
- `false`：这会阻止该 action 进行推送，不会运行任何 `git push` 命令。
- 任何其他字符串：
该 action 会将你的字符串用作 `git push` 命令的参数。请注意，除了你的参数之外，不会使用任何其他内容，最终命令将为 `git push ${push input}`（没有远程仓库、没有分支、也没有 `--set-upstream`，你必须自己包含它们）。
如果你想强制推送到你仓库的一个分支，这是一种用法：你需要将 `push` 输入设置为例如 `origin yourBranch --force`。
### 创建新分支
如果你希望该 action 在新分支中进行提交，可以使用 `new_branch` 输入。
请注意，如果该分支已存在，该 action 仍然会尝试向其推送，但推送可能会因为不是直接快进（non-straightforward）而被远程拒绝。
如果是这种情况，你需要确保在运行该 action 之前，已经检出（checkout）了你要提交的分支。
如果你**非常**确定要提交到该分支，你也可以通过将 `push` 输入设置为类似于 `origin yourBranchName --set-upstream --force` 的方式来进行强制推送。
如果你想“跨不同分支”提交文件，这里有两种方法可以做到：
1. 你可以在两个不同的目录中检出它们，生成你的文件，将它们移动到你的目标位置，然后使用 `cwd` 输入在目标目录中运行 `add-and-commit`。
2. 你可以像在你的本地机器上那样，使用 `git` 命令手动提交这些文件。根据场景的不同，有几种方法可以做到这一点。其中一种方法是 stash 你的更改，检出目标分支，然后 pop 这个 stash。然后你就可以像往常一样使用 `add-and-commit` action 了。请注意，这只是一个示例，可能并不适用于你，因为你的使用场景可能有所不同。
### 打标签
你可以使用 `tag` 选项来输入 `git tag` 命令的参数。为了让该 action 将标签名称与其余参数隔离开来，它应该是不带连字符的第一个词（例如 `-a tag-name -m "some other stuff"` 是没问题的）。
你也可以更改标签的 push 命令的参数：`tag_push` 输入中的每个参数都将被追加到 `git push --tags` 命令中。
有关如何解析 git 参数的更多信息，请参阅[“Git 参数”部分](#git-arguments)。
## 输出参数
该 action 提供以下输出：
- `committed`：该 action 是否创建了提交（`'true'` 或 `'false'`）
- `commit_long_sha`：刚刚创建的提交的完整 SHA
- `commit_sha`：刚刚创建的提交的 7 字符短 SHA
- `pushed`：该 action 是否推送到远程（`'true'` 或 `'false'`）
- `tagged`：该 action 是否创建了标签（`'true'` 或 `'false'`）
- `tag_pushed`：该 action 是否推送了标签（`'true'` 或 `'false'`）
有关如何使用输出的更多信息，请参阅[“上下文和表达式语法”](https://docs.github.com/en/free-pro-team@latest/actions/reference/context-and-expression-syntax-for-github-actions)。
## 常见问题
### 处理 PR
默认情况下，当你在 PR 上使用 `actions/checkout` 时，它将以 detached head（分离头指针）状态检出 head commit。
如果你想进行一些更改，你必须检出 head 仓库中该 PR 所属的分支。
你可以像这样进行设置：
```
- uses: actions/checkout@v4
with:
repository: ${{ github.event.pull_request.head.repo.full_name }}
ref: ${{ github.event.pull_request.head.ref }}
```
你可以在[这里](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#webhook-payload-example-32)找到 `pull_request` 事件 payload 的完整文档。
如果你打算仅在“内部” PR（即 head 和 base 在同一个仓库中）上运行此操作，那么你可以省略 `repository` 输入。
如果你打算将其用于来自其他 fork 的 PR，请记住你可能没有这些仓库的写入权限。
你可以尝试使用你的 PAT 来设置仓库，如本节[“关于 Token”段落](#about-tokens)中的说明。
请记住，这种“自定义检出”仅适用于 PR：如果你的工作流在多个事件（如 `push` 或 `workflow_dispatch`）上运行，你可以尝试让此步骤仅针对 `pull_request` 事件运行，而其他事件则触发常规的检出。
如果你希望这样做，可以使用 `step.if` 属性，[这里](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif)是相关文档。
### 关于 Token
在推送时，该 action 使用本地 git 仓库配置的 token：这意味着如果你想更改它，你需要在运行此 action 之前的步骤中进行。例如：如果你使用 [`actions/checkout`](https://github.com/actions/checkout/) 设置你的仓库，那么你必须在那里添加 token。
更改仓库配置使用的 token 会很有用，特别是当你希望由此 action 推送的提交触发 CI 检查时；无论如何，它都必须在此 action 之外进行设置。
该 action 会自动从 `github_token` 输入中获取 GitHub token：用户不应修改此输入，因为它不会影响提交，而仅仅是用于访问 GitHub API 以获取用户信息（以防他们为提交作者选择了该选项时使用）。
### 来自该 action 的提交没有触发 CI！
那是因为你正在使用内置的 [`GITHUB_TOKEN` secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) 来检出仓库：GitHub 检测到该 push 事件是由 CI 生成的提交触发的，为了避免无意中的检查循环，不会运行任何进一步的检查。
**如果你确定**希望在 CI 期间生成的提交能够触发其他工作流运行，你可以使用 [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) 来检出仓库：这将使得生成的提交就像是你自己进行的一样。
如果你正在使用 `actions/checkout`，请查看他们的[文档](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)以了解如何设置你的仓库 token。
### 关于 `actions/checkout`
你使用此 action 设置仓库时所用的 token，将决定 `add-and-commit` 会使用哪个 token。
一些用户报告说他们遇到了以下错误：
```
> fatal: could not read Username for 'https://github.com': No such device or address
```
如果你遇到此错误并且正在使用 `actions/checkout@v1`，请尝试升级到 `actions/checkout@v2`。如果你在升级后仍然遇到问题，欢迎提交 issue。Issue 参考：[#146](https://github.com/EndBug/add-and-commit/issues/146)
请注意，使用 `persist-credentials: false` 会导致同样的问题。
### 大型仓库的性能问题
默认情况下，该 action 会在开始处理之前先 fetch 仓库：这确保它能够看到已存在的引用（refs）。
当处理包含大量分支和标签的仓库时，fetch 可能会花费很长时间。如果 fetch 步骤耗时太长，你可以通过将 `fetch` 输入设置为 `false` 来跳过它：这将完全阻止该 action 运行 `git fetch`。
请注意，你必须相应地设置你的工作流：不 fetch 仓库可能会影响该 action 内部的分支和标签创建，因此建议仅在必要时才禁用它。Issue 参考：[#386](https://github.com/EndBug/add-and-commit/issues/386)
## 示例
### 不同的作者/提交者配置
如果你不想在 CI 提交中使用你的 GitHub 用户名，你可以通过将 `default_author` 输入的值设置为 `github_actions`，使其看起来像是由“GitHub Actions”做出的提交。
```
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: EndBug/add-and-commit@v10
with:
default_author: github_actions
```
你也可以使用 `committer_name` 和 `committer_email` 输入，使其看起来像是 GitHub Actions 作为提交者，这里有几个步骤示例：
```
- uses: EndBug/add-and-commit@v10
with:
message: Show GitHub Actions logo
committer_name: GitHub Actions
committer_email: actions@github.com
```
```
- uses: EndBug/add-and-commit@v10
with:
message: Show GitHub logo
committer_name: GitHub Actions
committer_email: 41898282+github-actions[bot]@users.noreply.github.com
```
### 数组输入
由于 GitHub action API 的限制，所有输入必须是字符串或布尔值。
该 action 在 `add` 和 `remove` 中支持数组，但它们必须被编码为带有 YAML 流序列（flow sequence）的字符串：
```
- uses: EndBug/add-and-commit@v10
with:
add: '["afile.txt", "anotherfile.txt"]'
```
（注意单引号）或者是 YAML 块序列（block sequence）：
```
- uses: EndBug/add-and-commit@v10
with:
add: |
- afile.txt
- anotherfile.txt
```
（注意使其成为多行字符串的管道符 `|`。）
### 自动化 Lint
你是否希望使用 ESLint 对位于 `src` 文件夹中的 JavaScript 文件进行 lint，以便无需你干预即可完成可修复的更改？你可以使用像这样的工作流：
```
name: Lint source code
on: push
jobs:
run:
name: Lint with ESLint
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
- name: Install dependencies
run: npm install
- name: Update source code
run: eslint "src/**" --fix
- name: Commit changes
uses: EndBug/add-and-commit@v10
with:
author_name: Your Name
author_email: mail@example.com
message: 'Your commit message'
add: '*.js'
```
### 在不同的目录中运行该 action
如果你需要在不位于 [`$GITHUB_WORKSPACE`](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables#default-environment-variables) 的仓库上运行该 action，你可以使用 `cwd` 选项：该 action 使用的是常规的 `cd` 命令，因此该路径应遵循 bash 标准。
```
name: Use a different repository directory
on: push
jobs:
run:
name: Add a text file
runs-on: ubuntu-latest
steps:
# If you need to, you can check out your repo to a different location
- uses: actions/checkout@v4
with:
path: './pathToRepo/'
# You can make whatever type of change to the repo...
- run: echo "123" > ./pathToRepo/file.txt
# ...and then use the action as you would normally do, but providing the path to the repo
- uses: EndBug/add-and-commit@v10
with:
message: 'Add the very useful text file'
add: '*.txt --force'
cwd: './pathToRepo/'
```
## 相关文章
- [Console by CodeSee #156](https://console.substack.com/p/console-156)
- [MichealHeap.com](https://michaelheap.com/add-and-commit-action/)
### 额外致谢
此 action 的灵感来源于由 [Stefan Zweifel](https://github.com/stefanzweifel) 开发的 [`git-auto-commit-action`](https://github.com/stefanzweifel/git-auto-commit-action)。
## 许可证
此 action 是在 MIT 许可证下分发的，查看[许可证](LICENSE)了解更多信息。
```
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: EndBug/add-and-commit@v10
with:
default_author: github_actions
```
你也可以使用 `committer_name` 和 `committer_email` 输入，使其看起来像是 GitHub Actions 作为提交者，这里有几个步骤示例：
```
- uses: EndBug/add-and-commit@v10
with:
message: Show GitHub Actions logo
committer_name: GitHub Actions
committer_email: actions@github.com
```
```
- uses: EndBug/add-and-commit@v10
with:
message: Show GitHub logo
committer_name: GitHub Actions
committer_email: 41898282+github-actions[bot]@users.noreply.github.com
```
### 数组输入
由于 GitHub action API 的限制，所有输入必须是字符串或布尔值。
该 action 在 `add` 和 `remove` 中支持数组，但它们必须被编码为带有 YAML 流序列（flow sequence）的字符串：
```
- uses: EndBug/add-and-commit@v10
with:
add: '["afile.txt", "anotherfile.txt"]'
```
（注意单引号）或者是 YAML 块序列（block sequence）：
```
- uses: EndBug/add-and-commit@v10
with:
add: |
- afile.txt
- anotherfile.txt
```
（注意使其成为多行字符串的管道符 `|`。）
### 自动化 Lint
你是否希望使用 ESLint 对位于 `src` 文件夹中的 JavaScript 文件进行 lint，以便无需你干预即可完成可修复的更改？你可以使用像这样的工作流：
```
name: Lint source code
on: push
jobs:
run:
name: Lint with ESLint
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
- name: Install dependencies
run: npm install
- name: Update source code
run: eslint "src/**" --fix
- name: Commit changes
uses: EndBug/add-and-commit@v10
with:
author_name: Your Name
author_email: mail@example.com
message: 'Your commit message'
add: '*.js'
```
### 在不同的目录中运行该 action
如果你需要在不位于 [`$GITHUB_WORKSPACE`](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables#default-environment-variables) 的仓库上运行该 action，你可以使用 `cwd` 选项：该 action 使用的是常规的 `cd` 命令，因此该路径应遵循 bash 标准。
```
name: Use a different repository directory
on: push
jobs:
run:
name: Add a text file
runs-on: ubuntu-latest
steps:
# If you need to, you can check out your repo to a different location
- uses: actions/checkout@v4
with:
path: './pathToRepo/'
# You can make whatever type of change to the repo...
- run: echo "123" > ./pathToRepo/file.txt
# ...and then use the action as you would normally do, but providing the path to the repo
- uses: EndBug/add-and-commit@v10
with:
message: 'Add the very useful text file'
add: '*.txt --force'
cwd: './pathToRepo/'
```
## 相关文章
- [Console by CodeSee #156](https://console.substack.com/p/console-156)
- [MichealHeap.com](https://michaelheap.com/add-and-commit-action/)
### 额外致谢
此 action 的灵感来源于由 [Stefan Zweifel](https://github.com/stefanzweifel) 开发的 [`git-auto-commit-action`](https://github.com/stefanzweifel/git-auto-commit-action)。
## 许可证
此 action 是在 MIT 许可证下分发的，查看[许可证](LICENSE)了解更多信息。标签：Git, GitHub Actions, MITM代理, SOC Prime, 开发工具, 网络调试, 自动化, 自动化攻击, 自动笔记