Perforce, or more specifically, Perforce Helix Core, is a revision control software often used in the semiconductor industry. It is made up of one or more servers to manage shared file repositories, and clients to provide an interface to check files in and out, resolve conflicts, and more.

The command-line interface to Perforce Helix Core is called p4. The Command Guide and User Guide contain very useful information.

The following sections are broken up into where the commands would be used.

Information

p4 info

The p4 info command displays information about the current Helix Server application.

➜ p4 info
Perforce client error:
	Connect to server failed; check $P4PORT.
	TCP connect to perforce:1666 failed.
	nodename nor servname provided, or not known

It’s required that the $P4PORT environment variable is set before calling p4 info, otherwise p4 won’t know where the server is located.

➜ export P4PORT=localhost:1666
➜ p4 info
User name: cody.cziesler
Client name: cody-mbp
Client host: cody-mbp.lan
Client unknown.
Current directory: /Users/cody.cziesler
Peer address: 127.0.0.1:51638
Client address: 127.0.0.1
Server address: localhost:1666
Server root: /Users/cody.cziesler/p4-tutorial/server
Server date: 2024/06/07 09:55:38 -0400 EDT
Server uptime: 00:11:15
Server version: P4D/MACOSX12ARM64/2024.1/2596294 (2024/05/09)
Server license: none
Case Handling: insensitive

And if $P4CLIENT is set, p4 info will show information about the client.

➜ export P4CLIENT=cody.cziesler_base1
➜ p4 info
User name: cody.cziesler
Client name: cody.cziesler_base1
Client host: cody-mbp.lan
Client root: /Users/cody.cziesler/p4-tutorial/base1
Client stream: //JamCode/main
Current directory: /Users/cody.cziesler/p4-tutorial/base1
Peer address: 127.0.0.1:51673
Client address: 127.0.0.1
Server address: localhost:1666
Server root: /Users/cody.cziesler/p4-tutorial/server
Server date: 2024/06/07 10:02:44 -0400 EDT
Server uptime: 00:18:21
Server version: P4D/MACOSX12ARM64/2024.1/2596294 (2024/05/09)
Server license: none
Case Handling: insensitive

p4 print

The p4 print command prints the contents of a depot file revision.

➜ p4 print fileA#1
//JamCode/main/fileA#1 - move/add change 3 (text)

➜ p4 print fileA#2
//JamCode/main/fileA#2 - edit change 6 (text)
Some text here.

➜ p4 print fileA#3
//JamCode/main/fileA#3 - edit change 7 (text)
Some text here.
Some more text here.
And a bit more.

p4 annotate

The p4 annoate command prints file lines along with their revisions to annotate where each line was added.

The -u option displays the name of the user who modified the change and the date when the modification occurred.

➜ p4 annotate fileA
//JamCode/main/fileA#3 - edit change 7 (text)
2: Some text here.
3: Some more text here.
3: And a bit more.

➜ p4 annotate -u fileA
//JamCode/main/fileA#3 - edit change 7 (text)
2: cody.cziesler 2024/06/07 Some text here.
3: cody.cziesler 2024/06/07 Some more text here.
3: cody.cziesler 2024/06/07 And a bit more.

p4 fstat

The p4 fstat command dumps file information in a tagged format that is suitable for parsing by scripts.

➜ p4 fstat fileA
... depotFile //JamCode/main/fileA
... clientFile /Users/cody.cziesler/p4-tutorial/base1/fileA
... isMapped
... headAction move/add
... headType text
... headTime 1717774213
... headRev 1
... headChange 3
... headModTime 1717768126
... pathSource //JamCode/main
... pathType share
... pathPermissions writable
... effectiveComponentType none
... haveRev 1

p4 files

The p4 files command provides information about files in the depot without accessing their contents.

➜ p4 files //...
//JamCode/main/d1/f1#3 - move/add change 11 (text)
//JamCode/main/d2/f1#2 - move/delete change 11 (text)
//JamCode/main/file1#2 - move/delete change 3 (text)
//JamCode/main/file2#2 - delete change 3 (text)
//JamCode/main/fileA#6 - edit change 13 (text)
//JamCode/main/fileB#1 - add change 5 (text)

➜ p4 files -e //...
//JamCode/main/d1/f1#3 - move/add change 11 (text)
//JamCode/main/fileA#6 - edit change 13 (text)
//JamCode/main/fileB#1 - add change 5 (text)

This command can also be used to search for a file by using wildcards.

➜ p4 files "//.../fileA"
//JamCode/main/fileA#6 - edit change 13 (text)

p4 filelog

The p4 filelog command prints detailed information about files’ revisions.

➜ p4 filelog fileA
//JamCode/main/fileA
... #4 change 9 edit on 2024/06/07 by cody.cziesler@cody.cziesler_base2 (text) 'Something'
... #3 change 7 edit on 2024/06/07 by cody.cziesler@cody.cziesler_base2 (text) 'More text to fileA'
... #2 change 6 edit on 2024/06/07 by cody.cziesler@cody.cziesler_base1 (text) 'Added text to fileA'
... #1 change 3 move/add on 2024/06/07 by cody.cziesler@cody.cziesler_base1 (text) 'Changes for JIRA-1001'
... ... moved from //JamCode/main/file1#1
//JamCode/main/file1
... #1 change 2 add on 2024/06/07 by cody.cziesler@cody.cziesler_base1 (text) 'Initial add of file1 and file2'
... ... moved into //JamCode/main/fileA#1

p4 have

The p4 have command lists the files and revisions that are synced to the client workspace.

➜ p4 have
//JamCode/main/d1/f1#1 - /Users/cody.cziesler/p4-tutorial/base1/d1/f1
//JamCode/main/fileA#1 - /Users/cody.cziesler/p4-tutorial/base1/fileA

File Tasks

p4 sync

The p4 sync command updates the client workspace to reflect the contents of the depot.

➜ p4 sync
//JamCode/main/fileB#1 - added as /Users/cody.cziesler/p4-tutorial/base2/fileB

This command also can update to a specific changelist.

➜ p4 sync @1
//JamCode/main/d1/f1#3 - deleted as /Users/cody.cziesler/p4-tutorial/base2/d1/f1
//JamCode/main/fileA#6 - deleted as /Users/cody.cziesler/p4-tutorial/base2/fileA
//JamCode/main/fileB#1 - deleted as /Users/cody.cziesler/p4-tutorial/base2/fileB

The -n option previews what files will be modified, without actually modifying the client workspace

➜ p4 sync -n
//JamCode/main/fileC#1 - added as /Users/cody.cziesler/p4-tutorial/base1/fileC

p4 add

The p4 add command opens a file in a client workspace for addition to the depot.

Notice that only files need to be added – the directory structure is preserved but cannot be explicitly added.

When files are added, opened, or deleted – they are by default done in the default changelist.

➜ p4 add d1/f1
//JamCode/main/d1/f1#1 - opened for add

p4 edit

The p4 edit command opens a file for edit in the client workspace. By default, the file is opened on the default changelist.

➜ p4 open file1
//JamCode/main/file1#1 - opened for edit

p4 delete

The p4 delete command opens a file in a client workspace for deletion from the depot. The files are immediately removed from the client workspace, but won’t be deleted from the depot until the corresponding changelist is committed with p4 submit.

➜ p4 delete file2
//JamCode/main/file2#1 - opened for delete

p4 move

The p4 move command moves a file from one location to another within the branch. The file must already be opened for edit or add.

➜ p4 move file1 fileA
//JamCode/main/fileA#1 - moved from //JamCode/main/file1#1

p4 revert

The p4 revert command discards changes made to open files.

➜ p4 revert ./...
//JamCode/main/fileA#1 - was edit, reverted

p4 submit

The p4 submit command commits a pending changelist and the files it contains to the depot.

The -d description switch allows a description to be set on the command-line.

➜ p4 submit -d "Changes for JIRA-1001"
Submitting change 3.
Locking 4 files ...
add //JamCode/main/d1/f1#1
move/delete //JamCode/main/file1#2
delete //JamCode/main/file2#2
move/add //JamCode/main/fileA#1
Change 3 submitted.

Locking

p4 lock

The p4 lock command locks an opened file against other users submitting changes to the file.

➜ p4 open fileA
//JamCode/main/fileA#4 - opened for edit

➜ p4 lock fileA
//JamCode/main/fileA - locking

➜ p4 opened
//JamCode/main/fileA#4 - edit default change (text) *locked*

p4 unlock

The p4 unlock command releases the lock on one or more files.

Note that a file is also unlocked when it is committed with p4 submit.

➜ p4 unlock fileA
//JamCode/main/fileA - unlocking

➜ p4 opened
//JamCode/main/fileA#4 - edit default change (text)

Changelists

Changelists contain a list of files, their revision numbers, and the operations to be performed on the files. An unsubmitted changelist is called a pending changelist.

Changelists are submitted as an all-or-nothing operation, meaning either all files are submitted together or if an error occurs none of the files are submitted.

Numbers are assigned to changelists. The default changelist is a local changelist, and is assigned a number when it is submitted. Files are opened on the default changelist by default.

Changelists can be shelved to temporarily preserve work in progress.

p4 status

The p4 status command previews information about what files are marked for add, delete, or edit in order to reconcile a workspace with changes made outside of Helix Server.

➜ p4 status
d1/f1 - submit change default to add //JamCode/main/d1/f1#1
file1 - submit change default to move/delete //JamCode/main/file1#1
file2 - submit change default to delete //JamCode/main/file2#1
fileA - submit change default to move/add //JamCode/main/fileA#1
No file(s) to reconcile.

p4 opened

The p4 opened command lists files that are open in pending changelists.

➜ p4 opened
//JamCode/main/d1/f1#1 - add default change (text)
//JamCode/main/file1#1 - move/delete default change (text)
//JamCode/main/file2#1 - delete default change (text)
//JamCode/main/fileA#1 - move/add default change (text)

p4 describe

The p4 describe command provides information about changelists and files in changelists.

➜ p4 describe 3
Change 3 by cody.cziesler@cody.cziesler_base1 on 2024/06/07 11:30:13

  Changes for JIRA-1001

  Affected files ...

  ... //JamCode/main/d1/f1#1 add
  ... //JamCode/main/file1#2 move/delete
  ... //JamCode/main/file2#2 delete
  ... //JamCode/main/fileA#1 move/add

  Moved files ...

  ... //JamCode/main/fileA#1 moved from //JamCode/main/file1#1

  Differences ...

  ==== //JamCode/main/fileA#1 (text) ====

p4 reopen

The p4 reopen command moves opened files between changelists or changes the files’ type.

The -c default option moves the file onto the default changelist.

➜ p4 opened
//JamCode/main/fileA#3 - edit change 8 (text)

➜ p4 reopen -c default //...
//JamCode/main/fileA#3 - reopened; default change

➜ p4 opened
//JamCode/main/fileA#3 - edit default change (text)

p4 diff

The p4 diff command diffs workspace content to depot content.

➜ p4 diff fileA
==== //JamCode/main/fileA#6 - /Users/cody.cziesler/p4-tutorial/base2/fileA ====
1c1
< Some text here.
---
> Some text here. -- New
1c1
< Some text here.
---
> Some text here. -- New

By default, p4 diff uses the built-in p4 diff tool. However this can be changed by setting the $P4DIFF environment variable.

➜ export P4DIFF=vimdiff
➜ p4 diff fileA

p4 resolve

The p4 resolve command resolves conflicts between file revisions.

When resolving, a prompt will select how to merge the conflicted file.

➜ p4 submit -d "Changed fileA"
Submitting change 13.
//JamCode/main/fileA - must resolve before submitting
//JamCode/main/fileA - must resolve #5
Out of date files must be resolved or reverted.
Submit failed -- fix problems above then use 'p4 submit -c 13'.

➜ p4 resolve
/Users/cody.cziesler/p4-tutorial/base1/fileA - merging //JamCode/main/fileA#5
Diff chunks: 1 yours + 1 theirs + 0 both + 0 conflicting
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) am: a
//cody.cziesler_base1/fileA - merge from //JamCode/main/fileA

➜ p4 submit -c 13
Submitting change 13.
Locking 1 files ...
edit //JamCode/main/fileA#6
Change 13 submitted.

p4 undo

The p4 undo command undoes a range of revisions.

➜ p4 undo @10
//JamCode/main/d1/f1#2 - opened for move/add
... moved from/undid //JamCode/main/d2/f1#1

➜ p4 opened
//JamCode/main/d1/f1#2 - move/add default change (text)
//JamCode/main/d2/f1#1 - move/delete default change (text)

➜ p4 submit -d "Undo @10"
Submitting change 11.
Locking 2 files ...
move/add //JamCode/main/d1/f1#3
move/delete //JamCode/main/d2/f1#2
Change 11 submitted.

Shelves

p4 shelve

The p4 shelve command stores files from a pending changelist in the depot without submitting them.

Without any arguments, p4 shelve creates a new changelist, adds files from the user’s default changelist, and shelves the files into the depot.

➜ p4 shelve
Change 4 created with 1 open file(s).
Shelving files for change 4.
edit //JamCode/main/fileA#1
Change 4 files shelved.

The -r option can be used to replace all shelved files with the files opened in your workspace.

p4 unshelve

The p4 unshelve command restores shelved files from a pending change into a workspace. The -s shelvedchange option should be used to specify the changelist to unshelve.

➜ p4 unshelve -s 4
//JamCode/main/fileA#1 - unshelved, opened for edit

p4 reshelve

The p4 reshelve command copies shelved files from an existing shelve into a new shelve or one that has already been created.

➜ p4 shelve
Change 14 created with 1 open file(s).
Shelving files for change 14.
edit //JamCode/main/fileA#6
Change 14 files shelved.

➜ p4 reshelve -s 14
edit //JamCode/main/fileA#6
Change 15 files shelved.

Labels

Labels mark a version of a file or repository, allowing you to retrieve a past version of a file that was marked for a specific reason.

p4 label

The p4 label command creates or edits a label specification and its view.

➜ p4 label tag0001
Label tag0001 saved.

A list of labels can be printed with the p4 labels command.

➜ p4 labels
Label tag0001 2024/06/07 'Created by cody.cziesler. '

Note that files are not automatically tagged with a label (unless a revision is placed in the form) – the p4 labelsync command should be used to attach a label to files.

p4 labelsync

The p4 labelsync command synchronizes a label with the contents of the current client workspace. This can be used to recreate a workspace configuration.

➜ p4 files @tag0001
@tag0001 - no such file(s).

➜ p4 labelsync -l tag0001
//JamCode/main/d1/f1#1 - added
//JamCode/main/fileA#1 - added

➜ p4 files @tag0001
//JamCode/main/d1/f1#1 - add change 3 (text)
//JamCode/main/fileA#1 - move/add change 3 (text)

Common commands

Rename directories

The below snippet shows to rename a directory (from Stack Overflow).

➜ p4 edit d1/...
//JamCode/main/d1/f1#1 - opened for edit

➜ p4 move d1/... d2/...
//JamCode/main/d2/f1#1 - moved from //JamCode/main/d1/f1#1

Show shelves

➜ p4 -u $USER changes -s shelved
Change 4 on 2024/06/07 by cody.cziesler@cody.cziesler_base1 *pending* 'Updated fileA '

Delete a shelve

➜ p4 shelve -d -c 4
Shelved change 4 deleted.

TODO

  • Talk about branches, integrating, etc.

References