简体中文 ▾ 主题 ▾ 最新版本 ▾ git-p4 最后更新于 2.50.0

名称

git-p4 - 从 Perforce 仓库导入并提交到 Perforce 仓库

概要

git p4 clone [<sync-options>] [<clone-options>] <p4-depot-path>…​
git p4 sync [<sync-options>] [<p4-depot-path>…​]
git p4 rebase
git p4 submit [<submit-options>] [<master-branch-name>]

描述

此命令提供了一种使用 Git 与 p4 仓库交互的方式。

使用 git p4 clone 从现有的 p4 仓库创建新的 Git 仓库，并指定一个或多个 p4 depot 路径。使用 git p4 sync 合并来自 p4 变更的新提交。sync 命令也用于从其他 p4 depot 路径包含新分支。使用 git p4 submit 将 Git 变更提交回 p4。命令 git p4 rebase 执行 sync 操作，并将当前分支 rebase 到更新后的 p4 远程分支之上。

示例

  • 克隆仓库

    $ git p4 clone //depot/path/project

  • 在新创建的 Git 仓库中进行一些工作

    $ cd project
$ vi foo.h
$ git commit -a -m "edited foo.h"

  • 用 p4 的最新更改更新 Git 仓库，并在此之上 rebase 您的工作

    $ git p4 rebase

  • 将您的提交提交回 p4

    $ git p4 submit

命令

克隆

通常，git p4 clone 用于从现有 p4 仓库创建新的 Git 目录

$ git p4 clone //depot/path/project

这

  1. 在名为 project 的子目录中创建一个空的 Git 仓库。

  2. 将给定 p4 depot 路径的头修订版本的完整内容导入到 Git 分支 refs/remotes/p4/master 中的单个提交中。

  3. 从此远程创建一个本地分支 master 并将其检出。

要在 Git 中重现整个 p4 历史，请在 depot 路径上使用 @all 修饰符

$ git p4 clone //depot/path/project@all

同步

随着 p4 仓库中的开发继续，这些更改可以使用以下命令包含在 Git 仓库中

$ git p4 sync

此命令查找 p4 中的新更改并将其作为 Git 提交导入。

p4 仓库也可以使用 git p4 sync 添加到现有的 Git 仓库中

$ mkdir repo-git
$ cd repo-git
$ git init
$ git p4 sync //path/in/your/perforce/depot

这会将指定的 depot 导入到现有 Git 仓库的 refs/remotes/p4/master 中。--branch 选项可用于指定用于 p4 内容的不同分支。

如果 Git 仓库包含分支 refs/remotes/origin/p4，那么在 git p4 sync 期间将首先拉取并参考这些分支。由于直接从 p4 导入比从 Git 远程拉取更改慢得多，这在多开发者环境中可能很有用。

如果存在多个分支，执行 git p4 sync 将自动使用“分支检测”算法来尝试将新更改分区到正确的分支中。这可以通过 --branch 选项来覆盖，以指定仅更新单个分支。

变基

一种常见的工作模式是从 p4 depot 获取最新更改并将其与本地未提交的更改合并。通常，p4 仓库是所有代码的最终位置，因此 rebase 工作流是有意义的。此命令执行 git p4 sync，然后执行 git rebase，将本地提交移动到更新的 p4 更改之上。

$ git p4 rebase

提交

将 Git 仓库中的更改提交回 p4 仓库需要一个单独的 p4 客户端工作区。这应该通过 P4CLIENT 环境变量或 Git 配置变量 git-p4.client 来指定。p4 客户端必须存在，但如果客户端根目录不存在，则会创建并填充。

要提交当前 Git 分支中存在但不在 p4/master 分支中的所有更改，请使用

$ git p4 submit

要指定当前分支以外的分支，请使用

$ git p4 submit topicbranch

要指定单个提交或提交范围，请使用

$ git p4 submit --commit <sha1>
$ git p4 submit --commit <sha1..sha1>

上游引用通常是 refs/remotes/p4/master，但可以使用 --origin= 命令行选项覆盖。

p4 更改将由调用 git p4 submit 的用户创建。--preserve-user 选项将导致所有权根据 Git 提交的作者进行修改。此选项需要 p4 管理权限，可以使用 p4 protect 授予。

要搁置更改而不是提交，请使用 --shelve 和 --update-shelve

$ git p4 submit --shelve
$ git p4 submit --update-shelve 1234 --update-shelve 2345

取消搁置

取消搁置将获取一个搁置的 P4 变更列表，并在分支 refs/remotes/p4-unshelved/<changelist> 中生成等效的 git 提交。

git 提交是相对于当前源修订版本（默认为 HEAD）创建的。根据源创建一个父提交，然后根据该父提交创建取消搁置的提交。

源修订版本可以通过“--origin”选项更改。

如果 refs/remotes/p4-unshelved 中的目标分支已经存在，则旧分支将被重命名。

$ git p4 sync
$ git p4 unshelve 12345
$ git show p4-unshelved/12345
<submit more changes via p4 to the same files>
$ git p4 unshelve 12345
<refuses to unshelve until git is in sync with p4 again>

选项

通用选项

除了 clone 之外的所有命令都接受这些选项。

--git-dir <dir>

设置 GIT_DIR 环境变量。参见 git[1]。

-v
--verbose

提供更多进度信息。

同步选项

这些选项可以在初始 clone 以及后续的 sync 操作中使用。

--branch <ref>

将更改导入到 <ref> 而不是 refs/remotes/p4/master。如果 <ref> 以 refs/ 开头，则按原样使用。否则，如果它不以 p4/ 开头，则添加该前缀。

默认情况下，不以 refs/ 开头的 <ref> 被视为远程跟踪分支（在 refs/remotes/ 下）的名称。此行为可以通过 --import-local 选项进行修改。

默认的 <ref> 是 "master"。

此示例将新的远程“p4/proj2”导入到现有 Git 仓库中

    $ git init
    $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2
--detect-branches

使用分支检测算法在 p4 中查找新路径。它在下面的“分支检测”中有详细说明。

--changesfile <file>

精确导入文件中列出的 p4 变更号，每行一个。通常，git p4 会检查当前的 p4 仓库状态并检测它应该导入的变更。

--silent

不打印任何进度信息。

--detect-labels

查询 p4 获取与 depot 路径关联的标签，并将其添加为 Git 中的标签。由于只导入与新变更列表关联的标签，因此用处有限。已弃用。

--import-labels

从 p4 导入标签到 Git。

--import-local

默认情况下，p4 分支存储在 refs/remotes/p4/ 中，在那里它们将被 git-branch[1] 和其他命令视为远程跟踪分支。此选项改为将 p4 分支放在 refs/heads/p4/ 中。请注意，未来的同步操作也必须指定 --import-local，以便它们可以在 refs/heads 中找到 p4 分支。

--max-changes <n>

最多导入 n 个变更，而不是给定修订说明符中包含的整个变更范围。典型的用法是使用 @all 作为修订说明符，但随后使用 --max-changes 1000 来只导入最后 1000 个修订版本，而不是整个修订历史。

--changes-block-size <n>

将修订说明符（如 @all）转换为特定变更号列表时使用的内部块大小。不是使用单个 p4 changes 调用来查找完整的变更列表进行转换，而是有一系列对 p4 changes -m 的调用，每个调用请求给定大小的一个变更块。默认块大小为 500，通常应该适用。

--keep-path

默认情况下，从 p4 depot 路径到 Git 的文件名映射会删除整个 depot 路径。使用此选项，完整的 p4 depot 路径将保留在 Git 中。例如，从 //depot/main/ 导入的路径 //depot/main/foo/bar.c 会变为 foo/bar.c。使用 --keep-path，Git 路径则为 depot/main/foo/bar.c。

--use-client-spec

使用客户端规范查找 p4 中感兴趣的文件列表。请参阅下面的“客户端规范”部分。

-/ <path>

在克隆或同步时排除选定的 depot 路径。

克隆选项

这些选项可以在初始 clone 中使用，以及上面描述的 sync 选项。

--destination <directory>

创建 Git 仓库的位置。如果未提供，则使用 p4 depot 路径的最后一个组件来创建新目录。

--bare

执行裸克隆。参见 git-clone[1]。

提交选项

这些选项可用于修改 git p4 submit 的行为。

--origin <commit>

标识要提交到 p4 的提交的上游位置。默认情况下，这是从 HEAD 可达的最新 p4 提交。

-M

检测重命名。参见 git-diff[1]。重命名将在 p4 中使用显式 move 操作表示。没有相应的选项来检测复制，但有变量用于移动和复制。

--preserve-user

在提交到 p4 之前重新创作 p4 更改。此选项需要 p4 管理权限。

--export-labels

将 Git 中的标签作为 p4 标签导出。Git 中找到的标签将应用于 perforce 工作目录。

-n
--dry-run

仅显示哪些提交将提交到 p4；不更改 Git 或 p4 中的状态。

--prepare-p4-only

将提交应用到 p4 工作区，像正常的提交操作一样在 p4 中打开、添加和删除文件。不要发出最终的“p4 submit”命令，而是打印一条关于如何手动提交或回滚的消息。此选项总是会在第一个（最旧的）提交之后停止。Git 标签不会导出到 p4。

--shelve

不是提交，而是创建一系列搁置的变更列表。创建每个搁置后，相关文件将被恢复/删除。如果您有多个提交待处理，将创建多个搁置。

--update-shelve CHANGELIST

使用此提交更新现有搁置的变更列表。隐含 --shelve。对于多个搁置的变更列表重复此操作。

--conflict=(ask|skip|quit)

将提交应用到 p4 时可能会发生冲突。发生这种情况时，默认行为（"ask"）是提示是跳过此提交并继续，还是退出。此选项可用于绕过提示，导致冲突提交自动跳过，或在不提示的情况下退出尝试应用提交。

--branch <branch>

提交后，同步此命名分支而不是默认的 p4/master。有关更多信息，请参见上面的“同步选项”部分。

--commit (<sha1>|<sha1>..<sha1>)

仅提交指定的提交或提交范围，而不是当前 Git 分支中变更的完整列表。

--disable-rebase

成功提交所有提交后禁用自动 rebase。也可以通过 git-p4.disableRebase 设置。

--disable-p4sync

禁用提交后从 Perforce 自动同步 p4/master。隐含 --disable-rebase。也可以通过 git-p4.disableP4Sync 设置。如果可能，与 origin/master 的同步仍将进行。

提交钩子

p4-pre-submit

如果 p4-pre-submit 钩子存在且可执行，则执行。该钩子不带参数，也不从标准输入接收任何内容。如果此脚本以非零状态退出，则阻止 git-p4 submit 启动。它可以通过 --no-verify 命令行选项绕过。

一种使用场景是在钩子中运行单元测试。

p4-prepare-changelist

在准备好默认变更列表消息并启动编辑器之前，执行 p4-prepare-changelist 钩子。它带一个参数，即包含变更列表文本的文件名。如果脚本以非零状态退出，则会中止进程。

该钩子的目的是就地编辑消息文件，并且不会被 --no-verify 选项抑制。即使设置了 --prepare-p4-only，也会调用此钩子。

p4-changelist

在用户编辑完变更列表消息后，执行 p4-changelist 钩子。它可以通过 --no-verify 选项绕过。它接受一个参数，即保存提议的变更列表文本的文件名。如果以非零状态退出，则命令中止。

该钩子允许编辑变更列表文件，并可用于将文本规范化为某个项目标准格式。它还可以用于在检查消息文件后拒绝提交。

p4-post-changelist

在 P4 中成功提交后，将调用 p4-post-changelist 钩子。它不带参数，主要用于通知，不能影响 git p4 submit 操作的结果。

变基选项

这些选项可用于修改 git p4 rebase 的行为。

--import-labels

导入 p4 标签。

取消搁置选项

--origin

设置 git refspec，与搁置的 P4 变更列表进行比较。默认为 p4/master。

DEPOT 路径语法

git p4 sync 和 git p4 clone 的 p4 depot 路径参数可以是一个或多个空格分隔的 p4 depot 路径，末尾可带可选的 p4 修订说明符

"//depot/my/project"

导入一个提交，其中包含该树下 #head 变更中的所有文件。

"//depot/my/project@all"

为该 depot 路径历史中的每个更改导入一个提交。

"//depot/my/project@1,6"

仅导入更改 1 到 6。

"//depot/proj1@all //depot/proj2@all"

将两个命名 depot 路径中的所有更改导入到单个仓库中。仅包含这些目录下的文件。Git 中没有“proj1”和“proj2”的子目录。当指定多个 depot 路径时，必须使用 --destination 选项。修订说明符必须在每个 depot 路径上指定相同。如果 depot 路径中有同名文件，则最新更新版本的文件路径将出现在 Git 中。

有关 p4 修订说明符的完整语法，请参阅 p4 help revisions。

客户端规范

p4 客户端规范通过 p4 client 命令维护，其中包含（除其他字段外）一个 View，它指定了 depot 如何映射到客户端仓库。当给定 --use-client-spec 选项或 useClientSpec 变量为 true 时，clone 和 sync 命令可以参考客户端规范。在 git p4 clone 之后，useClientSpec 变量会自动设置在仓库配置文件中。这允许未来的 git p4 submit 命令正常工作；submit 命令只查看该变量，没有命令行选项。

p4 视图的完整语法在 p4 help views 中有文档说明。git p4 只知道视图语法的一个子集。它理解多行映射、带 + 的覆盖、带 - 的排除以及空格周围的双引号。在所有可能的通配符中，git p4 只处理 …​，并且仅当它在路径末尾时。如果 git p4 遇到未处理的通配符，它会报错。

重叠映射的实现存在 bug。如果多个 depot 路径通过覆盖映射到仓库中的同一位置，git p4 可能会选择错误的路径。这很难解决，除非专门为 git p4 分配一个客户端规范。

客户端名称可以通过多种方式提供给 git p4。如果 git-p4.client 变量存在，它将优先。否则，使用正常的 p4 机制来确定客户端：环境变量 P4CLIENT、P4CONFIG 引用的文件或本地主机名。

分支检测

P4 没有与 Git 相同的分支概念。相反，p4 将其内容组织为目录树，约定上不同的逻辑分支位于树中不同的位置。p4 branch 命令用于维护树中不同区域之间的映射，并指示相关内容。git p4 可以使用这些映射来确定分支关系。

如果您的仓库中所有感兴趣的分支都存在于单个 depot 路径的子目录中，则在克隆或同步时可以使用 --detect-branches，让 git p4 自动查找 p4 中的子目录，并将其生成为 Git 中的分支。

例如，如果 P4 仓库结构是

//depot/main/...
//depot/branch1/...

并且“p4 branch -o branch1”显示了一个 View 行，看起来像

//depot/main/... //depot/branch1/...

那么这个 git p4 clone 命令

git p4 clone --detect-branches //depot@all

在 refs/remotes/p4/ 中为 //depot/main 生成一个单独的分支，名为 master，并为 //depot/branch1 生成一个名为 depot/branch1 的分支。

然而，没有必要在 p4 中创建分支才能像分支一样使用它们。由于自动推断分支关系很困难，因此可以使用 Git 配置设置 git-p4.branchList 来明确标识分支关系。它是一个“源:目标”对列表，类似于简单的 p4 分支规范，其中“源”和“目标”是 p4 仓库中的路径元素。上面的示例依赖于 p4 分支的存在。如果没有 p4 分支，使用以下命令将获得相同的结果

git init depot
cd depot
git config git-p4.branchList main:branch1
git p4 clone --detect-branches //depot@all .

性能

git p4 使用的 fast-import 机制为每次 git p4 sync 调用创建一个 pack 文件。通常，Git 垃圾压缩（git-gc[1]）会自动将其压缩为更少的 pack 文件，但显式调用 git repack -adf 可能会提高性能。

配置变量

以下配置设置可用于修改 git p4 行为。它们都位于 git-p4 部分。

通用变量

git-p4.user

使用 -u <user> 选项指定给所有 p4 命令的用户。也可以使用环境变量 P4USER 代替。

git-p4.password

作为所有 p4 命令的选项指定的密码，带有 -P <password>。可以使用环境变量 P4PASS 代替。

git-p4.port

作为所有 p4 命令的选项指定的端口，带有 -p <port>。可以使用环境变量 P4PORT 代替。

git-p4.host

作为所有 p4 命令的选项指定的主机，带有 -h <host>。可以使用环境变量 P4HOST 代替。

git-p4.client

作为所有 p4 命令的选项指定的客户端，带有 -c <client>，包括客户端规范。

git-p4.retries

指定如果网络超时，重试 p4 命令（特别是 p4 sync）的次数。默认值为 3。将值设置为 0 以禁用重试，或者如果您的 p4 版本不支持重试（2012.2 之前）。

克隆和同步变量

git-p4.syncFromOrigin

因为从其他 Git 仓库导入提交比从 p4 导入快得多，所以存在一种机制，可以在 Git 远程中首先查找 p4 更改。如果 refs/remote/origin/p4 下存在分支，则在从 p4 同步时将拉取并使用这些分支。此变量可以设置为 false 以禁用此行为。

git-p4.branchUser

分支检测的一个阶段涉及查看 p4 分支以查找要导入的新分支。默认情况下，所有分支都会被检查。此选项将搜索限制为仅限于变量中指定单个用户拥有的分支。

git-p4.branchList

启用分支检测时要导入的分支列表。每个条目应为一对用冒号 (:) 分隔的分支名称。此示例声明 branchA 和 branchB 都是从 main 创建的

git config       git-p4.branchList main:branchA
git config --add git-p4.branchList main:branchB
git-p4.ignoredP4Labels

要忽略的 p4 标签列表。这是随着发现不可导入的标签而自动构建的。

git-p4.importLabels

根据 --import-labels 将 p4 标签导入到 git 中。

git-p4.labelImportRegexp

只有匹配此正则表达式的 p4 标签才会被导入。默认值为 [a-zA-Z0-9_\-.]+$。

git-p4.useClientSpec

指定应使用 p4 客户端规范来标识感兴趣的 p4 depot 路径。这等同于指定选项 --use-client-spec。请参阅上面的“客户端规范”部分。此变量是布尔值，而不是 p4 客户端的名称。

git-p4.pathEncoding

Perforce 按照原始操作系统给定的编码保留路径。Git 期望路径以 UTF-8 编码。使用此配置来告诉 git-p4 Perforce 对路径使用了哪种编码。此编码用于将路径转码为 UTF-8。例如，Windows 上的 Perforce 通常使用“cp1252”来编码路径名。如果此选项传递给 p4 clone 请求，它将保留在结果新 git 仓库中。

git-p4.metadataDecodingStrategy

Perforce 按照给定操作系统上客户端存储的编码保留变更列表描述和用户全名。p4v 客户端使用操作系统本地编码，因此不同的用户最终可能会在同一个 depot 中以不同的编码存储不同的变更列表描述或用户全名。Git 容忍提交消息和作者姓名中不一致/不正确的编码，但期望它们以 utf-8 指定。git-p4 可以使用三种不同的解码策略来处理 Perforce 中的编码不确定性：passthrough 只是将原始字节从 Perforce 直接传递到 git，当 Perforce 数据以 utf-8 以外的任何编码编码时，会创建可用但编码不正确的数据。strict 期望 Perforce 数据以 utf-8 编码，并且当事实并非如此时，导入失败。fallback 尝试将数据解释为 utf-8，否则回退到使用辅助编码——默认是常见的 windows 编码 cp-1252——如果使用回退编码解码也失败，则会转义高位字节。在 python2 下，由于历史原因，默认策略是 passthrough，在 python3 下，默认是 fallback。当选择 strict 且解码失败时，错误消息将建议更改此配置参数作为解决方法。如果此选项传递给 p4 clone 请求，它将保留在结果新 git 仓库中。

git-p4.metadataFallbackEncoding

在使用 fallback 策略解码 Perforce 作者姓名和变更列表描述时，指定要使用的回退编码（请参阅 git-p4.metadataDecodingStrategy）。回退编码仅在 utf-8 解码失败时使用。此选项默认为 cp1252，一种常见的 windows 编码。如果此选项传递给 p4 clone 请求，它将保留在结果新 git 仓库中。

git-p4.largeFileSystem

指定用于大（二进制）文件的系统。请注意，大文件系统不支持 git p4 submit 命令。目前仅实现了 Git LFS（有关更多信息，请参阅 https://git-lfs.github.com/）。下载并安装 Git LFS 命令行扩展以使用此选项并像这样配置它

git config       git-p4.largeFileSystem GitLFS
git-p4.largeFileExtensions

列表中所有匹配文件扩展名的文件都将由大文件系统处理。不要在扩展名前加 .。

git-p4.largeFileThreshold

所有未压缩大小超过阈值的文件都将由大文件系统处理。默认情况下，阈值以字节为单位定义。添加后缀 k、m 或 g 以更改单位。

git-p4.largeFileCompressedThreshold

所有压缩大小超过阈值的文件都将由大文件系统处理。此选项可能会减慢您的克隆/同步过程。默认情况下，阈值以字节为单位定义。添加后缀 k、m 或 g 以更改单位。

git-p4.largeFilePush

布尔变量，定义大文件是否自动推送到服务器。

git-p4.keepEmptyCommits

如果此布尔选项设置为 true，则仅包含排除文件的变更列表将作为空提交导入。

git-p4.mapUser

将 P4 用户映射到 Git 中的姓名和电子邮件地址。使用以下格式的字符串创建映射

git config --add git-p4.mapUser "p4user = First Last <mail@address.com>"

映射将覆盖 P4 中的任何用户信息。可以定义多个 P4 用户的映射。

提交变量

git-p4.detectRenames

检测重命名。参见 git-diff[1]。这可以是 true、false，或者 git diff -M 所期望的分数。

git-p4.detectCopies

检测复制。参见 git-diff[1]。这可以是 true、false，或者 git diff -C 所期望的分数。

git-p4.detectCopiesHarder

更努力地检测复制。参见 git-diff[1]。一个布尔值。

git-p4.preserveUser

提交时，重新设置更改的作者以反映 Git 作者，无论谁调用 git p4 submit。

git-p4.allowMissingP4Users

当 preserveUser 为 true 时，如果 git p4 无法在 p4 用户映射中找到作者，它通常会终止。此设置无论如何都会提交更改。

git-p4.skipSubmitEdit

提交过程在每个 p4 更改提交之前调用编辑器。但是，如果此设置设置为 true，则跳过编辑步骤。

git-p4.skipSubmitEditCheck

在编辑 p4 变更消息后，git p4 通过查看文件修改时间来确保描述确实已更改。此选项禁用该测试。

git-p4.allowSubmit

默认情况下，任何分支都可以用作 git p4 submit 操作的源。如果设置了此配置变量，则只允许命名分支用作提交源。分支名称必须是短名称（无“refs/heads/”），并且应该用逗号（“,”）分隔，没有空格。

git-p4.skipUserNameCheck

如果运行 git p4 submit 的用户在 p4 用户映射中不存在，git p4 会退出。此选项可用于强制提交。

git-p4.attemptRCSCleanup

如果启用，git p4 submit 将尝试清理 RCS 关键字（$Header$ 等）。否则，这些关键字将导致合并冲突并阻止提交进行。此选项目前应视为实验性。

git-p4.exportLabels

根据 --export-labels 将 Git 标签导出到 p4 标签。

git-p4.labelExportRegexp

只有匹配此正则表达式的 p4 标签才会被导出。默认值为 [a-zA-Z0-9_\-.]+$。

git-p4.conflict

当发现与 p4 冲突时，指定提交行为，与 --conflict 相同。默认行为是 ask。

git-p4.disableRebase

提交后不要对树进行 rebase 操作，使其与 p4/master 对齐。

git-p4.disableP4Sync

提交后不要将 p4/master 与 Perforce 同步。隐含 git-p4.disableRebase。

实现细节

  • 来自 p4 的变更集使用 Git fast-import 导入。

  • 克隆或同步不需要 p4 客户端；文件内容是使用 p4 print 收集的。

  • 提交需要一个 p4 客户端，它与 Git 仓库不在同一位置。补丁会一个接一个地应用到这个 p4 客户端，然后从那里提交。

  • 由 git p4 导入的每个提交在其日志消息末尾都有一行，指示 p4 depot 位置和变更号。此行用于后续 git p4 sync 操作，以了解哪些 p4 更改是新的。

GIT

Git[1] 套件的一部分

scroll-to-top