Perforce Shelving

Overview

概述

Shelving stores pending changes on the Perforce server without submitting them. This enables code review, work-in-progress backup, sharing between workspaces, and collaboration.

Shelving（暂存）可将待提交的变更存储在Perforce服务器上，无需实际提交。这支持代码评审、在研工作备份、工作区之间的共享及协作。

When to Use

使用场景

Backing up work-in-progress
Sharing changes for code review
Switching between tasks
Transferring work between workspaces
Parking changes temporarily
Pre-submit review (Swarm)

备份在研工作
共享变更以进行代码评审
切换任务
在工作区之间转移工作
临时搁置变更
提交前评审（Swarm）

Core Concepts

核心概念

Shelving vs Submitting

Shelving vs 提交

Feature	Shelving	Submitting
Stored on server	Yes	Yes
Creates revision	No	Yes
Visible to others	Yes (optional)	Yes
Reversible	Easy delete	Need revert
Affects depot	No	Yes
Builds triggered	Usually no	Usually yes

特性	Shelving	提交
存储在服务器	是	是
创建版本	否	是
对他人可见	是（可选）	是
可撤销	易删除	需要回退
影响代码库（depot）	否	是
触发构建	通常不会	通常会

Basic Shelving

基础暂存操作

Shelve Changes

暂存变更

bash

undefined

bash

undefined

Shelve all files in changelist

p4 shelve -c 12345

Shelve specific files

p4 shelve -c 12345 file1.txt file2.txt

Shelve and keep files open

p4 shelve -c 12345

Shelve default changelist

p4 shelve

Replace existing shelf

p4 shelve -f -c 12345

Shelve with delete of local files (submit-like)

p4 shelve -c 12345 p4 revert -c 12345 //...

undefined

p4 shelve -c 12345 p4 revert -c 12345 //...

undefined

View Shelved Changes

查看暂存的变更

bash

undefined

bash

undefined

List shelved changelists

p4 changes -s shelved

List your shelved changelists

p4 changes -s shelved -u $P4USER

Describe shelved changelist

p4 describe -S 12345

List files in shelf

p4 describe -S -s 12345

Diff shelved file vs depot

p4 diff2 //depot/file.txt //depot/file.txt@=12345

undefined

p4 diff2 //depot/file.txt //depot/file.txt@=12345

undefined

Unshelve Changes

恢复暂存的变更

bash

undefined

bash

undefined

Unshelve to same changelist

p4 unshelve -s 12345

Unshelve to different changelist

p4 unshelve -s 12345 -c 12346

Unshelve to new changelist

p4 unshelve -s 12345 -c default

Then move to new CL if desired

Unshelve specific files

p4 unshelve -s 12345 file.txt

Force unshelve (overwrite local changes)

p4 unshelve -s 12345 -f

undefined

p4 unshelve -s 12345 -f

undefined

Delete Shelf

删除暂存内容

bash

undefined

bash

undefined

Delete shelved files from changelist

p4 shelve -d -c 12345

Delete specific files from shelf

p4 shelve -d -c 12345 file.txt

Delete shelf completely

p4 shelve -d -c 12345 //...

Promote shelf to commit (delete shelf after submit)

p4 submit -e 12345

undefined

p4 submit -e 12345

undefined

Shelving Workflows

暂存工作流

Work-in-Progress Backup

在研工作备份

bash

undefined

bash

undefined

End of day - shelve your work

p4 shelve -c 12345 -f

Next day - continue working

Files already open, shelf is backup

If workspace lost, unshelve to recover

p4 unshelve -s 12345

undefined

p4 unshelve -s 12345

undefined

Task Switching

任务切换

bash

undefined

bash

undefined

Working on Feature A (CL 12345)

Urgent bug needs fixing

Shelve Feature A work

p4 shelve -c 12345

Revert local changes (keep shelf)

p4 revert -c 12345 //...

Work on bug fix

p4 edit bugfile.cs

... fix bug ...

p4 submit -d "Fix critical bug"

Resume Feature A

p4 unshelve -s 12345

undefined

p4 unshelve -s 12345

undefined

Code Review Workflow

代码评审工作流

bash

undefined

bash

undefined

Developer: Shelve for review

p4 shelve -c 12345 echo "Please review CL 12345"

Reviewer: Get shelved changes to review workspace

p4 unshelve -s 12345 -c default

Review code...

Reviewer: Revert after review (or keep to test)

p4 revert //...

Developer: After approval, submit

p4 submit -c 12345 p4 shelve -d -c 12345 # Clean up shelf

undefined

p4 submit -c 12345 p4 shelve -d -c 12345 # Clean up shelf

undefined

Share Between Workspaces

工作区之间共享

bash

undefined

bash

undefined

Workspace A: Shelve changes

p4 shelve -c 12345

Workspace B: Get shelved changes

(in different workspace)

p4 unshelve -s 12345 -c default

Now both workspaces have the changes

undefined

undefined

Pre-Integration Testing

预集成测试

bash

undefined

bash

undefined

Shelve feature branch changes

p4 shelve -c 12345

In integration workspace:

Sync to main

p4 sync //depot/main/...

Unshelve feature changes

p4 unshelve -s 12345

Test integration

... run tests ...

If tests pass, developer can submit

If tests fail, developer can fix

undefined

undefined

Advanced Shelving

高级暂存操作

Shelve with Resolve

带冲突解决的暂存恢复

bash

undefined

bash

undefined

When unshelving conflicts with current workspace

Preview unshelve conflicts

p4 unshelve -n -s 12345

Unshelve and resolve

p4 unshelve -s 12345 p4 resolve -am # Auto-merge

Or force overwrite

p4 unshelve -f -s 12345

undefined

p4 unshelve -f -s 12345

undefined

Update Existing Shelf

更新已有的暂存内容

bash

undefined

bash

undefined

Make more changes

p4 edit file.txt

... edit file ...

Update shelf with new changes

p4 shelve -f -c 12345

-f (force) replaces existing shelf

undefined

undefined

Partial Shelving

部分暂存

bash

undefined

bash

undefined

Shelve only some files from changelist

p4 shelve -c 12345 important.cs critical.cs

Leave other files unshelved but still open

undefined

undefined

Shelve Across Streams

跨流暂存

bash

undefined

bash

undefined

Shelve in one stream

p4 shelve -c 12345

Unshelve to different stream (if mappings allow)

May need branch mapping

p4 unshelve -s 12345 -b branch_mapping

undefined

p4 unshelve -s 12345 -b branch_mapping

undefined

Shelf Management

暂存内容管理

Find Old Shelves

查找旧的暂存内容

bash

undefined

bash

undefined

Find your old shelves

p4 changes -s shelved -u $P4USER

Find shelves older than 30 days

p4 changes -s shelved -u $P4USER | while read line; do CL=$(echo $line | awk '{print $2}') DATE=$(p4 change -o $CL | grep "^Date:" | awk '{print $2}') echo "$CL: $DATE" done

undefined

p4 changes -s shelved -u $P4USER | while read line; do CL=$(echo $line | awk '{print $2}') DATE=$(p4 change -o $CL | grep "^Date:" | awk '{print $2}') echo "$CL: $DATE" done

undefined

Clean Up Old Shelves

清理旧的暂存内容

bash

#!/bin/bash

bash

#!/bin/bash

cleanup-shelves.sh

Delete shelves older than 30 days

CUTOFF=$(date -v-30d +%Y/%m/%d)

p4 changes -s shelved -u $P4USER | while read line; do CL=$(echo $line | awk '{print $2}') DATE=$(echo $line | awk '{print $4}')

if [[ "$DATE" < "$CUTOFF" ]]; then
    echo "Deleting old shelf: $CL ($DATE)"
    p4 shelve -d -c $CL //...
fi

done

undefined

CUTOFF=$(date -v-30d +%Y/%m/%d)

p4 changes -s shelved -u $P4USER | while read line; do CL=$(echo $line | awk '{print $2}') DATE=$(echo $line | awk '{print $4}')

if [[ "$DATE" < "$CUTOFF" ]]; then
    echo "Deleting old shelf: $CL ($DATE)"
    p4 shelve -d -c $CL //...
fi

done

undefined

Shelf Statistics

暂存内容统计

bash

undefined

bash

undefined

Count files in shelf

p4 describe -S -s 12345 | grep "^..." | wc -l

Size of shelved files

p4 describe -S -s 12345 | grep "^..." | while read line; do FILE=$(echo $line | awk '{print $1}') p4 fstat -Ol "$FILE@=$CL" 2>/dev/null | grep fileSize done

undefined

p4 describe -S -s 12345 | grep "^..." | while read line; do FILE=$(echo $line | awk '{print $1}') p4 fstat -Ol "$FILE@=$CL" 2>/dev/null | grep fileSize done

undefined

Swarm Integration

Swarm集成

Shelve for Swarm Review

为Swarm评审暂存变更

bash

undefined

bash

undefined

Create review-ready changelist

p4 change # Add description with review info

Shelve for Swarm

p4 shelve -c 12345

Swarm automatically detects and creates review

Or trigger manually:

POST to Swarm API

undefined

undefined

Update Review

更新评审内容

bash

undefined

bash

undefined

Make changes based on feedback

p4 edit file.txt

... make changes ...

Update shelf (triggers review update in Swarm)

p4 shelve -f -c 12345

undefined

p4 shelve -f -c 12345

undefined

Commit After Approval

批准后提交

bash

undefined

bash

undefined

After review approved in Swarm

p4 submit -e 12345

-e submits shelved files directly

Cleans up shelf automatically

undefined

undefined

Best Practices

最佳实践

Shelve frequently - Backup work in progress
Use descriptive changelist names - Easy to identify shelves
Clean up old shelves - Don't leave orphaned shelves
Force update with
```
-f
```
when re-shelving
Verify unshelve - Check files are correct
Delete shelf after submit - Keep server clean
Use for code review - Before committing
Don't rely solely on shelves - Not a permanent backup
Communicate shelf numbers - For collaboration
Test unshelved code - Before submitting

频繁暂存 - 备份在研工作
使用描述性的变更列表名称 - 便于识别暂存内容
清理旧的暂存内容 - 不要留下无人维护的暂存
重新暂存时使用
-f
强制更新
验证恢复的暂存内容 - 检查文件是否正确
提交后删除暂存内容 - 保持服务器整洁
用于代码评审 - 提交前进行评审
不要仅依赖暂存内容 - 这不是永久备份
告知他人暂存的变更列表编号 - 便于协作
测试恢复的暂存代码 - 提交前进行测试

Troubleshooting

故障排除

Issue	Solution
"Files not shelved"	Check files are open in changelist
"Can't unshelve - conflicts"	Use `-f` to force or resolve
"Shelf not found"	Check changelist number, may be deleted
"No permission to unshelve"	Check protections, may need owner
"Files differ"	Use `-f` to replace or resolve
"Can't delete shelf"	Must delete all files first

问题	解决方案
"Files not shelved"	检查文件是否在变更列表中处于打开状态
"Can't unshelve - conflicts"	使用 `-f` 强制恢复或解决冲突
"Shelf not found"	检查变更列表编号，可能已被删除
"No permission to unshelve"	检查权限设置，可能需要拥有者权限
"Files differ"	使用 `-f` 替换或解决差异
"Can't delete shelf"	必须先删除所有暂存文件

Common Commands Reference

常用命令参考

bash

undefined

bash

undefined

Shelve

p4 shelve -c CL # Shelve changelist p4 shelve -f -c CL # Replace existing shelf p4 shelve -d -c CL # Delete shelf

Unshelve

p4 unshelve -s CL # Unshelve to same CL p4 unshelve -s CL -c TARGET # Unshelve to different CL p4 unshelve -f -s CL # Force unshelve

View

p4 describe -S CL # View shelved changelist p4 changes -s shelved # List all shelves p4 changes -s shelved -u USER # List user's shelves

Submit shelved

p4 submit -e CL # Submit shelf directly

undefined

p4 submit -e CL # Submit shelf directly

undefined

tools-p4-shelving

Original

Translation

Perforce Shelving

Perforce Shelving

Overview

概述

When to Use

使用场景

Core Concepts

核心概念

Shelving vs Submitting

Shelving vs 提交

Basic Shelving

基础暂存操作

Shelve Changes

暂存变更

Shelve all files in changelist

Shelve all files in changelist

Shelve specific files

Shelve specific files

Shelve and keep files open

Shelve and keep files open

Shelve default changelist

Shelve default changelist

Replace existing shelf

Replace existing shelf

Shelve with delete of local files (submit-like)

Shelve with delete of local files (submit-like)

View Shelved Changes

查看暂存的变更

List shelved changelists

List shelved changelists

List your shelved changelists

List your shelved changelists

Describe shelved changelist

Describe shelved changelist

List files in shelf

List files in shelf

Diff shelved file vs depot

Diff shelved file vs depot

Unshelve Changes

恢复暂存的变更

Unshelve to same changelist

Unshelve to same changelist

Unshelve to different changelist

Unshelve to different changelist

Unshelve to new changelist

Unshelve to new changelist

Then move to new CL if desired

Then move to new CL if desired

Unshelve specific files

Unshelve specific files

Force unshelve (overwrite local changes)

Force unshelve (overwrite local changes)

Delete Shelf

删除暂存内容

Delete shelved files from changelist

Delete shelved files from changelist

Delete specific files from shelf

Delete specific files from shelf

Delete shelf completely

Delete shelf completely

Promote shelf to commit (delete shelf after submit)

Promote shelf to commit (delete shelf after submit)

Shelving Workflows

暂存工作流

Work-in-Progress Backup

在研工作备份

End of day - shelve your work

End of day - shelve your work

Next day - continue working

Next day - continue working

Files already open, shelf is backup

Files already open, shelf is backup

If workspace lost, unshelve to recover

If workspace lost, unshelve to recover

Task Switching

任务切换

Working on Feature A (CL 12345)