Plastic SCM - GitServer 指南

每个 Plastic SCM 服务器现在都可以使用 Git 协议（支持 git 和 http）为存储库提供服务。

这意味着每个 Git 客户端都可以直接推送/拉取到 Plastic SCM 服务器。

Git 生态系统中的任何工具现在都可以使用原生 Git 功能直接连接到 Plastic SCM。Plastic 上的团队现在可以受益于针对 Git 开发的所有开发运维、CI 和项目管理集成功能。

GitServer 是 GitSync 的服务器端对应物（允许每个 Plastic SCM 客户端推送/拉取到 Git 服务器）并闭合 Git 互操作性循环。

GitServer 可用于广泛的场景，但其主要目标是充当任何 Git 软件连接到 Plastic 的“通用连接器”。

任何与 Git 兼容的 Git 客户端都可以将更改推送/拉取到 GitServer，从而支持许多不同的使用场景：

1. 将与 Git 兼容的软件连接到 Plastic SCM - 开发者可以使用 GitServer 将 FishEye、CodeCollaborator、ReviewBoard、TeamCity 和许多其他软件连接到使用 Git 集成的 Plastic SCM。
2. 使用 Plastic SCM 作为中央 Git 服务器 - 开发者可以从 Git 推送/拉取到启用了 GitServer 的 Plastic SCM 服务器。
3. 用作异构团队的中央存储库 - 多个团队现在可以在 Git 和 Plastic SCM 上进行协作。这种情况可能是逐步迁移到 Plastic SCM 的结果（因此一些团队仍在使用 Git），或者只是作为某种策略的一部分（即不同的团队将选择 Plastic 和 Git 作为他们的版本控制选项，并且仍然使用 Plastic 作为中央集合点进行协作）。

在 Plastic SCM 服务器上启用 GitServer 非常简单：

1. 在服务器的二进制文件目录（plasticd.exe 所在的位置）中创建一个空的 gitserver.conf 文件。
2. 然后，重新启动 Plastic SCM 服务器。它将开始侦听 Git 协议默认端口：9418。

现在可以从 Git 推送/拉取到 Plastic SCM，如下所示：

此命令会将您的 Git 存储库推送到名为 default 的 Plastic 存储库。

gitserver.conf 是用于控制 GitServer 配置的文件，具有以下格式，其中每一行都是可选的：

# port configuration
tcp.port=9418
http.port=80

# mapping storage - the mappings between git and plastic objects
# the default path is automatically generated by the server
storage.baseDirectory=e:\gitserver\mappings

# mapping interval - how often GitServer looks for new changes
# on the Plastic side to make them available to git
# By default, it is 5 minutes (300 seconds)
mapping.interval=300

# repositories to be exported. By default, all repositories 
# will be available on GitServer unless a list is specified here
export.repo=code
export.repo=quake
export.repo=robotcode

Windows 对 HTTP 施加了安全限制，因此必须采取特殊措施以允许 GitServer 使用给定的 HTTP 端口。此设置只影响不在特权帐户下运行的进程。因此，将 Plastic SCM 作为 Windows 服务运行不需要执行任何特殊操作来启用 http。

如果您的 Plastic SCM 服务器在非管理员模式下运行（不是作为默认的 Windows 服务），那么您需要做的就是向运行该进程的特定用户授予权限。这一操作可通过以下命令完成：

GitServer 可以使用 HTTP 基本身份验证来保护 Git 客户端。

这意味着，如果启用此身份验证，Git 客户端会在连接到 GitServer 时要求您输入用户名和密码。

要配置 HTTP 身份验证，只需要在 gitserver.conf 文件中添加以下条目：

# http authentication
http.basicauth=true

当然，GitServer 必须配置为侦听 HTTP 协议：

# http authentication
http.port=8080
http.basicauth=true

Plastic SCM 服务器可以像 Git 服务器（由 Git 客户端透明地访问）一样运行。

进入 GitServer 的更改可能来自不同的来源：

• 来自 Git，通过 git push 操作。一旦 Git 命令完成，Plastic SCM 和 Git 客户端便可立即使用更改。
• 来自 Plastic，通过 check-in 或 replica 操作。Git 客户端不能立即使用这些更改。后台线程每 mapping.interval 秒检查一次“已导出”到 Git 的存储库中是否有新的 Plastic 更改。如果发现更改，便会开始计算映射，一旦完成，新的更改将对 Git 可见。

Plastic SCM 支持部分复制，这是一项无法映射到 Git 的功能。虽然这项功能在纯 Plastic 环境中非常有用，但在混合的 Git/Plastic 场景中可能是一个问题。

考虑以下场景，其中 John 首先将 main 推送到 main 存储库（也就是使用 GitServer 同步到 Git 的那个存储库），但不推送合并到 main 的分支 main/task001：

当 GitServer 代码开始“索引”新的变更集（在本例中为编号 10）以使它们可用于 Git 时，它只会看到变更集 10。新的变更集将用作 Git 提交，并可能由 Git 客户端拉取。

假设后来 John 记得将 main/task001 推送到 central。新分支 task001 始终不会对 Git 可见，因为变更集 10 已被导出，而重新计算 task001 将更改 10 的“sha”，因此会中断与先前已经拉取 10 的远程 Git 复本之间的同步。

应了解此限制并确保仅当正确的分支位于要同步到 Git 的 Plastic 存储库中时才计算 Git 映射，这一点非常重要。

查看以下场景，其中的中央存储库刚使用部分复制功能接收到 task002。task002 的父级在主存储库上不可用，因此如果计算以 Git 为目标的映射，则会忽略相应的分支：

即使稍后推送 task001，如果 task002 的映射是在将 task001 推送到中央存储库之前计算的，那么它对 Git 存储库仍然不可见。

请记住，Git 强烈不建议对已经远程推送的存储库进行“变基”和“改写历史记录”。此处描述的场景也是如此；在这些场景中，考虑新的历史记录意味着在 Git 端改写历史记录，因此会破坏远程 Git 存储库。

假设现在前面示例的一个变体中有未链接的分支作为完全复制的合并：

在本示例中，不能将 task002 设为对 Git 可见，因为它是一个未链接的分支。这意味着新的变更集 10 也不会对 Git 可见，因为这意味着可能会破坏历史记录。一旦分支 task002 的父分支被复制，GitServer 将能够链接整个历史记录并使变更集 10 对 Git 客户端可见。

即使某些变更集不满足条件，也可以强制 GitServer 使一个分支对 Git 可用。

在前面的场景中，即使 task002 没有完全链接并且绝不会映射到 Git，也可以强制 GitServer“映射”变更集 10。

只需将 branch.toForceMap 条目添加到 gitserver.conf 中，如下所示：

# branches which changesets are made visible
# although they have unlinked merge sources
branch.toForceMap=/main

带有未解析的 Xlink 的变更集也会被 GitServer 忽略，因此不会被 Git 客户端看到。

考虑以下场景，其中的分支 main@root 包含 main@xlink 的 Xlink。在 root 的变更集 15 中，Xlink 指向 Xlink 的变更集 4，但尚未复制该变更集：

这意味着变更集 15 将被忽略，并且在复制通过 Xlink 链接到的变更集之前对 Git 客户端不可见。

可将 GitServer 配置为跳过缺失的 Xlink，允许即使某些内容缺失也可与 Git 同步。

只需将 unresolvedxlink.skip=true 添加到 gitserver.conf 中，如下所示：

# skip the xlink entries that cannot be resolved
unresolvedxlink.skip=true

Git 子模块转换为 Plastic SCM Xlink。我们可以说 Xlink 就像演化的子模块，旨在减轻开发者的工作量。

将一些 Git 更改/存储库推送到 GitServer 时，如果存在指向 Git 存储库的子模块，则操作可能会失败，但 GitServer 不知道如何解决：

在本示例中，有一个子模块指向名为 mduem 的存储库，GitServer 无法识别它是有效的 Plastic SCM 存储库。

为了解决这个问题，必须在 Plastic 中创建一个名为 mduem 的存储库，并将子模块存储库推送到 Gitserver：

在本示例中，Git 子模块定义如下：

[submodule "mduem"]
        path = mduem
        url = git://github.com/user/mduem

假设我们要自定义 Git 子模块和 Plastic Xlink 之间的映射。

为此，我们可以在 gitserver.conf 文件中添加以下条目（我们可以为不同的 Git 子模块添加任意数量的条目）：

repository.mapping=git://github.com/user/mduem -> mduem-xlinked@localhost:8084 writable:true relativeserver:false

此条目表示存储库 mduem 在 Plastic 端将转换为 mduem-xlinked。

可以跳过某些 Git 子模块，这样它们就不会映射到 Plastic SCM 存储库。为了执行该操作，请按如下方式编辑您的 gitserver.conf：

# when a submoule points to one of the following
# git urls, it will be ignored.
ignore.submoduleUrl= git://github.com/user/mduem

您可以根据需要添加任意数量的 ignore.submoduleUrl 条目。

要使 Plastic SCM 服务器成功启用 GitServer，需要有效的 Enterprise Edition 许可证。

Personal Edition 和 Community Edition 不支持 GitServer。

GitServer 适用于所有支持的 Plastic SCM 服务器平台：Linux、Windows 和 macOS。

避免在要推送到 GitServer 的 Git 存储库上进行快进 (fast-forward)、变基 (rebasing) 和删除提交。

避免变基或删除提交已经是推送到常规 Git 服务器的 Git 间限制。

由于 Plastic SCM 和 Git 之间的内部差异，因此存在快进限制。在 Git 中，一个提交可以被多个分支头部“指向”，因此一个提交可以位于多个分支中。

在 Plastic SCM 中，每个变更集都绑定到单个分支，并且不能同时位于多个分支上。正因为如此，建议避免在应该与 Plastic SCM 同步的 Git 存储库上进行快进合并。

GitServer 不会对导出的存储库执行任何安全检查。

Git 客户端可以下载整个存储库内容或将更改推送到存储库。

请记住，您可以使用 gitserver.conf 中的 export.repo 条目限制对 GitServer 可见的存储库。

GitServer 不支持增量化的 Git 包。也就是说，必须以非增量化格式发送包。

这是一种为了加速两个系统之间的元数据和数据转换的性能限制。

要在 Git 端禁用增量功能，请对您的 Git 存储库运行以下命令：

如果 GitServer 在推送期间收到带有增量的包，则会显示以下错误消息：

该消息包含有关如何“重新打包”Git 存储库以禁用增量的明确说明：

GitServer 不支持浅克隆。根据 Git 客户端版本，系统将显示以下错误消息：

自 1.7.2 以来，我们没有看到任何与 Git 客户端版本之间的兼容性问题。不过，我们强烈建议您使用最新的 Git 客户端软件。

git push 在将对象导入 Plastic SCM 时不会显示任何进度。此过程可能需要几秒钟、几分钟或几小时，具体取决于推送大小。

带批注的标记已正确导入到 Plastic SCM，但如果再次将它们从 GitServer 克隆到 Git，它们将作为轻量级标记导出。

多级分支名称在 Plastic SCM 和 Git 中可能不同。

例如，Plastic SCM 分支 /main/Fix-5.0/scm003 将转换为 Git 中的 main-Fix-5.0-scm003。

目前可以通过 git:// 和 http:// 两种协议访问 GitServer。

稍后将添加 SSH 支持。

目前 GitServer 导出的存储库的文件内容是重复的。这意味着它们以 Plastic SCM 格式存储在数据库内以及 GitServer 存储文件夹中。

如果您出于任何原因需要重新创建 GitServer 映射文件夹，我们不能保证新的 Git SHA 将与旧的相匹配。

以下操作示例将创建与旧的 Git SHA 不匹配的新 Git SHA：

• 如果编辑变更集的注释。
• 如果执行影响任何已映射变更集的复制（例如，添加新的合并链接）。

所以在重新创建 Git 映射后，请始终创建一个新的 Git 存储库并从 Plastic 克隆该存储库。

如果您重用以前的 Git 存储库，最终可能会得到重复的提交（当您推送回 Plastic 时，最终也会出现重复的变更集）。

2019 年 3 月 22 日

• 我们替换了对已弃用的存储库管理命令（如 cm mkrep）的引用，改为新的对应命令。

2018 年 11 月 23 日

• 我们添加了一条注意事项来提醒您必须安装 Plastic SCM 客户端。

2018 年 11 月 8 日

• 现在可以使用 http 基本身份验证来保护 Git 客户端。

2018 年 11 月 2 日

• 我们添加了关于重新创建 GitServer 映射文件夹的新限制。

2016 年 4 月 19 日

• 现在可以从 Git 推送/拉取到 Plastic。

2016 年 3 月 30 日

• 发布日期。