使用 AWS CLI 的 merge-branches-by-three-way 命令在 CodeCommit 中进行三路合并-平芜编程栈

使用 AWS CLI 的 merge-branches-by-three-way 命令在 CodeCommit 中进行三路合并

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

aws codecommit merge-branches-by-three-way是 AWS Command Line Interface（AWS CLI）中用于在 AWS CodeCommit 仓库内以三路合并（three-way merge）策略合并两个分支的命令。本文基于当前仓库中的示例文档与 CodeCommit 服务模型，完整讲解该命令的用法、全部参数含义、冲突处理机制与输出解析，帮助你直接在命令行中完成分支合并、冲突自动解决与提交记录写入。

命令概览与核心用途

在 CodeCommit 中，当两个分支从同一基点分叉后各自发生提交时，merge-branches-by-three-way命令会在仓库内直接创建一个合并提交，将源分支（source）的变更合入目标分支（destination），而不需要经过拉取请求（pull request）流程。三路合并算法会以两个分支的共同祖先提交（base commit）为基准，将 source 与 destination 各自的变更进行比对合并，因此可以保留两边的提交历史。

命令对应的服务端 API 为MergeBranchesByThreeWay，其官方定义为 "Merges two specified branches using the three-way merge strategy"，定义于 service-2.json。在同一份服务模型中，CodeCommit 还提供了另外两种合并策略：

MergeBranchesByFastForward（fast-forward 快进合并）
MergeBranchesBySquash（squash 压缩合并）

三者同属 CodeCommit 的merge-branches-*命令族，对应的示例文档分别位于 merge-branches-by-fast-forward.rst 与 merge-branches-by-squash.rst。若不确定某个仓库当前支持哪些合并策略，可先运行aws codecommit get-merge-options查询（见 get-merge-options.rst），其输出中的mergeOptions字段会列出如FAST_FORWARD_MERGE、SQUASH_MERGE、THREE_WAY_MERGE等可用选项。

基本用法示例

以下命令将源分支main的变更合并到目标分支bugfix-bug1234，并为生成的合并提交指定作者、邮箱与提交信息。该示例出自仓库中的 merge-branches-by-three-way.rst：

aws codecommit merge-branches-by-three-way \ --source-commit-specifier main \ --destination-commit-specifier bugfix-bug1234 \ --author-name "Jorge Souza" --email "jorge_souza@example.com" \ --commit-message "Merging changes from main to bugfix branch before additional testing." \ --repository-name MyDemoRepo

输出示例：

{ "commitId": "4f178133EXAMPLE", "treeId": "389765daEXAMPLE" }

其中commitId是合并提交的提交 ID（落在 destination 或 target 分支上），treeId是合并结果的树对象 ID，二者均由服务端在完成合并后返回，可据此在仓库中定位合并提交。

参数详解

根据服务模型 MergeBranchesByThreeWayInput 的定义，该命令支持以下参数（前三个为必填项）：

参数	必填	类型	说明
`--repository-name`	是	字符串	执行合并的仓库名称。
`--source-commit-specifier`	是	字符串	用于标识源提交的分支、标签、HEAD 或其他完全限定引用（例如分支名或完整提交 ID）。
`--destination-commit-specifier`	是	字符串	用于标识目标提交的分支、标签、HEAD 或其他完全限定引用（例如分支名或完整提交 ID）。
`--target-branch`	否	字符串	合并结果实际应用到的分支。不指定时，合并提交落在 destination 分支上。
`--conflict-detail-level`	否	枚举	冲突检测粒度，取值为`FILE_LEVEL`（默认）或`LINE_LEVEL`。文件级冲突指同一文件在两分支中均有改动；行级冲突指同一文件同一行在两分支中均有改动。
`--conflict-resolution-strategy`	否	枚举	冲突解决策略，取值为`NONE`（默认）、`ACCEPT_SOURCE`、`ACCEPT_DESTINATION`、`AUTOMERGE`，详见下文。
`--author-name`	否	字符串	创建提交的作者姓名，同时作为该提交的 author 与 committer 信息。
`--email`	否	字符串	执行合并人员的邮箱地址，写入合并提交的提交信息中。
`--commit-message`	否	字符串	合并提交的提交信息。
`--keep-empty-folders`	否	布尔	若合并包含删除操作且删除后文件夹为空，是否保留该空文件夹。设为`true`时为空文件夹创建`.gitkeep`文件，默认为`false`。
`--conflict-resolution`	否	结构体	当`--conflict-resolution-strategy`为`AUTOMERGE`时，指定合并冲突解决的输入列表（JSON 语法），详见下文。

注：CLI 参数中的连字符命名与 API 字段的驼峰命名（如conflictDetailLevel、conflictResolutionStrategy）一一对应。枚举取值见服务模型中的 ConflictDetailLevelTypeEnum 与 ConflictResolutionStrategyTypeEnum。

冲突检测与解决策略

三路合并的核心风险在于两分支对同一区域产生冲突。服务模型明确了两级冲突检测粒度：

FILE_LEVEL（默认）：只要同一文件在两个分支中都有差异，即视为不可自动合并（not-mergeable）。
LINE_LEVEL：只有同一文件在两个分支中的同一行都存在差异时，才判定为不可自动合并。

--conflict-resolution-strategy决定冲突发生时如何处理，四种取值对应四种行为：

取值	行为
`NONE`（默认）	不自动解决任何冲突；存在冲突时必须先人工处理，否则合并操作不会成功。
`ACCEPT_SOURCE`	冲突发生时直接采用源分支（`--source-commit-specifier`）一侧的内容。
`ACCEPT_DESTINATION`	冲突发生时直接采用目标分支（`--destination-commit-specifier`）一侧的内容。
`AUTOMERGE`	尝试自动合并同一文件的两个版本；可配合`--conflict-resolution`提供额外的逐文件解决输入。

使用 AUTOMERGE 与 conflict-resolution 的进阶示例

当选择AUTOMERGE时，可通过--conflict-resolution指定逐文件的冲突解决输入。根据服务模型 ConflictResolution 的定义，该结构体支持三类成员：

replaceContents：替换指定文件的内容；
deleteFiles：删除指定文件；
setFileModes：设置指定文件的文件模式。

参考示例（使用 JSON 语法传入）：

aws codecommit merge-branches-by-three-way \ --repository-name MyDemoRepo \ --source-commit-specifier feature-xyz \ --destination-commit-specifier main \ --conflict-resolution-strategy AUTOMERGE \ --conflict-resolution '{ "replaceContents": [ { "filePath": "README.md", "replacementType": "CONTENT", "content": "IyBOZXcgY29udGVudA==" } ], "deleteFiles": [ { "filePath": "obsolete-config.txt" } ], "setFileModes": [ { "filePath": "deploy.sh", "fileMode": "EXECUTABLE" } ] }' \ --author-name "Maria Garcia" \ --email "maria_garcia@example.com" \ --commit-message "Automerge feature branch into main"

提示：replaceContents中content字段要求 base-64 编码的文件内容（服务端模型中以blob类型传输，CLI 层面对应 base64 编码字符串），可用base64 README.md之类的方式生成。replacementType可取值CONTENT或FILE_MODE。若不指定--conflict-resolution，AUTOMERGE 会尽力自动合并，无法自动解决的冲突仍会以失败告终。

合并结果输出解析

命令成功执行后返回一个 JSON 对象，包含两个字段（见 MergeBranchesByThreeWayOutput）：

commitId：合并提交在目标（或--target-branch指定）分支上的提交 ID；
treeId：合并结果对应的树对象 ID。

合并提交创建成功后，可用仓库中的其他命令进一步验证结果：

aws codecommit get-commit查看合并提交详情（示例见 get-commit.rst）；
aws codecommit get-branch查看目标分支的最新提交是否已更新为合并提交（示例见 get-branch.rst）；
aws codecommit get-differences对比合并前后两个提交之间的差异（示例见 get-differences.rst）。

常见错误场景与排错

服务模型在MergeBranchesByThreeWay操作上声明了大量错误类型（service-2.json），以下是实际使用中容易遇到的几类：

仓库或引用不存在：RepositoryNameRequiredException、InvalidRepositoryNameException、RepositoryDoesNotExistException、CommitRequiredException、CommitDoesNotExistException、InvalidCommitException，通常由仓库名拼写错误、提交 ID 无效或引用指向不存在的提交导致。
分支相关：BranchNameRequiredException、InvalidBranchNameException、BranchDoesNotExistException、InvalidTargetBranchException、BranchNameIsTagNameException，说明传入的分支名缺失、非法，或把标签名误当成了分支名。
合并失败：TipsDivergenceExceededException（两分支提交历史差异过大，超出合并比较上限）、ManualMergeRequiredException（存在冲突且--conflict-resolution-strategy为NONE，需要先人工解决冲突）。
并发与加密：ConcurrentReferenceUpdateException（同一引用被并发更新，请重试）、EncryptionIntegrityChecksFailedException及EncryptionKey*系列异常（KMS 加密相关故障，检查仓库加密密钥的访问权限与可用性）。

适用前提与注意事项

使用该命令需要先完成 AWS CLI 的安装与凭证配置；本仓库根目录的 README.rst 与 CONTRIBUTING.md 提供了构建与开发环境相关说明，scripts/install可用于本地安装。
执行合并的 IAM 身份需要对目标仓库具备codecommit:GitPull与codecommit:GitPush（或等价的仓库级权限）以及创建合并提交所需的权限。
三路合并会保留 source 与 destination 的完整提交历史并生成一个新的合并提交，与 fast-forward（线性推进）和 squash（压缩为单次提交）在提交历史上行为不同，选择策略前请先确认团队的分支与历史管理约定。
若分支从未分叉（destination 包含 source 的全部历史），服务端可能会提示改用 fast-forward 等更合适的策略；可先通过get-merge-options查询可用选项，再决定调用哪一个merge-branches-*命令。