Perforce 98.2: Glossary

access level
A permission given to a user controlling which Perforce commands can be used. Access levels are assigned with p4 protect. The five access levels are list, read, write, review, and super.

add
An operation that takes a file in the client workspace and adds it as a new file to the depot.

atomic
Grouping a number of operations together such that either all of them occur, or none of them do. See atomic change transaction.

atomic change transaction
Grouping a number of files and operations together in a single changelist, such that when the changelist is submitted, either all the files are updated in the depot, or none of them are.

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

binary file
A non-ascii file. Whether a file is binary or ascii is determined by the C library call isascii(). Binary files are always stored in the depot in full.

branch

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

(verb) To create a codeline branch with p4 integrate.

Additionally, branch is often used as a synonym for branch view.

branch form
The form displayed when the p4 branch command is given.

branch view
A stored 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. Branch views are created with p4 branch and are subsequently referenced by p4 integrate.
See branch.

build management
Task performed by tools that manages the process of turning source code into product. Perforce does not have a build tool, built in, but Perforce Software offers a companion freeware build tool called Jam/MR at <www.perforce.com>.

change

An edit of a file.

In previous versions of Perforce, this term was used as a synonym for changelist.

changelist
A list of files, revision numbers of those files, and operations to be performed on those files. The commands p4 add, p4 edit, p4 delete, and p4 integrate all include files in a particular changelist, which is sent to the depot atomically when p4 submit is typed with no parameters.

changelist form
The form brought up by p4 change, and by p4 submit when submitting the default change.

changelist number
The number that a particular changelist is known by. The default changelist is assigned a number if a submit of the default changelist fails. Changelist numbers always increase in sequence.

change review
The process of sending email to users when files that they are interested in have changed within the depot.

checkpoint
A copy of the underlying server metadata at one moment in time. This is one half of the journaling process.

client
A stored record of a set of files being worked on. In the Perforce database, each client is a uniquely named entity that identifies

a workspace location,

a set of depot files (the client view), and

the status of the workspace copies of those files.

client form
The form brought up by the p4 client command to define a client workspace.

client name
A name that uniquely identifies the current client workspace. It is set through the P4CLIENT environment variable, or on the command-line with the -c flag.

client root
The root directory of a client workspace; the lowest level directory under which the managed files sit. The client root is set in the Root: field of the client form. If the client name is proj1, and the client root is /usr/joe/project1, then the file //proj1/docs/read.me is actually located on the client machine under /usr/joe/project1/docs/read.me.

client side
The right-hand side of a mapping within a client view. Expresses where the corresponding depot files are found within a client workspace.

client view
A set of mappings that express which files from the depot can be accessed from a particular client workspace, and where in the client workspace the depot files are mapped to. Client views are defined in the View: field of the form brought up by p4 client.

client workspace
A local copy of some or all of the files stored in the depot. These files are managed by Perforce; users may work on Perforce files only within a client workspace. Client workspaces are defined with the p4 client command.

codeline
A set of files that evolve collectively. One codeline can be branched from another, allowing both sets of files to evolve separately from the other.

command line
The interface that this Perforce manual describes. If you're looking at this glossary entry because you don't know what a command line is, and you're expecting to use a GUI, you're in the wrong manual.

conflict
See file conflict.

counter
A variable tracked and set by p4 review. Used internally by Perforce to track which changelists have and haven't been reviewed; users can create their own counters for use in their own daemons.

daemon
A program running in the background, usually on the Perforce server, although it can reside on other machines. Perforce provides a change review daemon; users can create their own to handle other needs.

database
Files in a Perforce server used to store the server metadata.

default changelist
The changelist used by p4 add, p4 edit, p4 delete, p4 submit, etc., unless a numbered changelist is provided to these commands with the -c flag. There is always a single default changelist in use for each client workspace.

default depot
The depot that is always available on a Perforce server. Its name is depot.

delete

To remove a file from the client workspace and from the depot with p4 delete followed by p4 submit. Deleted files are not actually erased from the depot; the head revision of the file is marked as being deleted, but older revisions of the file are still available.

To remove an existing client, label, or branch from the Perforce server. This is accomplished with the -d flag to p4 client, p4 label, and p4 branch.

delta
The line-by-line differences between one file revision and its next (or previous) revision.

delta storage
See reverse delta storage.

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

depot root
The root directory for a particular depot. For the default depot depot, the depot root is the depot subdirectory of the server root directory.

depot side
The left side of any client view mapping. The union of all depot sides of a client view specifies which files are available to the corresponding client workspace.

depot syntax
Perforce syntax, when applied to a file in the depot. A file called readme in the depot's doc subdirectory would be referred to in depot syntax as //depot/doc/readme.

detached
A client workspace not connected to a Perforce server with a functioning network connection is said to be detached. Permissions must be set on files using OS commands; Perforce is unable to open files for you.

difference marker
A named counter used by p4 review. Each difference marker keeps track of which changes have already been reviewed for the counter with that name.

distributed depot
A depot within another p4d server, accessed by the local p4d server acting as a proxy client.

donor file
The file from which changes are taken when propagating changes from one codeline to another. A donor file can come either from the branched codeline or the original codeline; this is determined by the use of the -r flag to p4 integrate.

edit
Opening a file in a client workspace with p4 edit. Perforce notes that the file has been opened, adds the file revision to a changelist, and turns on write privileges for this file within the client workspace. A file is opened for edit before it is edited with the system editor.

environment variable
A variable set in the operating system's command shell. Perforce utilizes environment variables that are passed to the p4 client or p4d server.

exclusionary mapping
A view mapping that excludes depot files from a client workspace. Exclusionary mappings begin with a minus sign. For example, to allow a client workspace to access all the files in the depot except for the file called secret, the view might look like this:
//depot/... //a_client/... -//depot/secret //a_client/secret

exclusionary access
A permission that denies access on the specified files. For example, the following permission denies Ed write permissions on all files in the directory secret:
write edk * -//depot/secret

fast
See Perforce.

file
In a client workspace, file has the usual meaning. A file in the depot consists of the head revision of the file, and every revision of the same file.

file conflict
A state in which the version of a file in the client workspace is not an edit of the head revision in the depot at submit time.

file pattern
An argument on a p4 command line specifying files using wildcards.

file reference
A file revision specification, like foo#3. Used specifically when storing pointers to files in lists such as a label. The label contains file references, not the contents of the files themselves.

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

file revision
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, like foo#3.

file tree
All the subdirectories and files under a given root directory.

file type
An attribute that determines how a particular file is handled by Perforce. The two basic Perforce file types are text and binary, but there are quite a few subtypes.

fix
A job that has been linked to a changelist with p4 fix, p4 submit, or p4 change. Under most circumstances, a fixed job has a status of closed, but this is not always true: when an open job is linked to a pending changelist, it is still open, and closed, fixed jobs can always be reopened or suspended.

form
Screens brought up by certain Perforce commands containing elements whose value needs to be changed. The form is displayed in an external editor; the editor used is defined by the environment variable P4EDIT.
The commands that bring up forms are p4 change, p4 client, p4 depot, p4 job, p4 label, p4 user, and sometimes p4 submit.

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

get
Formerly used to describe the process accomplished by p4 get, which has been renamed p4 sync. The p4 get command can still be used as a synonym for p4 sync. See sync.

GNU
Software provided by the Free Software Foundation. Most GNU software is system level software such as enhanced versions of standard UNIX utilities and language compilers.
GNU stands for "GNU's not UNIX".

have list
The list of file revisions that the Perforce server believes are currently in the client workspace. Generated by p4 have.

head revision
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 the file. To refer to the head revision of file foo, use foo#head.

integrate
To compare two sets of files (e.g., 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.

integration record
The data structure by which Perforce keeps track of integrated files. It tracks which revisions of which donor files were integrated into which target files.

Inter-File Branching
Perforce's branching mechanism. It differs from the branching mechanism used by most SCM systems, allowing arbitrary copies of files to be stored anywhere in the depot, and allowing these files to evolve separately. Additionally, changes made to any file can be propagated to the corresponding file in any branch.

job
A generic term for a defect report, system improvement request, or change order. An arbitrary textual description of some change intended to be made to the system.

job specification
A superuser-defined template for a Perforce job. New fields can be defined, and unneeded fields deleted.

job view
A string used to find jobs that match particular criteria; used with p4 jobs -e. For example, p4 jobs -e `name=joe status=open' will report all open jobs created by joe.

job tracking
Perforce's mechanism for keeping track of jobs. It is implemented via p4 job and p4 fix.

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

journaling
Keeping track of every change made to the Perforce server's metadata since one particular moment in time. Requires a checkpoint file and a journal file. Only the server's metadata is journaled; external processes need to be run to backup the depot's file revisions.

label
A user-configurable list of file revisions. Used to save "important" file configurations for later use. Any file included in a label can be referred to with the revision specifier @labelname; e.g. [email protected].

label view
The view that defines which files in the depot are stored in a particular label. This can be edited in the form brought up by p4 label. The left-hand side of each mapping represents a subtree of the depot's file tree; the right side represents the files' corresponding location within the label.

lazy copy
Action taken by p4 integrate when a copy is ostensibly performed: a virtual copy is done instead. Internally, metadata is stored indicating that the copy has not been done; the copy is actually performed when someone actually changes the branch copy and the branched original will no longer suffice.

license
Perforce's mechanism to ensure that our software is run on each site only by the number of users that have been paid for. Two users may be run on any Perforce server without a license or any form of payment. For more information on licensing, please send email to [email protected].

list access
A protections level giving the user permission to run reporting commands, such as p4 client, that give access to metadata. A user with only list access to a particular file can't run any commands that would allow them to read or write the contents of the file.

local depot
Any depot located on the current Perforce server. By default, only one such depot is constructed; others may be defined with p4 depot.

local syntax
The native name of a file on the client host, as would be used by other commands in that operating system. For example, file foo in joe's home directory in UNIX local syntax would be ~joe/foo, or /usr/joe/foo, etc.

lock
Locking a file with p4 lock ensures that no other clients will be able to submit the same file until the file is unlocked by the locking client. Files are automatically locked when submission starts, and unlocked when submission ends; they can be manually unlocked with p4 unlock.

log
Error output from the p4d server. By default, this is written to standard error; a specific file can be set in the P4LOG environment variable, or with the -L flag to p4d.

mapping
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.
(See also client view, branch view, label view).

merge
To combine the contents of two conflicting file revisions into a single file. This is accomplished with p4 resolve.

merge file
A file revision generated by Perforce from two conflicting file revisions. This file can be edited by the user during the p4 resolve process, producing a result acceptable to the user.

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

modtime
The modification time of a file that has been read from the depot into a client workspace. By default, the modtime is the time that the file was last written to the depot; this can be changed in the p4 client form to be the time that the file is read into the client workspace.

namespace
The pool of legal names for clients, branches, depots, and labels. Clients, branches, depots, and labels all share the same namespace; therefore a client cannot have the same name as any branch, depot, or label.

network connection
A TCP/IP connection between a Perforce client and Perforce server. Generally, users are expected to work within a functioning network connection; they can still edit client files without a network connection by following the instructions for working detached.

nonexistent revision
A special file revision; a completely empty revision of any file. Useful only to remove a file from the client workspace while leaving it intact in the depot: use p4 sync foo#none.

numbered changelist
A changelist that has been created by Perforce but that has not yet been submitted. A numbered changelist can be created manually, with p4 change -c, or is created automatically by Perforce when a submit of the default change has failed. Once a changelist has been assigned a number, it must be referred to by that number in all subsequent commands, e.g. p4 submit -c 31.

open
A file in a client workspace that has been included on a changelist with p4 add, p4 delete, p4 edit, or p4 integrate. The file is said to be open within the client workspace.

owner
The Perforce user who created a particular client, branch, or label. This can be changed through the form brought up by p4 client, p4 branch, or p4 label.

p4
The program invoked by users from a client to run all Perforce commands. It talks via TCP/IP to the Perforce server, mediating the interaction between the managed files in the client workspace and the master repository and metadata on the server host.

p4d
The program on the Perforce server that manages the depot and the metadata. It waits on a TCP/IP port for a connection from the client program.

pending change
An existing changelist that has not yet been submitted. These can be created manually with p4 change -c, and are automatically created when submission of the default change fails.

Perforce
The fast Software Configuration Management system.

Perforce server
See server.

Perforce syntax
A syntax for referring to files that remains invariant across operating systems. It consists of two slashes, followed by the depot or client name, followed by a slash, and then the name of the file specified relative to the depot or client root.

Perl
A scripting language available for most operating systems. Useful for creating programs that utilize Perforce commands, such as the change review daemon.

permission
See access.

port
A TCP/IP logical channel. Since every application on a host listens to a different port, the ports are used to funnel messages to the correct application. The p4d server program listens on the port assigned by P4PORT.

project
Generic term for some set of files kept by Perforce. One server might be storing source files for multiple projects.

propagate
To copy changes in one set of files to the branched copies of the same files, leaving the rest of the branch file intact; to make changes in a target set of files that are identical or functionally equivalent to changes in an originating set of files.

protections
The complete set of permissions as stored in the server's protections table.

pure integration
An integration in which changes to the target file incorporates only revisions from a single source file.

RCS format
Revision Control System algorithm and data structure for storing file revisions. Uses reverse delta encoding for file storage. This is the method used by Perforce. See also reverse delta encoding.

read access
A protections level giving the user permission to run commands, such as p4 sync, that allow them to read the contents of Perforce files stored in the depot. Read access includes list access.

refresh
To copy the contents of an unopened file from the depot into the client workspace.

remote depot
A depot located on a server other than the current Perforce server defined under P4PORT. Perforce superusers can make these depots accessible to the current server's clients for read-only access.

renumber
Perforce may renumber a changelist when it is submitted. Since change numbers are allocated sequentially, a change might have one number when it is created, and another when it is submitted.

reresolve
To run the resolve process a second time. This can be done only between the time a file is resolved and the time it is submitted

resolve
The process by which an integration is finalized by the user. The resolve process, run by p4 resolve, allows the user to decide whether to keep the integrated file, edit it, or accept some other revision of the file in place of the integrated revision.

resource fork
One fork of a Macintosh file. The Perforce file type is resource.

reverse delta storage
The method by which Perforce stores file revisions of text files within the depot. Rather than store every file revision in full, Perforce stores only the deltas from each revision to the one previous, storing the full text of only the head revision.

revert
To throw away a file in the client workspace, replacing it with the revision in the depot that was being edited. Files that were opened with p4 add are left in the client workspace; they are simply removed from the corresponding changelist. Reverting files can only be done before the files have been submitted.

review access
A special protections level given to the review daemon, or to any daemon created by a user. It includes read and list accesses, plus permission to run the p4 review command.

review daemon
Any daemon process written that uses the p4 review command. See also change review.

review marker
Any named counter used by p4 review. Counter values are stored as Perforce metadata, so their value remains the same from execution to execution of p4 review. Each review marker has its own name, hence its own value. The value of any counter can be accessed and set at any time. Review markers are commonly used to track which changelists have been processed by a particular daemon, but other uses are possible.

revision
A specific version of a file within the depot.

revision number
A number indicating which revision of the file is being referred to. Revision numbers start at 1, and increase sequentially. To refer to a particular revision of a file, append the pound sign and the revision number to the name of the file; e.g., the tenth revision of file foo would be referred to as foo#10.
The revision specification foo#10 is actually the same as the revision range specification foo#1,#10, since revision ten of the file encompasses all the changes made in the file from revision 1 to revision 10.

revision range
A range of revision numbers for a specified file, specified as the low and high end of the range. For example, foo#5,7 would access the fifth through seventh revisions of file foo.
Only a few commands allow revision ranges to be specified. The only non-reporting command that allows a revision range is p4 integrate.

revision specification
A suffix to filenames that specify a particular revision of that file. Revision specifiers can refer to files by revision number, change number, label name or client name.

root
A top level directory under which all accessible files are found. See client root, server root, depot root.

SCM
Commonly used abbreviation for Software Configuration Management.

Sendmail
A UNIX mail transfer agent that, like a post office, collects mail and figures out how to move it further along. Used by the Perforce change review daemon.

server
The Perforce depot and metadata on a central UNIX or NT host. All the client workspaces in a Perforce system access the same server.
The term server is often used within Perforce in the following ways:

As an abbreviation for production server: the particular p4d process that manages a production installation of Perforce. Each p4d process can be identified by a unique port address of the form machine:nnnn.

To indicate the machine on which p4d runs.

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

Software Configuration Management
A category of software whose definition changes from manufacturer to manufacturer. Perforce is a Software Configuration Management system. Functions commonly said to comprise SCM systems are version control, concurrent development, release management, build management, and change review.

status
For a changelist, a value that indicates whether the changelist is new, pending or submitted. For a job, an indicator of whether the job is open, closed, or suspended.

submit
To send a pending changelist to the server for processing. The files referenced by the changelist are locked, the corresponding operations are performed, and then the files are unlocked.

subscribe
To register to receive email whenever changelists are submitted that affect particular files. Files are subscribed to via the p4 user form; the change review daemon watches the depot and sends email when the specified files have been affected.

superuser
A Perforce user with superuser permissions.

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

sync
To copy a file revision (or set of file revisions) from the depot to a client workspace. This is accomplished with the p4 sync command.

target file
When integrating changes between a branched codeline and the original codeline, the target file is the file that receives the changes from the donor file. Either the branched file or the original file can be the target; this is determined by the use or non-use of the -r flag when calling p4 integrate.

TCP/IP
A networking protocol; the protocol of the Internet.

text file
The basic Perforce file type. Text files can be stored using reverse delta encoding, saving space on the server.

theirs
When resolving a file conflict, the theirs file is the revision in the depot that the client file conflicts with. This is usually the head revision.
When working with branched files, theirs is the donor file.

three-way merge
A merge between yours, theirs, and base. When a three-way merge is schedule by Perforce, it is because yours and theirs are both revisions of a common base file, theirs has been submitted to the depot, and the unconditional acceptance of yours would lose all the changes to theirs.

tip revision
A term sometimes used by other SCM systems in place of head revision.

two-way merge
The type of merge performed when a donor file is being integrated into a target file that was branched from a different file. In this case, there is no base file, so a two-way merge is performed, in which your file is used as the base of the merge. In a two-way merge, all changes appear as theirs, and there can be no conflicts.

user
An identifier that informs Perforce who is running the p4 commands. By default, this is the same as the system username, but the environment variable P4USER overrides this, allowing any user to impersonate any other.

version control
The tracking of each revision and variant of every file managed by an SCM system

view
A description of the relationship between files in the depot and a client workspace, label, or branch. The view determines which files from the depot are included in the mapping, and the names by which the mapped files are known. See client view, label view, branch view.

wildcard
A special character that is not interpreted literally, but is used to match other characters in strings. Perforce wildcards are `*', which matches anything except a slash; `...', which matches any string including slashes, and `%d', which is used for parametric substitution in views.

workspace
See client workspace.

write access
A protections level that gives the user permission to run commands, such as p4 submit and p4 edit, that allow him to alter the contents of files in the depot. Write access includes read and list accesses.

yours
When resolving a file conflict, the yours file is the edited version within the client workspace. In an integration of a branched file, yours is the target file.