tools-p4-basics

Perforce 基础知识

概述

Perforce（P4）是一种集中式版本控制系统，针对大型代码库和二进制资源进行了优化。本技能涵盖日常操作的基本知识。

使用场景

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

核心概念

文件状态

状态	描述	更改状态的命令
不在 depot 中	文件存在于本地，但未纳入跟踪	p4 add
已同步	文件与 depot 版本一致	-
已编辑	已打开以供编辑，并在本地修改	p4 edit，然后修改
已添加	已标记为添加到 depot	p4 add
已删除	已标记为从 depot 删除	p4 delete
版本过期	depot 中有更新版本	p4 sync

修订版本说明符

# Specific revision number
file.txt#3

# Head revision (latest)
file.txt#head

# Changelist number
file.txt@12345

# Label
file.txt@release_1.0

# 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

同步操作

基本同步

# 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

同步选项

# 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

选择性同步

# 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/...

编辑操作

打开文件以供编辑

# 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

检查编辑状态

# 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

添加操作

添加新文件

# 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

文件类型

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

# 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

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

删除操作

删除文件

# 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

处理已删除的文件

# 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

撤销操作

撤销更改

# 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 //...

还原到指定修订版本

# 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

提交操作

提交更改

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

# Submit specific files from default changelist
p4 submit file.txt

# Submit and reopen files for further editing
p4 submit -r -c 12345

提交前检查

# 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

# Check changelist description
p4 change -o 12345

状态命令

工作区状态

# Files open for edit/add/delete
p4 opened

# Files that need sync
p4 sync -n //...

# Files modified but not opened (reconcile needed)
p4 status

# Reconcile local changes with depot
p4 reconcile //...

Depot 状态

# 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

对账操作

查找未跟踪的更改

# Find all local changes not in 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

# Reconcile to specific changelist
p4 reconcile -c 12345 //...

常见工作流

每日同步工作流

# 1. Check for open files
p4 opened

# 2. Sync latest
p4 sync

# 3. Resolve any conflicts
p4 resolve

# 4. Continue working

编辑-提交工作流

# 1. Open file for edit
p4 edit file.txt

# 2. Make changes
# ... edit file ...

# 3. Verify changes
p4 diff file.txt

# 4. Submit
p4 submit -d "Description of changes"

添加新文件工作流

# 1. Create files locally
# ... create files ...

# 2. Add to Perforce
p4 add newfile.txt

# 3. Verify
p4 opened

# 4. Submit
p4 submit -d "Add new feature files"

最佳实践

1. 编辑前务必先同步 - 避免冲突
2. 使用描述清晰的更改列表说明 - 帮助其他人了解更改
3. 将相关更改一起提交 - 确保提交的原子性
4. 使用 p4 revert -a 撤销未更改的文件
5. 离开前检查 p4 opened
6. 使用 p4 reconcile 捕获本地更改
7. 执行破坏性操作前，先使用 -n 预览
8. 对二进制文件使用独占锁
9. 不要提交有问题的代码 - 先进行测试
10. 保持更改列表精简 - 更易于审查和撤销

故障排除

问题	解决方案
"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 验证