To retrieve files from the depot into your client workspace, issue the p4 sync command. You cannot sync files that are not in your client view. For details about specifying client views, see Refining workspace views.

C:\bruno_ws>p4 sync
//depot/dev/main/bin/bin.linux24x86/readme.txt#1 - added as c:\bruno_ws\dev\main\bin\bin.linux24x86\readme.txt
//depot/dev/main/bin/bin.ntx86/glut32.dll#1 - added as c:\bruno_ws\dev\main\bin\bin.ntx86\glut32.dll
//depot/dev/main/bin/bin.ntx86/jamgraph.exe#2 - added as c:\bruno_ws\dev\main\bin\bin.ntx86\jamgraph.exe
[...]

The p4 sync command adds, updates, or deletes files in the client workspace to bring the workspace contents into agreement with the depot. If a file exists within a particular subdirectory in the depot, but that directory does not exist in the client workspace, the directory is created in the client workspace when you sync the file. If a file has been deleted from the depot, p4 sync deletes it from the client workspace.

To sync revisions of files prior to the latest revision in the depot, use revision specifiers. For example, to sync the first revision of Jamfile, which has multiple revisions, issue the following command:

p4 sync //depot/dev/main/jam/Jamfile#1

For more details, refer to Specifying file revisions.

To sync groups of files or entire directories, use wildcards. For example, to sync everything in and below the jam folder, issue the following command:

p4 sync //depot/dev/main/jam/...

For more details, see Perforce wildcards.

The Perforce service tracks which revisions you have synced. For maximum efficiency, Perforce does not resync an already-synced file revision. To resync files you (perhaps inadvertently) deleted manually, specify the -f option when you issue the p4 sync command.

To add files to the depot, create the files in your workspace, then issue the p4 add command. The p4 add command opens the files for add in the default pending changelist. The files are added when you successfully submit the default pending changelist. You can open multiple files for add using a single p4 add command by using wildcards. You cannot use the Perforce ... wildcard to add files recursively.

For platform-specific details about adding files recursively (meaning files in subdirectories), see "Adding a Directory Tree" in the Perforce knowledge base:

http://answers.perforce.com/articles/KB_Article/Adding-a-Directory-Tree

C:\bruno_ws\dev\main\docs\manuals>p4 add *.txt
//depot/dev/main/docs/manuals/installnotes.txt#1 - opened for add
//depot/dev/main/docs/manuals/requirements.txt#1 - opened for add

Change: new
Client: bruno_ws
User:   bruno
Status: new
Description:
        <enter description here>
Type:   public
Files:
    //depot/dev/main/docs/manuals/installnotes.txt   # add
    //depot/dev/main/docs/manuals/requirements.txt   # add

You must enter a description in the Description: field. You can delete lines from the Files: field. Any files deleted from this list are moved to the next default changelist, and are listed the next time you submit the default changelist.

If you are adding a file to a directory that does not exist in the depot, the depot directory is created when you successfully submit the changelist.

You can restrict a changelist from public view by changing the Type: field from public to restricted. In general, if a changelist is restricted, only those users with list access to at least one of the files in the changelist are permitted to see the changelist description.

Sometimes development processes result in the creation of extraneous content that should not be submitted to the depot. Compilers produce object files and executables during development, text editors and word processors produce backup files, and you may have your own personal conventions for notes on work in progress.

To ignore files (or groups of files) when adding, create a file with a list of file specifications you wish to ignore, and set the P4IGNORE environment variable to point to this file.

When you add files, the full local path and parent directories of any file to be added are searched for P4IGNORE files. If any P4IGNORE files exist, their rules are added to a list, with greater precedence given to P4IGNORE rules closest to the file being added.

The syntax for P4IGNORE files is not the same as Perforce syntax. Instead, it is similar to that used by other versioning systems: files are specified in local syntax, a # character at the beginning of a line denotes a comment, a ! character at the beginning of a line excludes the file specification, and the * wildcard matches substrings. The Perforce wildcard of "..." is not permitted.

# Ignore .p4ignore files
.p4ignore
# Ignore object files, shared libraries, executables
*.dll
*.so
*.exe
*.o
# Ignore all text files except readme file
*.txt
!readme.txt

To override (or ignore) the P4IGNORE file, use the -I option with the p4 add, p4 reconcile, or p4 status commands.

To open a file for edit, issue the p4 edit command. When you open a file for edit, Perforce enables write permission for the file in your workspace and adds the file to a changelist. If the file is in the depot but not in your workspace, you must sync it before you open it for edit. You must open a file for edit before you attempt to edit the file.

p4 sync //depot/dev/command.c
//depot/dev/command.c#8 - added as c:\bruno_ws\dev\command.c

p4 edit //depot/dev/command.c
//depot/dev/command.c#8 - opened for edit

To remove an open file from a changelist and discard any changes you made, issue the p4 revert command. When you revert a file, Perforce restores the last version you synced to your workspace. If you revert a file that is open for add, the file is removed from the changelist but is not deleted from your workspace.

p4 revert *.txt
//depot/dev/main/docs/manuals/installnotes.txt#none - was add, abandoned
//depot/dev/main/docs/manuals/requirements.txt#none - was add, abandoned

To preview the results of a revert operation without actually reverting files, specify the -n option when you issue the p4 revert command.

To delete files from the depot, you open them for delete by issuing the p4 delete command, then submit the changelist in which they are open. When you delete a file from the depot, previous revisions remain, and a new head revision is added, marked as "deleted." You can still sync previous revisions of the file.

When you issue the p4 delete command, the files are deleted from your workspace but not from the depot. If you revert files that are open for delete, they are restored to your workspace. When you successfully submit the changelist in which they are open, the files are deleted from the depot.

p4 delete //depot/dev/main/docs/manuals/vendor.doc
//depot/dev/main/docs/manuals/vendor.doc#1 - opened for delete

To create a numbered changelist, issue the p4 change command. This command displays the changelist form. Enter a description and make any desired changes; then save the form and exit the editor.

All files open in the default changelist are moved to the new changelist. When you exit the text editor, the changelist is assigned a number. If you delete files from this changelist, the files are moved back to the default changelist.

C:\bruno_ws\>p4 sync //depot/dev/main/jam/*.c
[list of files synced...]

C:\bruno_ws>p4 edit //depot/dev/main/jam/*.c
[list of files opened for edit...]

C:\bruno_ws\dev\main\docs\manuals>p4 change

    [Enter description and save form]

Change 777 created with 33 open file(s).

The numbers assigned to submitted changelists reflect the order in which the changelists were submitted. When a changelist is submitted, Perforce might renumber it, as shown in the following example.

To submit a pending changelist, issue the p4 submit command. When you issue the p4 submit command, a form is displayed, listing the files in the changelist. You can remove files from this list. The files you remove remain open in the default pending changelist until you submit them or revert them.

To submit specific files that are open in the default changelist, issue the p4 submit filename command. To specify groups of files, use wildcards. For example, to submit all text files open in the default changelist, type p4 submit "*".txt. (Use quotation marks as an escape code around the * wildcard to prevent it from being interpreted by the local command shell).

After you save the changelist form and exit the text editor, the changelist is submitted to the Perforce service, and the files in the depot are updated. After a changelist has been successfully submitted, only a Perforce administrator can change it, and the only fields that can be changed are the description and user name.

If an error occurs when you submit the default changelist, Perforce creates a numbered changelist containing the files you attempted to submit. You must then fix the problems and submit the numbered changelist using the -c option.

Perforce enables write permission for files that you open for edit and disables write permission when you successfully submit the changelist containing the files. To prevent conflicts with Perforce's management of your workspace, do not change file write permissions manually.

Before committing a changelist, p4 submit briefly locks all files being submitted. If any file cannot be locked or submitted, the files are left open in a numbered pending changelist. By default, the files in a failed submit operation are left locked unless the submit.unlocklocked configurable is set. Files are unlocked even if they were manually locked prior to submit if submit fails when submit.unlocklocked is set.

To delete a pending changelist, you must first remove all files and jobs associated with it and then issue the p4 change -d changenum command. Related operations include the following:

Changelists that have already been submitted can be deleted only by a Perforce administrator. See the Perforce Server Administrator's Guide: Fundamentals for more information.

To rename or move files, you must first open them for add or edit, and then use the p4 move command:

p4 move source_file target_file

To move groups of files, use matching wildcards in the source_file and target_file specifiers. To move files, you must have Perforce write permission for the specified files. For details about Perforce permissions, see the Perforce Server Administrator's Guide: Fundamentals.

When you rename or move a file using p4 move, the versioning service creates an integration record that links it to its deleted predecessor, preserving the file's history. Integration is also used to create branches and to propagate changes. For details, see Integrating changes.

The Perforce shelving feature enables you to temporarily make copies of your files available to other users without checking the changelist into the depot.

Shelving is useful for individual developers who are switching between tasks or performing cross-platform testing before checking in their changes. Shelving also enables teams to easily hand off changes and to perform code reviews.

$ p4 edit //depot/dev/command.c
//depot/dev/command.c#9 - opened for edit
...

$ p4 shelve
Change 123 created with 1 open file(s).
Shelving files for change 123.
edit //depot/dev/command.c#9
Change 123 files shelved.

Shelved files remain open in the changelist from which they were shelved. (To add a file to an existing shelved changelist, you must first open that file in that specific changelist.) You can continue to work on the files in your workspace without affecting the shelved files. Shelved files can be synced to other workspaces, including workspaces owned by other users. For example:

C:\bruno_ws\dev> p4 unshelve -s 123 //depot/dev/command.c
//depot/dev/command.c#9 - unshelved, opened for edit

When you shelve a file, the version on the shelf is unaffected by commands that you perform in your own workspace, even if you revert the file to work on something else.

$ p4 revert //depot/dev/command.c
//depot/dev/command.c#9 - was edit, reverted

$ p4 unshelve -s 123 -c 124 //depot/dev/command.c
//depot/dev/command.c#9 - unshelved, opened for edit

The p4 submit command has a -e option that enables the submitting of shelved files directly from a changelist. All files in the shelved change must be up to date and resolved. Other restrictions can apply in the case of files shelved to stream targets; see the P4 Command Reference for details. (To avoid dealing with these restrictions, you can always move the shelved files into a new pending changelist before submitting that changelist.)

C:\bruno_ws\dev> p4 shelve -d -c 124
Shelve 124 deleted.

C:\bruno_ws\dev> p4 submit -c 124
Change 124 submitted.

To display brief information about changelists, use the p4 changes command. To display full information, use the p4 describe command. The following table describes some useful reporting commands and options.

For more information, see Changelist reporting.