Getting started with Perforce

To start using Perforce, you need to configure your client computer to access the Perforce server. For more information, see Introducing Perforce.

P4GT offers access to a number of Perforce commands. Use the Perforce menu to:

  • Add files to the Perforce depot.

  • Check files into and out of the Perforce depot.

  • Lock a file while you have it checked out, preventing others from modifying it.

  • Undo or revert your add or check out.

NOTE: When you revert a checked-out file, all changes you made after check-out are discarded and the file is restored to the last checked-in version (which is not necessarily the last version you saved).

  • View detailed Perforce and file information, including revision history, file status, and connection information.

To learn more about these commands, see the Perforce menu overview.

To uninstall P4GT

Method one: Run the P4GT installer and choose Uninstall.

Method two: Use the appropriate Windows control panel (for example, Add or Remove Programs), choose Perforce Plug-in for Graphical Tools, and uninstall it.


About_Perforce_and_P4GT

Perforce is a software configuration management tool. The files managed by Perforce reside in a depot. To work on files, you open and edit them in your client workspace. When you're done, you check in changed files, using the Perforce menu options. The depot keeps track of all the current and previous revisions of a file.

P4GT integrates Perforce into drawing tools including Autodesk 3ds Max, Autodesk Maya, Autodesk Softimage and Adobe Photoshop. For a complete list of supported programs and versions, refer to the P4GT release notes. For technical details about Perforce, see the Perforce documentation.


Getting more help

For more information about using Perforce, consult the following sources:

  • For information about using Perforce: See the documentation available at our web site.

  • For information about maintaining your Perforce installation: Refer to the Perforce System Administrator's Guide.

If you cannot find the answers to your question in this help system, call (510) 864-7400 or send email to support@perforce.com.

Please send any comments about Perforce technical documentation, including this help system, to manual@perforce.com.


Perforce menu overview

The Perforce menu contains the following items:

Perforce menu option | Description
Add to Perforce | Adds the file that you are currently working on to Perforce. For more information, see Adding files to Perforce.
Check Out | Checks a file out of Perforce so you can edit it. For more information, see Checking files out of Perforce.
Check In... | Checks files into Perforce, to store your changes in the depot. For more information, see Checking files in to Perforce.
Lock/Unlock file | Prevents other users from checking in a file while you have it open, to prevent conflicts.
Undo Add/Check Out | Discards any changes that you have made to the files in your workspace. This operation is known as reverting a file.
Results of Last Command... | Displays the results of the last Perforce command that you performed.
File Status... | Displays the status of the current file, including the file name and path, as well as Perforce information.
File History... | Displays the current file's name and path, as well as the past revisions of the file, and the changelists associated with it.
Checked-out Files... | Displays a list of all of the files that you currently have checked out of Perforce
Perforce Information... | Displays your Perforce connection information. For more information about these fields, see the Perforce technical documentation.
Get Latest Revision from Perforce... | Enables you to browse and open files that are stored in the depot (as opposed to your workspace).
Options... | Enables you to set P4GT options. For more information on these options, see Configuring P4GT.
Help... | Displays the online help.
About P4GT... | Displays information about the version of P4GT that you are running.
Disconnect from Server/Connect to Server | Deactivate/activate Perforce operations.


Adding files to Perforce

To add a files to Perforce, the files that you want to add must be in your client workspace. If the files is not in your client workspace, P4GT displays an error message and the files is not added.

  • To add a file to Perforce:

  1. Choose Perforce > Add to Perforce. If prompted to check the file into Perforce, enter in a description of your changes.

  2. Click Submit. P4GT confirms that your file has been successfully added.

  3. Click OK.

For troubleshooting help, see Troubleshooting: Adding files.


Retrieving files from the depot

The depot is the central repository for files under Perforce control. Files that you and your coworkers create and modify are stored in the depot when you check the files in.

To retrieve a copy of a file in the depot:

  1. Choose Perforce > Get Latest Revision from Perforce..., browse to the desired file, and click Open. The file is copied to your workspace and opened.

  2. If you want to change the file, choose Perforce > Check out.

To view an older version of an open file, choose Perforce > File History, click the desired version, then click View. To copy the older version to your workspace, click Sync.


Checking files out of Perforce

To work on a file that has been checked into Perforce, you must check the file out. There are two ways to check a file out of Perforce: automatically and manually.

When you open a file that is checked into Perforce, you are prompted to check the file out. To check the file out at this time, click OK.

If you click Cancel, the file opens in "Read-only" mode. You can edit this file, but you cannot save it (unless you use Save As... and specify a different file name). To edit and save a file that is in Perforce, you must first check it out.

To check a file out of Perforce:

  1. Open the file.

  2. Choose Perforce > Check Out.

NOTE: By default, you are prompted to check files out after you open them. You can configure P4GT not to prompt by disabling the When opening a file, check out from Perforce option.

For troubleshooting help, see Troubleshooting: Checking files out. If you are working offline (without network access), see Working offline for details about checking out files offline.


Checking files into Perforce

When you are finished working on a file that has been checked out of Perforce, you need to check it back in, to ensure that your changes are stored in the depot.

  • To check a file into Perforce:

  1. Choose Perforce > Check in... The Submit dialog is displayed.

  2. In the Description field, enter in a brief description of the work you have done on the file. Note that you must enter something into this field before submitting.

  3. If prompted, choose the files that you want to check in. The file that you are working on is automatically selected.

  4. If you want to check in your changes and immediately check the file out again (for example, to save a interim version), check Keep checked out.

  5. Click Submit.

NOTE: You can change the status of Perforce jobs (which track work to be done) when you submit a file. To close jobs using P4GT, you must either set a jobview or attach jobs to changelists. These tasks must be done outside of P4GT. Consult your Perforce administrator for details.

  • To discard changes:

To discard your changes and restore the version you checked out, choose Perforce >Undo Add/Checkout.


Working offline

Typically your computer is connected the network and has access to your Perforce server. However, if you work remotely, you might need to be able to work without network access. P4GT supports working offline.

To work offline, choose Perforce > Disconnect from Server. To restore the connection, choose Perforce > Connect to Server. Note that, if you inadvertently lose network access to the Perforce server, P4GT displays a warning dialog and automatically disconnects. When the connection is restored, choose Perforce > Connect to Server to resume the connection.

When working offline, you cannot check files in or out using the Perforce menu entries. If you want to work on a file that you did not check out while connected, perform the following steps:

  • Before editing a file: using Windows Explorer, browse to the file, right click it, and choose Properties. Uncheck its Read-only attribute and click OK.

  • After editing the file: reset its Read-only attribute.

  • After reconnecting: open the file and choose Perforce > Check out. At this point you can make more changes or check the file in.


Configuring P4GT

To configure P4GT, choose Perforce > Options, configure settings as desired, then click OK. You can configure the following settings.

  • Check In/Check Out tab

When adding a file to Perforce check in immediately:

    • To automatically check in a file that you have just added to perforce, choose Always.

    • To disable automatic check-in, choose Never -- files are not checked in until you choose Perforce > Check In...

    • To display a "Check In?" prompt after you add a file, choose Prompt.

When checking out a file, automatically lock it: When you lock a file, other users can check the file out, but cannot check it in until you unlock it, check it in, or revert it

    • To lock files when you check them out, choose Always.

    • To disable automatic locking, choose Never.

    • To display a "Lock?" prompt, choose Prompt. .

When checking in a file: to list all checked-out files when you check a file in, check View other files in changelist. Checking this option enables you to check in multiple files at one time.

Informational prompts: enables you to configure the level of verbosity for P4GT. Check to display confirmation of successful operations (errors are always displayed, regardless of this setting).

  • Open/Close tab

When opening a file, check out from Perforce:

    • To automatically check out files when you open them, click Always.

    • To disable automatic check-out, click Never.

    • To display a "Check Out?" prompt, click Prompt.

When reopening a file after undo (reverting), check out from Perforce:

    • To automatically check out files when you reopen them after reverting, click Always.

    • To disable automatic check-out, click Never.

    • To display a "Check Out?" prompt, click Prompt.

When closing a file, check in to Perforce:

    • To automatically check in files when you close them, click Always.

    • To disable automatic check-in, click Never.

    • To display a "Check In?" prompt, click Prompt.

When opening a file, update external file references: for Maya and 3ds, automatically syncs the head revision of any external files referenced by the main file. If other users are working on files that are referenced by your files, you can ensure that you always have the most recent version of their files by enabling this option.

    • To automatically sync any external files when you open a file you close them, click Always.

    • To disable automatic syncing, click Never.

    • To display a "Sync?" prompt, click Prompt.

When closing a file, prompt to revert file from Perforce: gives you the option to discard any changes you have made and restore the file from the depot to your workspace.

NOTE: Most of these options can also be configured through the "Do not show this dialog again" checkbox that is displayed on dialogs in P4GT.


Adding files to Perforce

Troubleshooting: Adding files

  • When I try to add a file to Perforce, I get an error stating that the file is not "under client's root." What does this mean?

To add a file to Perforce successfully, the file must be saved in your client workspace. If you do not know what this means, see your Perforce administrator.


Checking files out

Troubleshooting: Checking files out

  • When I try to check out a file from Perforce, I get an error stating that the "newest version in the Perforce depot has been deleted." What does this mean?

The file that you are trying to check out has been deleted from Perforce. If you are familiar with Perforce, you can use P4V or the Perforce command-line client to undo the delete. If you are not familiar with Perforce, contact your Perforce administrator.

You cannot access this file in Perforce until the file has been recovered.


Glossary

A
access level
atomic change transaction

B
base
binary file type
branch
branch specification
branch view

C
changelist
changelist form
changelist number
change review
checkpoint
client form
client name
client root
client side
client view
client workspace
codeline
conflict
counter

D
default changelist
default depot
deleted file
delta
depot
depot root
depot side
depot syntax
detached
diff

E
exclusionary access
exclusionary mapping

F
file conflict
file pattern
file repository
file revision
file tree
file type
fix
form
full-file storage

G
group

H
have list
head revision

I
integrate
Inter-File Branching

J
job
job specification
job view
journal
journaling

L
label
label view
lazy copy
license file
list access
local depot
local syntax
lock
log

M
mapping
MD5 checksum
merge
merge file
metadata
modification time

N
nonexistent revision
numbered changelist

O
open file
owner

P
P4
P4D
pending changelist
Perforce server
protections

R
RCS format
read access
remote depot
reresolve
resolve
resource fork
reverse delta storage
revert
review access
review daemon
revision number
revision range
revision specification

S
server root
status
submit
subscribe
super access
symlink file type
sync

T
target file
text file type
theirs
three-way merge
tip revision
trigger
two-way merge
typemap

U
user

V
view

W
wildcard
write access

Y
yours


glossary001

 A permission assigned to a user to control which Perforce commands the user can execute.


glossary002

 The grouping of operations that affect multiple files into a single transaction. If all operations in the transaction succeed, all the files are updated. If any operation in the transaction fails, none of the files are updated.


glossary003

 The file revision that two newer, conflicting file revisions were commonly based on.


glossary004

 A non-text file.


glossary005

 (noun) A codeline created by copying another codeline, as opposed to a codeline that was created by adding original files.
(verb) To create a codeline by integrating files.


glossary006

 The Perforce form you use to modify a branch.


glossary007

 A specification of the branching relationship between two codelines in the depot. Each branch view has a unique name, and defines how files are mapped from the originating codeline to the target codeline.


glossary008

 The process of sending email to users who have registered their interest in changes made to specified files in the depot.


glossary009

 An atomic change transaction in Perforce. The changes specified in the changelist are not stored in the depot until the changelist is submitted to the depot.


glossary010

 The Perforce form you use to modify a changelist.


glossary011

 The unique numeric identifier of a changelist.


glossary012

 A copy of the underlying server metadata at a particular moment in time.


glossary013

 The Perforce form you use to define a client workspace.


glossary014

 A name that uniquely identifies the current client workspace.


glossary015

 The root directory of a client workspace.


glossary016

 The right-hand side of a mapping within a client view, specifying where the corresponding depot files are located in the client workspace.


glossary017

 A set of mappings that specifies the correspondence between file locations in the depot and the client workspace.


glossary018

 Directories on the client computer where you work on file revisions that are managed by Perforce. By default this name is set to the name of the host machine on which the client workspace is located. To override the default name, set the P4CLIENT environment variable. Client workspaces, labels and branch specifications cannot share the same name.


glossary019

 A set of files that evolve collectively. One codeline can be branched from another, allowing each set of files to evolve separately.


glossary020

 One type of conflict occurs when two users open a file for edit. One user submits the file; after which the other user can't submit because of a conflict. The cause of this type of conflict is two users opening the same file.
The other type of conflict is when users try to merge one file into another. This type of conflict occurs when the comparison of two files to a common base yields different results, indicating that the files have been changed in different ways. In this case, the merge can't be done automatically and must be done by hand.


glossary021

 A numeric variable used by Perforce to track changelist numbers in conjunction with the review feature.


glossary022

 The changelist used by Perforce commands, unless a numbered changelist is specified.


glossary023

 The depot name that is assumed when no name is specified. The default depot name is "depot."


glossary024

 In Perforce, a file with its head revision marked as deleted. Older revisions of the file are still available.


glossary025

 The differences between two files.


glossary026

 A file repository on the Perforce server. It contains all versions of all files ever submitted to the server. There can be multiple depots on a single server.


glossary027

 The left side of any client view mapping, specifying the location of files in a depot.


glossary028

 The root directory for a depot.


glossary029

 Perforce syntax for specifying the location of files in the depot.


glossary030

 A client computer that is not connected to a Perforce server.


glossary031

 A set of lines that don't match when two files are compared (whereas a conflict is a pair of unequal diffs between each of two files and a common third file).


glossary032

 A permission that denies access to the specified files.


glossary033

 A view mapping that excludes specific files.


glossary034

 In a three-way file merge, a situation in which two revisions of a file differ from each other and from their base file.
Also: the result of an attempt to submit a file that is not an edit of the head revision of the file in the depot, which typically occurs when another user opens the file for edit after you have opened the file for edit.


glossary035

 Perforce command line syntax that enables you to specify files using wildcards.


glossary036

 The master copy of all files; shared by all users. In Perforce, this is called the depot.


glossary037

 A specific version of a file within the depot. Each revision is assigned a number, in sequence. Any revision can be accessed in the depot by its revision number, for example: testfile#3.


glossary038

 All the subdirectories and files under a given root directory.


glossary039

 An attribute that determines how Perforce stores and diffs a particular file. Examples of file types are text and binary.


glossary040

 A job that has been linked to a changelist.


glossary041

 Screens displayed by certain Perforce commands. For example, you use the Perforce change form to enter comments about a particular changelist and to verify the affected files.


glossary042

 The method by which Perforce stores revisions of binary files in the depot: every file revision is stored in full. Contrast this with reverse delta storage, which Perforce uses for text files.


glossary043

 A list of Perforce users.


glossary044

 The list of file revisions currently in the client workspace.


glossary045

 The most recent revision of a file within the depot. Since file revisions are numbered sequentially, this will also be the highest-numbered revision of that file.


glossary046

 To compare two sets of files (two codeline branches) and determine which changes in one set are applicable to the other; determine whether those changes have already been propagated; and propagate outstanding changes.


glossary047

 Perforce's proprietary branching mechanism.


glossary048

 A user-defined unit of work tracked by Perforce. The job template determines what information is tracked. The template can be modified by the Perforce system administrator.


glossary049

 A specification containing the fields and valid values stored for a Perforce job.


glossary050

 A string used to find jobs that match particular criteria.


glossary052

 A file containing a record of every change made to the Perforce server's metadata since the time of the last checkpoint.


glossary053

 The process of recording changes made to the Perforce server's metadata.


glossary054

 A named list of user-specified file revisions.


glossary055

 The view that specifies which file names in the depot can be stored in a particular label.


glossary056

 A method used by Perforce to make internal copies of files without duplicating file content in the depot. Lazy copies minimize the consumption of disk space by storing references to the original file instead of copies of the file.


glossary057

 Ensures that the number of Perforce users on your site does not exceed the number for which you have paid.


glossary058

 A protection level that enables you to run reporting commands but prevents access to the contents of files.


glossary059

 Any depot located on the current Perforce server.


glossary060

 The operating-system-specific syntax for specifying a file name.


glossary061

 A Perforce file lock prevents other clients from submitting the locked file.


glossary062

 Error output from the Perforce server. By default, error output is written to standard error. To specify a log file, set the P4LOG environment variable, or use the p4d -L flag.


glossary063

 A single line in a view, consisting of a left side and a right side that specify the correspondences between files in the depot and files in a client, label, or branch. The left side specifies the depot file and the right side specifies the client files.


glossary064

 The method used by Perforce to verify the integrity of archived files.


glossary065

 The process of combining the contents of two conflicting file revisions into a single file.


glossary066

 A file generated by Perforce from two conflicting file revisions.


glossary067

 The data stored by the Perforce server that describes the files in the depot, the current state of client workspaces, protections, users, clients, labels, and branches. Metadata includes all the data stored in the server except for the actual contents of the files.


glossary068

 The time a file was last changed.


glossary069

 A completely empty revision of any file. Syncing to a nonexistent revision of a file removes it from your workspace. An empty file revision created by 'p4 delete' and the #none revision specifier are examples of nonexistent file revisions.


glossary070

 A pending changelist to which Perforce has assigned a number.


glossary071

 A file that you are changing in your client workspace.


glossary072

 The Perforce user who created a particular client, branch, or label.


glossary073

 The Perforce command line interface program, and the command you issue to execute Perforce commands from the operating system command line.


glossary074

 The program on the Perforce server that manages the depot and the metadata.


glossary075

 The Perforce GUI application that compares two files.


glossary076

 The Perforce Windows GUI client program.


glossary077

 A changelist that has not been submitted.


glossary078

 The Perforce depot and metadata on a central host. Also the program that manages the depot and metadata.


glossary079

 The permissions stored in the Perforce server's protections table.


glossary080

 Revision Control System format. Used for storing revisions of text files. RCS format uses reverse delta encoding for file storage. Perforce uses RCS format to store text files.


glossary081

 A protection level that enables you to read the contents of files managed by Perforce.


glossary082

 A depot located on a server other than the current Perforce server.


glossary083

 The process of resolving a file after the file is resolved and before it is submitted


glossary084

 The process you use to reconcile the differences between two revisions of a file.


glossary085

 One fork of a Macintosh file. (Macintosh files are composed of a resource fork and a data fork.) You can store resource forks in Perforce depots as part of an AppleSingle file by using Perforce's apple file type. (In pre-99.2 Perforce, use the resource file type).


glossary086

 The method that Perforce uses to store revisions of text files. Perforce stores the changes between each revision and its previous revision, plus the full text of the head revision.


glossary087

 To discard the changes you have made to a file in the client workspace.


glossary088

 A special protections level that includes read and list accesses, and grants permission to run the review command.


glossary089

 Any daemon process that uses the p4 review command.


glossary090

 A number indicating which revision of the file is being referred to.


glossary100

 A range of revision numbers for a specified file, specified as the low and high end of the range. For example, myfile#5,7 specifies revisions 5 through 7 of a file called "myfile"..


glossary101

 A suffix to a filename that specifies a particular revision of that file. Revision specifiers can be revision numbers, change numbers, label names, date/time specifications, or client names.


glossary102

 The directory in which the server program stores its metadata and all the shared files. To specify the server root, set the P4ROOT environment variable.


glossary103

 For a changelist, a value that indicates whether the changelist is new, pending or submitted. For a job, a value that indicates whether the job is open, closed, or suspended. You can customize job statuses.


glossary104

 To send a pending changelist and changed files to the Perforce server for processing.


glossary105

 To register to receive email whenever changelists that affect particular files are submitted.


glossary106

 An access level that gives the user permission to run every Perforce command, including commands that set protections, obliterate files, verify files with an MD5 signature, and set up connections to remote depots.


glossary107

 Perforce file type assigned to symbolic links.


glossary108

 To copy a file revision (or set of file revisions) from the depot to a client workspace.


glossary109

 The file that receives the changes when you are integrating changes between a branched codeline and the original codeline.


glossary110

 A file that contains only ASCII or Unicode text.


glossary111

 When you resolve a file conflict, the revision in the depot with which the client file is merged. When you are working with branched files, theirs is the donor file.


glossary112

 The process of combining three file revisions. During a three-way merge, you can identify where conflicting changes have occurred and specify how you want to resolve the conflicts.


glossary113

 In Perforce, the head revision. Tip revision is a term used by some other SCM systems.


glossary114

 A script automatically invoked by the Perforce server when changelists are submitted.


glossary115

 The process of combining two file revisions. In a two-way merge, you can see differences between the files but cannot see conflicts.


glossary116

 A Perforce table in which you assign Perforce file types to files.


glossary117

 The identifier that Perforce uses to determine who is performing an operation.


glossary118

 A description of the relationship between two sets of files.


glossary119

 A special character used to match other characters in strings. Perforce wildcards are:
* matches anything except a slash
... matches anything including slashes
%d used for parameter substitution in views.


glossary120

 A protection level that enables you to run commands that alter the contents of files in the depot. Write access includes read and list accesses.


glossary121

 The edited version of a file in the client workspace, when you resolve a file. Also, the target file when you integrate a branched file.