Git
English ▾ 主题 ▾ 最新版本 ▾ git-p4 最后更新于 2.37.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 仓库路径。使用 git p4 sync 将来自 p4 更改的新提交合并。sync 命令还用于从其他 p4 仓库路径包含新的分支。使用 git p4 submit 将 Git 更改提交回 p4。命令 git p4 rebase 执行同步,并将当前分支重新设置到更新的 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 并检出。

要在 Git 中重现整个 p4 历史记录,请在仓库路径上使用 @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 提交相对于当前源修订版(默认为 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>

选项

常规选项

除克隆外,所有命令都接受这些选项。

--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 的映射涉及删除整个库路径。使用此选项,Git 中将保留完整的 p4 库路径。例如,路径//depot/main/foo/bar.c//depot/main/导入时,将变为foo/bar.c。使用--keep-path,Git 路径则为depot/main/foo/bar.c

--use-client-spec

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

-/ <path>

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

克隆选项

这些选项可用于初始克隆以及上面描述的同步选项。

--destination <directory>

在何处创建 Git 存储库。如果未提供,则使用 p4 库路径中的最后一个组件创建新目录。

--bare

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

提交选项

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

--origin <commit>

识别要提交到 p4 的提交的上游位置。默认情况下,这是从HEAD可访问的最新 p4 提交。

-M

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

--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。也可以使用 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

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

库路径语法

git p4 syncgit 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命令维护,其中包含视图等字段,这些字段指定库如何映射到客户端存储库中。当给出--use-client-spec选项或 useClientSpec 变量为真时,clonesync命令可以查阅客户端规范。git p4 clone之后,存储库配置文件中会自动设置 useClientSpec 变量。这允许将来的git p4 submit命令正常工作;submit 命令仅查看变量,并且没有命令行选项。

p4 视图的完整语法在p4 help views中有记录。git p4仅了解视图语法的一个子集。它理解多行映射、使用+的覆盖、使用-的排除以及空格周围的双引号。在可能的通配符中,git p4仅处理…​,并且仅在路径末尾时处理。如果git p4遇到未处理的通配符,它会发出抱怨。

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

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

分支检测

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

如果您有一个存储库,其中所有感兴趣的分支都作为单个库路径的子目录存在,则可以在克隆或同步时使用--detect-branchesgit 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使用的快速导入机制为每次git p4 sync调用创建一个打包文件。通常,Git 垃圾压缩(git-gc[1])会自动将这些文件压缩为更少的打包文件,但显式调用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

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

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 克隆请求中,它将保留在生成的新的 git 存储库中。

git-p4.metadataDecodingStrategy

Perforce 保留更改列表描述和用户全名的编码,这些编码由给定操作系统上的客户端存储。p4v 客户端使用 OS 本地编码,因此不同的用户最终可能会在同一个库中以不同的编码存储不同的更改列表描述或用户全名。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 克隆请求中,它将保留在生成的新的 git 存储库中。

git-p4.metadataFallbackEncoding

使用 fallback 策略(参见 git-p4.metadataDecodingStrategy)解码 Perforce 作者名称和更改列表描述时,指定要使用的回退编码。仅当以 utf-8 解码失败时才会使用回退编码。此选项默认为 cp1252,这是一种常见的 windows 编码。如果将此选项传递到 p4 克隆请求中,它将保留在生成的新的 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 <[email protected]>"

映射将覆盖来自 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

根据 --conflict 指定在发现与 p4 冲突时的提交行为。默认行为为 ask

git-p4.disableRebase

在提交后不要将树重新定位到 p4/master。

git-p4.disableP4Sync

在提交后不要将 p4/master 与 Perforce 同步。意味着 git-p4.disableRebase。

实现细节

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

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

  • 提交需要一个 p4 客户端,它与 Git 仓库不在同一位置。补丁会逐个应用到此 p4 客户端,并从那里提交。

  • git p4 导入的每个提交,其日志消息末尾都有一行指示 p4 仓库位置和变更编号。后续的 git p4 sync 操作会使用此行来识别哪些 p4 变更为新的变更。

GIT

git[1] 套件的一部分

scroll-to-top