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

名称

git-p4 - 从 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 仓库路径。使用 git p4 sync 来合并 p4 的新提交。sync 命令也用于包含来自其他 p4 仓库路径的新分支。使用 git p4 submit 将 Git 更改提交回 p4。git p4 rebase 命令执行 sync 操作，然后将当前分支变基到更新的 p4 远程分支之上。

示例

  • 克隆仓库

    $ git p4 clone //depot/path/project

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

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

  • 使用 p4 的最新更改更新 Git 仓库，并将你的工作变基到其上

    $ git p4 rebase

  • 将你的提交提交回 p4

    $ git p4 submit

命令

克隆

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

$ git p4 clone //depot/path/project

此命令

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

  2. 将指定 p4 仓库路径的最新修订版本的所有内容导入到 Git 分支 refs/remotes/p4/master 的单个提交中。

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

要将完整的 p4 历史记录复制到 Git 中，请在仓库路径上使用 @all 修饰符。

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

同步

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

$ git p4 sync

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

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

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

此命令将指定的仓库导入到现有 Git 仓库中的 refs/remotes/p4/master。--branch 选项可用于指定一个不同的分支来存放 p4 内容。

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

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

变基

一种常见的开发模式是获取 p4 仓库的最新更改并将其与本地未提交的更改合并。通常，p4 仓库是所有代码的最终存放地，因此变基工作流程是有意义的。此命令执行 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 提交是相对于当前 origin 修订版本（默认为 HEAD）创建的。将基于 origin 创建一个父提交，然后基于该父提交创建 unshelve 提交。

origin 修订版本可以通过 --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>

仅导入 file 中列出的 p4 更改编号，每行一个。通常，git p4 会检查当前的 p4 仓库状态并检测它应该导入的更改。

--silent

不打印任何进度信息。

--detect-labels

查询 p4 以获取与仓库路径关联的标签，并将它们作为 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 仓库路径到 Git 的文件名映射包括删除整个仓库路径。使用此选项时，完整的 p4 仓库路径会保留在 Git 中。例如，路径 //depot/main/foo/bar.c，当从 //depot/main/ 导入时，会变成 foo/bar.c。使用 --keep-path 时，Git 路径将变为 depot/main/foo/bar.c。

--use-client-spec

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

-/ <path>

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

克隆选项

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

--destination <directory>

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

--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

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

--disable-p4sync

禁用在提交后自动从 Perforce 同步 p4/master。表示 --disable-rebase。如果可能，仍然会同步 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-post-changelist 钩子在 P4 中成功提交后调用。它不接受任何参数，主要用于通知，并且不能影响 git p4 submit 操作的结果。

变基选项

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

--import-labels

导入 p4 标签。

取消暂存选项

--origin

设置将暂存的 P4 变更列表与之进行比较的 git refspec。默认为 p4/master。

仓库路径语法

git p4 sync 和 git p4 clone 的 p4 仓库路径参数可以是一个或多个空格分隔的 p4 仓库路径，并在末尾带有可选的 p4 修订版本说明符。

"//depot/my/project"

导入该树下的最新更改 (#head) 的一个提交，包含所有文件。

"//depot/my/project@all"

为该仓库路径的历史记录中的每个更改导入一个提交。

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

仅导入更改 1 到 6。

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

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

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

客户端规范

p4 客户端规范使用 p4 client 命令进行维护，其中包含一个 View（视图），指定仓库如何映射到客户端存储库。clone 和 sync 命令在给出 --use-client-spec 选项或 useClientSpec 变量为 true 时，可以咨询客户端规范。在 git p4 clone 之后，useClientSpec 变量会自动在存储库配置文件中设置。这使得未来的 git p4 submit 命令能够正常工作；submit 命令仅查看该变量，并且没有命令行选项。

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

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

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

分支检测

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

如果你的存储库中所有感兴趣的分支都作为单个仓库路径的子目录存在，那么在克隆或同步时可以使用 --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

作为所有 p4 命令的选项指定的用户名，使用 -u <user>。可以使用 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

将 p4 标签导入 git，如 --import-labels 所示。

git-p4.labelImportRegexp

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

git-p4.useClientSpec

指定应使用 p4 客户端规范来识别感兴趣的 p4 仓库路径。这等同于指定 --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 客户端使用操作系统的本地编码，因此不同的用户可能在同一仓库中以不同的编码存储不同的变更列表描述或用户全名。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 策略（请参阅 git-p4.metadataDecodingStrategy）解码 Perforce 作者姓名和变更列表描述时使用的回退编码。回退编码仅在 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 作者，而不管谁调用 git p4 submit。

git-p4.allowMissingP4Users

当 preserveUser 为 true 时，如果找不到 p4 用户映射中的作者，git 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

将 Git 标签导出到 p4 标签，如 --export-labels 所示。

git-p4.labelExportRegexp

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

git-p4.conflict

指定冲突时提交的行为，如 --conflict 所示。默认行为是 ask。

git-p4.disableRebase

提交后不将树变基到 p4/master。

git-p4.disableP4Sync

提交后不同步 p4/master 与 Perforce。表示 git-p4.disableRebase。

实现细节

  • p4 的变更集使用 Git fast-import 进行导入。

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

  • 提交需要一个 p4 客户端，该客户端与 Git 存储库不在同一位置。补丁会一次一个地应用到此 p4 客户端，并从那里进行提交。

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

GIT

Git[1] 套件的一部分