Perforce Operations Manual

Perforce (P4) is a centralized version control system. Core concepts: depot, workspace/client (workspace mapping), changelist (change set, similar to Git's staging), shelve (shelve to server, similar to git stash push), stream (branching model).

The p4 command relies on the environment variables P4PORT, P4USER, and P4CLIENT, or they can be specified via the -p/-u/-c parameters.

Workspace

A workspace defines the mapping from depot paths to local paths. Each workspace has a unique client name (usually equal to hostname).

p4 client                              # Create/edit current workspace (opens editor)
p4 client -o                          # View workspace configuration (without editing)
p4 client -o <name>                   # View specified workspace
p4 client -d <name>                   # Delete workspace
p4 clients                            # List all workspaces
p4 clients -u <user>                  # Workspaces for a specific user

# Key View field: depot → local mapping
# //depot/project/... //client/project/...
# -//depot/project/build/... //client/project/build/...   ← Exclude directory

Sync and Update

p4 sync                               # Sync current workspace (only pulls files with changes)
p4 sync -f                            # Force overwrite local (re-pulls even if file hasn't changed)
p4 sync -f #none                      # Clear local (does not delete files but marks them as not having)
p4 sync //depot/path/...              # Sync only specific path
p4 sync @changelist                   # Sync to specified changelist
p4 sync ...@2025/01/15                # Sync to specified date

Changelist

P4 has no staging area—changes automatically enter the default changelist. Before submitting, it is common to create a numbered changelist to manage a group of changes.

# View
p4 changes -m 10                      # Last 10 commits
p4 changes -u <user> -m 10            # Commits by a specific user
p4 changes -s submitted               # View only submitted ones
p4 describe <changelist>              # View changelist details (file diff + description)

# Operations
p4 opened                             # Files opened in current workspace (similar to git status)
p4 opened -c <changelist>             # Files for specified changelist

p4 change                             # Create new numbered changelist (opens editor)
p4 change -o                         # View current changelist content

p4 reopen -c <changelist> <file>      # Move file to specified changelist
p4 revert <file>                      # Revert changes (similar to git checkout -- file)
p4 revert -c <changelist> //...       # Revert entire changelist

p4 submit -c <changelist>             # Submit specified changelist
p4 submit -d "description"            # Submit default changelist

Shelve

Shelve unfinished changes to the server without submitting. Other developers can unshelve to view or take over.

p4 shelve -c <changelist>             # Shelve to server
p4 shelve -c <changelist> -f          # Overwrite existing shelve
p4 unshelve -s <changelist>           # Retrieve shelved changes
p4 unshelve -s <changelist> -c <new>  # Retrieve to new changelist
p4 shelve -d -c <changelist>          # Delete shelve
p4 describe -S -s <changelist>        # View shelved content

# List all shelved changelists
p4 changes -s shelved -u <user>

File Operations

p4 add <file>                         # Add new file (similar to git add)
p4 edit <file>                        # Checkout for edit (similar to git concepts, P4 files are read-only by default)
p4 delete <file>                      # Mark for deletion
p4 move <src> <dst>                   # Move/rename (preserves history)
p4 copy <src> <dst>                   # Copy (records branch source)

p4 diff <file>                        # View changes (similar to git diff)
p4 diff -f <file>                     # Force diff (even if file is not checked out)
p4 diff2 -q //depot/...@cl1 //depot/...@cl2  # Differences between two changelists

p4 annotate <file>                    # Annotate, similar to git blame
p4 filelog <file>                     # File history
p4 filelog -l <file>                  # Full commit descriptions

Stream (Branching Model)

p4 stream -o //depot/stream-name      # View stream configuration
p4 streams                            # List all streams

Debugging

p4 info                               # Server information (version, address, username)
p4 where //depot/path/file            # View actual local path mapped from depot path
p4 have                               # List local existing files (similar to synced versions)
p4 files //depot/path/...             # List files in depot
p4 fstat <file>                       # File status: head revision, last change, lock...
p4 login                              # Login (enter password)
p4 login -s                           # View login status
p4 logout
p4 set                                # View environment variables (P4PORT/P4USER/P4CLIENT)