Perforce Basics

Perforce 基础操作

Overview

概述

Perforce (P4) is a centralized version control system optimized for large codebases and binary assets. This skill covers essential daily operations.

Perforce（P4）是一款针对大型代码库和二进制资产优化的集中式版本控制系统。本技能涵盖了日常必备的操作内容。

When to Use

适用场景

Syncing latest changes
Editing files for modification
Adding new files
Deleting files
Submitting changes
Reverting unwanted changes

同步最新变更
编辑文件以进行修改
添加新文件
删除文件
提交变更
撤销不需要的变更

Core Concepts

核心概念

File States

文件状态

State	Description	Command to Change
Not in depot	File exists locally but not tracked	`p4 add`
Synced	File matches depot version	-
Edited	Open for edit, modified locally	`p4 edit` then modify
Added	Marked for addition to depot	`p4 add`
Deleted	Marked for deletion from depot	`p4 delete`
Out of date	Depot has newer version	`p4 sync`

状态	描述	变更命令
未在仓库中	文件存在于本地但未被追踪	`p4 add`
已同步	文件与仓库版本一致	-
已编辑	已打开用于编辑，本地已修改	`p4 edit` 后进行修改
已标记添加	已标记为要添加到仓库	`p4 add`
已标记删除	已标记为要从仓库删除	`p4 delete`
已过期	仓库中有更新的版本	`p4 sync`

Revision Specifiers

版本指定符

bash

undefined

bash

undefined

Specific revision number

特定版本号

file.txt#3

Head revision (latest)

Changelist number

变更列表编号

file.txt@12345

Label

Date/time

日期/时间

file.txt@2024/01/15 file.txt@2024/01/15:14:30:00

Revision range

版本范围

file.txt#2,#5 file.txt@10000,@12000

undefined

file.txt#2,#5 file.txt@10000,@12000

undefined

Sync Operations

同步操作

Basic Sync

基础同步

bash

undefined

bash

undefined

Sync entire workspace to head

将整个工作区同步到最新版本

p4 sync

Sync specific path

同步特定路径

p4 sync //depot/project/...

Sync specific file

同步特定文件

p4 sync //depot/project/file.txt

Sync to specific revision

同步到特定版本

p4 sync //depot/project/...#head p4 sync //depot/project/...@12345

Sync to specific changelist

同步到特定变更列表

p4 sync @12345

undefined

p4 sync @12345

undefined

Sync Options

同步选项

bash

undefined

bash

undefined

Preview sync (don't actually sync)

预览同步（实际不执行同步）

p4 sync -n //depot/project/...

Force sync (re-download even if up to date)

强制同步（即使已最新也重新下载）

p4 sync -f //depot/project/...

Parallel sync (faster for many files)

并行同步（多文件时更快）

p4 sync --parallel=threads=4 //depot/project/...

Safe sync (don't clobber writable files)

安全同步（不覆盖可写文件）

p4 sync -s //depot/project/...

Sync and show affected files

同步并显示受影响的文件

p4 sync //depot/project/... 2>&1 | head -50

undefined

p4 sync //depot/project/... 2>&1 | head -50

undefined

Selective Sync

选择性同步

bash

undefined

bash

undefined

Sync only specific file types

仅同步特定文件类型

p4 sync //depot/project/....cs p4 sync //depot/project/....prefab

Sync excluding paths (use workspace view instead)

排除路径同步（建议使用工作区视图替代）

Or sync specific subdirectories

或同步特定子目录

p4 sync //depot/project/Assets/Scripts/...

undefined

p4 sync //depot/project/Assets/Scripts/...

undefined

Edit Operations

编辑操作

Opening Files for Edit

打开文件进行编辑

bash

undefined

bash

undefined

Edit single file

编辑单个文件

p4 edit file.txt

Edit multiple files

编辑多个文件

p4 edit *.cs

Edit files in directory

编辑目录中的文件

p4 edit Assets/Scripts/...

Edit with specific changelist

在特定变更列表中编辑

p4 edit -c 12345 file.txt

Edit to default changelist

在默认变更列表中编辑

p4 edit -c default file.txt

undefined

p4 edit -c default file.txt

undefined

Check Edit Status

检查编辑状态

bash

undefined

bash

undefined

See files open for edit

查看已打开用于编辑的文件

p4 opened

See files open in specific changelist

查看特定变更列表中已打开的文件

p4 opened -c 12345

See files open by all users

查看所有用户已打开的文件

p4 opened -a //depot/project/...

See who has file open

查看谁打开了该文件

p4 opened -a //depot/project/file.txt

undefined

p4 opened -a //depot/project/file.txt

undefined

Add Operations

添加操作

Adding New Files

添加新文件

bash

undefined

bash

undefined

Add single file

添加单个文件

p4 add newfile.txt

Add multiple files

添加多个文件

p4 add *.cs

Add files recursively

递归添加文件

p4 add Assets/NewFeature/...

Add to specific changelist

添加到特定变更列表

p4 add -c 12345 newfile.txt

Add with specific file type

指定文件类型添加

p4 add -t binary+l largefile.bin p4 add -t text+x script.sh

undefined

p4 add -t binary+l largefile.bin p4 add -t text+x script.sh

undefined

File Types

文件类型

bash

undefined

bash

undefined

Common file types

常见文件类型

text # Text file, diff/merge enabled binary # Binary file, no diff/merge unicode # Unicode text symlink # Symbolic link

text # 文本文件，支持差异对比/合并 binary # 二进制文件，不支持差异对比/合并 unicode # Unicode文本 symlink # 符号链接

Modifiers

修饰符

+l # Exclusive lock (only one user can edit) +w # Always writable on client +x # Executable bit +S # Only head revision stored (saves space) +F # Check for RCS keywords

+l # 独占锁（仅一个用户可编辑） +w # 在客户端始终可写 +x # 可执行权限 +S # 仅存储最新版本（节省空间） +F # 检查RCS关键字

Examples

示例

p4 add -t binary+l Assets/Textures/hero.psd # Locked binary p4 add -t text Assets/Scripts/Player.cs # Text file

undefined

p4 add -t binary+l Assets/Textures/hero.psd # 锁定的二进制文件 p4 add -t text Assets/Scripts/Player.cs # 文本文件

undefined

Delete Operations

删除操作

Deleting Files

删除文件

bash

undefined

bash

undefined

Delete single file

删除单个文件

p4 delete file.txt

Delete multiple files

删除多个文件

p4 delete *.bak

Delete in specific changelist

在特定变更列表中删除

p4 delete -c 12345 file.txt

Delete files matching pattern

删除匹配模式的文件

p4 delete //depot/project/....tmp

undefined

p4 delete //depot/project/....tmp

undefined

Handling Deleted Files

处理已删除文件

bash

undefined

bash

undefined

See deleted files in depot

查看仓库中已删除的文件

p4 files //depot/project/...@head | grep "delete change"

Recover deleted file (sync old revision, then add)

恢复已删除文件（同步旧版本，然后重新添加）

p4 sync //depot/project/file.txt#head-1 p4 add file.txt

Or use obliterate (admin only) to permanently remove

或使用obliterate（仅管理员可用）永久删除

undefined

undefined

Revert Operations

撤销操作

Reverting Changes

撤销变更

bash

undefined

bash

undefined

Revert single file

撤销单个文件

p4 revert file.txt

Revert all files in changelist

撤销变更列表中的所有文件

p4 revert -c 12345 //...

Revert all open files

撤销所有已打开的文件

p4 revert //...

Revert unchanged files only

仅撤销未修改的文件

p4 revert -a //...

Revert with preview

预览撤销操作

p4 revert -n //...

undefined

p4 revert -n //...

undefined

Revert to Specific Revision

撤销到特定版本

bash

undefined

bash

undefined

Sync to old revision (makes file read-only)

同步到旧版本（文件变为只读）

p4 sync //depot/project/file.txt#3

To actually revert content and submit:

若要实际撤销内容并提交：

p4 sync //depot/project/file.txt#head p4 edit file.txt p4 sync -f //depot/project/file.txt#3 p4 resolve -ay file.txt

Now submit

现在提交

undefined

undefined

Submit Operations

提交操作

Submitting Changes

提交变更

bash

undefined

bash

undefined

Submit default changelist (opens editor for description)

提交默认变更列表（打开编辑器输入描述）

p4 submit

Submit specific changelist

提交特定变更列表

p4 submit -c 12345

Submit with description

带描述提交

p4 submit -d "Fix player movement bug"

p4 submit -d "修复玩家移动bug"

Submit specific files from default changelist

提交默认变更列表中的特定文件

p4 submit file.txt

Submit and reopen files for further editing

提交并重新打开文件以进行进一步编辑

p4 submit -r -c 12345

undefined

p4 submit -r -c 12345

undefined

Pre-Submit Checks

提交前检查

bash

undefined

bash

undefined

Check what will be submitted

查看即将提交的内容

p4 opened -c default

Check for conflicts before submit

提交前检查冲突

p4 sync p4 resolve

Verify files are correct

验证文件正确性

p4 diff -se //... # Files that differ from depot

p4 diff -se //... # 与仓库版本不同的文件

Check changelist description

检查变更列表描述

p4 change -o 12345

undefined

p4 change -o 12345

undefined

Status Commands

状态命令

Workspace Status

工作区状态

bash

undefined

bash

undefined

Files open for edit/add/delete

已打开用于编辑/添加/删除的文件

p4 opened

Files that need sync

需要同步的文件

p4 sync -n //...

Files modified but not opened (reconcile needed)

已修改但未打开的文件（需要 reconcile）

p4 status

Reconcile local changes with depot

协调本地变更与仓库

p4 reconcile //...

undefined

p4 reconcile //...

undefined

Depot Status

仓库状态

bash

undefined

bash

undefined

List files in depot

列出仓库中的文件

p4 files //depot/project/...

List files with specific pattern

列出匹配特定模式的文件

p4 files //depot/project/....cs

Get file info

获取文件信息

p4 fstat //depot/project/file.txt

Detailed file info

详细文件信息

p4 fstat -Ol //depot/project/file.txt

undefined

p4 fstat -Ol //depot/project/file.txt

undefined

Reconcile Operations

协调操作

Finding Untracked Changes

查找未追踪的变更

bash

undefined

bash

undefined

Find all local changes not in Perforce

查找所有未在Perforce中记录的本地变更

p4 reconcile //...

Preview reconcile

预览协调操作

p4 reconcile -n //...

Reconcile specific types

协调特定类型的变更

p4 reconcile -e //... # Edited files p4 reconcile -a //... # Added files p4 reconcile -d //... # Deleted files

p4 reconcile -e //... # 已编辑文件 p4 reconcile -a //... # 已添加文件 p4 reconcile -d //... # 已删除文件

Reconcile to specific changelist

协调到特定变更列表

p4 reconcile -c 12345 //...

undefined

p4 reconcile -c 12345 //...

undefined

Common Workflows

常见工作流

Daily Sync Workflow

日常同步工作流

bash

undefined

bash

undefined

1. Check for open files

1. 检查已打开的文件

p4 opened

2. Sync latest

2. 同步最新版本

p4 sync

3. Resolve any conflicts

3. 解决任何冲突

p4 resolve

4. Continue working

4. 继续工作

undefined

undefined

Edit-Submit Workflow

编辑-提交工作流

bash

undefined

bash

undefined

1. Open file for edit

1. 打开文件进行编辑

p4 edit file.txt

2. Make changes

2. 进行修改

... edit file ...

... 编辑文件 ...

3. Verify changes

3. 验证变更

p4 diff file.txt

4. Submit

4. 提交

p4 submit -d "Description of changes"

undefined

p4 submit -d "变更描述"

undefined

Add New Files Workflow

添加新文件工作流

bash

undefined

bash

undefined

1. Create files locally

1. 在本地创建文件

... create files ...

... 创建文件 ...

2. Add to Perforce

2. 添加到Perforce

p4 add newfile.txt

3. Verify

3. 验证

p4 opened

4. Submit

4. 提交

p4 submit -d "Add new feature files"

undefined

p4 submit -d "添加新功能文件"

undefined

Best Practices

最佳实践

Always sync before editing - Avoid conflicts
Use descriptive changelist descriptions - Help others understand
Submit related changes together - Atomic commits
Revert unchanged files with
```
p4 revert -a
```
Check
p4 opened
before leaving for the day
Use
p4 reconcile
to catch local changes
Preview with
-n
before destructive operations
Use exclusive locks for binary files
Don't submit broken code - Test first
Keep changelists small - Easier to review/revert

编辑前务必同步 - 避免冲突
使用描述性的变更列表说明 - 帮助他人理解变更内容
相关变更一起提交 - 原子提交
使用
p4 revert -a
撤销未修改的文件
下班前检查
p4 opened
使用
p4 reconcile
捕获本地变更
执行破坏性操作前用
-n
预览
对二进制文件使用独占锁
不要提交有问题的代码 - 先测试
保持变更列表小型化 - 便于评审和撤销

Troubleshooting

故障排除

Issue	Solution
"File not on client"	Run `p4 sync` first
"Can't edit - not synced"	Sync file, then edit
"Can't clobber writable file"	Use `p4 sync -f` or fix permissions
"File already open"	Check `p4 opened -a` for who has it
"Out of date"	Sync and resolve before submit
"No such file"	Check path, use `p4 files` to verify

问题	解决方案
"File not on client"	先运行 `p4 sync`
"Can't edit - not synced"	同步文件后再编辑
"Can't clobber writable file"	使用 `p4 sync -f` 或修复权限
"File already open"	运行 `p4 opened -a` 查看谁打开了文件
"Out of date"	提交前先同步并解决冲突
"No such file"	检查路径，使用 `p4 files` 验证文件是否存在

tools-p4-basics

Original

Translation

Perforce Basics

Perforce 基础操作

Overview

概述

When to Use

适用场景

Core Concepts

核心概念

File States

文件状态

Revision Specifiers

版本指定符

Specific revision number

特定版本号

Head revision (latest)

最新版本（Head）

Changelist number

变更列表编号

Label

标签

Date/time

日期/时间

Revision range

版本范围

Sync Operations

同步操作

Basic Sync

基础同步

Sync entire workspace to head

将整个工作区同步到最新版本

Sync specific path

同步特定路径

Sync specific file

同步特定文件

Sync to specific revision

同步到特定版本

Sync to specific changelist

同步到特定变更列表

Sync Options

同步选项

Preview sync (don't actually sync)

预览同步（实际不执行同步）

Force sync (re-download even if up to date)

强制同步（即使已最新也重新下载）

Parallel sync (faster for many files)

并行同步（多文件时更快）

Safe sync (don't clobber writable files)

安全同步（不覆盖可写文件）

Sync and show affected files

同步并显示受影响的文件

Selective Sync

选择性同步

Sync only specific file types

仅同步特定文件类型

Sync excluding paths (use workspace view instead)

排除路径同步（建议使用工作区视图替代）

Or sync specific subdirectories

或同步特定子目录

Edit Operations

编辑操作

Opening Files for Edit

打开文件进行编辑

Edit single file

编辑单个文件

Edit multiple files

编辑多个文件

Edit files in directory

编辑目录中的文件

Edit with specific changelist

在特定变更列表中编辑

Edit to default changelist

在默认变更列表中编辑

Check Edit Status

检查编辑状态

See files open for edit

查看已打开用于编辑的文件

See files open in specific changelist