Home

Perforce 97.3 Command Line User`s Manual

1.
2. THEIR VERSION 98992 YOUR VERSION 98993 lt lt lt lt He and Lisa have both tried to add a zip code to an address in the file Ed had typed it wrong He changes this portion of the file so it reads as follows Intuitive Systems Mountain View California 98992 The merge file is now acceptable to him he s viewed Lisa s changes seen that they re compatible with his own and the only line conflict has been resolved He quits from the editor and types am the edited merge file is written to the client and the resolve process continues on the next doc guide file When a version of the file is accepted onto the client the previous client file is overwrit ten and the new client file must still be submitted to the depot Note that it is possible for another user to have submitted yet another revision of the same file to the depot between the time p4 resolve completes and the time p4 submit is performed in this case it Perforce 97 3 User s Manual 45 Chapter 5 Perforce Basics Resolving File Conflicts File locking is described in Locking Files to Minimize File Conflicts later in this chapter Gea Example Automatically accepting particular revisions of conflicting files would be necessary to perform another resolve This can be prevented by locking the file before performing the resolve Using Flags with Resolve to Non Interactively Accept Pa
3. Two other reporting commands are used quite often Command Meaning p4 have p4 sync n Lists all file revisions that the PERFORCE server knows you have in the client workspace Reports what files would be updated in the client workspace by p4 sync without actually performing the sync operation Perforce 97 3 User s Manual 26 CHAPTER 4 PERFORCE Basics The Details The Quick Start chapter explained the basics of using PERFORCE but discussion of the practical details were deferred This chapter which supplements the Quick Start chapter covers the dry PERFORCE rules The topics discussed include views mapping depots to cli ent workspaces PERFORCE wildcards rules for referring to older file revisions file types and form syntax It is assumed that the material in the Quick Start chapter has been read and properly digested Description of the Client Workspace A PERFORCE client workspace is a collection of source files managed by PERFORCE on a host Each such collection is given a name which identifies the client workspace to the PERFORCE server The name is by default simply the host s name but that can be overrid den by the environment variable P4CLIENT There can be more than one PERFORCE client workspace on a client host All files within a PERFORCE client workspace share a common root directory called the client root In the degenerate case the client root can be the host s root but i
4. cards Wildcards and p4 add There is one case in which the wildcard cannot be used and that is with the p4 add command The wildcard is expanded by the P4D server and since the server doesn t know what files are being added after all they re not in the depot yet it can t expand that wildcard The wildcard can be used with p4 add in this case it is expanded by the local OS shell not by the P4D server Perforce 97 3 User s Manual 28 Chapter 4 Perforce Basics The Details 95 NT On NT the PERFORCE client workspace must be specified in a slightly different format if it is to span multiple drives Please see the release notes which are available at our Web site for details Mapping the Depot to the Client Workspace Just as a client name is nothing more than an alias for a particular directory on the client machine a depot name is an alias for a directory on the PERFORCE server The relationship between files in the depot and files in the client workspace is described in the client view and it is set with the p4 client command When p4 client is typed a variation of the following form is displayed Client eds_elm Owner edk Description Created by ed Root usr edk elm Options nomodtime noclobber View depot eds_elm The contents of the View field determine where client files get stored in the depot and where depot files are
5. 0 In previous versions of PERFORCE re resolution of files was accomplished with p4 reresolve which has now been replaced by p4 resolve f Integrating Specific File Revisions By default the integrate command will integrate into the target all the revisions of the donor since the last donor revision that integrate was performed on A revision range can be specified when integrating this prevents unwanted revisions from having to be manually deleted from the merge while editing In this case the revision used as base is the first revision below the specified revision range The syntax here is a little strange although the file provided as an argument to p4 inte grate is the target the file revision specifier is applied to the donor Ed has made two bug fixes to his file src init c and Kurt wants to integrate the change into his branched version which is called newinit c Unfortunately init c has gone through 20 revisions and Kurt doesn t want to have to delete all the extra code from all 20 revisions while resolving Kurt knows that the bug fixes he wants were made to file revisions submitted in changelist 30 From the directory of his newinit c file in his branched workspace he types p4 integrate b elm r1 src newinit c 30 30 The target file is given as an argument but the file revisions are applied to the donor When Kurt runs p4 resolve only the revision of Ed s file that was submitted in change list 30
6. Connect to server failed check P4PORT TCP connect to perforce 1666 failed perforce host unknown then P4PORT has not been correctly set If the value you see in the third line of the error message is perforce 1666 as above then P4PORT has not been set at all if the value is anything else P4PORT has been incorrectly set In either case you ll need to set the value of P4PORT Telling P4 Where P4b is Before continuing you ll need to ask your system administrator the name of the host that P4D is located on and the number of the TCP IP port it s listening on Once you ve obtained this information set your P4PORT environment variable to host port where host is the name of the host that P4D is running on and port is the port that p4d is listening on For example If the P4D host is named and the P4D port is named set PAPORT to dogs 3435 dogs 3435 X com 1818 x com 1818 The definition of P4PORT can be shortened if P4 is running on the same host as P4D In this case only the P4D port number need be provided to P4 And if P4D is running on a host named or aliased perforce listening on port 1666 the definition of P4PORT for the P4 client can be dispensed with altogether For example If the P4D host is named and the P4D port is set P4PORT to lt same host as the p4 client gt 9783 9783 perforce 1666 lt no value needed gt When P4PORT has been set you should re verify the con
7. OPE after job has not yet been fixed creation form is ne closed A closed job is one that has been completed A suspended job is an open job that is not currently being worked on New jobs exist only while the change creation form is open Description Arbitrary text assigned by the user Usually a text that must be written description of the problem that is changed meant to be fixed If p4 job is called with no parameters a new job is created The name that appears on the form is new but this can be changed by the user to any desired string If the Job field is left as new or is blank PERFORCE will assign the job the name jobN where Nis a sequen tially assigned six digit number Existing jobs can be edited with p4 job jobname The owner and description can be changed arbitrarily the status can be changed to any of the three valid status values open closed or suspended If p4 job jobname is called with a non existing jobname a new job is created Linking Jobs to Changelists and Changing a Job s Status Automatically Performed Functions By default all open jobs owned by a particular user will appear in all PERFORCE change lists subsequently created by that user A job is automatically closed when one of its asso ciated changelists is successfully submitted Jobs can be disassociated from changelists by deleting the job from the changelist s change form and any job of any status may be added to a changeli
8. Options nomodtime noclobber View depot elm_proj eds_elm The modt ime option controls the modification times of client files when gotten from the depot with p4 sync orp4 revert Setting this value to modt ime leaves the modifica tion times of files in the client as the times these files were submitted to the depot If this Perforce 97 3 User s Manual 51 Chapter 6 Perforce Basics Miscellaneous Topics 0 The depot is divided into subdirectories simply by setting up the proper mappings within the client views option is left as the default nomodtime the modification date is set to the time the file was copied into the client The clobber option which can be set to clobber or noclobber controls how p4 sync behaves while retrieving files from the depot that already exist in the client The default noclobber tells p4 sync to avoid clobbering client files that aren t open in PERFORCE but have otherwise been made writable by the user If clobber is selected these files will be overwritten Recommendations for Organizing the Depot The default view brought up by p4 client maps the entire depot to the entire client workspace If the client workspace is named eds_elm the default view would look like this depot eds_elm This is the easiest mapping and can be used for the most simple PERFORCE depots but mapping the entire depot to the workspace can lead to pr
9. Ifa submit fails the default changelist will be assigned a number and you ll need to submit that changelist in a slightly different way Please see Chapter 5 for instructions on resolving file conflicts At this point the files he wants to add to the depot have been added to his default change list However the files are not actually added to the depot until the p4 submit command is given Ed is ready to submit his added files to the depot He types p4 submit and sees the fol lowing form in a standard UNIX text editor Change new Client edk User edk Status new Description lt enter description here gt Files depot elm_proj doc elm help 0 add depot elm_proj doc elm help 1 add depot elm_proj doc elm help 2 add depot elm_proj doc elm help 3 add Ed changes the contents of the Description field to describe what these file updates do When he s done he quits from the editor the new files are added to the depot The Description field contents must be changed or the depot update won t be accepted Lines can be deleted from the Files field any files deleted from this list will carry over to the next default changelist and will appear again the next time p4 submit is performed Multiple file arguments can be provided on the command line Ed wants to add all his Elm library documentation and header files to the depot S cd p4 add elm lib elm hdrs elm doc
10. Since the client s IP address is provided by IP itself this field provides as much security as is provided by the network The files in the depot that permission is being granted on means all files in all depots Access Levels The access level is described by the first field the six access levels are Access Level List read open write Meaning Permission is granted to run PERFORCE commands that display data about files e g p4 filelog No permission is granted to view or change the contents of the files The user s can run those PERFORCE commands that are needed to read files such as p4 client andp4 sync The read permission in cludes list access Grants permission to read files from the depot into the client workspace and gives permission to open and edit those files This permission does not allow the user to write the files back to the depot open is similar to write except that with open permission users are not allowed to run p4 submit or p4 lock The open permission includes read and list access Permission is granted to run those commands that edit delete or add files Write permission includes read list and open access This permission allows use of all PERFORCE commands except pro tect depot obliterate and verify Perforce 97 3 User s Manual 102 Chapter 14 System Administration Protections Access Level Meaning review A special permission granted to review
11. The View describes the relationship between files in the depot and files in the client work space Creating a client specification has no immediate visible effect no files are created when a client specification is created or edited The client specification simply indicates where files will be located when subsequent P4 commands are used Editing an Existing Client Specification p4 client can be used at any time to change the client workspace specification Just as when a client specification is created changing a specification has no immediate affect on the locations of any files the location of files in the depot and workspace is affected only when the client specification is used in subsequent commands But there is an important distinction between changing the client s root and changing the client s view if you change the root PERFORCE assumes that you will manually relocate the files as well If you change the view and then bring files into the client from the depot PERFORCE will delete and add files as necessary to make the client workspace reflect the view Perforce 97 3 User s Manual 20 Chapter 3 Perforce Basics Quick Start 0 If you re working in an already established PERFORCE environment and want to start by retrieving already existing files you can skip to page 24 and come back to this section later 0 This chapter discusses only the default changelist which is automatically maint
12. branch views 64 and exclusionary mapping 65 exclusionary mapping and 65 branches creating 63 64 listing 89 naming 64 branching 13 63 72 and reporting 72 and re resolving 70 donor files and 68 integration and 65 re integration and 70 surprise by product of 70 target files and 68 browser 3 bug descriptions tracking of 13 build management 11 c c changenum flag 55 change numbers contrasted to labels 58 change review 14 78 and protections 81 changelists 12 20 53 57 and branches 65 and integration 65 automatic renumbering of 41 commands affecting 54 creating 54 creation 54 creation of 56 default 53 deleting 56 deleting jobs from 57 describing 88 failure of submission and 56 listing 87 listing files in 57 moving files between 57 numbered 54 pending 54 removing files from 57 renumbering of 56 reporting 57 checkpointing 97 client form fields of 18 client root 28 client view 12 28 and branched files 65 usage 28 client workspaces 12 defined 17 26 27 defining 18 deleting 20 effects of editing specification 28 listing 92 naming 18 client specifying 48 client server 12 client server architecture 15 clients detached 49 clobber 51 closed status of jobs 74 closing files 24 codeline 63 codelines 13 evolution of 67 command arguments syntax of 32 command arguments from files 49 Command Reference 3 command line flags 48 commands and required access levels 104 format for 17 concurrent development 11
13. 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 partic ular 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 Perforce 97 3 User s Manual 124 Chapter APPENDIX B Glossary superuser access sync target file TCP IP text file theirs three way merge tip revision two way merge user version control view wildcard workspace write access yours A protections level that gives the user permission to run every PERFORCE com mand including those that set protections obliterate files verify files with an MD5 signature and set up connections to remote depots To copy a file revision or set of file revisions from the depot to aclient workspace This is accomplished with the p4 sync command When integrating changes between a branched codeline and the original codeline the target file is the file that
14. depot elm_proj lib Makefile SH 1 opened for add depot elm_proj lib add_site c l opened for add depot elm_proj lib addrmchusr c 1l opened for add lt etc gt and then does a p4 submit The operating system s write permission on submitted files is turned off in the client workspace when p4 submit is performed This helps ensure that file editing is done with PERFORCE s knowledge The write permissions are turned back on by p4 edit which is described below You might have noticed in the example above that the filenames are displayed as file name 1 PERFORCE always displays filenames with a n suffix the n indicates that this is the n th revision of this file Revision numbers are always assigned sequentially Updating Depot Files To open a file for edit use p4 edit This has two effects e The file s write permissions are turned on in the client workspace and e The file s to be edited are added to the default changelist Perforce 97 3 User s Manual 22 Chapter 3 Perforce Basics Quick Start Ga Example Deleting a file from the depot Ga Example Adding updating and deleting files in a single submit Since the files must have their write permission turned back on before they can be edited the p4 edit command must be given before the file is actually edited To save the new file revision in the depot use p4 submit as above Example Ed wants to make changes to his el
15. error logging 97 example set 4 exclusionary mappings and protections 103 F file conflicts 38 47 locking files to minimize 45 reasons for 38 types of 42 file names limitations on 33 syntax for 31 file permissions 21 file type inheritance of 35 file types 35 changing 35 determining 36 files closing 24 comparing contents 85 conflicts in 13 copying as branches 63 deleting from labels 62 depot s storage of 38 getting 23 modification times of 51 moving between changelists 57 obliterating 107 permissions 12 reintegration of 70 relationship between client and depot 84 removing from changelist 57 renaming 52 reproducing state of 58 re resolving of 70 reverting 24 revision history 83 revisions 12 storage of 36 viewing 85 forced integration 70 form editing 18 forms 36 and syntax 36 full file storage 36 G GNU diff 40 GUI 3 H head revision 13 help online 25 host name 15 l icons in margin notes 3 installation of p4 and p4d 95 integration algorithm for 71 and changelists 65 and revision ranges 70 atomicity of 65 forcing 70 of unrelated files 70 reporting 89 reversing sense of 68 integration to external defect tracking systems 77 intended work 73 Inter File Branching 13 See branching J Jam Make 1 Redux 11 job fix reporting 91 job reporting 90 job tracking 13 73 jobs 13 73 automatic naming of 74 creation of 73 deleting from changelist 57 list
16. label s existence and changelists are always referred to by PERFORCE assigned numbers labels are named by the user Creating a Label Labels are created with p4 label labelname this command brings up a form similar to the p4 client form Like clients labels have associated views the label view limits Perforce 97 3 User s Manual 59 Chapter 8 Labels which files can be referenced by the label Once the label has been created the p4 labelsync command is used to load the label with file references Label names share the same namespace as clients branches and depots thus a label name can t be the same as any existing client branch or depot name Ea Ed has finished the first version of filtering in elm he wants to create a label that refer Example ences only those files in the filter and hdrs subdirectories He wants to name the label Creating a label filters 1 he types p4 label filters 1 and fills in the resulting form as follows Label filters 1 Owner edk Description Created by edk Options unlocked View depot elm_proj filter depot elm_proj hdrs When he quits from the editor the label is created Before following this example further it s worth stopping for a moment to examine exactly what has and hasn t been accomplished So far a label called filters 1 has been created It can contain files only from the depot s elm_proj filter and hdrs subdi rector
17. platforms supported 12 port 15 port specifying 48 printing files 85 protection mechanism 14 protections 100 and exclusionary mappings 103 and superusers 102 commands affected by 104 levels needed for integration 68 protections form 100 PWD environment variable 48 R RCS format 38 RCS keyword expansion 36 read access level 101 reference manual command line 3 refreshing files 50 release management 11 releases labeling 58 62 renaming files 52 renumbering changelists 56 reporting 82 and changelists 57 87 and daemons 91 and labels 62 basic 24 37 branches 89 client workspaces 92 depots 92 file contents 85 file metadata 82 file revision comparisons 85 file revision history 83 fixes 91 integration 72 89 jobs 77 90 labels 88 of branches 72 of depots 110 of system configuration 92 opened files 84 PERFORCE users 92 resolves 46 resolve non interactive 45 of binary files 45 reporting 46 scheduling 40 resolve dialog 41 42 options 43 resource forks 35 result file 41 retrieving files 23 retrieving label contents 61 reverse delta storage 38 reverting files 24 review access level 102 review daemon 79 review functionality 11 review markers 80 revision history 83 revision numbers 21 revision ranges 35 and integration 70 revision specifications 33 without filenames 35 revisions head 13 of files 12 root directory 95 root See client root depot root S scheduling of merges 67 scheduling of resolves
18. Community Trust Disclaimer To the best of our knowledge the Elm team has never used PERFORCE for source management As far as we know they never heard of PERFORCE until they received our email asking for permission to use their code in our manual No implica tion that the Elm team uses or endorses PERFORCE is intended none should be inferred Please Give Us Feedback We are always interested in receiving feedback on our manuals Dodoes this guide teach the topic well Are there any glaring errors Are the explanations clear or are the exem plifications obfuscated by this enchiridion Please let us know what you think we can be reached at manual perforce com Perforce 97 3 User s Manual 4 Table of Contents PREFACE About This Manual 3 New 97 3 Features 3 Margin Note Icons 3 The Example Set 4 Please Give Us Feedback 4 CHAPTER 1 Perforce Concepts Il Perforce Architecture 12 Moving Files Between the Clients and the Server 12 File Conflicts 13 Labeling Groups of Files 13 Branching Files 13 Job Tracking 13 Change Review and Daemons 14 Protections 14 CHAPTER 2 Connecting to the p4d Server 15 Verifying the Connection to the p4d Server 15 Telling p4 Where p4dis 16 CHAPTER 3 Perforce Basics Quick Start 17 Underlying Concepts 17 File Configurations Used in the Examples 17 Setting Up a Client Workspace 18 Naming the Client Workspace 18 Describing the Client Workspace to the PERFOR
19. Filenames specified in this way begin with two slashes and the client or depot name Perforce 97 3 User s Manual 32 Chapter 4 Perforce Basics The Details Multiple depots can be provided within a single PERFORCE server See chapter 15 for details Ga Example Uses of different syntaxes to refer to a file Hl The point of this section is worth repeating any file can be specified within any PERFORCE command in client syntax depot syntax or local syntax The examples in this manual will use these syntaxes interchangeably followed by the path name of the file relative to the client or depot root directory The components of the path are separated by slashes Examples of PERFORCE Syntax depot elm_client docs help 1 PERFORCE syntax is sometimes called depot syntax or client syntax depending on whether the file specifier refers to a file in the depot or on the client But the syntax is the same in either case The specifier is occasionally used it means all files in all depots Providing Files as Arguments to Commands Because the client view provides a one to one mapping between any file in the client workspace and any file in the depot any file can be specified within any PERFORCE com mand in client syntax depot syntax or local syntax A depot s file specifier can be used to refer to a file in the client and vice versa PERFORCE will do the necessary mappi
20. Files 41 File Revisions Used and Generated by p4 resolve 41 Types of Conflicts Between File Revisions 42 How the Merge File is Generated 42 The p4 resolve Options 43 Using Flags with Resolve to Non Interactively Accept Particular Revisions 45 Binary Files and p4 resolve 45 Locking Files to Minimize File Conflicts 45 Preventing Multiple Resolves with File Locking 46 Resolves and Branching 46 Resolve Reporting 46 Perforce Basics Miscellaneous Topics 48 Command Line Flags Common to All Perforce Commands 48 Working Detached 49 Finding Changed Files with p4 diff 50 Using p4 diff to Update the Depot 50 Refreshing files 50 Options in the p4 client Form 51 Recommendations for Organizing the Depot 51 Renaming Files 52 Reading Forms from Standard Input Writing Forms to Standard Output 52 Changelists 53 Working with the Default Changelist 53 Creating Numbered Changelists Manually 54 Working With Numbered Changelists 55 Automatic Creation and Renumbering of Changelists 56 When Submit of the Default Changelist Fails the Changelist is Assigned a Number 56 Perforce May Renumber a Changelist upon Submission 56 Deleting Changelists 57 Changelist Reporting 57 CHAPTER 8 CHAPTER 9 Labels 58 Why Not Just Use Change Numbers 58 Creating aLabel 58 Adding and Changing Files Listed ina Label 59 Previewing Labelsync s Results 61 Preventing Accidental Overwrites of a Label s Contents 61 Retrieving
21. If no revision number or range is given where a revision range is expected the default is all revisions File Types PERFORCE supports normal text files as well as binary large text files keyword text files Macintosh resource forks and symbolic links PERFORCE attempts to determine the type of the file automatically when a file is opened with p4 add PERFORCE first deter mines if the file is a regular file or a symbolic link and then examines the first part of the file to determine whether is it text or binary If any non text characters are found the file is assumed to be binary otherwise the file is assumed to be text The detected file type can be overridden with p4 add t type where type is one of binary text ltext xbinary xtext ktext kxtext resource or symlink Descriptions of these file types are provided below A file s type is inherited from one revision to the next A file can be opened with a differ ent type for the new revision with p4 edit t type Ifa file has already been opened with p4 addorp4 edit its type can be changed with p4 reopen t type Perforce 97 3 User s Manual 36 Chapter 4 Perforce Basics The Details RCS format and delta storage are described in detail at the start of the next chapter PERFORCE must sometimes store the complete version of every file in the depot but most often it stores only the changes in the file since the previous revision This is called d
22. P4D s internal diff routine But the differences displayed by dy dt dm and d are generated by a diff internal to the P4 client program and this diff can be overridden by specifying an external diff in the P4DIFF environment variable Thus editing the PERFORCE generated merge file is often as simple as opening the merge file searching for the difference marker gt gt gt gt and editing that portion of the text How ever this is not always the case it s often useful and necessary to examine the changes made to theirs to make sure they re compatible with other changes that you made This can be facilitated by calling p4 resolve with the v flag p4 resolve v tells PER FORCE to generate difference markers for all changes made in either file being resolved instead of only for changes that are in conflict between the yours and theirs files The p4 resolve Options The p4 resolve command offers the following options Option Short Meaning What it Does e edit merged Edit the preliminary merge file generated by PER FORCE ey edit yours Edit the revision of the file currently in the client et edit theirs Edit the revision in the depot that the client revision conflicts with usually the head revision This edit is read only dy diff yours Diff line sets from yours that conflict with base dt diff theirs Diff line sets from theirs that conflict with base dm diff merge Diff line sets from m
23. Perl permission 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 ac ceptable to the user 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 The modification time of a file that has been read from the depot into a client work space 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 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 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 A special file revision a completely empty revision of any file Useful only to re move a file from the client workspace while leaving it intact in the depot use p4 sync foo none A changelist that has been created by PERFORCE but that has not yet been
24. Revision History The revision history of a file is provided by p4 filelog One or more file arguments must be provided and since the point of p4 filelog is to list information about each revision of particular files file arguments to this command may not contain a revision specification The output of p4 filelog has this form 3 change 23 edit on 1997 09 26 by edk doc Updated hel 2 change 9 edit on 1997 09 24 by lisag src Made chang 1 change 3 add on 1997 09 24 by edk doc Added the f For each file that matches the filespec argument the complete list of file revisions is pre sented along with the number of the changelist that the revision was submitted in the date of submission the user who submitted the revision and the first few characters of the changelist description With the 1 flag the entire description of each changelist is printed 3 change 23 edit on 1997 09 26 by edk doc Updated help files to reflect changes in filtering system amp other subsystems in a SOLES gt To See File Revision Information Use This Command including revisions of specific files with a short de p4 filelog filespec scription of each changelist the file was submitted in with the full description of each changelist p4 filelog l filespec Perforce 97 3 User s Manual 84 Chapter 12 Reporting and Data Mining Opened Files To see which files are currently opened within a client workspa
25. The most important of the variables are described in the first table the second table describes the more esoteric variables Perforce 97 3 User s Manual 112 Chapter APPENDIX A Environment Variables TABLE 1 Basic PERFORCE Environment Variables page 1 of 2 Environment Variable Description Command Line Alternative Used by P4 Used by P4d Examples Value if not Explicitly Set P4CLIENT Name of client workspace P4JOURNAL Database journal file P4LOG File to write errors to c J L Yes No No No Yes Yes eds_elm journal log manual disk2 perf journal disk2 perf log UNIX P4ROOT journal standard error name of P4 host NT value of COMPUTERNAME environment variable File is specified relative to PAD server root or as an ab solute path Setting this variable or using the command line alternative enables journaling File is specified relative to P4D server root or as an absolute path Perforce 97 3 User s Manual 113 Chapter APPENDIX A Environment Variables TABLE 2 Basic PERFORCE Environment Variables page 2 of 2 P4PORT For P4D server P4ROOT Directory in which P4USER PERFORCE client port to listen on P4D stores its files username For P4 client and subdirectories P4D host and its port P f u Yes No Yes Yes Yes No P4D server example usr 1cl edk 1515 Preece lisag
26. The review daemon is quite simple Every time a changelist is submitted to the PERFORCE depot email is sent to every user who has subscribed to review any files that are contained in that changelist Unlike other job review systems that you may be familiar with the PERFORCE system doesn t require the email recipient to respond the email message is sent for notification purposes only The daemon is implemented as follows 1 The PERFORCE depot is polled for submitted unreviewed changelists with the com mand p4 review 2 p4 reviews is used to generate a list of reviewers for each of these changelists 3 SENDMAIL is used to email the p4 describe changelist description to each reviewer 4 The first three steps are repeated every sixty seconds this value can be changed when the review daemon is installed The commands used in steps 2 and 3 p4 reviews and p4 describe are straightfor ward reporting commands The p4 review command used in step 1 is rather unusual All these commands are described below Perforce 97 3 User s Manual 80 Chapter 11 Change Review amp Other Daemons A The review counter names journal job and change are used internally by PERFORCE use of any of these three names as review counters could corrupt the PERFORCE database Access levels are covered in Chapter 14 Tracking Reviewed Changelists with Review Counters The review daemon needs to keep track of which changel
27. a client view Expresses where the corre sponding depot files are found within a client workspace 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 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 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 The interface that this PERFORCE manual describes If you re looking at this glos sary 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 See file conflict 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 A program running in the background on the PERFORCE server PERFORCE provides a change review daemon users can create their own to handle other needs Files in a PERFORCE server used to store the server metadata The changelist used by p4 add p4 edit p4 delete p4 submit etc un less a numbered change
28. above example the original codeline provided the donor files and the target files were located in the branched codeline but changes can be propagated in the other direc tion as well There is one fundamental difference between resolving conflicts in two revisions of the same file and resolving conflicts between the same file in two different codelines The difference is that PERFORCE will detect conflicts between two revisions of the same file and then schedule a resolve but there are always differences between two versions of the same file in two different codelines and these differences usually don t need to be resolved You must tell PERFORCE that text in one file needs to be propagated to its branch with p4 integrate If the codelines evolve separately and changes never need to be propagated you ll never need to integrate or resolve the files in the two codelines p4 integrate only acts on files that are the intersection of target files in the branch view and the client view If file patterns are given on the command line integrate further limits its actions to files matching the patterns The donor files supplied as arguments to integrate need not be in the client view To run the p4 integrate command write access is needed on the target files and read access is required on the donor files Propagating Changes from Branched Files to the Original Files A change can be propagated in the reverse direction from branched files to
29. allows any set of files to be copied within the depot By default the new file set or codeline evolves separately from the original files but changes in either codeline can be propagated to the other with the p4 inte grate command What is Branching Branching is a method of keeping in sync two or more sets of similar but not identical files Most software configuration management systems have some form of branching we believe that PERFORCE s mechanism is unique in that it mimics the style in which users create their own file copies when no branching mechanism is available Suppose for a moment that you re writing a program and are not using an SCM system You re ready to release your program what would you do with your code Chances are that you d copy all your files to a new location One of your file sets would become your release codeline and bug fixes to the release would be made to that file set your other files would become your development file set and new functionality to the code would be added to these files What would you do when you find a bug that s shared by both file sets You d fix it in one file set and then copy the edits that you made into the other file set The only difference between this homegrown method of branching and PERFORCE s branching methodology is that PERFORCE manages the file copying and edit propagation for you In PERFORCE s terminology copying the files is called making a bra
30. and Lisa both edit their client workspace versions of foo Ed submits a changelist containing that file and his submit succeeds Lisa submits a changelist with her version of the file her submit fails because of file conflicts with the new depot s foo Lisa starts a resolve Ed edits and submits a new version of the same file Lisa finishes the resolve and attempts to submit the submit fails and must now be merged with Ed s latest file lt etc gt File locking can be used in conjunction with resolves to avoid this sort of headache The sequence would be implemented as follows before scheduling a resolve lock the file Then sync the file resolve the file and submit the file New versions can t be submitted by other users until the resolved file is either submitted or unlocked Resolves and Branching Files in separate codelines can be integrated with p4 resolve discussion of resolving branched files begins in the Branching chapter on page 68 Resolve Reporting Four reporting commands are related to file conflict resolution p4 diff p4 diff2 p4 sync n andp4 resolved Perforce 97 3 User s Manual 47 Chapter 5 Perforce Basics Resolving File Conflicts Command Meaning p4 diff filenames p4 diff2 filel file2 p4 sync n filenames p4 resolved Runs a diff program between the file revision currently in the client and the revision that was last gotten from the depot If the fil
31. and merges 40 scheduling resolves 40 SCM See software configuration management scripts sample 93 server connecting to 15 starting 96 shared file repository See depot signatures of files 107 software configuration management 11 standard input 52 standard output 52 status of jobs 74 76 storage of files 38 subdirectories of depot 94 submission failure of 56 subscribing to files 78 super access level 102 superuser commands 107 superusers and protections 102 suspended status of jobs 74 symlink files 36 synbolic links 35 sync use of in resolving 40 syntax client 31 depot 31 local 31 perforce 31 system improvement request 13 T target files 68 reversing sense with donor 68 TCP IP 95 temporary files 27 text files 36 theirs and integration 71 theirs 41 71 three way merge 13 tracking viewed changes 80 types of files See file types U unlocking files 45 unopened files bringing into client workspace 50 updating files 21 user cooperation with Perforce 26 USER environment variable 49 user specifying 49 USERNAME environment variable 49 users listing 92 Dn v version control 11 version information 99 viewing files 85 views and branching 64 and labels 59 client 19 usage 28 WwW wildcards 27 and p4 add 27 in views 29 usage 33 work intended 13 work intended 73 workspace See client workspace write access level 101 X xbinary files 36 xtext files 36 Y yours file 41 and integrate 71
32. another in the client workspace or be moved to an entirely different directory in the client workspace No matter how the files are named there is always a one to one mapping To determine the exact location of any client file on the host machine substitute the value of the p4 client form s Root field for the client name on the client side of the map ping For example if the p4 client form s Root field for the client eds_elm is set to Perforce 97 3 User s Manual 29 Chapter 4 Perforce Basics The Details Example Mapping part of the depot to the client workspace usr edk elm then the file eds_elm doc elm help 1 will be found on the client host in usr edk elm doc elm help 1 On NT the PERFORCE client workspace must be specified in a slightly different format if it is to span multiple drives Please see the release notes for details Wildcards in Views Any wildcard used on the depot side of a mapping must be matched with an identical wildcard in the mapping s client side Any string matched by the wildcard will be identical on both sides In the client view depot elm_proj eds_elm the single mapping contains PERFORCE s wildcard which matches everything including slashes The result is that any file in the eds_elm client workspace will be mapped to the same location within the depot s elm_proj file tree For example the file depot elm_proj nls gencat README will be mapped
33. can later be used to reproduce the state of these files within a client workspace Labels provide a method of naming important combinations of file revisions for later ref erence For example the file revisions that comprise a particular release of your software might be given the label release2 0 1 Ata later time all the files in that label can be retrieved into a client workspace with a single command Create a label when e You want to keep track of all the file revisions contained in a particular release of the software e There exists a particular set of file revisions that you want to give to other users or e You have a set of file revisions that you want to branch from but you don t want to per form the branch yet In this case you would create a label for the file revisions that will form the base of the branch Why Not Just Use Change Numbers Labels share certain important characteristics with change numbers both refer to particu lar file sets and both act as handles to refer to all the files in the set But labels have four important advantages over change numbers the file revisions referenced by a particular label can come from different changelists a change number refers to the state of all the files in the depot at the time the changelist was submitted a label can refer to any arbitrary set of files and revisions the files and revisions referenced by a label can be arbitrarily changed at any point in the
34. checkpoint client client form client name client root client side client view client workspace codeline command line conflict counter daemon database default changelist default depot The number that a particular changelist is known by The default changelist is as signed a number if a submit of the default changelist fails Changelist numbers al ways increase in sequence The process of sending email to users when files that they are interested in have changed within the depot A copy of the underlying server metadata at one moment in time This is one half of the journaling process A computer running P4 a computer storing a client workspace All PERFORCE work is done by users on client machines A single PERFORCE system can have many cli ents which all talk to a single server via TCP IP The form brought up by the p4 client command to define a client workspace 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 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 rootis usr joe projectl then the file eroj1 docs read me is actually located on the client machine under usr joe projectl docs read me The right hand side of a mapping within
35. e Refreshing the client workspace e Additional p4 client options e Renaming files e Flags that allow form data to be read from a file e Recommendations for organization of files within the depot Command Line Flags Common to All PERFORCE Commands Five flags are available for use with all PERFORCE commands These flags are given between the system command p4 and the command argument taken by p4 These flags are Flag Meaning Example c clientname Runs the command on the p4 c joe edit depot foo specified client Overrides the P4CLIENT environment vari able Opens file foo for editing under client workspace joe d directory Specifies the current directory p4 d elm src edit foo overriding the environment bar variable PWD Opens files foo and bar for edit these files are found relative to elm src p Gives the p4d server s listen p4 p mama 1818 clients dd i idi ey Er E ing address overriding Reports a list of clients on the serv P4PORT er on host mama port 1818 Perforce 97 3 User s Manual 49 Chapter 6 Perforce Basics Miscellaneous Topics 0 It is perfectly safe to use p4 edit on any file this command gives the local file write permissions but does not otherwise alter it Flag Meaning Example u username Specifies a PERFORCE user p4 u bill user overriding the P4USER USER and USERNAME environment Presents the p4 user form
36. fixes The output of p4 fix looks like this job000302 fixed by change 634 on 1997 09 01 by edk eds_mach filter_bug fixed by change 540 on 1997 10 22 by edk eds_mach A number of options allow the reporting of only those changes that fix a particular job or jobs fixed by a particular changelist or jobs fixed by changelists that are linked to particu lar files A fixed job is not the same as a closed job since open jobs can be linked to pending changelists and pending jobs can be reopened even after the associated changelist has been submitted To list jobs with a particular status use p4 jobs To See a Listing of Use This Command all fixes for all jobs p4 fixes all changelists linked to a particular job p4 fixes j jobname all jobs linked to a particular changelist p4 fixes c changenum all jobs fixed by changelists that contain particular p4 fixes filespec files all jobs fixed by changelists that contain particular p4 fixes i filespec files including changelists that contain files that were later integrated with the specified files Reporting for Daemons The PERFORCE change review mechanism uses the following reporting commands Any of these commands might also be used with user created daemons For further information on daemons please see chapter 11 and consult the source code of the PERFORCE Change Review daemon To list Use This Command the names of all counter variable
37. in the form p4 command arguments File Configurations Used in the Examples This manual makes extensive use of examples based on the Elm source code set The Elm examples used in this manual are set up as follows A single depot is used to store the elm files and perhaps other projects as well The elm files will be shared by storing them under an e1m subdirectory within the depot Perforce 97 3 User s Manual 18 Chapter 3 Perforce Basics Quick Start Ga Example Naming the client workspace ai Many P4 commands including p4 client display a form for editing ina standard text editor The editor that is used is defined through the EDITOR environment variable Each user will store his or her client workspace Elm files in a different subdirectory The two users we ll be following most closely Ed and Lisa will work with their Elm files in the following locations User Username Client Workspace Name Top of own Elm File Tree Ed edk eds_elm usr edk elm Lisa lisag lisas_ws usr lisag docs Setting Up a Client Workspace To move files between a client workspace and the depot the PERFORCE server requires two pieces of information e A name that uniquely identifies the client workspace and e The top level directory of this workspace Naming the Client Workspace To name your client workspace or to use a different workspace set the environment vari able PACLIENT to the n
38. is He fixes both bugs at his leisure He realizes that the filter problem will require updates to another file ilter lock c He opens this file for edit with p4 edit c 29 filter lock c opening the file with the c 29 flag puts the file in changelist 29 which he cre Perforce 97 3 User s Manual 56 Chapter 7 Changelists ated above If the file had already been open for edit in the default changelist he could have moved it to changelist 29 with p4 reopen c 29 filter lock c Ed finishes fixing the aliasing bug since the affected files are in the default changelist he submits the changelist with a straightforward p4 submit He ll finish fixing the filtering bug later Automatic Creation and Renumbering of Changelists When Submit of the Default Changelist Fails the Changelist is Assigned a Number Submits of changelists will occasionally fail This can happen for a number of reasons e A file in the changelist has been locked by another user with p4 lock e The client workspace no longer contains a file included in the changelist e There is a server error such as not enough disk space or e The user was not editing the head revision of a particular file The following sequence shows an example of how this can occur User A types p4 edit depot foo User B types p4 edit depot foo User B submits her default changelist User A submits his default changelist User A s submit is rejected since the fi
39. is scheduled for resolve that is Kurt only sees the changes that Ed made to init c in changelist 30 The file revision that was present in the depot at changelist 29 is used as base Re Integrating and Re Resolving Files Once a particular revision of a donor file has been integrated into a particular target that particular revision is usually skipped in subsequent integrations with the same target If all the revisions of a donor have been integrated into a particular target p4 integrate will give the error message All revisions already integrated But integration of a particular donor can be forced even though integration has already been performed by providing the f flag to p4 integrate Similarly a target file that has been resolved but not yet submitted can be re resolved by providing the f flag to p4 resolve which forces re resolution of already resolved files When this flag is used the original client target file will already have been replaced with the result file of the original resolve process thus when re resolving yours will already be the new client file the result of the original resolve How Integrate Works The preceding material in this chapter was written from a user s perspective This section makes another pass at the same material this time describing the mechanism behind the integration process Perforce 97 3 User s Manual 71 Chapter 9 Branching p4 integrate s Definitions of yours
40. is used to find all files in the workspace that have changed without PERFORCE s knowledge Output from this command is used to bring the depot in sync with the client workspace Finding Changed Files with p4 diff The p4 diff reporting command is used to compare a file in the client workspace with the corresponding file in the depot Its behavior can be modified with two flags p4 diff Variation Meaning p4 diff se Tells the names of unopened files that are present on the cli ent but whose contents are different than the files last taken by the client with p4 sync These files are candidates for p4 edit p4 diff sd Reports the names of unopened files missing from the client These files are candidates for p4 delete Perforce 97 3 User s Manual 50 Chapter 6 Perforce Basics Miscellaneous Topics Using p4 diff to Update the Depot The p4 diff variations described above can be used in combination with the x flag to bring the state of the depot in sync with the changes made to the client workspace To open changed files for edit after working detached use p4 diff se gt CHANGED_FILES p4 x CHANGED_FILES edit To delete files from the depot that were removed from the client workspace use p4 diff sd gt DEL_FILES p4 x DEL_FILES delete 0 p4 sync fis similar to p4 refresh a command found in previous versions of PERFORCE Whereas p4 refresh
41. new version and wants to replace the old revi sion of this file in the label filters 1 with the new revision From the filter subdirectory he types p4 labelsync 1 filters 1 doc filter c and sees depot elm_proj filter filter c 15 updated The head revision of filter c replaces the revision that had been previously included in the label 5 If labelsync is called with filename arguments that contain revision specifications these file revisions are included in the label s file list Ed realizes that the version of ilter audit c contained in his label filters 1 isnot the version he wants to include in the label he d prefer to include revision 12 of that file From the main Elm directory he types l filters 1 filter audit c 12 p4 labelsync and sees depot elm_proj filter audit c 12 updated This revision of audit c replaces the revision that had been previously included in the label Perforce 97 3 User s Manual 61 Chapter 8 Labels Ga Example Retrieving files into a client workspace from a label Previewing Labelsync s Results The results of p4 Llabelsync can be previewed with p4 labelsync n This lists the files that would be added deleted or replaced in the label without actually performing the operation Preventing Accidental Overwrites of a Label s Contents Since p4 labelsync with no file arguments overwrites all the files that are li
42. only copied unopened files from the depot that PERFORCE thinks you already As always these edit and delete requests are stored in a changelist which is not pro cessed until the p4 submit command is given Refreshing files The process of syncing a depot with a formerly detached client workspace has a converse it is possible for PERFORCE to become confused about the contents of a client workspace through the accidental use of UNIX commands For example suppose that you accidently delete a client workspace file via the UNIX rm command and that the file is one that you wanted to keep Even after a submit p4 have will still list the file as being present in the have p4 sync f workspace copies any l unopened files from Just as the process described above will bring the depot in sync with the client workspace p4 sync f files can be used to bring the client workspace in sync with the files the depot thinks you have This command is mostly a recovery tool for bringing the client workspace back into sync with the depot after accidentally removing or damaging files managed by PERFORCE the depot to the client workspace p4 refresh will still run in this version of PERFORCE but will disappear in some future version Options in the p4 client Form The form brought up by p4 client has an option field which takes two values Client eds_elm Owner ed Description Created by ed Root usr edk elm
43. p4 reopen c default filenames Ed is working on two bug fixes simultaneously One of the bugs involves mail filtering and requires updates of files in the filter subdirectory the other problem is in the elm aliasing system and requires an update of utils elmalias c Ed wants to update each bug separately in the depot this will allow him to refer to one bug fix by one change number and the other bug fix by another change number He s already started fixing both bugs and has opened some of the affected files for edit He types p4 change and sees Change new Client eds_elm User edk Status new Description lt enter description here gt Files depot elm_proj filter filter c edit depot elm_proj filter lock c edit depot elm_proj utils elmalias c edit Ed wants to use this changelist to submit only the fix to the filter problems He changes the form deleting the last file revision from the file list when he s done the form looks like this Change new Client eds_elm User edk Status new Description Fixes filtering problems Files depot elm_proj filter filter c edit depot elm_proj filter lock c edit When he quits from the editor he s told Change 29 created with 2 open file s The file that he removed from the list utils elmalias c is now found in the default changelist He could include that file in another numbered changelist but decides to leave it where it
44. protect 100 The Permission Lines Four Fields 101 Access Levels 101 Default Protections 102 Interpreting Multiple Permission Lines 103 Exclusionary Protections 103 Access Levels Required by Perforce Commands 104 How Protections are Implemented 105 System Administration Superuser Commands 107 File Verification by Signature 107 File Obliteration 107 Changelist Deletion amp Description Editing 107 Distributed Depots 108 Defining New Depots 108 Accessing Files In Other Depots 109 Integrating Files From Other Depots 110 Deleting Depots 110 Depot Reporting Commands 110 APPENDIX A Environment Variables 111 APPENDIX B Glossary 116 CHAPTER 1 0 You don t need to read this chapter if you don t want to All the material discussed here is also covered in the how to chapters which comprise the rest of the manual This chapter is provided as a guide to what PERFORCE does without the details of how to do it PERFORCE Concepts PERFORCE facilitates the sharing of files among multiple users It is a software configura tion management tool but software configuration management SCM is defined in many different ways depending on who is giving the definition SCM has been described as providing version control file sharing release management defect tracking build man agement and a few other things It s worth looking at exactly what PERFORCE does and doesn t do e PERFORCE offers version c
45. submit ted 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 A file in a client workspace that has been included on a changelist with p4 add p4 delete orp4 edit The file is said to be open within the client workspace 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 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 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 An existing changelist that has not yet been submitted These can be created man ually with p4 change c and are automatically created when submission of the default change fails The fast Software Configuration Management system See server 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 specifie
46. tents of the file Any depot located on the current PERFORCE server By default only one such depot is constructed others may be defined with p4 depot 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 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 Error output from the P4D server By default this is written to standard error a spe cific file can be set in the P4LOG environment variable or with the L flag to P4D A single line in a view consisting of a left side and a right side that specify the cor respondences between files in the depot and files in a client label or branch See also client view branch view label view To combine the contents of two conflicting file revisions into a single file This is accomplished with p4 resolve Perforce 97 3 User s Manual 121 Chapter APPENDIX B Glossary merge file metadata modtime hamespace network con nection nonexistent revision numbered changelist open owner p4 P4D pending change PERFORCE PERFORCE server PERFORCE syn tax
47. that describes the file The banner can be removed by passing the q flag to p4 print When printed the banner has this format depot elm_proj README 23 edit change 50 text p4 print takes a mandatory file argument which can include a revision specification The file will be printed at the specified revision if no revision is specified the head revi sion will be printed To See the Contents of Files Use This Command at the current head revision p4 print filespec without the one line file header p4 print q filespec at a particular change number p4 print filespec changenum File Content Comparisons A client workspace file can be compared to any revision of the same file within in the depot with p4 diff This command takes a filespec argument if no revision specification is supplied the workspace file is compared against the revision last read into the work space The p4 diff command has many options available only a few are described in the table below For more details please consult the PERFORCE Command Reference Whereas p4 diff compares a client workspace file against depot file revisions p4 diff2 can be used to compare any two revisions of a file It can even be used to compare revisions of different files p4 diff2 takes two file arguments wildcards are allowed but any wildcards in the first file argument must be matched with a corresponding wildcard in the second This makes it possib
48. that generate reports on jobs are Command Description p4 jobs Generates a report of all jobs on the server Prints the job name Sale date modified owner status and the first 32 characters of the s statusval description for each job file p4 jobs 1 outputs the full description of each job p4 jobs s statusvaican be used to limit the report to only those jobs with a particular status value If any file names are provided on the command line with p4 jobs files the report will be limited to jobs linked to those changelists that affected files that match the filepatterns p4 fixes Lists each job along with the change numbers they ve been j jobName linked to c change p4 fixes j jobname provides information only for change FILS aui bye lists linked to that particular job p4 fixes c changenumlists only those jobs associated with the given change number Any file arguments that are provided will limit the listing to changelists that affect those files Perforce 97 3 User s Manual 78 CHAPTER 11 Ga Example Providing change review parameters with p4 user Change Review amp Other Daemons PERFORCE s change review functionality allows users to be notified via email whenever files that they re interested in have been updated in the depot Since change review is pro vided via a background PERL script or daemon this functionality can be modified Other daemons can be cr
49. the corresponding changelist Re verting files can only be done before the files have been submitted 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 Any daemon process written that uses the p4 review command See also change review Perforce 97 3 User s Manual 123 Chapter APPENDIX B Glossary 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 re view 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 num bers 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 toas foo 10 The revision specification foo 10 is actually the same as the revision range speci fication foo 1 10 since revision ten of the file encompasses all the changes made in the file from revision 1 to revision 10 r
50. the same mapping The wildcards are replaced in the copied to direction by the substring that the wildcard represents in the copied from direction There can be multiple wildcards the n th wildcard in the depot specification corresponds to the n th wildcard in the client description Perforce 97 3 User s Manual 31 Chapter 4 Perforce Basics The Details Example Changing string order in client workspace names Ga Example Mappings that fail Changing the Order of Filename Substrings The d wildcard can be used to rearrange the order of the matched substrings Mike wants to change the names of any files with a dot in them within his doc subdirec tory in such a way that the file s suffixes and prefixes are reversed in his client workspace For example he d like to rename the Elm cover file in the depot cover E1m in his cli ent workspace Mike can be a bit difficult to work with He uses the following mappings depot elm_proj mike_elm depot elm_proj doc 1 2 mike_elm doc 2 1 Two Mappings Can Conflict and Fail It is possible for multiple mappings in a single view to lead to a situation in which the name does not map the same way in both directions When a file doesn t map the same way in both directions the file is ignored Joe has constructed a view as follows depot elm_proj j0e elm depot nowhere j0e elm doc The depot file depot elm_proj doc help w
51. this line set the same in yours and base but different in theirs e Is this line set the same in yours and theirs but different in base e Is this line set different in all three files Any line sets that are the same in all three files don t need to be resolved The number of line sets that answer the other four questions are reported by p4 resolve in this form 2 yours 3 theirs 1 both 5 conflicting In this case two line sets are identical in theirs and base but are different in yours three line sets are identical in yours and base but are different in theirs one line set was changed identically in yours and theirs and five line sets are different in yours theirs and base How the Merge File is Generated p4 resolve generates a preliminary version of the merge file which can be accepted as is edited and then accepted or rejected A simple algorithm is followed to generate this file any changes found in yours theirs or both yours and theirs are applied to the base file and written to the merge file and any conflicting changes will appear in the merge file in the following format gt gt gt gt ORIGINAL VERSION foo n text from the original version THEIR VERSION foo m text from their file YOUR VERSION foo text from your file lt lt lt lt Perforce 97 3 User s Manual 43 Chapter 5 Perforce Basics Resolving File Conflicts 0 The merge file is generated by
52. to edit specification for user bill variables Only those commands that the specified user has permissions on may be run x filename Instructs p4 to read arguments See Working Detached section one per line from the named below file All PERFORCE commands can take these flags even commands for which this flag usage is clearly useless e g p4 u bill d usr joe help Other flags are available as well these additional flags are command dependent Please use p4 help commandname to find the flags available to each command Working Detached Under normal circumstances users work in their client workspace with a functioning net work connection to a PERFORCE server As they edit files they are supposed to announce their intentions to the server with p4 edit and the server responds by noting the edit in the depot s metadata and by unlocking the file in the client workspace However it is not always possible for a network connection to be present a method is needed for users to work entirely detached from the server The scheme is as follows e The user works on files without giving PERFORCE commands instead OS commands are given that manually change the permissions on files and then these files are edited or deleted e If the files were not edited within the client workspace they should be copied to the cli ent workspace when the network connection is reestablished e The p4 diff reporting program
53. use the p4 opened reporting command Forms and PERFORCE Commands Certain PERFORCE commands such as p4 client and p4 submit present a form to the user to be filled in with values This form is displayed in the editor defined in the environ ment variable EDITOR When the user changes the form and exits the editor the form is parsed by PERFORCE checked for errors and used to complete the command operation If there are errors PERFORCE gives an error message and you must try again The rules of form syntax are simple keywords must be against the left margin and end with a colon and values must either be on the same line as the keyword or indented by a tabstop on the lines below the keyword Only the keywords already present on the form are recognized Some keywords such as the Client field in the p4 client form take Perforce 97 3 User s Manual 37 Chapter 4 Perforce Basics The Details a single value other fields such as Description take a block of text and others like View take a list of lines Certain fields like Client in p4 client can t have their values changed others like Description in p4 submit must have their values changed If you don t change a field that needs to be changed or vice versa the worst that will happen is that you ll get an error We ve done our best to make these cases as self evident as possible when in doubt use p4 help command General Reporting Commands
54. want to view data in a format that PERFORCE doesn t directly support In these situations the reporting commands can be used in combination with scripts to print only the data that you want to see Three examples are provided here Comparing the Change Content of Two File Sets To compare the change content of two sets of files it is necessary to diff them exter nally To do this run p4 changes twice once on each set of files and then use any exter nal diff routine to compare them In the following example main represents the main codeline and r98 4 is a codeline that was originally branched from main p4 changes depot main gt changes in main p4 changes depot r98 4 gt changes in r98 4 diff changes in main changes in r98 4 This could be used to uncover which changes have been made to r98 4 that haven t been integrated back into main Changelists Submitted by Particular Users The p4 changes command does not have a flag that allows only those changes submitted by particular users to be viewed but this can be accomplished by grepping the output of p4 changes For example in the Korn shell create an executable file with these con tents p4 changes grep by 1 When this script is called with a username as an argument only those changes created by that user will be printed Perforce 97 3 User s Manual 94 Chapter 12 Reporting and Data Mining Listing Subdirectories of th
55. 42 Chapter 5 Perforce Basics Resolving File Conflicts Discussion of resolving branched files begins on page 47 merge File variation generated by PERFORCE from theirs yours and base result The file resulting from the resolve process result is written to the cli ent workspace overwriting yours and must subsequently be submit ted by the user The instructions given by the user during the resolve process determine exactly what is contained in this file The user can simply accept theirs yours or merge as the result or can edit merge to have more control over the result The remainder of this chapter will use the terms theirs yours base merge and result to refer to the corresponding file revisions The definitions given above are somewhat different when resolve is used to integrate branched files Types of Conflicts Between File Revisions The diff program that underlies the PERFORCE resolve mechanism determines differ ences between file revisions on a line by line basis Once these differences are found they are grouped into chunks for example three new lines that are adjacent to each other are grouped into a single chunk Yours and theirs are both generated by a series of edits to base for each set of lines in yours theirs and base p4 resolve asks the fol lowing questions e Is this line set the same in yours theirs and base e Is this line set the same in theirs and base but different in yours e Is
56. 4D server program for processing and communicates with p4d via TCP IP Each P4 program needs to know the address and port of the P4D server that it communi cates with This address is stored in the P4PORT environment variable Verifying the Connection to the P4p Server A p4 client needs to know two things in order to talk to the P4D server e The name of the host that P4D is running on e The port that P4D is listening on These are set via a single environment variable P4PORT It is possible that your system administrator has already set P4PORT if not you ll need to set it yourself To verify the connection type p4 info at the command line If the P4PORT environment variable is correctly set you ll see something like this User name edk Client name eds_elm Client unknown Current directory usr edk Client address 206 14 52 194 3119 Server address margarine 1818 Server root usr local p4root Server version P4D FREEBSD 12 13 96 Server license test 10 users T Perforce 97 3 User s Manual 16 Chapter 2 Connecting to the P4D Server Ga Example Error from p4 info the P4D server connection is incorrectly specified The server address field shows which P4D server has been connected to it displays the host and port number that P4D is listening on In the above example everything is fine If however you receive a variant of this mes sage Error
57. All depots known to the system are reported on the described fields include the depot s name its creation date its type local or remote its IP address if remote the mapping to the local depot and the system admin istrator s description of the depot To view Use This Command user information for all PERFORCE users p4 users user information for only certain users p4 users username brief descriptions of all client workspaces p4 clients a list of all defined depots p4 depots Special Reporting Flags Two special flags o and n can be used with certain action commands to change their behavior from action to reporting The o flag is available with most of the PERFORCE commands that normally bring up forms for editing This flag tells these commands to write the form information to standard output instead of bringing the definition into the user s editor Perforce 97 3 User s Manual 93 Chapter 12 Reporting and Data Mining The o flag is supported by the following commands p4 branch p4 client p4 label p4 change p4 job p4 user The n flag prevents commands from doing their job Instead the commands will simply tell you what they would ordinarily do The n flag can be used with the following commands p4 integrate p4 resolve p4 labelsync p4 sync Reporting with Scripting Although PERFORCE s reporting commands are sufficient for most needs there may be times when you
58. CE Server 18 Editing an Existing Client Specification 19 Deleting an Existing Client Specification 20 CHAPTER 4 CHAPTER 5 Copying Files from the Workspace to the Depot 20 Adding Files to the Depot 20 Updating Depot Files 21 Deleting Files From the Depot 22 Submitting with Multiple Operations 22 Retrieving Files from the Depot into a Workspace 23 Reverting Files to their Unopened States 24 Basic Reporting Commands 24 Perforce Basics The Details 26 Description of the Client Workspace 26 Wildcards 27 Wildcards and p4 add 27 Mapping the Depot to the Client Workspace 28 Using Views 28 Wildcards in Views 29 Types of Mappings 29 Referring to Files on Command Lines 31 Local Syntax 31 Perforce Syntax 31 Providing Files as Arguments to Commands 32 Wildcards and Perforce Syntax 33 Name and String Limitations 33 File Names 33 Descriptions 33 Specifying Older File Revisions 33 Using Revision Specifications without Filenames 35 Revision Ranges 35 File Types 35 Forms and Perforce Commands 36 General Reporting Commands 37 Perforce Basics Resolving File Conflicts 38 RCS Format How Perforce Stores File Revisions 38 Only the Differences Between Revisions are Stored 39 Use of diff to Determine File Revision Differences 40 Scheduling Resolves of Conflicting Files 40 Why p4 sync to Schedule a Resolve 40 How Do I Know When a Resolve is Needed 41 CHAPTER 6 CHAPTER 7 Performing Resolves of Conflicting
59. CE provides a protection scheme to prevent unauthorized or inadvertent access to the depot The protections determines which PERFORCE commands can be run on which files by whom and from which host Since any user can change their PERFORCE username with P 4USER user level protections provide safety not security At the host level protec tions are as secure as the host itself Protections are set with the p4 protect command When Should Protections Be Set Before p4 protect is run every PERFORCE user is a superuser and can access and change anything in the depot The first time protect is invoked a protections table is created that gives the invoking user superuser access from all hosts and lowers everyone else s access level to write permission on all files from all hosts Therefore protect should be run as the concluding step of all new PERFORCE installations the superuser can change the access levels as needed at any time The PERFORCE protections are stored in the db protect file in the server root direc tory if p4 protect is first run by an unauthorized user the depot can be brought back to its unprotected state by removing this file Setting Protections with p4 protect The p4 protect form contains a single field with multiple lines Each line specifies a particular permission the contents look something like this E Protections Sampe read emily depot elm_proj protections table write 195 3 21
60. Chapter 11 Change Review amp Other Daemons Running the Daemon Change review is implemented via a PERL script perfreview perl which can be downloaded from http www perforce com perforce loadsupp html This review daemon must be run under PERL 4 or higher SENDMAIL is also required It s usually run from the P4D server account in the same directory as the P4D server although it can be installed anywhere Once it s been installed do the following 1 Edit the script and follow the instructions at the top You may need to change the val ues of certain values in the script including the locations of the PERL and SENDMAIL For more executables information on 2 Make sure that the environment variable P4PORT is set the proper port so the review P4PORT see daemon can communicate with the p4 server hapter 11 Chap E EON 3 Run perfreview perl in the background with Appendix A perfreview perl amp e 4 Make sure that the review daemon is running as a user with review or superuser access If protections are in their default non enabled state the review daemon will automati This protection level cally have review access is described in Chapien aa The script can be modified to provide any desired functionality For example you may want to change the text of the outgoing message or you might change the script to write change reviews to files instead of sending email How the Review Daemon Works
61. Client Views can consist of multiple mappings which are used to map portions of the depot file tree to different parts of the client file tree If there is a conflict in the mappings later map pings have precedence over the earlier ones Perforce 97 3 User s Manual 30 Chapter 4 Perforce Basics The Details Z Example Multiple mappings in a single client view a Example Using views to exclude files from a client workspace a Example Files with different names in the depot and client workspace The elm_proj subdirectory of the depot contains a directory called doc which has all the Elm documents Included in this directory are four files named elm help 0 through elm help 3 Mike wants to separate these four files from the other documentation files in his client workspace which is called mike_elm To do this he creates a new directory in his client workspace called help it s located at the same level as his doc directory The four e1m help files will go here he fills in the View field of the p4 client formas follows depot depot elm_proj doc elm help mike_elm mike_elm help elm help Any file whose name starts with elm help within the depot s doc subdirectory will be caught by the later mapping and appear in Mike s workspace s help directory all other files are caught by the first mapping and will appear in their normal location Conversely any files beginning wit
62. E to version 97 3 The journaling and checkpointing subsystems have changed the release notes contain safety instructions on performing the upgrade Margin Note Icons This manual makes use of notes in the left margin to supply additional information The icons accompanying these notes have the following meanings Information specific to the Windows 95 or Windows NT command line A cross reference to other material in this manual A concrete example of the material discussed Perforce 97 3 User s Manual 3 Chapter PREFACE About This Manual A note of general interest T This note is rather important The Example Set We have attempted to develop a uniform example set for use with this manual All of the examples use the source code for Elm a popular UNIX mail program We selected the Elm source code for a number of reasons e Flm is widely used and many PERFORCE users will be familiar with the program If they are not they at least understand what it does e The source code is stored in well organized subdirectories which allow us to demon strate certain capabilities of PERFORCE e The source code for Elm is widely available users of this manual can download Elm and try the examples as they re encountered Links to the Elm source code can be found at http www myxa com elm html We are using the Elm source with the kind permission of Sydney Weinstein and Bill Pem berton of the USENET
63. FORCE Architecture PERFORCE has a client server architecture in which many computers called clients are connected to one central machine the server Each user works on a client at their com mand files they ve been editing are transferred to and from the server The clients com municate with the server via TCP IP Perforce 97 3 User s Manual 12 Chapter 1 PERFORCE Concepts The PERFORCE installation guide can be found in Chapter 13 Basic PERFORCE usage is taught in Chapters 3 and 4 The details of changelists are discussed in Chapter 7 Resolving file conflicts is the topic of Chapter 5 The PERFORCE clients may be distributed around a local area network wide area network dialup network or any combination of these There can also be PERFORCE clients on the same host as the server Two programs do the bulk of PERFORCE s work e The P4D program is run on the PERFORCE server It manages the shared file repository and keeps track of users clients protections and other PERFORCE metadata P4d must be run on a UNIX or Windows NT host e The P4 program is run on each PERFORCE client It sends the users requests to the P4d server program for processing and communicates with P4D via TCP IP P4 client programs can be run on many platforms including UNIX Windows VMS Macintosh BeOS and Next hosts Moving Files Between the Clients and the Server Users create edit
64. FORCE than it is to copy and restore the file manually Files not managed by PERFORCE may also be under a client s root and they are largely ignored by PERFORCE For example PERFORCE may manage the source files in a client workspace while the workspace also holds compiled objects libraries executables as well as a developer s temporary files In addition to accessing the client files the P4 client program sometimes creates temporary files on the client host Otherwise PERFORCE neither creates nor uses any files on the cli ent host Wildcards PERFORCE uses three wildcards for pattern matching Any number and combination of these can be used in a single string Wildcard Meaning Matches anything except slashes matches only within a single directory Matches anything including slashes matches across multiple directories zd Used for parametric substitution in views See page 32 for a full expla nation The wildcard is passed by the P4 client program to the P4D server where it is expanded to match the corresponding files known to P4D The wildcard is expanded locally by the OS shell before the P4 command is sent to the server and the files that match the wildcard are passed as multiple arguments to the P4 command To have PER FORCE match the wildcard against the contents of the depot it must be escaped usually with quotes or a backslash Most command shells don t interfere with the other two wild
65. Many reporting commands have specialized functions and these are discussed in later chapters The following reporting commands give the most generally useful information all these commands can take file name arguments with or without wildcards to limit reporting to specific files Without the file arguments the reports are generated for all files These reports always generate information on depot files not files within the client work space As with any other PERFORCE command when a client file is provided on the com mand line PERFORCE maps it to the proper depot file Command Meaning p4 filelog Generates a report on each revision of the file s in reverse chronological order p4 files Lists file name latest revision number file type and other in formation about the named file s p4 sync n Tells you what p4 sync would do without doing it p4 have Lists all the revisions of the named files within the client that were last gotten from the depot Without any files specifier it lists all the files in the depot that the client has p4 opened Reports on all files in the depot that are currently open for edit add delete branch or integrate within the client workspace p4 print Lists the contents of the named file s to standard input p4 where For each file in the client show the location of the correspond ing file within the depot Revision specifiers can be used with all of these reporting commands for ex
66. P4 client example squid 1666 it com 1308 For P4D server lt none gt UNIX 1666 For P4 client perforce 1666 the value of the USER environment variable NT the value of the USERNAME envi ronment variable Format on P4 client is host port or port by itself if the P4 client and the PAD server run on the same host To use the default value with P4D define perforce as an alias to the host in etc hosts or use the domain name services Port numbers must be in the range 1024 31767 Create this directo ry before starting P4D Only the account running P4D needs read write permis sions in this direc tory By default the PER FORCE username is the same as the OS username but this can be set to any other PERFORCE us er Perforce 97 3 User s Manual 114 Chapter APPENDIX A Environment Variables TABLE 3 Esoteric PERFORCE Environment Variables page 1 of 2 Environment Variable Description Command Line Alternative Used by P4 Used by P4D Examples Value if not Explicitly Set P4DIFF Name and location of the diff program used by p4 resolveandp4 diff P4EDITOR Editor used by P4 com mands like p4 client that bring up forms P4MERGE MERGE program used by p4 resolve s merge command Yes Yes Yes No No No diff vi Prescient Software s diff b emacs MergeRight windiff Sim
67. PERFORCE uses two separate diffs one is built into the P4D server and the other is used by the P4 client Both diffs contain identical proprietary code but are used by separate sets of commands The client diff is used by p4 diff and p4 resolve and the server diff is used by p4 describe p4 diff2 andp4 submit PERFORCE s built in diff routine allows three d lt flag gt flags du dc and dn both p4 diff and p4 diff2 allow any of these flags to be specified These flags behave identi cally to the corresponding flags in the standard UNIX diff Although the server must always use PERFORCE s internal diff routine the client diff can be set to any external diff program by pointing the P4DIFF environment variable to the full path name of the desired executable Any flags used by the external diff can be passed to it with p4 diff s qd flag Flags are passed to the underlying diff according to the fol lowing rules e If the character immediately following the 4 is not a single quote then all the charac ters between the d and whitespace are prepended with a dash and sent to the underlying diff e If the character immediately following the d is a single quote then all the characters between the opening quote and the closing quote are prepended with a dash and sent to the underlying diff The following examples demonstrate the use of these rules in practice If you want to pass the following flag toan Then call p4 diff this way
68. Perforce 97 3 Command Line User s Manual Manual 97 3m1 November 25 1997 This manual copyright 1997 PERFORCE Software All rights reserved PERFORCE software and documentation is available from http www perforce com You may download and use PERFORCE programs but you may not sell or redistribute them You may download and print the documentation but you may not sell or redistribute it You may not modify or attempt to reverse engineer the programs PERFORCE programs and documents are available from our Web site as is No warranty or support is provided Warranties and support along with higher capacity servers are sold by PERFORCE Software PERFORCE Software assumes no responsibility or liability for any errors or inaccuracies that may appear in this book By downloading and using our programs and documents you agree to these terms PERFORCE and Inter File Branching are trademarks of PERFORCE Software PERFORCE software includes software developed by the University of California Berkeley and its contributors All other brands or product names are trademarks or registered trademarks of their respective companies or organizations The remainder of this column is left blank for your use You may utilize it to store such written inscribed drawn painted copied drafted or duplicated material as you see fit or for any other use providing the use does not violate the laws ordinances statutes regulations edict
69. a Label s Contents into a Client Workspace 61 Deleting Labels 62 Label Reporting 62 Branching 63 What is Branching 63 When to Create a Branch 63 Branching s First Action Creating a Branch 64 Step 1 Create the Branch View 64 Step 2 Include the Branched Files in the Client View 65 Steps 3 amp 4 Use p4 integrate and p4 submit to Create the Target Files 66 Working With Branched Files 67 Branching s Second Action Propagating Changes from One Codeline to the Other 67 Propagating Changes from Branched Files to the Original Files 68 When the r flag is used to propagate changes from branched donors to original targets the original source files must be visible through the target view 69 Branching and Merging Without a Branch View 69 Deleting Branches 69 Advanced Integration Functions 69 Integrating Specific File Revisions 70 Re Integrating and Re Resolving Files 70 How Integrate Works 70 p4 integrate s Definitions of yours theirs and base 71 The Integration Algorithm 71 Integrate s Actions 71 Integration Reporting 72 CHAPTER 10 CHAPTER I1 CHAPTER 12 Job Tracking 73 Creating and Editing Jobs 73 Linking Jobs to Changelists and Changing a Job s Status 74 Automatically Performed Functions 74 Controlling Which Jobs Appear in Changelists 76 Manually Associating Jobs with Changelists 76 Arbitrarily Changing a Job s Status 76 Deleting Jobs 77 Integrating to External Defect Tracking System
70. 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 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 de pot s file revisions A user configurable list of file revisions Used to save important file configura tions for later use Any file included in a label can be referred to with the revision specifier labelname e g foo release3 0 1 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 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 licens ing please send email to info perforce com 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 partic ular file can t run any commands that would allow them to read or write the con
71. ady been submitted the job s status is changed to closed It is never necessary to use p4 fix to link an open job to a changelist newly created by the owner of the job since this is done automatically However p4 fix can be used to link a changelist to a job owned by another user Arbitrarily Changing a Job s Status We ve already seen two ways of changing a job s status 1 A job is automatically closed when an associated changelist is submitted 2 p4 fix will change the status of an open job to closed if the associated changelist has already been submitted and will change the status of a closed job to open when the job is linked to a pending changelist The status of any job can also be changed by bringing up the job definition form with p4 job jobname and then changing the status to one of the three allowed values This is the only way of changing a job s status to suspended Perforce 97 3 User s Manual 77 Chapter 10 Job Tracking Deleting Jobs A job that has been linked to a changelist can be unlinked from that changelist with p4 fix d c changenum jobname Jobs can be deleted entirely with p4 job d job name Integrating to External Defect Tracking Systems The PERFORCE job reporting functionality can be used to integrate jobs into external pro grams such as defect tracking systems via daemons Please see the next chapter for more information on daemons Job Reporting The commands
72. ained by PERFORCE Changelists can be created by the user please see Chapter 7 for a full discussion a Example Adding files to a changelist Deleting an Existing Client Specification An existing client workspace specification can be deleted with p4 client a client name Deleting a client specification has no effect on any files in the client workspace or depot it simply removes the P4D server s record of the mapping between the depot and the client workspace To delete existing files from a client workspace use p4 sync none described on page 35 on the files before deleting the client specification or use the stan dard local OS deletion commands after deleting the client specification Copying Files from the Workspace to the Depot Any file in a client workspace can be added to updated in or deleted from the depot This is accomplished in two steps 1 PERFORCE is told the new state of client workspace files with the commands p4 add filenames p4 edit filenames or p4 delete filenames When these com mands are given the corresponding files are listed in a PERFORCE changelist which is a list of files and operations on those files to be performed in the depot 2 The operations are performed on the files in the changelist when the p4 submit com mand is given The commands p4 add p4 edit and p4 delete do not immediately add edit or delete files in the depot Instead the affected file and the correspondi
73. al the command p4 depot book would be typed and the resulting form would be filled in as follows Depot Name book Type local Address subdir Map manual Perforce 97 3 User s Manual 109 Chapter 15 System Administration Superuser Commands Defining Remote Depots Defining a new depot on a remote P4D server is only slightly more complicated The Type is remote the server address must be provided in the Address field and the Map field must be given a mapping into the remote depot namespace Ea Lisa is working on a GUI for Elm She and Ed are using different P4D servers his is on Example host pine and it s listening on port 1818 Lisa wants to grab Ed s GUI routines for her Defining a remote own use she knows that Ed s color routine files are located on his P4D server s single depot depot under the subdirectory graphics GUI Lisa s first step towards accessing Ed s files would be to create a new depot She ll call this depot gui she d type p4 depot GUT and fill in the form as follows Depot Name gui Type remote Address pine 1818 Map depot graphics gui This creates a remote depot called gui on Lisa s P4D server this depot maps to Ed s depot s namespace under its graphics gui subdirectory The Mapping Field and What it Means The Map field is analogous to a client s view except that the view may contain multiple mappings and the Map field alwa
74. ame of the client workspace Ed is working on the code for E1m He wants to refer to the collection of files he s working on by the name eds_elm In the Korn shell he d type export P4CLIENT eds_elm Each operating system or shell has its own method of defining environment variables Appendix A describes how to create environment variables within each shell and OS Describing the Client Workspace to the PERFORCE Server Once the client workspace has been named it must be identified and described to the PER FORCE server with the p4 client command Typing p4 client brings up the client def inition form in a standard text editor once the form is filled in and the editor exited the PERFORCE server will be able to move files between the depot and the client workspace The p4 client form has a number of fields the two most important are the Root and View The meanings of these fields are as follows Field Meaning Root Identifies the top subdirectory of the client workspace This should be the lowest level directory that includes all the files and directories that you ll be working with in this workspace View Describes which files and directories in the depot are available to the client workspace and where the files in the depot will be located within the client workspace Perforce 97 3 User s Manual 19 Chapter 3 Perforce Basics Quick Start Example Setting the client root and t
75. ample p4 files clientname can be used to report on all the files in the depot that are currently found in client client name Chapter 12 the reporting chapter contains a more detailed discussion of each of these commands Perforce 97 3 User s Manual 38 CHAPTER 5 PERFORCE Basics Resolving File Conflicts File conflicts can occur when two users edit and submit two versions of the same file Conflicts can occur in a number of ways but the situation is usually a variant of the fol lowing Ed opens file foo for edit Lisa opens the same file in her client for edit Ed and Lisa both edit their client workspace versions of foo Ed submits a changelist containing foo and the submit succeeds Lisa submits a changelist with her version of foo her submit fails If PERFORCE were to accept Lisa s version into the depot the head revision would contain none of Ed s changes Instead the changelist is rejected and a resolve must be performed The resolve process allows a choice to be made Lisa s version can be submitted in place of Ed s Lisa s version can be dumped in favor of Ed s a PERFORCE generated merged version of both revisions can be submitted or the PERFORCE generated merged file can be edited and then submitted Resolving a file conflict is a two step process first the resolve is scheduled then the resolve is performed A resolve is automatically scheduled when a submit of a changelist fails because of a
76. and delete files in their own directories on the clients these directories are called client workspaces PERFORCE commands are used to move files to and from a shared file repository on the server known as the depot PERFORCE users can retrieve files from the depot into their own client workspaces where they can be read edited and resubmitted to the depot for other users to access When a new revision of a file is stored in the depot the old revisions are kept and are still accessible Files that have been edited within a client workspace are sent to the depot via a changelist which is a list of files and instructions that tell the depot what to do with those files For example one file might have been changed in the client workspace another added and another deleted These file changes might be sent to the depot in a single changelist which is processed atomically either all the changes are made to the depot at once or none of them are This allows problem fixes that span multiple files to be updated in the depot at exactly the same time Each client workspace has its own client view which determines which files in the depot can be accessed by that client workspace One client workspace might be able to access all the files in the depot another client workspace might access only a single file The PER FORCE server is responsible for tracking the state of the client workspace PERFORCE knows which files a client workspace has where they
77. angelists that contain open files or jobs must have the files and jobs removed from them before they can be deleted use p4 reopen to move files to another changelist p4 revert to remove files from the changelist and revert them back to their old versions or p4 fix d to remove jobs from the changelist Changelists that have already been submitted can never be deleted Changelist Reporting The two reporting commands associated with changelists are p4 changes and p4 describe The former is used to view lists of changelists with short descriptions the lat ter prints verbose information for a single changelist Command Meaning p4 changes Displays a list of all pending and submitted changelists one line per changelist and an abbre viated description p4 changes m numchanges Limits the number of changelists reported on to the last numchanges changelists p4 changes s status Limit the list to those changelists with a particular status for example p4 changes s submitted will list only al ready submitted changelists p4 describe changenum Displays full information about a single change list if the changelist has already been submitted the report will include a list of affected files and the diffs of these files The s flag can be used to exclude the diffs of the files Perforce 97 3 User s Manual 58 CHAPTER 8 Labels A PERFORCE label is simply a user determined list of files and revisions The label
78. are and which files have write per mission turned on File Conflicts When two users edit the same file it is possible for their changes to conflict For example suppose two users copy the same file from the depot into their workspaces and each edits his copy of the file in different ways The first user sends his version of the file back to the depot subsequently the second user tries to do the same thing If PERFORCE were to unquestioningly accept the second user s file into the depot the first user s changes would not be included in the latest revision of the file known as the head revision When a file conflict is detected PERFORCE allows the user experiencing the conflict to perform a resolve of the conflicting files The resolve process allows the user to decide Perforce 97 3 User s Manual 13 Chapter 1 PERFORCE Concepts Chapter 8 discusses labels The workings of Inter File Branching is covered in Chapter 9 You ll learn how to do job tracking in Chapter 10 what needs to be done should his file overwrite the other user s Should his own file be thrown away Or should the two conflicting files be merged into one At the user s request PERFORCE will perform a three way merge between the two conflicting files and the single file that both were based on This process generates a merge file from the con flicting files the merge file contains all the changes from both conflicti
79. at once or none of them are The basic syntax of the integrate command is p4 integrate b branchname filepatterns If the filepatterns are left off all the files in the branch are affected When included the filepatterns must describe the new files not the original files and these files must be visi ble through the client view Kurt has created the branch e1m_r1 as above and he s ready to create the branched cop ies in the depot He types p4 integrate b elm_rl and sees depot elm_releasel Changes 1 branch sync from depot elm_proj Changes 6 depot elm_releasel NOTICE 1 branch sync from depot elm_proj NOTICE 23 lt etc gt The branched files have been created in his client workspace and instructions to branch these files have been added to his default changelist He types p4 submit and sees Change new Client kurtv_elm User kurtv Status new Description lt enter description here gt Files depot elm_releasel Changes branch depot elm_releasel Configure branch lt etc gt Perforce 97 3 User s Manual 67 Chapter 9 Branching Discussion of file conflict resolution begins on page 39 Ga Example Propagating original codeline changes to the branched codeline He changes the description and quits the editor the branched files are created within the depot and are copied into the client workspace If Kurt wanted the files to be crea
80. cally either all the files are updated in the depot or none of them are In PER FORCE s terminology this is called an atomic change transaction Changelists can be used to keep files together that have a common purpose Ed is writing the portion of Elm that is responsible for multiple folders multiple mail boxes He has a new source file src newmbox c and he needs to edit the header file Perforce 97 3 User s Manual 23 Chapter 3 Perforce Basics Quick Start 0 p4 sync was named p4 get in previous versions of PERFORCE p4 get can still be used as an alias for p4 sync Example Retrieving files from the depot into the client workspace hdrs s_elm h and the doc elm help files He adds the new file and prepares to edit the existing files cd S p4 add elm src newmbox c depot elm_proj src newmbox c 1 opened for add lt etc gt p4 edit elm hdrs s_elm h doc elm help depot elm_proj hdrs s_elm h 1 opened for edit depot elm_proj doc elm help 0 1 opened for edit n n depot elm_proj doc elm help 1 1 op d for edit depot elm_proj doc elm help 2 2 op d for edit He edits the existing files and then p4 submit s the default changelist Change new Client eds_elm User edk Status new Description Changes to Elm s multiple mailbox functionality Files depot elm_proj doc elm help 0O edit depot elm_proj doc elm help 1 edit depo
81. ce use p4 opened For each opened file within the client workspace that matches a filepattern argument p4 opened will print a line like the following depot elm_proj README edit default change text Each opened file is described by its depot name and location the operation that the file is opened for add edit delete branch or integrate which changelist the file is included in and the file s type To See Use This Command a listing of all opened files in the current workspace p4 opened a list of all opened files in all client workspaces p4 opened a whether or not a specific file is opened by you p4 opened filespec whether or not a specific file is opened by anyone p4 opened a filespec Relationships Between Client and Depot Files It is often useful to know how the client and depot are related at a particular moment in time Perhaps you simply want to know where a particular client file is mapped to within the depot or you may want to know whether or not the head revision of a particular depot file has been copied to the client The commands that express the relationship between cli ent and depot files are p4 where p4 have and p4 sync n The first of these com mands p4 where is used to determine where client files would be mapped through the client view into the depot and vice versa p4 have tells you which depot files and revi sions are available within your client workspace and
82. cess to all files on all hosts but the fifth permis sion gives her back write access on all files within a specific directory If the fourth and fifth lines were switched Lisa would be unable to run any PERFORCE command Access Levels Required by PERFORCE Commands The following table lists the minimum access level required to run each command For example since p4 add requires at least open access p4 add can be run if open write or super protections are granted Command Access Level Command Access Level add open jobs list branch open label open branches list labels list change open labelsync open change f super lock write changes Tist obliterate super client list open open clients list opened list delete open print read depot super protect super depots list refresh read describe read reopen open describe s list reresolve open diff read resolve open diff2 read resolved open edit open revert open files list review review filelog list reviews list fixis open submit write Perforce 97 3 User s Manual 105 Chapter 14 System Administration Protections Command Access Level Command Access Level fixes list sync read have list unlock open help none user list info none users list integrate p open verify review integrated list where none job open a This command doesn t operate on specific files Thus permission is granted to run these com mands if the user has t
83. ch performs a lazy copy referring to the source file revision until a new revi sion is submitted Import copies the contents of the source file revision to the local target 2 Since it is not possible to make remote files the targets of integration integrations are one way only from remote to local Deleting Depots Depots may be deleted with p4 d depotname Depot Reporting Commands All depots known to the current P4D server can be listed with the p4 depots command Perforce 97 3 User s Manual 111 Environment Variables APPENDIX A Each operating system and shell uses its own syntax for setting environment variables This table shows how each OS and shell would set the P4CLIENT environment variable OS amp Shell Environment Variable Example UNIX ksh sh bash UNIX csh VMS Mac MPW Windows 95 NT export P4CLIENT value setenv P4CLIENT value def j P4CLIENT value set e P4CLIENT value Environment variables can be set with set P4CLIENT value but if registry variables are set they will override the environment variable values The registry variables can be set in the user specific part of the registry through the P4 client program with p4 set P4VAR value and can be set in the system registry with p4 set s P4VAR value The use of registry variables is recom mended The two tables on the next four pages describe the environment variables used by PER FORCE
84. connecting to server 15 contacting PERFORCE 4 counters 80 listing 91 cross platform development with branching 63 D daemons 14 creating 81 reporting commands for 91 defect tracking 11 defect tracking systems integrating with 77 deleted file revisions 83 deleting files 22 deletion of changelists 56 of client workspace specifications 20 of jobs 77 of jobs from changelists 57 of labels 62 delta storage 36 38 depot adding files to 20 deleting files from 22 mapping to client workspace 28 subdirectories within 94 updating files in 21 depots defining new 108 deleting 110 distributed 108 listing 92 multiple 108 organization of 51 reporting 110 Description field 19 Descriptions limitations on 33 development vs release code 63 diff 40 and flags 86 overriding client s 47 Perforce s internal 86 setting client program 86 use of in Perforce 85 diff chunks 41 DIFF environment variable 43 difference marker 42 difference markers 43 directory specifying 48 disk space management 99 distributed depots 108 integrating files from 110 donor files 68 reversing sense with target 68 E editing files 21 EDITOR environment variable 18 36 Edits 67 Elm use of in examples 4 email automatically sent 78 email reaching Perforce by 4 environment variables PACLIENT 18 19 26 48 PA4DIFF 43 P4EDITOR 18 36 P4MERGE 43 P4PORT 15 48 79 P4USER 49 PWD 48 USER 49 USERNAME 49 error from incorrect connection to server 16
85. copied to in the client Using Views Views consist of multiple lines or mappings and each mapping has two parts The left hand side specifies one or more files within the depot and has the form depotname file_specification The right hand side of each mapping describes one or more files within the client work space and has the form clientname file_specification The left hand side of a client view mapping is called the depot side the right hand side is the client side The default view in the example above is quite simple it maps the entire depot to the entire client workspace But views can contain multiple mappings and can be much more complex Any client view no matter how elaborate performs the same two functions e The client view determines which files in the depot can be seen by a client workspace This is determined by the sum of the depot sides of the mappings within a view A view might allow the client workspace to retrieve every file in the depot or only those files within two directories or only a single file e It constructs a one to one mapping between files in the depot and files in the client workspace Each mapping within a view describes a subset of the complete mapping The one to one mapping might be straightforward for example the client workspace file tree might be identical to a portion of the depot s file tree Or it can be oblique for example a file might have one name in the depot and
86. cumstances the p4 submit command can fail For example if one user has a file locked and another user submits a changelist that contains that file the submit will fail When a submit of the default changelist fails the changelist is assigned a number is no longer the default changelist and must be referred to by its number In the above circumstances the user must understand how to work with numbered changelists Working with the Default Changelist A changelist is a list of files revision numbers of those files and operations to be per formed on those files For example a single changelist might contain the following Perforce 97 3 User s Manual 54 Chapter 7 Changelists 0 The material in this subsection has already been presented in slightly different form in earlier chapters It is presented again here to provide a complete discussion of changelists A PERFORCE superuser may change the description of a changelist and in some cases may delete changelists entirely Please see page 108 for details doc elm help 1 utils elmalias c revision 3 edit revision 2 delete Each of the files in the changelist are said to be open within the client workspace the first of the files above was opened for edit with p4 edit and the second was opened for dele tion with p4 delete The files in the changelist are updated within the depot with p4 submit which sends the changelist to the server
87. d doesn t need direct access to the remote P4D server programs The use of distributed depots on remote servers is currently limited to read only opera tions thus a P4 client program may not add edit delete or integrate files that reside in depots on other servers Depots sharing the same P4D server as the client are not subject to this limitation Defining New Depots New depots in a server namespace are defined with the command p4 depot depot name If called with the default depotname depot the p4 depot command will bring up the following form Depot Name depot Type local Address subdir Map depot When p4 depot depot is called the form is filled in with values representing the state of the default depot Its name of course is depot It resides in the local P4D server namespace so its type is local as opposed to remote The Map field indicates where the depot subdirectory is located relative to the root directory of the P4D server pro gram in this default case the depot called depot starts in the depot subdirectory directly underneath the root Defining Local Depots To define a new local depot that is a new depot in the current P4D server program namespace p4 depot is called with the new depot name and only the Map field in the resulting form need be changed For example to create a new depot called book with the files stored in the local P4D server namespace in a root subdirectory called manu
88. d language compilers GNU stands for GNU s not UNIX The list of file revisions that the PERFORCE server believes are currently in the cli ent workspace Generated by p4 have The most recent revision of a file within the depot Since file revisions are num bered sequentially this will also be the highest numbered revision of the file To refer to the head revision of file foo use foo head To propagate changes from one codeline to another 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 Perforce 97 3 User s Manual 120 Chapter APPENDIX B Glossary Inter File Branching job job tracking journal journaling label label view license list access local depot local syntax lock log mapping merge 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 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 PERFORCE s mechanism for keeping track of jobs It is implemented via p4 job and p4 fix A file containing
89. d relative to the depot or client root A scripting language available for most operating systems Useful for creating pro grams that utilize PERFORCE commands such as the change review daemon See access Perforce 97 3 User s Manual 122 Chapter APPENDIX B Glossary port project propagate protections pure integration RCS format read access refresh remote depot renumber reresolve resolve resource fork reverse delta storage revert review access review daemon 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 serv er program listens on the port assigned by P4PORT Generic term for some set of files kept by PERFORCE One server might be storing source files for multiple projects To copy changes in one file to a branched copy of the same file leaving the rest of the branch file intact The complete set of permissions as stored in the server s protections table An integration in which changes to the target file incorporates only revisions from a single source file 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 A protections level giving the user permission to run commands such as p4 sync that allow them to read the c
90. d the depot elm_proj doc guide files in a changelist the file conflicts would cause the p4 submit to fail and the resolves would be scheduled as part of the submission failure Perforce 97 3 User s Manual 41 Chapter 5 Perforce Basics Resolving File Conflicts Please see Chapter 7 for a discussion of numbered changelists How Do I Know When a Resolve is Needed p4 submit will fail if it determines that any of the files in the submitted changelist need to be resolved and the error message will include the names of the files that need resolu tion If the changelist provided to p4 submit was the default changelist it will be assigned a number and this number must be used in all future references to the changelist Another way of determining whether a resolve is needed is to run p4 sync n file names before performing the submit using the files in the changelist as arguments to the command If file conflict resolutions are necessary p4 sync n will report them The only advantage of this scheme over viewing the submit error is that the default changelist will not be assigned a number Performing Resolves of Conflicting Files File conflicts are fixed with p4 resolve filenames Each file provided as an argument to p4 resolve is processed separately p4 resolve starts with three revisions of the same file and generates a fourth version the user can accept any of these revisions in place of the current clien
91. daemons It includes 1ist and read access plus use of the p4 review command It is needed only by review daemons super For PERFORCE superusers grants permission to run all PERFORCE com mands Provides write and review access plus the added ability to edit protections create depots obliterate files and verify files Each PERFORCE command is associated with a particular minimum access level for exam ple to run p4 sync on a particular file the user must have been granted at least read access on that file The access level required to run a particular command can usually be reasoned from knowledge of what the command does for example it is somewhat obvi ous that p4 print would require read access A full list of the minimum access levels required to run each PERFORCE command is provided on page 105 Which Users Should Receive Which Permissions The simplest method of granting permissions is to give write permission to all users who don t need to manage the PERFORCE system and give super access to those who do But there are times when this simple solution isn t sufficient Read access to particular files should be granted to users who don t ever need to edit those files For example an engineer might have write permissions for source files but have only read access to the documentation managers might be granted only read access to all files Because open access allows local editing of files but doesn t allow these files t
92. device driver they re now going to begin work on a Macintosh driver using the UNIX code as their starting point They create a branch from the existing UNIX code they now have two copies of the same code and these codelines can evolve separately If bugs are found in either codeline bug fixes can be propagated from one codeline to the other with the PERFORCE integrate command e At PERFORCE we use branching to manage our releases Development always proceeds in files located within depot main When a new release is ready it s branched into another codeline for example the code for this release was copied from depot main into depot 97 3 Bug fixes that affect both codelines will be made within depot main and later integrated into the other codeline Development of release 98 1 will proceed in depot main when the new release is ready it will be branched into depot 98 1 and the process will con tinue like this for all PERFORCE releases Branching s First Action Creating a Branch As described above two separate actions comprise branching first a branch is created e g files are copied second edits are copied from one codeline to the other as needed This section describes the first of these actions The steps to creating a branched codeline are 1 Create the new branch view with p4 branch branchname Use the view in the resulting form to indicate which files are to be included in th
93. e Depot Although all files in the depot can be listed with p4 files there is no option for report ing only the names of subdirectories within the depot However this can be accomplished with the following Perl script which takes file arguments in either PERFORCE or local syn tax open P4 p4 files join ARGV while lt P4 gt s 1 if exists d _ print Sd _ 42 These scripting examples are of course non exhaustive Use scripts whenever you want to generate reports that can t be created through existing PERFORCE commands Perforce 97 3 User s Manual 95 CHAPTER 13 NT 95 Installation of PERFORCE on Windows machines is handled by the installer If you re using PERFORCE on Windows you can skip to the protections and journaling sections both of which start on page 98 System Administration Installation and Maintenance Installation of P4D and P4 PERFORCE operation requires two executables P4D the server and P4 the client If you haven t already downloaded these they may be retrieved from http www per force com perforce load html The P4 program typically resides in usr local bin and P4D is usually located in usr local bin or in its own root directory see below although they can be installed anywhere The P4 program can be installed on any server that has TCP IP access to the P4D host To limit access to the P4D server files
94. e above criteria or if the top of the protections table is reached without finding a matching protection then the user has no permission to run the command and will receive the message You don t have permission for this operation Perforce 97 3 User s Manual 107 curmis System Administration Superuser Commands Three PERFORCE commands can be used only by users with PERFORCE superuser privi leges These commands allow the superuser to verify files using 128 bit signatures remove all traces of file from the depot create multiple depots on the local server or pro vide read access to files on other servers File Verification by Signature The p4 verify filenames command can be used to generate 128 bit signatures of each revision of the named files A list of signatures generated by p4 verify can later be used to confirm proper recovery in case of a crash if the signatures of the recovered files match the previously saved signatures the files were recovered accurately For more information about the MD5 algorithm which is used to generate the file signa tures please see lt http backupvault com md5 htm gt File Obliteration The depot is always growing Obviously this is not always desirable a branch might be performed incorrectly creating hundreds of unneeded files or perhaps there are simply a lot of old files around that are no longer being used p4 delete won t help since this command marks the file as delet
95. e branch and where the branched codeline will be stored within the depot s file tree 2 Make sure that the new files and directories are included in the p4 client view of the client workspace that will hold the new files 3 Use p4 integrate to open the new files for branching The new files are listed in a changelist the associated operation is branch 4 Use p4 submit to submit the changelist to the PERFORCE server This creates the new files in the depot 5 Copythe new files fromthe depottethe chentworkspace with 64 syne The following example demonstrates each of these steps Step 1 Create the Branch View The first step is to create the branch view Creating a branch view does four things 1 Assigns the branched codeline a name 2 Describes which files will be copied from 3 For each original file describes where the new copy will be stored within the depot Perforce 97 3 User s Manual 65 Chapter 9 Branching 4 Maintains a mapping between each original and branch file so that changes to one can u be easily propagated to the other A version of Elm is ready for release and a potential problem is foreseen the developers Example will be submitting code to the depot for the next version of Elm but the release engineers Creating a branch will be submitting fixes to the released version The two policies are clearly incompatible so a branched codeline with duplicate Elm files needs to be c
96. e from one location in the depot to another deleting the file from the original location and then submitting the changelist that includes the integrate and the delete The process is as follows p4 integrate from_files to_files p4 delete from_files p4 submit The from_file will be moved to the directory and renamed according to the to_file speci fier For example if from_file is d1 foo and to_file is d2 bar then foo will be moved to the d1 directory and will be renamed bar The from_file and to_file specifiers may include wildcards as long as they are matched on both sides PERFORCE write access is needed on all the specified files Reading Forms from Standard Input Writing Forms to Standard Output Any commands that require the user to fill in a form such as the p4 client and p4 submit commands can read the form from standard input with the i flag An example is p4 client i lt filename where filename contains the field names and values expected by the form Similarly the o flag can be used to write a form specification to standard output The commands that display forms and can therefore use these flags are p4 branch p4 change p4 client p4 job p4 label p4 protect p4 submit p4 user Perforce 97 3 User s Manual 53 CHAPTER 7 Changelists A PERFORCE changelist is a list of files their revision numbers and operations to be per formed on these files Commands such as p4 add filenames and p4 edit filenames i
97. e is not open for edit in the client the two file revisions should be identical so p4 diff will fail Comparison of the revisions can be forced with p4 diff f even when the file in the client is not open for edit Although p4 diff runs a diffroutine internal to P4 this routine can be overridden by specifying an external diffin the P4DIFF environment variable Runs P4D s diff subroutine on any two PERFORCE depot files The specified files can be any two file revisions even revisions of entirely different files The diff routine used by P4d cannot be overridden Reports what the result of running p4 sync would be without actually performing the sync This is useful to see which files have conflicts and need to be resolved Reports which files have been resolved but not yet sub mitted Chapter 12 has a longer description of each of these commands p4 help provides a com plete listing of the many flags for these reporting commands Perforce 97 3 User s Manual 48 CHAPTER 6 PERFORCE Basics Miscellaneous Topics The manual thus far has provided an introduction to the basic functionality provided by PERFORCE and subsequent chapters cover the more advanced features In between are a host of other smaller facilities this chapter covers these topics Included here is informa tion on the following e Command line flags common to all PERFORCE commands How to work on files while not connected to a PERFORCE server
98. e revisions participating in the merge are binary instead of text a three way merge is not possible Instead p4 resolve performs a two way merge the two conflicting file versions are presented and you can edit and choose between them Locking Files to Minimize File Conflicts Once open a file can be locked with p4 lock so that only the user who locked the file can submit the next revision of that file to the depot Once the file is submitted it is automati cally unlocked Locked files can also be unlocked manually by the locking user with p4 unlock The clear benefit of p4 lock is that once a file is locked the user who locked it will expe rience no further conflicts on that file and will not need to resolve the file But this comes at a price other users will not be able to submit the file until the file is unlocked and will have to do their own resolves once they submit their revision Under most circumstances Perforce 97 3 User s Manual 46 Chapter 5 Perforce Basics Resolving File Conflicts a user who locks a file is essentially saying to other users I don t want to deal with any resolves you do them But there is an exception to this rule Preventing Multiple Resolves with File Locking Without file locking there is no guarantee that the resolve process will ever end The fol lowing scenario demonstrates the problem Ed opens file foo for edit Lisa opens the same file in her client for edit Ed
99. e same file P4D contains its own diff routine which is used by PERFORCE servers to determine file differences when storing deltas Because PERFORCE s diff always determines file deltas by comparing chunks of text between newline characters it is by default only used with text files If a file is binary each revision is usually stored in full but binary files can be checked in as text files insuring that only the deltas are stored Scheduling Resolves of Conflicting Files Whenever a file revision is to be submitted that is not an edit of the file s current head revision there will be a file conflict and this conflict must be resolved In slightly more technical terms we ll call the file revision that was read into a client workspace the base file revision If the base file revision for a particular file in a client workspace is not the same as the head revision of the same file in the depot a resolve must be performed before the new file revision can be accepted into the depot Before resolves can be performed with p4 resolve they must be scheduled this can be done with p4 sync An alternative is to submit a changelist that contains the newly con flicting files if a resolve is necessary the submit will fail and the resolve will be sched uled automatically Why p4 sync to Schedule a Resolve Remember that the job of p4 sync is to project the state of the depot onto the client Thus when p4 sync is performed on a par
100. e target file doesn exist In this case the target file is opened for branch and PER FORCE will track the integration history between the two files Subsequent merges of the two files will treat this donor revision as base e The target file exists and was originally branched from the donor file with p4 inte grate In this case a three way merge is scheduled between the target and the donor e The target file exists but was not branched from the donor Since these two file revi sions did not begin their lives at a common older file revision there can be no base file so p4 resolve can t do a three way merge In this case p4 resolve will doa two way merge in which yours is also used as base Ina two way merge all changes appear as theirs and there can be no conflicts Deleting Branches To delete a branch use p4 branch d branchname Deleting a branch deletes only the branch view description making the branch inaccessi ble from any subsequent p4 integrate commands If the files in the branched codeline are to be removed they must be deleted with p4 delete Advanced Integration Functions PERFORCE s branching mechanism also allows integration of specific file revisions the re integration and re resolving of already integrated code and merging of two files that were previously not related Perforce 97 3 User s Manual 70 Chapter 9 Branching Ga Example Integrating Specific File Revisions
101. eated to perform entirely different functions The primary focus of this chapter is on using the change review daemon a secondary thread discusses how to create your own daemons This daemon creation topic discusses how a daemon might be created that integrates the PERFORCE job tracking facilities to an external defect tracking system Providing Change Review Parameters Any user wishing to receive email notification of changed files must provide two pieces of information to the PERFORCE server her email address and a list of the files and directo ries that she wants to track or subscribe to This information is provided via the p4 user form Sarah wants to be notified whenever any of the Elm README or document files are changed She types p4 user and fills in the resulting form with her email address and file review list User sarahm Email sarahm elmco com Update 04 29 1997 11 52 08 Access 04 29 1997 11 52 08 FullName Sarah MacLonnogan Reviews depot doc depot README Once the review daemon is running she ll be notified by email whenever any of the files in her Review list are changed This includes all README files and all files in the doc sub directory Notification is sent whenever a changelist is submitted by any user that edits deletes or adds files that match the p4 user form Reviews specification Perforce 97 3 User s Manual 79
102. eck pointing should be performed early and regularly Making a Checkpoint You can create a checkpoint by invoking the P4D program with the jc flag p4d r root jc This can be run while the P4D server is running To make the checkpoint P4D locks the entire database and then dumps the database contents to a file named checkpoint x where x is a sequence number Before unlocking the database P4D copies and then trun cates the journal file if it exists This action guarantees that the last checkpoint combined with the current journal always reflects the database A different checkpoint file can be specified by typing a filename after the jc flag Perforce 97 3 User s Manual 98 Chapter 13 System Administration Installation and Maintenance p4d r root jc disk2 perfback ckp A checkpoint file may be compressed archived or moved onto another disk At that time or shortly thereafter the files in the depot subdirectories should be archived as well When recovering the checkpoint must be no newer than the files in the depots The checkpoint file is often much smaller than the original database and can be made smaller still by compressing it The journal file on the other hand can grow quite large it is truncated whenever a checkpoint is made but the older journal is backed up and saved The older journal files can then be moved to external media freeing up more space locally Since checkpoints are readable onl
103. ed in its head revision but leaves the old revisions intact p4 obliterate filename can be used by superusers to remove all traces of a file from a depot making the file indistinguishable from one that never existed in the first place p4 obliterate is so destructive in fact that we haven t even told you how it really works yet p4 obliterate filename only reports on what it will do to actu ally destroy the files use p4 obliterat y filename Changelist Deletion amp Description Editing The f flag can be used with p4 change to change the description or username of sub mitted changelists The syntax is p4 change f changenumber this presents the stan dard changelist form in which the description and or username may be edited Perforce 97 3 User s Manual 108 Chapter 15 System Administration Superuser Commands The f flag can also be used to delete any submitted changelists that have been emptied of files with p4 obliterate The full syntax is p4 change d f changenumber Distributed Depots PERFORCE distributed depots allow the P4 client program to access files from multiple depots These other depots may reside within the P4D server normally accessed by the P4 client program or they may reside within other remote P4D servers The P4 client s local P4D server program acts as a proxy client to the remote server pro grams so the client doesn t need to know where the files are actually stored an
104. eeds to be made to the source code A job might be a bug description like the system crashes when I press return or it might be a system improvement request like please make the program run faster Whereas a job represents work that is intended to be performed a changelist represents work actually done PERFORCE s job tracking mechanism allows jobs to be linked to the changelists that implement the work requested by the job A job can later be looked up to determine if and when it was fixed which file revisions implemented the fix and who fixed it PERFORCE s job tracking mechanism does not implement all functionality normally sup plied by full scale defect tracking systems Its simple functionality can be used as is or it can be integrated with a full scale job tracking system with a scripting language such as Perl Perforce 97 3 User s Manual 14 Chapter 1 PERFORCE Concepts Chapter 11 discusses change review and contains instructions on creating your own daemons PERFORCE s protection mechanism is described in Chapter 14 Change Review and Daemons PERFORCE s change review mechanism allows users to receive email notifying them when particular files have been updated in the depot The files that a particular user receives notification on is determined by that user Change review is implemented by an external Perl program or daemon and can be recoded by a knowledgeable user a
105. elta storage and PERFORCE uses RCS format to store its deltas The file s type determines whether full file or delta storage is used When delta storage is used file merges and file compares can be performed Files that are stored in their full form can t be merged or compared The PERFORCE file types are Storage Keyword Description Comments Type text Text file Treated as text on the client delta xtext Executable text Like a text file but execute permission delta file is set on the client file binary Non text file Accessed as binary files on the client full file xbinary Executable bi Like a binary file but execute permis full nary file sion is set on the client file file ltext Long text file This type should be used for generated full text files such as PostScript files file symlink Symbolic link UNIX clients access these as symbolic delta links non UNIX clients treat them as small text files ktext Text file with Any inclusion of the literal string Id delta keyword ex within the file will be expanded to reflect pansion the depot file name and revision number kxtext Executable text Like a ktext file but execute permis delta file with key sion is set on the client file word expansion resource Macintosh re Please see the Macintosh client release full source fork notes at lt http www per file force com perforce doc mac notes txt gt To find the type of an existing file
106. ence Any revision can be accessed in the depot by its revision number like foo 3 All the subdirectories and files under a given root directory 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 sub types 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 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 The method by which PERFORCE stores file revisions of binary files within the de pot every file revision is stored in full Contrast this with reverse delta storage which is used for text files 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 Software provided by the Free Software Foundation Most GNU software is system level software such as enhanced versions of standard UNIX utilities an
107. er usr edk weasel All files on client weasel depot All files in the depot Name and String Limitations File Names Because of PERFORCE s naming conventions certain characters cannot be used in file names These include unprintable characters the above wildcards and the PERFORCE revi sion characters and Descriptions Label branch user and client workspace specifications have a silent limit of 128 bytes on descriptions The description field of a changelist or a job can be any length Specifying Older File Revisions All of the commands and examples we ve seen thus far have been used to operate only on the most recent revisions of particular files but many PERFORCE commands can act on older file versions For example if Ed types p4 sync eds_elm src lock c the lat est revision or head revision of lock c is retrieved but older revisions can be retrieved Perforce 97 3 User s Manual 34 Chapter 4 Perforce Basics The Details Change numbers are explained in chapter 7 Labels are explained in chapter 8 by tacking a revision specification onto the end of the file name There are seven types of revision specifications Revision Specifier Meaning Examples file n Revision number p4 sync lock c 3 Refers to revision 3 of file Lock c file n A change number p4 sync lock c 126 Refers to the version of lock c when changelist 126 was submitted even if it was not part of
108. erge that conflict with base d diff Diff line sets from merge that conflict with yours m merge Invoke the command MERGE base theirs yours merge To use this option you must set the environment variable MERGE to the name of a third party pro gram that merges the first three files and writes the fourth as a result 2 help Display help for p4 resolve s skip Don t perform the resolve right now ay accept yours Accept yours into the client workspace as the re solved revision ignoring changes that may have been made in theirs at accept theirs Accept theirs into the client workspace as the re solved revision The revision that was in the client workspace is trashed am accept merge Accept merged into the client workspace as the re solved revision The version originally in the client workspace is trashed a accept Keep PERFORCE s recommended result Depending on the circumstances this will be either yours theirs or merge Perforce 97 3 User s Manual 44 Chapter 5 Perforce Basics Resolving File Conflicts Ea Example Resolving file Conflicts Only a few of these options are visible on the command line but all options are always accessible and can be viewed by choosing help The command line has the following format Accept a Edit e Diff d Merge m Skip s Help am PERFORCE s recommended choice is displayed in brackets at the end of the command line Pressing return or choos
109. evision range A range of revision numbers for a specified file specified as the low and high end of the range For example fo0 5 7 would access the fifth through seventh revi sions of file foo Only a few commands allow revision ranges to be specified The only non report ing command that allows a revision range is p4 integrate revision A suffix to filenames that specify a particular revision of that file Revision speci specification fiers 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 server root The directory in which the server program stores its metadata and all the shared files The directory is set via the PHROOT environment variable Software A category of software whose definition changes from manufacturer to manufac Configuration turer PERFORCE is a Software Configuration Management system Functions com Management monly said to comprise SCM systems are version control concurrent development release management
110. external client diff program u p4 diff du brief p4 diff d brief C29 p4 diff d C 25 Perforce 97 3 User s Manual 87 Chapter 12 Reporting and Data Mining A Korn shell script that implements this report is described in Reporting with Scripting on page 94 a Very few PERFORCE commands allow revision ranges to be appended to file specifications For details on revision ranges please see page 36 Changelists Two separate commands are used to describe changelists The first p4 changes lists changelists that meet particular criteria without describing the files or jobs that make up the changelist The second command p4 describe lists the files and jobs affected by a single changelist These commands are described below Changelists that Meet Particular Criteria To view a list of changelists that meet certain criteria such as changelists with a certain status or changelists that affect a particular file use p4 changes The output looks like the following Change 36 on 1997 09 29 by edk eds_elm Changed filtering me Change 35 on 1997 09 29 by edk eds_elm Misc bug fixes fixe Change 34 on 1997 09 29 by lisag lisa Added new header inf By default p4 changes displays an aggregate report containing one line for every changelist known to the system but command line flags and arguments can be used to limit the changelists displayed to those of a particular statu
111. fife write joe IL ovis write lisag depot write lisag depot doc super edk pee The four fields may not line up vertically on your screen they are aligned here for ease of reading Perforce 97 3 User s Manual 101 Chapter 14 System Administration Protections The Permission Lines Four Fields Each line specifies a particular permission each permission is always described by four fields The meanings of these four fields are Field Meaning Access Level User Host Files Which access level is being granted list read open write super or review These are described below The user whose protection level is being defined This field can contain the wildcard by itself would grant this protection to everyone xe would grant this protection to everyone whose username ends with an e Since PERFORCE usernames can be changed by setting P4USER this field provides safety not security The TCP IP address of the host being granted access This must be pro vided as the numeric address of the host in dotted quad notation e g 206 14 52 194 This field may contain the wildcard A by itself means that this protection is being granted for all hosts The wildcard can be used as in any string so 127 30 41 would define access to any subnet within 127 30 41 and 3 would refer to any IP address with a 3 init
112. file conflict the same resolve can be scheduled manually without sub mitting by syncing the head revision of a file over an opened revision within the client workspace Resolves are always performed with p4 resolve PERFORCE also provides facilities for locking files when they are edited This can elimi nate file conflicts entirely RCS Format How PERFORCE Stores File Revisions PERFORCE uses RCS format to store its text file revisions binary file revisions are always saved in full If you already understand what this means you can skip to the next section of this chapter the remainder of this section explains how RCS format works Perforce 97 3 User s Manual 39 Chapter 5 Perforce Basics Resolving File Conflicts Only the Differences Between Revisions are Stored A single file might have hundreds even thousands of revisions Every revision of a par ticular file must be retrievable and if each revision was stored in full disk space problems could occur one thousand 10KB files each with a hundred revisions would use a gigabyte of disk space The scheme used by most SCM systems including PERFORCE is to save only the latest revision of each file and then store the differences between each file revision and the one previous As an example suppose that a PERFORCE depot has three revisions of file foo The head revision f00 3 looks like this foo 3 This is a test of the emergency broadcast system Revi
113. file is ever included in a label s file list 3 If labelsync is called with no filename arguments as in p4 labelsync 1 labelnam Perforce 97 3 User s Manual 60 Chapter 8 Labels Ga Example Storing file references in a label with p4 labelsync Ga Example Changing file references in a label with p4 labelsync ie Example Including a different file revision in a label then all the files mapped by the label view will be listed in the label The revisions added to the label will be those last synced into the client these revisions can be seen in the p4 have list Calling labelsync this way will replace all existing file references with the new ones Ed has created a label called i1ters 1 as specified above now he wants to load the filters 1 label with the proper file revisions He types p4 labelsync 1 filters 1 and sees the following depot elm_proj filter Makefile SH 20 added depot elm_proj filter actions c 25 added lt ete gt The file revisions added to the label are those contained in the intersection of the label view and the current client have list 4 If p4 labelsync is called with filename arguments and the arguments contain no revision specifications the head revisions of these files are included in the label s file list After performing the above labelsync command Ed finds that the file filter fil ter c is buggy He fixes it submits the
114. for all changelists numbered above that counter The review daemon s review counter is called review the daemon uses p4 review t review to get a list of all unreviewed changelists and uses p4 review t review c lastchangenumto store the highest numbered reviewed change number in the database under the name review PERFORCE can store any number of review counters each counter is identified by a unique name which can be up to ten characters long and cannot contain whitespace The perfreview perl daemon s review counter is named review if you re using perfreview perl and are writing your own daemon don t name the review counter review Change Review and Protections The change review daemon runs at the access level of the user who invokes it typically root not at the access level of the user receiving email Thus if the daemon is edited to perform additional functionality it should not mail out the contents of files unless it is safe for all users to see those files since a user needs only 1ist access in order to invoke the p4 user command to subscribe to particular files Perforce 97 3 User s Manual 81 Chapter 11 Change Review amp Other Daemons Creating Other Daemons To create another daemon use perfreview perl as a Starting point and change it as needed One such daemon might upload PERFORCE job information into an external bug tracking system after changelist submission It would use the p4 rev
115. fs of the new file revisions and the previous revisions use p4 describe Its output looks like this Jobs fixed Affected files depot doc elm 1 2 edit Differences depot doc elm 1 2 3c53 The second way A oO Il gt The second way eae leEtT S gt Change 43 by lisag warhols on 1997 08 29 13 41 07 Made grammatical changes to basic Elm documentation job000001 fixed on 1997 09 29 by edk edk Fix grammar in main Elm help file text used most commonly when transmitting which is commonly used when transmitting This output is quite lengthy a shortened form that eliminates the file diffs can be gener ated with p4 describe s changenum To See Use This Command a list of all files submitted and jobs fixed by a particular changelist displaying the diffs between the file revisions submitted in that changelist and the previous revisions a list of all files submitted and jobs fixed by a particular changelist without the file diffs a list of all files and jobs affected by a particular changelist while passing the context diff flag to the underlying diff pro gram the state of particular files at a particular changelist whether or not these files were affected by the changelist p4 describe changenum p4 describe s changenum p4 describe dc changenum p4 files changenum filespec Labels Reporting on labels is accomplished with a very small set
116. h integrate e client name e user name and e description If the operation was branch or integrate the names and revisions of the corresponding branch files are re ported as well There is an ordering to the first four of these commands the first is performed before integrate the second is done after integrate and before resolve the third is given after resolve but before submit and the fourth is performed after submit The fifth command provides a complete history of any file and is incredibly useful Perforce 97 3 User s Manual 73 CHAPTER 10 Daemons are described in Chapter 11 Ga Example Creating a Job Job Tracking A job is a written description of some modification to be made to a source code set A job might be a bug description like the system crashes when I press return or it might be a system improvement request like please make the program run faster Whereas a job represents work that is intended a changelist represents work actually done PERFORCE s job tracking mechanism allows jobs to be linked to the changelists that implement the work requested by the job A job can later be looked up to determine if and when it was fixed which file revisions implemented the fix and who fixed it A job linked to a particular changelist is marked as completed when the changelist is submitted Jobs perform no functions internally to PERFORCE rather they are provided as a method of
117. h elm help within Mike s client workspace help subdirectory will be mapped to the doc subdirectory of the depot Excluding Files and Directories from the View Exclusionary mappings allow files and directories to be excluded from a client workspace this is accomplished by prefacing the mapping with a minus sign Whitespace is not allowed between the minus sign and the mapping Bill whose client is named billm wants to view only source code he s not interested in the documentation files His client view would look like this billm billm doc depot elm_proj depot elm_proj doc Since later mappings have precedence over earlier ones no files from the depot s doc subdirectory will ever be copied to Bill s client Conversely if Bill does have a doc subdi rectory in his client no files from that subdirectory will ever be copied to the depot Allowing Filenames in the Client to be Different than Depot Filenames Mappings can be used to make the names of files different in the client workspace than they are in the depot Mike wants to store the files as above but he wants to take the elm help X files in the depot and call them helpfile X in his client workspace He uses the following map pings mike_elm mike_elm help helpfile depot elm_proj depot elm_proj doc elm help Each wildcard on the depot side of a mapping must have a corresponding wildcard on the client side of
118. hat are not in the intersection of the label s contents and depot elm_proj hdrs are deleted from her workspace Ifp4 sync labelname is called with no file parameters all files in the client that are not in the label will be deleted from the client If this command is called with file argu ments asin p4 sync files labelname then the client workspace at the intersection Perforce 97 3 User s Manual 62 Chapter 8 Labels of the depot the client workspace view and the file parameters will be updated to match the contents of the depot at that intersection Deleting Labels A label can be deleted in its entirety with p4 label d labelnam Files can be deleted from labels with p4 labelsync d 1 labelname filepatterns A variant of this is p4 labelsync d 1 labelname This command deletes all the files from the label s file list but leaves the empty label in the system Label Reporting The commands that output reports on labels are Command Description p4 labels Report the names dates and descriptions of all labels known to the server p4 files Lists all files and revisions contained in the given label labelname p4 sync n Shows what p4 sync would do when retrieving files from a labelname particular label into your client workspace without actually performing the sync Perforce 97 3 User s Manual 63 CHAPTER 9 Branching PERFORCE s Inter File Branching mechanism
119. he branched files must be accessible through the cli ent view Perforce 97 3 User s Manual 66 Chapter 9 Branching Example Including branched files in a client view a Example Using integrate to create branched files Kurt will be working with the branched files His client is kurtv_cli he types p4 cli ent and adds a line to his client view Client kurtv_cli Date 05 25 1997 18 34 58 Owner kurtv Description Created by kurtv Root usr kurtv View depot elm_releasel kurtv_cli elm rl There might be other mappings within the client view the only crucial factor is that the files in the depot s elm branch directory be mapped to some location in Kurt s client workspace The mapping shown here accomplishes this Steps 3 amp 4 Use p4 integrate and p4 submit to Create the Target Files To create the new branch files use p4 integrate followed by p4 submit When the branch files don t yet exist in the depot integrate creates the branched files in the client workspace and tells the server that the branch files are to be copied from the original files described in the branch mapping The integrate command like add edit and delete does not actually affect the depot immediately instead it adds the affected files to a changelist which must be submitted with p4 submit This keeps the integrate operation atomic either all the named files are affected
120. he client view i To use PERFORCE properly it is crucial to understand how views work Views are explained in more detail at the start of the next chapter Ed is working with his elm files in a setting as described above He s set the environment variable P4CLIENT to eds_elm now he types p4 client from his home directory and sees the following form Client eds_elm Owner ed Description Created by ed Root usr edk Options View depot nomodtime noclobber eds_elm If he were to leave the form as is all of the files under usr edk would be mapped to the depot and they would map to the entire depot instead of to just the elm project He changes the values in the Root and View fields as follows Client eds_elm Owner ed Description Created by ed Root usr edk elm Options nomodtime noclobber View depot elm_proj eds_elm This specifies that usr edk elm is the top level directory of Ed s client workspace and that the files under this workspace directory are to be mapped to the depot s elm_pro j subtree When Ed s done he quits from the editor and the p4 client command completes The read only Client field contains the string stored in the P4CLIENT environment variable Description can be filled with anything at all up to 128 characters this pro vides an arbitrary textual description of what s contained in this client workspace
121. he specified access to at least one file in the depot b Torunp4 integrate the user needs open access on the target files and read access on the donor files Those commands that list files such as p4 describe will only list those files to which the user has at least 1ist access How Protections are Implemented This section describes the algorithm that PERFORCE follows to implement its protection scheme Protections can be used properly without reading this section the material here is provided to explain some of the more eccentric behavior described above Users access to files is determined by the following steps e The command is looked up in the command access level table shown on page 105 to determine the minimum access level needed to run that command In our example p4 print is the command and the minimum access level required to run that command is read e PERFORCE makes the first of two passes through the protections table Both passes move up the protections table bottom to top looking for the first relevant line The first pass is used to determine whether or not the user is allowed to know whether or not the file exists and this search simply looks for the first line encountered that matches the user name host IP address and file argument If the first matching line found is an inclusion ary protection then the user has permission to list the file and PERFORCE proceeds to the second pass If the first mapping f
122. ibed in the next section E Lisa whose PERFORCE username is lisag is using a client with the IP address Example 195 42 39 17 The protections file reads as follows How protections work Protections read 195 42 39 17 VA eee write lisag 195 42 39 17 depot elm_proj doc read lisag JA isisa super edk ane The union of the first three permissions apply to Lisa Her username is 1isag and she s currently using a client workspace on the host specified in lines 1 and 2 Thus she can write files located in the depot s doc subdirectory but can only read other files Lisa tries the following She types p4 edit lisag doc elm help 1 and is successful She types p4 edit lisag READ ME and is told that she doesn t have the proper permission She is trying to write a file that she only has read access to She types p4 sync lisag READ ME and this command succeeds only read access is needed and this is granted to her on line 1 Lisa later switches to another machine with IP address 195 42 39 13 She types p4 edit lisag doc elm help 1 and the command fails when she s using this host only the third permission applies to her and she only has read privileges Exclusionary Protections A user can be denied access from particular files by prefacing the fourth field in a permis sion line with a minus sign This is useful for giving most users access to a particular set of file
123. ies But the label filters 1 is empty it contains no file references It will be loaded with its file references with p4 labelsync The View field is used to limit the files that are included in the label These files must be specified by their location in the depot this view differs from other views in that only the depot side of the view is specified The locked unlocked option in the Options field can prevent p4 labelsync from overwriting previously synced labels this is described further in Preventing Accidental Overwrites of a Label s Contents on page 62 Adding and Changing Files Listed in a Label Once a label has been created references to files can be included in the label with the labelsync command The syntax for labelsync is l p4 labelsync a d n 1 labelname filename The rules followed by labelsync to include files in a label are as follows 1 All files listed in a label must be contained in the label view specified in the p4 label form Any files or directories that are not mapped through the label view are ignored by labelsync All the following rules assume this without further mention 2 When labelsync is used to include a particular file in a label s file list the file is added to the label if it is not already included in the label If a different revision of the file is already included in the label s file list it is replaced with the newly specified revision Only one revision of any
124. ies may be relocated to other disks using symbolic links from the depot trees This should be done while the PAD server is not running The database files can become internally bloated due to the nature of the implementa tion of their access methods They can sometimes be compressed by recreating them from a checkpoint take a checkpoint delete the database files then recover This should only be done if the database files are more than about 10 times the size of the checkpoint in total License File PERFORCE servers are licensed according to how many users they will support This licensing information lives in a file called license in the P4D root directory It is a plain text file supplied by PERFORCE Software Without this license file the P4D server will limit itself to two users and two client workspaces The current licensing information can be viewed by invoking p4d_ V from the server root directory When the server is running the license information can also be viewed with p4 info Release and License Information The P4 client and P4D server programs will display their version and license information with the V flag The p4 info command will attempt to connect to the server and display its license information among other things Version information can also be gleaned from P4 or p4d executables with the UNIX what 1 command Perforce 97 3 User s Manual 100 carn System Administration Protections PERFOR
125. iew command with a new review counter to list new changelists and use p4 fixes to get the list of jobs fixed by the newly submitted changelists This information might then be fed to the exter nal system notifying it that certain jobs have been completed If you do write a daemon of your own and would like to share it with other users please let us know about it at info perforce com Change Review Reporting The change review daemon uses two reporting commands that have not yet been dis cussed an additional reporting command describes the counters tracked by the P4D server Command Meaning p4 reviews Provides a list of all users who have subscribed to review any c changenum files i hess t z 5 lt To see a list of reviewers for the files affected by a particular changelist use p4 reviews c changenum p4 reviews files can also be used to report the reviewers of only those files that are provided as arguments p4 users Describe the users currently known to the P4D server The report includes user names their email addresses their full names and the last time they logged in p4 counters Provides a list of counters known to the current P4D server along with their values Perforce 97 3 User s Manual 82 carr Reporting and Data Mining PERFORCE s reporting commands supply information on all data stored within the depot There are many reporting commands in fact there are almost as many reporting co
126. ile is mapped through the branch view the target is marked for deletion This is consistent with integrate s semantics it attempts to make the tar get tree reflect the donor tree When the r flag is not provided to p4 integrate the original codeline provides the donor files and the branched codeline provides the targets When the r flag is given the branched codeline is the donor and the original files are the targets Integration Reporting The branching related reporting commands are Command Function p4 integrate n filepatterns p4 resolve p4 p4 p4 p4 n filepatterns resolved integrated filepatterns branches filelog filepatterns Reports what integrate would do without actually do ing it Any of the usual parameters to integrate can be specified as well Reports files that have been scheduled for resolve by p4 integrate but that have not yet been resolved Reports what p4 resolve would do without actually doing it Any of the usual parameters to resolve can be provided as well Lists those files that have been resolved but have not yet been submitted Describes all integrated and submitted files that match the filepattern arguments Display a list of all branches known to the system Describes the revision history of the named files For each revision of the named files the following is report ed e change number e operation edit add delete branc
127. ing 90 reporting 77 status 74 jollity and mirth 2 journaling 97 K keyword expansion 36 keyword text files 35 ktext files 36 kxtext files 36 L label revision specifier 61 label views 59 labels 13 58 62 adding files to 59 changing files within 59 contrasted to change numbers 58 creating 58 deleting 62 deleting files from 62 locking 59 61 name limitations of 59 preventing accidental overwrite 61 reporting 62 88 when to use 58 labelsyne 59 and filename arguments 59 60 large text files 35 licensing 99 lifecycle management 11 list access level 101 local depots 108 locking of labels 59 61 locking files 45 to minimize file conflicts 46 Itext files 36 M Macintosh resource forks 35 manual bugs and 4 manual authors of Robert Orenstein Philboyd Studge mapping depots to client workspaces 28 mappings and depots 109 changing string order 30 conflicting 31 defined 28 exclusionary 30 types of 29 wildcards in 29 margin note icons 3 MD5 algorithm 107 MERGE environment variable 43 merge file 41 generation of 42 merge scheduling 67 merge See resolve merging three way 13 metadata 15 and protections 100 modification times of files 51 modtime 51 moving files between changelists 57 N n flag 92 namespaces of labels 59 naming the p4d host 16 noclobber 51 nomodtime 51 O o flag 92 older revisions 33 one to one mapping between depot and client 28 open 20 definition of 20 open status of jobs 74 open
128. ing Accept will perform the recommended choice The recom mended command is chosen by PERFORCE by the following algorithm if there were no changes to yours accept theirs If there were no changes to theirs accept yours Otherwise accept merge In the last example Ed scheduled the doc guide files for resolve This was necessary because both he and Lisa had been editing the same files Lisa had already submitted ver sions and Ed needs to reconcile his changes with Lisa s To perform the resolves he types p4 resolve depot elm_proj doc guide and sees the following usr edk elm doc Alias guide merging depot elm_proj doc Alias guide 5 Diff chunks 4 yours 2 theirs 1 both 1 conflicting Accept a Edit e Diff d Merge m Skip s Help e This is the resolve dialog for doc Alias guide the first of the four doc guide files Ed sees that he s made four changes to the base file that don t conflict with any of Lisa s changes he also notes that Lisa has made two changes that he s unaware of He types dt for display theirs to view Lisa s changes he looks them over and sees that they re fine Of most concern to him of course is the one conflicting change He types e to edit the PERFORCE generated merge file and searches for the difference marker gt gt gt gt The following text is displayed Intuitive Systems Mountain View California gt gt gt gt ORIGINAL VERSION
129. ing files See editing files options p4 client 51 organization of depot 51 OS file permissions 21 P p4 12 15 installation 95 p4 client options 51 p4 commands add 20 27 35 54 branch 52 64 branches 89 change 52 54 57 74 changes 57 87 client 18 20 28 29 36 51 52 clients 92 counters 91 delete 20 22 50 54 depots 92 110 describe 57 79 88 diff 47 49 50 85 86 diff2 47 85 86 edit 20 21 35 40 50 54 56 filelog 37 83 90 files 37 62 82 83 88 89 fix 57 76 77 fixes 77 81 90 91 get 23 have 25 37 50 60 84 help 25 49 info 25 integrate 52 66 72 89 integrated 90 job 52 73 77 jobs 77 90 91 label 52 58 62 labels 62 88 89 labelsync 59 62 lock 45 56 obliterate 107 opened 36 37 84 print 37 85 protect 52 100 106 refresh 24 50 rename 52 reopen 54 55 57 reresolve 70 resolve 38 46 67 71 89 resolved 47 72 89 revert 24 51 54 57 review 79 80 81 91 reviews 79 81 92 submit 20 22 36 41 44 52 54 65 74 75 sync 23 24 33 37 40 41 47 50 51 61 62 64 67 84 85 unlock 45 user 52 78 81 users 81 92 verify 107 where 37 84 85 PACLIENT environment variable 18 19 26 48 p4d 12 15 and journaling 97 error logging 97 installation 95 root directory of 95 starting 96 P4PORT environment variable 15 16 48 79 95 96 P4ROOT environment variable 95 P4USER environment variable 49 pending changelists 54 perfreview perl 79 Perl and PERFORCE 79 81 permissions See protections
130. ists have already had their descriptions emailed to reviewers in general most PERFORCE daemons will need to keep track of which changelists have already been processed The p4 review command exists to facilitate this process it was written solely to support daemon creation and is not likely to be run by an end user Every line of output produced by p4 review has the following form Change changenum user lt email_addr gt Full_Name For example Change 6 edk lt edk elmco com gt Ed Kuepper When used with no parameters p4 review will output one line for every changelist that has ever been submitted With the addition of review counter arguments p4 review can limit its output to only those changelists not already reported A review counter is simply a named counter each review counter can separately track which changelists have and haven t yet been reviewed Review counters are used in two variants of p4 review p4 review t countername c changenum Tells p4 review that all changelists between and changenum have already been reviewed by the review counter named countername p4 review t countername Reports only those changelists not already reported by re view counter countername Review counters work by storing one counter per review counter in the PERFORCE data base The first variant of p4 review above sets a counter value for a particular review counter the second variant gets the change information
131. it is recommended that P4D be owned and run by a PERFORCE user account Only a few steps need to be performed before P4 and P4D can be run a root directory for the P4D files is created a TCP IP port is provided to P4d and P4 is provided the name of the P4D host and number of the P4D port These steps are described in the following sec tions Creating a P4D Root Directory PAD stores all of its data in files and subdirectories of its own root directory which can reside anywhere on the server system This directory can be named anything at all and the only necessary permissions are read and write for the user who starts P4D Since P4D will store all submitted files in this directory the size of the directory can eventually become quite large Disk space management is described on page 100 The environment variable P4ROOT should be set to point to this directory Alternatively the r flag can be provided when P4D is started see below The P4 clients never directly use this directory so they don t need to know the value of P4ROOT Setting P4D s Port P4D and P4 communicate via TCP IP When P4D starts it will by default listen on port 1666 The P4 client will by default assume that its P4D server is located on host per force listening on port 1666 Perforce 97 3 User s Manual 96 Chapter 13 System Administration Installation and Maintenance If P4D is to listen on a different port the port can be specified
132. keeping track of what changes to the source are needed which user is responsible for implementing the job and which file revisions contain the implementation of the job Since jobs do nothing more than provide this information to the user the job reporting facilities are particularly important The job facilities in PERFORCE do not provide a full scale job tracking system They can be used as is or integrated with another system via a daemon Creating and Editing Jobs Jobs are created with the p4 job command Sarah who shares the same PERFORCE server as Ed has found a bug in Elm s filtering code Ed is fixing code so Sarah creates a new job with p4 job and fills in the resulting form as follows Job new User edk Status new Description Filters on the Reply To field don t work Perforce 97 3 User s Manual 74 Chapter 10 Job Tracking She has changed User from her username to edk Ed will see this job the next time he views any pending changelist with p4 submit or p4 change The p4 job form s fields are Field Name Description Default Job The name of the job Whitespace is not new allowed in the name User The user whom the job is assigned to usually PERFORCE user the username of the person assigned to fix name of the per this particular problem son creating the job Status open closed suspended or new new changes to An open job is one that has been created but
133. le revision of foo that he edited is no longer the head revision of that file If any file in a changelist is rejected for any reason the entire changelist is backed out and none of the files in the changelist are updated in the depot If the submitted changelist was the default changelist PERFORCE assigns the changelist the next change number in sequence and this change number must be used from this point on to refer to the change list If the submit failed because the client owned revision of the file is not the head revision a Chap ter 5 merge must be performed before the changelist will be accepted discusses the merge resolve process PERFORCE May Renumber a Changelist upon Submission The change numbers of submitted changelists always reflect the order in which the amp changelists were submitted Thus when a changelist is submitted it may be renumbered Eaa Ed has finished fixing the filtering bug that he s been using changelist 29 for Since he Example created that changelist he s since submitted another changelist change 30 and two Automatic other users have submitted changelists Ed submits change 29 with p4 submit c 29 renumbering of and is told changelists Change 29 renamed change 33 and submitted Perforce 97 3 User s Manual 57 Chapter 7 Changelists Deleting Changelists To remove a pending changelist that has no files or jobs associated with it use p4 change d changenum Pending ch
134. le to compare entire trees of files There are many more flags to p4 diff then are described below For a full listing please type p4 help diff at the command line or consult the PERFORCE Command Reference To See the Differences between Use This Command an open file within the client workspace and p4 diff file the revision last taken into the workspace any file within the client workspace and the p4 diff f file revision last taken into the workspace Perforce 97 3 User s Manual 86 Chapter 12 Reporting and Data Mining To See the Differences between Use This Command a file within the client workspace and the p4 diff file head same file s current head revision a file within the client workspace and a spe p4 diff file revnumber cific revision of the same file within the depot the n th and head revisions of a particular p4 diff2 filespec filespec n file all files at changelist n and the same files at p4 diff2 filespec n filespec m changelist m all files within two branched codelines p4 diff2 depot codelinel depot codeline2 a file within the client workspace andthe re p4 diff dc file vision last taken into the workspace passing the context diff flag to the underlying diff The last example above bears further explanation to understand how this works it is nec essary to discuss how PERFORCE implements and calls underlying diff routines
135. list is provided to these commands with the c flag There is always a single default changelist in use for each client workspace The depot that is always available on a PERFORCE server Its name is depot Perforce 97 3 User s Manual 118 Chapter APPENDIX B Glossary delete delta delta storage depot depot root depot side depot syntax detached difference marker distributed depot donor file edit environment variable exclusionary mapping exclusionary access fast 1 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 2 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 The line by line differences between one file revision and its next or previous re vision See reverse delta storage A file repository on the P4D server It contains all versions of all files ever submit ted to the server There can be multiple depots on a single server The root directory for a particular depot For the default depot depot the depot root is the depot subdirectory of the server root directory The left side of any client view mapping The union of all depot sides of a client view specifie
136. ll is one of these escape the before use Using Revision Specifications without Filenames Revision specifications can be provided without file names This limits the command s action to the specified revision of all files in the depot or in the client s workspace Thus head refers to the head revisions of all files in the depot and labe1 refers to the revi sions of all files in the named label Ed wants to retrieve all the doc files into his Elm doc subdirectory but he wants to see only those revisions that existed at change number 30 He types p4 sync eds_elm doc 30 Later he creates another client for a different user The new client should have all of the file revisions that Ed last synced Ed sets up the new client specification and types p4 sync depot elm_proj eds_elm He could have typed p4 sync eds_elm and the effect would have been the same Another client needs all its files removed but wants PERFORCE to know that it still con tains those files Ed sets PACLIENT to the correct clientname and types p4 sync none Revision Ranges A few PERFORCE client commands can limit their actions to a range of revision numbers rather than just a single revision A revision range is two revision specifications separated by a comma If only a single revision is given where a revision range is expected the named revision specifies the end of the range and the start of the range is assumed to be 1
137. llowing change review functionality to be customized Protections PERFORCE provides a protection scheme to prevent unauthorized or inadvertent access to the depot The protection mechanism determines exactly which PERFORCE commands are allowed to be run by any particular client Permissions are granted or denied based on the user s username and IP address Since PERFORCE usernames are easily changed protections at the user level provide safety not security Protections at the IP address level are as secure as the host itself Perforce 97 3 User s Manual 15 CHAPTER 2 This chapter assumes that both the P4D and P4 programs have been installed by a system administrator Installation instructions can be found in Chapter 13 Ga Example Output from p4 info when correctly connected to the P4D server Connecting to the P4p Server PERFORCE uses a client server architecture Files are created and edited by users on their own client hosts these files are transferred to and from a shared file repository located on a PERFORCE server Every running PERFORCE system uses a single server and can have many clients Two programs do the bulk of PERFORCE s work e The P4D program is run on the PERFORCE server It manages the shared file repository and keeps track of users clients protections and other PERFORCE metadata e The P4 program is run on each PERFORCE client It sends the users s requests to the P
138. m help 3 file He opens the file for edit cd elm p4 edit doc elm help 3 depot elm_proj doc elm help 3 1 opened for edit and then edits the file with any text editor When he s finished he submits the file to the depot with p4 submit as above Deleting Files From the Depot Files are deleted from the depot similarly to the way they are added and edited the p4 delete command opens the file for delete in the default changelist and then p4 submit is used to delete the file from the depot p4 delete also deletes the file from the client workspace this occurs when the p4 delete command is given In essence p4 delete replaces the operating systems rm or del command Ed s file doc elm help 3 is no longer needed He deletes it from both his client work space and from the depot as follows cd elm doc p4 delete elm help 3 depot elm_proj doc elm help 3 1 opened for delete The file is deleted from the client workspace immediately it is not deleted from the depot until the p4 submit command is given Once the changelist is submitted it will appear as if the file has been deleted from the depot however old file revisions are never actually removed This makes it possible to read older revisions of deleted files back into the client workspace Submitting with Multiple Operations Multiple files can be included in any changelist Submitting the changelist to the depot works atomi
139. m mands as there are action commands These commands have been discussed throughout the manual this chapter presents the same commands and provides additional information for each command Tables in each section contain answers to questions of the form How do I find information about Many of the reporting commands have numerous options discussion of all options for each command is beyond the scope of this manual For a full description of any particular command please consult the PERFORCE Command Reference or type p4 help command at the command line One previously mentioned note on syntax is worth repeating here any filespec argument in PERFORCE commands as in p4 files filespec will match any file pattern that is supplied in local syntax depot syntax or client syntax with any PERFORCE wildcards Brackets around filespec means that the file specification is optional Files The commands that report on files fall into two categories those that give information about file contents e g p4 print p4 diff and those that supply information on file metadata the data that describe a file with no reference to content e g p4 files p4 filelog The first set of reporting commands discussed in this section describes file metadata the second set describes file contents File Metadata Basic File Information To view information about single revisions of one or more files use p4 files This com mand provides the loca
140. n practice the client root is the lowest level directory under which the managed source files will sit PERFORCE manages the files in a client workspace in a few direct ways It creates updates or deletes files when the user requests PERFORCE to synchronize the client workspace with the depot it turns on write permission when the user requests to edit a file and turns off write permission and submits updated versions back to the depot when the user is finished editing the file The entire PERFORCE client workspace state is tracked by the PERFORCE server The server knows what files a client workspace has where they are and which files have write per mission turned on PERFORCE s management of a client workspace requires a certain amount of cooperation from the user Since client files are just plain files with write permission turned off willful users can circumvent the system by turning on write permission directly deleting or renaming files or otherwise modifying the file tree supposedly under PERFORCE s control PERFORCE counters this with two measures first PERFORCE has explicit commands to verify that the client workspace state is in accord with the server s recording of that state Perforce 97 3 User s Manual 27 Chapter 4 Perforce Basics The Details second PERFORCE tries to make using PERFORCE at least as easy as circumventing it For example to make a temporary modification to a file it is easier to use PER
141. nch each file set is known as a codeline and copying an edit from one file set to the other is called inte gration The entire process is called branching When to Create a Branch Create a branch whenever two sets of code have different rules governing when code should be submitted or whenever a set of files needs to evolve along different paths For example e The members of the development group want to submit code to the depot whenever their code changes whether or not it compiles but the release engineers don t want code to Perforce 97 3 User s Manual 64 Chapter 9 Branching a In previous versions of PERFORCE it was necessary to perform the fifth step retrieval of the new codeline files into the client workspace with p4 sync This step is no longer necessary p4 integrate now copies the files into the client workspace for you To disable this automatic file copying use p4 integrate v if you do this you ll need to perform a sync after the submit be submitted until it s been debugged verified and signed off on They would branch the release codeline from the development codeline when the development codeline is ready it would be integrated into the release codeline Patches and bug fixes would be made in the release code later these changes could be integrated into the development code e A company is writing a driver for a new multi platform printer They ve written a UNIX
142. nclude the affected files in a changelist the depot is not actually altered until the change list is submitted with p4 submit When a changelist is submitted to the depot the depot is updated atomically either all of the files in the changelist are updated in the depot or none of them are This grouping of files as a single unit guarantees that code alterations spanning multiple files will update in the depot simultaneously To reflect the atomic nature of changelist submissions submis sion of a changelist is sometimes called an atomic change transaction PERFORCE attempts to make changelist usage as transparent as possible in the normal case PERFORCE commands such as p4 edit add the affected files to a default changelist called appropriately enough the default changelist and p4 submit sends the default changelist to the server for processing However there are two sets of circumstances that would require the user to understand and manipulate non default changelists e Sometimes a user wants to split files into separate groups for submission For example suppose a user is fixing two bugs each of which spans a separate set of files Rather than submit the fixes to both bugs in a single changelist the user might elect to create one changelist for the files that fix the first bug and another changelist for the files that fix the second bug Each changelist would be submitted to the depot via separate p4 submit s e Under certain cir
143. nds e On the left hand side of any client view For example if the P4 client form is filled in as follows on client spice any files from the local depot depot will be mapped to usr jake src local and any files from the remote depot foo will be mapped to usr jake src remote Client spice Description Created by Jake Root usr jake sre View depot spice local foo spice remote e On the left hand side of any branch or label view in the same way the mapping has been provided in the above client view There is one rather large exception to these rules although files from other local depots can be used in any operation files from remote depots can be used only in read only oper ations Thus no files can ever be used ina p4 submit to a remote depot Additionally files from remote depots can t be used in p4 filelog or p4 describe even though these operations are read only Integrating Files From Other Depots A branch view may contain remote files in its mappings so that files can be branched and later integrated from a remote depot into the local one This works much as local branch ing and integration do with two exceptions 1 When remote files are integrated for the first time i e they don t exist locally they are opened for import rather than branch The difference between import and branch is only that upon submission the remote files are copied locally Normally bran
144. nection with p4 info as described above Once this has been done PERFORCE is ready to use Perforce 97 3 User s Manual 17 PERFORCE Basics CHAPTER 3 The use of the Elm source code set is described in the About This Manual chapter page 3 Quick Start This chapter teaches basic PERFORCE usage You ll learn how to move files to and from the common file repository how to back out of these operations and the basic PERFORCE reporting commands These concepts and commands are painted with very broad strokes in this chapter the details are provided in the next Underlying Concepts The basic ideas behind PERFORCE are quite simple files are created edited and deleted in the user s own directories which are called client workspaces PERFORCE commands are used to move files to and from a shared file repository known as the depot PERFORCE users can retrieve files from the depot into their own client workspaces where they can be read edited and resubmitted to the depot for other users to access When a new revision of a file is stored in the depot the old revisions are kept and are still accessible PERFORCE was written to be as unobtrusive as possible very few changes to your normal work habits are required Files are still created in your own directories with a standard text editor PERFORCE commands supplement your normal work actions instead of replacing them PERFORCE commands are always entered
145. ng operation are listed in the default changelist and the files in the depot are affected only when this changelist is submitted to the depot with p4 submit This allows a set of files to be updated in the depot all at once when the changelist is submitted either all of the files in the changelist are affected or none of them are When a file has been opened with p4 add p4 edit orp4 delete but the correspond ing changelist has not yet been submitted in the depot the file is said to be open in the cli ent workspace Adding Files to the Depot To add a file or files to the depot type p4 add filename s Thep4 add commands opens the file s for edit and lists them in the default changelist they won t be added to the depot until the p4 submit command is given Ed is writing a help manual for Elm The files are named elm help 0 through elm help 3 and they re sitting in the doc subdirectory of his client workspace root He wants to add these files to the depot cd elm doc p4 add elm help depot elm_proj doc elm help 0 1 opened for add depot elm_proj doc elm help 1 1 opened for add depot elm_proj doc elm help 2 1 opened for add depot elm_proj doc elm help 3 1 opened for add Perforce 97 3 User s Manual 21 Chapter 3 Perforce Basics Quick Start Ga Example Submitting a changelist to the depot Ga Example Using multiple file arguments on a single command line H
146. ng to determine which file is actually used Any filenames provided to PERFORCE commands can be specified in any valid local syn tax or in PERFORCE syntax by depot or client If a client filename is provided PERFORCE uses the client view to locate the corresponding file in the depot If a depot filename is given the client view is used to locate the corresponding file in the client workspace Ed wants to delete the src lock c file He can give the p4 delete command in a num ber of ways e While in his client root directory he could type p4 delete src lock c e While in the src subdirectory he could type p4 delete lock c e While in any directory on the client host he can type p4 delete eds_elm src lock c or p4 delete depot elm_proj src lock c or p4 delete usr edk elm src lock c Client names and depot names in a single PERFORCE server share the same namespace so PERFORCE will never confuse a client name with a depot name Client workspace names and depot names can never be the same Perforce 97 3 User s Manual 33 Chapter 4 Perforce Basics The Details Wildcards and PERFORCE Syntax PERFORCE wildcards may be mixed with both local or PERFORCE syntax For example J Files in the current directory starting with J help All files called help in current subdirectories All files under the current directory and its subdirectories He All such files ending in c usr edk All files und
147. ng versions and this file can be edited and then submitted to the depot Labeling Groups of Files It is often useful to mark a particular set of file revisions for later access For examples the release engineers might want to keep a list of all the file revisions that comprise a particu lar release of their program This list of files can be assigned a single mnemonic name like release2 0 1 this name is a label for the user determined list of files At any sub sequent time the label can be used to copy the old file revisions into a client workspace Branching Files Thus far it has been assumed that all changes of files happen linearly But this is not always the case suppose that one source file needs to evolve in two separate directions perhaps one set of upcoming changes will allow the program to run under VMS and another set will make it a Mac program Clearly two separately evolving copies of the same files are necessary PERFORCE s Inter File Branching mechanism allows any set of files to be copied within the depot By default the new file set or codeline evolves separately from the original files but changes in either codeline can be propagated to the other We re particularly proud of PERFORCE s branching mechanism Most SCM systems allow some form of branching but PERFORCE s is particularly flexible and elegant Job Tracking Job is a generic term for a plain text description of some change that n
148. o be integrated It discards any donor target pairs for which the donor file revisions have been inte grated in previous changes Each revision of each file that has been integrated is remembered individually in order to avoid making the user merge changes more than once It discards any donor target pairs whose donor file revisions have integrations pending in files that are already opened in the client All remaining donor target pairs will be integrated The target file is opened on the cli ent for the appropriate action see below and merging is scheduled Integrate s Actions The integrate command will take one of three actions depending on particular characteris tics of the donor and target files Action Meaning branch If the target file does not exist it is opened for branch The branch action is a variant of add but PERFORCE keeps a record of which do nor file the target file was branched from This allows three way merges to be performed between subsequent donor and target revi sions with the original donor file revision as base Perforce 97 3 User s Manual 72 Chapter 9 Branching integrate delete If both the donor and target files exist the target is opened for inte gration which is a variant of edit Before a user can submit a file that has been opened for integration the donor and target must be merged with p4 resolve When the target file exists but no corresponding donor f
149. o be writ ten to the depot open access is usually granted only in unusual circumstances Choose open access over write access when users will be testing their changes locally but when these changes should not be seen by other users For example bug testers may want to change code in order to test theories as to why particular bugs occur but these changes would be for their own use and would not be written to the depot Or a codeline might be frozen with local changes submitted to the depot only after careful review by the develop ment team In this case open access would be granted until the code changes have been approved at that time the protection level would be upgraded to write Default Protections When p4 protect is first run two permissions are set by default The default protec tions form looks like this Protections write 7 ee super edk X ERA This indicates that write access is granted to all users on all hosts to all files Addition ally the user who first invokes p4 protect in this case edk is granted superuser privileges Perforce 97 3 User s Manual 103 Chapter 14 System Administration Protections Interpreting Multiple Permission Lines The access rights granted to any user are defined by the union of mappings in the pro tection lines that match her user name and client IP address This behavior is slightly different when exclusionary protections are provided this is descr
150. ob Tracking Ga Example Using p4 fix to attach a job to a changelist Controlling Which Jobs Appear in Changelists The types of jobs that appear in new changelists created by a particular user can be con trolled through the p4 user form This form s JobView field allows one of three values Value of JobView field Description Mine When a new changelist is created automatically in clude all open jobs owned by the invoking user in the changelist form This setting of JobView is the de fault None Don t include any jobs on new changelist forms All Include all open jobs owned by all users in all new changelists forms In all three cases any unwanted job may be deleted from the form before leaving the edi tor and additional jobs can be added Manually Associating Jobs with Changelists p4 fix c changenum jobname can be used to link any job whether open closed or suspended to any PERFORCE changelist whether pending or submitted If the job is open but the changelist has already been submitted the job is closed If the job has been closed but the changelist is pending the job is reopened Otherwise the job keeps its cur rent status Sarah has submitted a job called options bug to Ed Unbeknownst to Sarah the bug reported by the job was fixed in Ed s previously submitted changelist 18 Ed links the job to the previously submitted changelist with p4 fix c 18 options bug Since the changelist has alre
151. oblems later on Suppose your server currently stores files for only one project but another project is added later every one who has a client workspace mapped as above will wind up receiving all the files from both projects into their workspaces Additionally the default view does not facilitate branch creation The safest way to organize the depot even from the start is to create one subdirectory per project within the depot For example if your company is working on three projects code named foo bar and zeus three subtrees might be created within the depot depot foo depot bar and depot zeus If Joe is working on the foo project his map ping might look like this depot foo jo0e And Sarah who s working on the bar and zeus projects might set up her client work space as depot bar sarah bar depot zeus sarah zeus This sort of organization can be extended on the fly to as many projects and branches as are needed Another way of solving the same problem would be to have the PERFORCE system admin istrator create one depot for each project or branch Please see Chapter 15 page 109 for details Perforce 97 3 User s Manual 52 Chapter 6 Perforce Basics Miscellaneous Topics PERFORCE access levels are explained in chapter 14 Renaming Files Although PERFORCE doesn t have a rename command a file can be renamed by using p4 integrate to copy the fil
152. of commands The only com mand that reports only on labels p4 labels prints its output in the following format Perforce 97 3 User s Manual 89 Chapter 12 Reporting and Data Mining Label releasel 3 1997 5 18 Created by edk Label lisas_temp 1997 10 03 Created by lisag re SECTORS The other label reporting commands are variations of commands we ve seen earlier To See Use This Command a list of all labels the dates they were created p4 labels and the name of the user who created them a list of files that have been included in a partic p4 files labelname ular label with p4 labelsync what p4 sync would do when retrieving files p4 sync n labelname from a particular label into your client workspace Branch and Integration Reporting The plural form command of branch p4 branches lists the different branches in the system along with their owners dates created and descriptions Separate commands are used to list files within a branched codeline to describe which files have been integrated and to perform other branch related reporting The table below describes the most com monly used commands for branch and integration related reporting To See Use This Command a list of all branches known to the p4 branches system a list of all files in a particular p4 files filespec branched codeline what a particular p4 integrate p4 integrate args n filespec va
153. ommand Only one additional step needs to be performed before resolving the integrate command is used to schedule the merge between the original files and the branched files In its normal use with branched files p4 integrate takes the form p4 integrate b branchname files where the specified files are the branched files rather than the original files A bug has been fixed in the original codeline s src elm c file Kurt wants to propagate the same bug fix to the branched codeline he s been working on He types p4 integrate b elm_rl kurtv elm rl src elm c and sees depot elm_releasel src elm c 1 integrate from depot elm_proj src elm c 9 Perforce 97 3 User s Manual 68 Chapter 9 Branching Protections are discussed in Chapter 9 Ga Example Propagating branched codeline changes to the original codeline The file has been scheduled for resolve He types p4 resolve and the standard merge dialog appears on his screen usr kurtv elm rl src elm c merging depot elm_proj src elm c 2 Diff chunks 0 yours 1 theirs 0 both 0 conflicting Accept a Edit e Diff d Merge m Skip s Help at He resolves the conflict with the standard use of p4 resolve When he s done the result file overwrites the file in his branched client and it still must be submitted to the depot In PERFORCE terminology changes are always propagated from donor files to target files In the
154. onflicting file revisions were commonly based on 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 Creating a copy of a file or files in the depot so that the new file set can evolve sep arately from the original files See Inter File Branching The form displayed when the p4 branch command is given The view that specifies how files are mapped from the original codeline to the branched codeline The mappings within a branch map files within the depot to the copied files within the depot Branch views are edited in the branch form A tool 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 at lt www perforce com gt 1 Anedit of a file 2 In previous versions of PERFORCE this term was used as a synonym for changelist A list of files revision numbers of those files and operations to be performed on these files The commands p4 add p4 edit p4 delete andp4 inte grate all include files in a particular changelist which is sent to the depot atom ically when p4 submit is typed with no parameters The form brought up by p4 change and by p4 submit when submitting the default change Perforce 97 3 User s Manual 117 Chapter APPENDIX B Glossary changelist number change review
155. ontents of PERFORCE files stored in the depot Read access includes list access To copy the contents of an unopened file from the depot into the client workspace A depot located on a server other than the current PERFORCE server defined under P4PORT PERFORCE supetusers can make these depots accessible to the current server s clients for read only access 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 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 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 One fork of a Macintosh file The PERFORCE file type is resource 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 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 cli ent workspace they are simply removed from
156. ontrol multiple revisions of the same file are stored and older revisions are always accessible e PERFORCE provides facilities for concurrent development multiple users can edit their own copies of the same file e Some release management facilities are offered PERFORCE will track which revisions of which files are part of a particular release e Bugs and system improvement requests can be tracked from entry to fix this is known as defect tracking e PERFORCE supplies some lifecycle management functionality files can be kept in release branches development branches or in any sort of needed file set e Change review functionality is provided by PERFORCE this allows users to be notified by email when particular files are changed e Although a build management tool is not built into PERFORCE we do offer a companion freeware product called JAM Make 1 Redux JAM and PERFORCE meet at the file system source files managed by PERFORCE are easily built by JAM PERFORCE excels at all file management functions Although PERFORCE was built to man age source files it can manage any sort of on line documents It can be used to store revi sions of a manual to manage Web pages or to store old versions of operating system administration files Its branching functionality which allows copies of files to evolve separately from the files they were copied from is unparalleled in the industry And PER FORCE is extremely fast PER
157. or aliased perforce listening on port 1666 Starting P4p The Basics After P4D s P4PORT and P4ROOT environment variables have been set P4D can be run in the background with the command p4d amp P4PORT can be overridden by starting P4D with the p flag and P4ROOT will be ignored if the r flag is provided The startup command would then have this form p4d r usr local p4files p 1818 amp Although this command is sufficient to run P4D other flags which control such things as error logging checkpointing and journaling can and should be provided These flags are discussed in the next two sections Perforce 97 3 User s Manual 97 Chapter 13 System Administration Installation and Maintenance A Checkpointing and journaling archive only the database files not the files in the depot directories Back up the depot files with the standard OS backup commands after checkpointing this is because the static checkpoint can be dumped and restored consistently while the dynamic database files may change during the course of backing up and may be inconsistent Logging Errors The P4D program tries to ensure that all error messages reach the user but if an error occurs and the client program disconnects before the error is sent P4D logs the error to its error output The error output file can be specified with the L flag to P4D or can be defined in the environment variable P4LOG If no error out
158. ould map to j0e elm doc help but the same file in the client workspace would map back to the depot via the higher pre cedence second line to depot nowhere help Because the file would be written back to a different location in the depot than where it was read from PERFORCE doesn t map this name at all In older versions of PERFORCE this was often used as a trick to exclude particular files from the client workspace Because PERFORCE now has exclusionary mappings this type of mapping is no longer useful and should be avoided Referring to Files on Command Lines File names provided as arguments to PERFORCE commands can be referred in one of two ways by using the names of the files in the client workspace or by providing the names of the files in the depot When providing client workspace file names the user may give the name in either local or PERFORCE syntax Local Syntax Local syntax is simply a file s name as specified by the local shell or OS This name may be an absolute path or may be specified relative to the current directory although it can only contain relative components at the beginning of the file name i e it doesn t allow sub dir here foo c For example on UNIX Ed could refer to the README file at Elm s top level as usr edk elm README or in a number of other ways PERFORCE Syntax PERFORCE provides its own filename syntax which remains the same across operating sys tems
159. ound is an exclusionary mapping or if the top of the protections table is reached without a matching protection being found then the user has no permission to even list the file and will receive a message like File not on client e As an example suppose that our protections table is set as follows write x x ID tes read edk at a are read edk depot elm_proj IfEdruns p4 print depot foo PERFORCE examines the protections table bottom to top and first encounters the last line The files specified there don t match the file that Ed wants to print so this line is irrelevant The second to last line is examined next this line matches Ed s user name his IP address and the file he wants to print since this line is an exclusionary mapping Ed isn t allowed to even list the file Perforce 97 3 User s Manual 106 Chapter 14 System Administration Protections e If the first pass is successful a second pass is made at the protections table again read ing bottom to top this pass is the same as the first except that access level is now taken into account If an inclusionary protection line is the first line encountered that matches the user name IP address file argument and has an access level greater than or equal to the access level required by the given command then the user is given permission to run the command If an exclusionary mapping is the first line encountered that matches according to th
160. p4 sync n describes which files would be read into your client workspace the next time you perform a p4 sync All these commands can be used with or without filespec arguments p4 sync n is the only command in this set that allows revision specifications on the filespec arguments The output of p4 where looks like this depot elm_proj doc Ref guide edk doc Ref guide p4 have s output has this form depot doc Ref guide 3 ul rlo edk elm doc Ref guide and p4 sync n provides output like depot doc Ref guide 3 updating usr edk elm doc Ref guide To See Use This Command which revisions of which files you have in p4 have the client workspace which revision of a particular file isin your p4 have filespec client workspace where a particular file in the client work p4 where filespec space maps to in the depot Perforce 97 3 User s Manual 85 Chapter 12 Reporting and Data Mining To See Use This Command where a particular file in the depot maps to p4 where depot filespec in the workspace which files would be synced into your client p4 sync n workspace from the depot when you do the next sync File Contents Contents of a Single Revision The contents of any file revision within the depot can be viewed with p4 print This command simply prints the contents of the file to standard output or to the specified out put file along with a one line banner
161. pleText UNIX If EDITOR environment If MERGE environment vari If DIFF is set then value of DIFF otherwise P4 s in ternal diff NT If DIFF is set then value of DIFF else if SHELL set diff otherwise p4diff exe variable is set its value otherwise UNIX vi NT if SHELL is set vi otherwise notepad VMS if POSITXSSHELLis set vi otherwise edit Mac if EDITOR_SIGNATURE is set the program with that four character creator oth erwise SimpleText able is set its value other wise nothing This EV can contain flags to diff such as diff u p4 describe p4 diff2 and p4 submit use the diff built into P4D this cannot be changed This program is used only by p4 resolve s merge command It takes four ar guments representing base theirs yours and the resulting merge file Please see page 43 for more de tails Perforce 97 3 User s Manual 115 Chapter APPENDIX A Environment Variables TABLE 4 Esoteric PERFORCE Environment Variables page 2 of 2 Environment Variable Description Command Line Alternative Used by P4 Used by P4D Examples Value if not Explicitly Set P4PAGER Program used to page out put from p4 resolve s AIET PWD The working directory when P4 commands are run TMP TEMP Directory in which tempo rary files are written q Yes Yes Yes No No No more ul doug
162. prog tmp If PAGER environment UNIX UNIX variable is set then the val Value of PWD as set by tmp ue of PAGER otherwise none shell if not set by shell getwd is used VMS NT Mac MPW Actual current working di rectory VMS Mac MPW NT on client current directory on server PAROOT Used only by p4 resolve If this variable is not set the output of p4 re solve s diff will not be paged If the TEMP environment variable is set this is used otherwise if TMP is set this is used otherwise defaults to the values above Perforce 97 3 User s Manual 116 APPENDIX B access level add atomic atomic change transaction base binary file branch branch form branch view build management change changelist changelist form Glossary 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 An operation that takes a file in the client workspace and adds it as a new file to the depot Grouping a number of operations together such that either all of them occur or none of them do See 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 The file revision that two newer c
163. pted or lost either because of disk errors errors in the PAD program itself or a disk crash the files can be recreated with your stored checkpoint and journal To do this kill P4D remove the database db files and then invoke the P4D program with the jr flag rm root db p4d jr checkpoint_file journal_file After recovering the database you will need to restore the depot files with the UNIX restore command to ensure that they are as new as the database Perforce 97 3 User s Manual 99 Chapter 13 System Administration Installation and Maintenance Managing Disk Space All of P4D s stored source files reside in subdirectories of the P4D root as do its database files and by default the checkpoints and journals The stored source file depots are grow only and this can clearly present disk space problems on high use systems The following approaches may be used to remedy this Store the journal file on a separate disk using the P 4 JOURNAL environment variable or the J flag to p4d Checkpoint on a daily basis to keep the journal file short Compress checkpoints after they are made Use the jc checkpointfile option with the P4D command to write the checkpoint to a different disk Or use the default checkpoint files but backup your checkpoints and then delete them from the root directory They aren t needed unless you are recovering UNIX only If necessary all or part of the depot subdirector
164. put file is defined errors are dumped to the P4D program s standard error Protections By default every PERFORCE user is a PERFORCE superuser and can run any PERFORCE command on any file These default access levels are changed easily with the p4 pro tect command the administrator who installs PERFORCE should run p4 protect soon after installing P4 and P4D Access levels are described in detail in the next chapter Checkpointing Journaling and Recovery Two sets of files in the P4D root directory are sufficient to recover the complete P4D server data e P4D stores its metadata in the top level of its root directory all of these files are binary and begin with db e Files submitted by P4 clients are stored in P4D subdirectories that have the same names as the depots By default there is only one of these subdirectories its name is depot P4D provides checkpointing and journaling facilities for recovery of the metadata database files A checkpoint is just a snapshot or copy of the database files at a particular moment in time and a journal is a log that records updates since that snapshot If the database files become corrupted or if there s a disk crash you can recover the files by reloading the checkpoint and applying the changes stored in the journal Both the checkpoint and jour nal are text files and have the same format Because the data stored in the PERFORCE database is irreplaceable journaling and ch
165. r The tracking of each revision and variant of every file managed by an SCM system 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 A special character that is not interpreted literally but is used to match other char acters 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 See client workspace 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 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 Perforce 97 3 User s Manual 125 Index Symbols have 34 head 34 label 34 none 34 Id RCS keyword 36 d 27 27 N gt gt gt gt 42 client 34 label 34 A access levels 101 adding files 20 algorithm of integration 71 architecture of PERFORCE 12 atomic 12 53 atomic change transaction 22 53 automatic changelist renumbering 56 B base 41 71 binary files 35 36
166. reated Kurt one of the release engineers is assigned to create the branch for the release engineers The original code is stored in the depot under its elm_proj subtree Kurt decides to call the branch elm_r1 and will store the branched codeline in the depot under an elm_releasel subdirectory He types p4 branch elm_r1 and sees the following Branch elm r1 Date 05 25 1997 17 43 28 Owner kurtv Description Created by kurtv View depot depot The default view above would map the entire depot to itself in a branch which is useless The View needs to map the original codeline s files on the left to branch files on the right Kurt changes the view field as follows Branch elm_rl Date 05 25 1997 17 43 28 Owner kurtv Description Created by kurtv View depot elm_proj depot elm_releasel This maps all the files in the depot s elm_proj_ file tree to a new depot file tree called elm_releasel All files from the source subtree will eventually be copied to the branch subtree these files will be the contents of the branch Kurt quits the editor the branch is created The p4 branch command does not copy files into the branch it simply specifies which original file will correspond to which branched file Exclusionary mappings may be used within a branch view Step 2 Include the Branched Files in the Client View In order to work with branched files t
167. 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 A networking protocol the protocol of the Internet The basic PERFORCE file type Text files can be stored using reverse delta encoding saving space on the server When resolving a file conflict the theirs file is the revision in the depot that the cli ent file conflicts with This is usually the head revision When working with branched files theirs is the donor file 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 A term sometimes used by other SCM systems in place of head revision 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 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 othe
168. riation would do without actually doing the integrate what a particular p4 resolve p4 resolve args n filespec variation would do without actually doing the resolve a list of files that have been re p4 resolved filespec solved but have not yet been submit ted Perforce 97 3 User s Manual 90 Chapter 12 Reporting and Data Mining To See Use This Command a list of integrated submitted files p4 integrated filespec that match the filespec arguments a description of the revision histo p4 filelog filespec ry of the named files including the following for each file revision e change number e operation add edit delete branch or integrate e client name e user name and e description a In this case the filespec should be presented in depot syntax and should represent the branched codeline For example if a codeline had been branched to depot r22 then a list of all files in the branched codeline would be obtained with p4 files depot r22 Job Reporting Job reporting is accomplished with two commands The first p4 jobs reports on all jobs known to the system the second command p4 fixes reports only on those jobs that have been attached to changelists Both these commands have numerous options Basic Job Information To see a list of all jobs known to the system use p4 jobs Options to this command can be used to specify criteria for de
169. rticular Revisions Five optional p4 resolve flags tell the command to work non interactively when these flags are used particular revisions of the conflicting files will be automatically accepted ay Automatically accept yours at Automatically accept theirs Use this option with caution the file re vision in the client workspace will be overwritten with no chance of re covery am Automatically accept the PERFORCE recommended file revision yours theirs or merge if there are no conflicting line sets If there are conflicts skip the resolve for this file af Accept the PERFORCE recommended file revision no matter what If this option is used the resulting file in the client should be edited to re move any difference markers as if theirs is identical to base accept yours if yours is identical to base accept theirs otherwise skip this file Ed has been editing the doc guide files and knows that some of them will require resolving He types p4 sync doc guide all of these files that conflict with files in the depot are scheduled for resolve He then types p4 resolve am the merge files for all scheduled resolves are generated and those merge files that contain no line set con flicts are written to his client workspace He ll still need to manually resolve all the other conflicting files but the amount of work he needs to do is substantially reduced Binary Files and p4 resolve If any of the three fil
170. s canons or decrees of your country state territory kingdom province county city or other municipality PERFORCE Software will assume no liability responsibility debt risk or other obligation for any defamatory libelous pejorative unlawful slanderous or otherwise illegal material appearing below this paragraph in this column on this page PREFACE 95 NT Gd About This Manual This is the PERFORCE 97 3 User s Guide It teaches the use of PERFORCE s command line interface the PERFORCE Windows GUI is not discussed For documentation on the Win dows GUI interface P4WIN please see our P4 to P4WIN Translation Guide for experi enced PERFORCE users or the P4WIN User s Guide for the PERFORCE novice Although this guide can be used as a reference manual it is primarily intended as guide tutorial on using PERFORCE The full syntax of most of the PERFORCE commands is not provided here we suggest that you supplement use of this guide with the upcoming PER FORCE Command Reference or with the on line help system Use of this manual for oper ating systems other than UNIX and NT should be supplemented with the release notes for that OS New 97 3 Features The features new to PERFORCE 97 3 have been marked with changebars in the left margin The release notes provide more detailed information and are available from our web site Please consult the release notes before upgrading from earlier versions of PERFORC
171. s or those affecting a particular file or the last n changelists Currently the output can t be restricted to changelists sub mitted by particular users although simple shell or Perl scripts can be written to imple ment this To See a List of Changelists Use This Command with the first 31 characters of the changelist p4 changes descriptions with the complete description of each p4 changes 1 changelist including only the last n changelists p4 changes m n with a particular status pending or sub p4 changes s status mitted limited to those that affect particular files p4 changes filespec limited to those that affect particular files p4 changes i filespec but including changelists that affect files which were later integrated with the named files limited to changelists that affect particular p4 changes filespec m n files including only those changelists be tween revisions m and n of these files limited to those that affect particular files at p4 changes filespec labl lab2 each files revisions between labels lab and lab2 Perforce 97 3 User s Manual 88 Chapter 12 Reporting and Data Mining Additional commands that report on jobs and changelists are described in the job reporting section of this chapter page 91 Files and Jobs Affected by Changelists To view a list of files and jobs affected by a particular changelist along with the dif
172. s while denying access to the same files to only a few users To use exclusionary mappings properly it is necessary to understand some peculiarities associated with them e When an exclusionary protection is included in the protections table the order of the protections is relevant the exclusionary protection is used to remove any matching pro tections above it in the table e No matter what access level is provided in an exclusionary protection all access levels for the matching files and IP addresses are denied The access levels provided in exclu sionary protections are irrelevant The reasons for this seemingly strange behavior are described in the section How Protec tions are Implemented on page 106 Perforce 97 3 User s Manual 104 Chapter 14 System Administration Protections Ed has used p4 protect to set up protections as follows im Protections Example read emily depot elm_proj Exclusionary write 7 EESE protections super joe ee list lisag OEE write lisag depot elm_proj doc The second permission seemingly grants write access to all users to all files in all depots but this is overruled by later exclusionary protections for certain users e The third permission denies Joe permission to access any file from any host No subse quent lines grant Joe any further permissions thus Joe has been effectively locked out of PERFORCE e The fourth permission denies Lisa all ac
173. s 77 Job Reporting 77 Change Review amp Other Daemons 78 Providing Change Review Parameters 78 Running the Daemon 79 How the Review Daemon Works 79 Tracking Reviewed Changelists with Review Counters 80 A Protections Warning 81 Creating Other Daemons 81 Change Review Reporting 81 Reporting and Data Mining 82 Files 82 File Metadata 82 Relationships Between Client and Depot Files 84 File Contents 85 Changelists 87 Changelists that Meet Particular Criteria 87 Files and Jobs Affected by Changelists 88 Labels 88 Branch and Integration Reporting 89 Job Reporting 90 Jobs Fixes and Changelists 91 Reporting for Daemons 91 System Configuration 92 Special Reporting Flags 92 CHAPTER 13 CHAPTER 14 CHAPTER 15 Reporting with Scripting 93 Comparing the Change Content of Two File Sets 93 Changelists Submitted by Particular Users 93 Listing Subdirectories of the Depot 94 System Administration Installation and Maintainance 95 Installation of p4d and p4 95 Creating a p4d Root Directory 95 Setting p4d s Port 95 Telling p4 Where The p4d Server Is 96 Starting p4d The Basics 96 Logging Errors 97 Protections 97 Checkpointing Journaling and Recovery 97 Making a Checkpoint 97 Turning Journaling On and Off 98 Recovering 98 Managing Disk Space 99 License File 99 Release and License Information 99 System Administration Protections 100 When Should Protections Be Set 100 Setting Protections with p4
174. s currently p4 counters used by your PERFORCE system the numbers of all changelists that have not p4 review t countername yet been reported by a particular counter vari able Perforce 97 3 User s Manual 92 Chapter 12 Reporting and Data Mining To list Use This Command all users who have subscribed to review particular files all users who have subscribed to read any files in a particular changelist a particular user s email address p4 reviews filespec p4 reviews c changenum p4 users username System Configuration Three commands report on the PERFORCE system configuration One command reports on all PERFORCE users another prints data describing all PERFORCE client workspaces and a third reports on PERFORCE depots p4 users generates its data as follows accessed 1997 07 13 accessed 1997 07 14 edk lt edk eds_ws gt Ed Kuepper lisag lt lisa lisas_ws gt Lisa Germano Each line includes a username an email address the user s real name and the date that PERFORCE was last accessed by that user To report on client workspaces use p4 clients Client eds_elm 1997 09 12 root usr edk Ed s Elm workspace Client lisa_doc 1997 09 13 root usr lisag Created by lisag Each line includes the client name the date the client was last updated the client root and the description of the client Depots can be reported with p4 depots
175. s which files are available to the corresponding client workspace 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 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 com mands PERFORCE is unable to open files for you 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 A depot within another P4D server accessed by the local P4D server acting as a proxy client The file from which changes are taken when propagating changes from one code line to another A donor file can come either from the branched codeline or the orig inal codeline this is determined by the use of the r flag to p4 integrate 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 A variable set in the operating system s command shell PERFORCE utilizes envi ronment variables that are passed to the p4 client or P4D server A view mapping that excludes depot files from a client workspace Exclusionary mappings begin with a min
176. scribing only particular types of jobs for example the s flag will limit the report to jobs of a particular status p4 jobs produces output similar to the following job000302 on 1997 08 13 by saram open FROM headers no filter_bug on 1997 08 23 by edk Can t read filters w Its output includes the jobs name date entered job owner and the first 32 characters of the job description The job status is included if the job is open or suspended closed jobs are indicated by the absence of job status from the report All jobs known to the system are displayed unless command line options are supplied These options are described in the table below To See a List of Jobs Use This Command including all jobs known to the server p4 jobs including the full texts of the job descriptions p4 jobs 1 Of a particular status open closed or suspended p4 jobs s status Perforce 97 3 User s Manual 91 Chapter 12 Reporting and Data Mining To See a List of Jobs Use This Command that have been fixed by changelists that contain spe p4 jobs filespec cific files that have been fixed by changelists that contain spe p4 jobs i filespec cific files including changelists that contain files that were later integrated into the specified files Jobs Fixes and Changelists Any jobs that have been linked to a changelist with p4 change p4 submit orp4 fix is said to be fixed and can be reported with p4
177. sion two might be stored as a symbolic version of the following foo 2 line 3 was urgent And revision would be a representation of this foo 1 line 4 was system From these partial file descriptions any file revision can be reconstructed The recon structed foo 1 would read This is a test of the urgent system The RCS Revision Control System algorithm developed by Walter Tichy uses a notation for implementing this system that requires very little storage space and is quite fast In RCS terminology it is said that the full text of the head revisions are stored along with the reverse deltas of each previous revision It is interesting to note that the full text of the first revision could be stored with the deltas leading forward through the revision history of the file but RCS has chosen the other path the full text of the head revision of each file is stored with the deltas leading backwards to the first revision This is because the head revision is accessed much more frequently than previous file revisions if the head revision of a file had to be calculated from the deltas each time it was accessed any SCM utilizing RCS format would run much more slowly Perforce 97 3 User s Manual 40 Chapter 5 Perforce Basics Resolving File Conflicts Use of diff to Determine File Revision Differences RCS utilizes the GNU diff program to determine the differences between two versions of th
178. st Perforce 97 3 User s Manual 75 Chapter 10 Job Tracking Example Including and excluding jobs from changelists Ed is unaware of the job that Sarah has assigned to him He is currently working on an unrelated problem he types p4 submit and sees the following Change new Client edk User edk Status new Description Updating File files Jobs job000125 Filters on the Reply To field d Files depot src file c edit depot src file_util c edit depot src fileio c edit Since this job is unrelated to the work he s been doing and since it hasn t been fixed he deletes it from the form and then quits from the editor The changelist is submitted the job is not associated with it Ed uses the reporting commands to read the details about the job He fixes this problem and a number of other filtering bugs when he next types p4 submit he sees Change new Client edk User rlo Status new Description Fixes a number of filter problems Jobs j30b000125 Filters on the Reply To fieldd Files depot filter actions c edit depot filter audit c edit depot filter filter c edit Since the job is fixed in this changelist Ed leaves the job on the form When he quits from the editor the job is marked as closed and will not appear in any subsequent changelists unless it is reopened Perforce 97 3 User s Manual 76 Chapter 10 J
179. sted in the label it is possible to accidently lose the information that a label is meant to contain To prevent this call p4 label labelname and set the value of the Options field to locked It will be impossible to call p4 Labelsync on that label until the label is subse quently unlocked Retrieving a Label s Contents into a Client Workspace To retrieve all the files listed in a label into a client workspace use p4 sync files labelname This command will match the state of the client work space to the state of the label rather than simply adding the files to the client workspace Thus files in the client workspace that aren t in the label may be deleted from the client workspace Lisa wants to retrieve all the files listed in Ed s ilters 1 label into her client work space She can type p4 sync depot labelname or even p4 sync labelname But she s interested in seeing only the header files from that label she types p4 sync depot elm_proj hdrs filters 1 and sees depot elm_proj hdrs curses h 1 added as usr lisag elm hdrs curses h depot elm_proj hdrs defs h 1 added as usr lisag elm hdrs defs h depot elm_proj hdrs test h 3 deleted as usr lisag elm hdrs test h lt etc gt All the files in the subdirectory hdrs that are within the intersection of Ed s filters 1 label and Lisa s client view are retrieved into her workspace But there is another effect as well files t
180. t elm_proj doc elm help 2 edit depot elm_proj hdrs s_elm h edit depot elm_proj src newmbox c add All of his changes supporting multiple mailboxes are grouped together in a single change list when Ed quits from the editor either all of these files are updated in the depot or if the submission fails for any reason none of them are Files can be deleted from the Files field these files are moved into the next default changelist and will appear again the next time p4 submit is performed Retrieving Files from the Depot into a Workspace Files can be retrieved from the depot into a client workspace from the depot with p4 sync Jill has been assigned to fix bugs in Ed s code She creates a directory called e1m_ws within her own directory and sets up a client workspace now she wants to copy all the existing elm files from the depot into her workspace cd elm_ws p4 sync depot elm_proj doc elm help 0 2 added as usr lisag elm_ws doc elm help 0 depot elm_proj doc elm help 1 2 added as usr lisag elm_ws doc elm help 1 lt etc gt Once the command completes the most recent revisions of all the files in the depot that are mapped through her client workspace view will be available in her workspace Perforce 97 3 User s Manual 24 Chapter 3 Perforce Basics Quick Start Ga Example Reverting a file back to the last synced version The p4 sync command maps depot files thro
181. t file and can edit the generated version before accepting it The new revisions must then be submitted with p4 submit p4 resolve is interactive a series of options are displayed for the user to respond to The dialog looks something like this usr edk elm doc answer 1 merging depot elm_proj doc answer 1 5 Diff chunks 4 yours 2 theirs 1 both 1 conflicting Accept a Edit e Diff d Merge m Skip s Help e The remainder of this section explains what this means and how to use this dialog File Revisions Used and Generated by p4 resolve p4 resolve filenames starts with three revisions of the same file generates a new version that merges elements of all three revisions allows the user to edit the new file and writes the new file or any of the original three revisions to the client The file revisions used by p4 resolve are these yours The newly edited revision of the file in the client workspace This file is overwritten by result once the resolve process is complete theirs The revision in the depot that the client revision conflicts with Usu ally this is the head revision but p4 sync can be used to schedule a resolve with any revision between the head revision and base base The file revision in the depot that yours was edited from Note that base and theirs are different revisions if they were the same there would be no reason to perform a resolve Perforce 97 3 User s Manual
182. ted in the depot but not synced to the client workspace he could have used the v flag with the integrate command If he did this the files would later need to be copied to the client workspace with p4 sync Editing Newly Branched Files By default a file that has been newly created in a client workspace by p4 integrate cannot be edited before its first submission To make a newly branched file available for editing before submission simply p4 edit the file Working With Branched Files Once a branch has been created and the files have been copied into the branched codeline with p4 integrate the branched files are treated exactly like non branched files with the normal use of sync edit delete submit etc Evolution of both codelines pro ceeds separately additional PERFORCE commands are used only when changes to one codeline need to be propagated to the other Branching s Second Action Propagating Changes from One Codeline to the Other It is worth repeating that two separate actions comprise branching first one set of files is copied from one location in the depot to another location and second changes made to one codeline can be copied to the branched codeline as needed The steps needed to accomplish the first action have been described above now we ll discuss how to accom plish the second action Edits to a file in either codeline can be propagated to the corresponding file in the other codeline with the resolve c
183. the change p4 sync depot 126 Refers to the state of the entire depot at changelist 126 file label A label name p4 sync lock c beta The revision of lock c in the label called beta file client A client name The re p4 sync lock c lisag_ws ene vison offile lasttaken The revision of 1ock c last taken into cli TO client workspace ent workspace lisag_ws clientname file none The nonexistent revi p4 sync lock c none Sion Says that there should be no version of lock c in the client workspace even if one exists in the depot file head The head revision or p4 sync lock c head latest version of the Except for explicitly noted exceptions this file is identical to referring to the file with no re vision specifier file have The revision on the p4 sync lock c have current client This is synonymous to client where client is the current client name The revision of lock c found in the cur rent client In all cases if a file doesn t exist at the given revision number it will appear as if the file doesn t exist at all Thus using a label to refer to a file that isn t in the label is indistin guishable from referring to a file that doesn t exist at all Perforce 97 3 User s Manual 35 Chapter 4 Perforce Basics The Details Ga Example Retrieving files using revision specifiers H Some OS shells will treat the asa comment character if it starts anew word If your she
184. the original files by supplying the r flag to p4 integrate In this case the names of the original files are provided as arguments to p4 integrate r Ed wants to integrate a change in Kurt s branched src screen c file to Ed s original version of the same file He types p4 integrat r b elm_r1 depot elm_proj src screen c and then p4 resolve The change in the branched file is propagated to his source file Perforce 97 3 User s Manual 69 Chapter 9 Branching When the r flag is used to propagate changes from branched donors to original targets the original source files must be visible through the target view Branching and Merging Without a Branch View Thus far we have been describing the two actions that comprise branching copying a set of files from one location in the depot to another and propagating edits of one of the code lines to the other codeline It is possible to use p4 integrate to perform both of these steps without ever having created a branch view This is accomplished by calling p4 integrate with two file arguments and without the b branch flag as in p4 integrate donor_file target_file When p4 integrate is called this way it will perform the integration between the two named files The first file argument provides the donor the second provides the target The donor file must already exist the target file needn t There are three possible combi nations of donor and target e Th
185. the server processes the files contained in the changelist and alters the depot accordingly The commands that add or remove files from changelists are p4 add p4 edit p4 delete p4 integrate p4 reopen p4 revert By default these commands and p4 submit act on the default changelist for example if a user types p4 add filename this file is added to the default changelist When a user types p4 submit the default changelist is submitted When p4 submit is typed a change form is displayed that contains the files in the default changelist Any file can be deleted from this list when a file is deleted it is moved to the next default changelist and will appear again the next time p4 submit is typed A changelist must contain a user entered description which should describe the nature of the changes being made p4 submit can take an optional single file pattern as an argument In this case only those files in the default change that match the file pattern will be included in the submit ted changelist Since the p4d server program must receive this file pattern as a single argu ment make sure to escape the wildcard if it is used When the user quits from the p4 submit editor the changelist is submitted to the server and the server attempts to update the files in the depot If there are no problems the changelist is assigned a sequential number and its status changes from new or pending to submitted Once a changelist has been s
186. theirs and base i The values of yours theirs and base in a three way merge are quite different when yours theirs propagating changes between two codelines and base are first discussed on yours The file that changes are being propagated to also known as the tar page 42 get file This file is in the client workspace and it is overwritten by the result once the resolve process is complete In a forward integrate this is a file in the branched codeline When the r flag has been provided to integrate this is a file in the original codeline theirs The file revision that changes are being read from also known as the donor file This file revision comes from the depot and is un changed by the resolve process In a forward integrate this is a file revision from the original codeline When the r flag has been provided to integrate this is a file in the branched codeline base The last integrated revision of the donor file When a new branch is created and integrate is used to create the branched copy of the file in the depot the newly branched copy is base The Integration Algorithm p4 1 integrate performs the following steps It applies the branch view to any target files provided on the command line to produce a list of donor target file pairs If no files are provided on the command line a list of all donor target file pairs is generated It notes individually each revision of each donor file that is t
187. ticular file e If the file does not exist in the client or it is found in the client but is unopened it is cop ied from the depot to the client e If the file has been deleted from the depot it is deleted from the client e If the file has been opened in the client with p4 edit the PERFORCE server can t sim ply copy the file onto the client any changes that had been made to the current revision of the file in the client would be overwritten Instead a resolve is scheduled between the file revision in the depot the file on the client and the base file revision the revision that was last read into the client Ea Ed is making a series of changes to the guide files in the elm doc subdirectory He has Example retrieved the depot elm proj doc guide files into his client and has opened Scheduling the files with p4 edit He edits the files but before he has a chance to submit them Lisa resolves submits new versions of some of the same files to the depot The versions Ed has been edit with p4 sync ing are no longer the head revisions resolves must be scheduled and performed for each of the conflicting files before Ed s edits can be accepted Ed schedules the resolves with p4 sync edk doc guide Since these files are already open in the client PER FORCE doesn t replace the client files instead PERFORCE schedules resolves between the client files and the head revisions in the depot Alternatively Ed could have submitte
188. tions of the files within the depot the actions add edit delete etc on those files at the specified revisions the changelists the specified file revisions were submitted in and the files types The output has this appearance depot README 5 edit change 6 text Perforce 97 3 User s Manual 83 Chapter 12 Reporting and Data Mining p4 files requires one or more filespec arguments Filespec arguments can as always be provided in PERFORCE or local syntax but the output will always report the corresponding files within the depot If no revision number is provided the head revision will be used Unlike most other commands p4 files will describe deleted revisions instead of sup pressing information about deleted files To View File Metadata for Use This Command all files in the depot whether or not visible p4 files depot through your client view all the files currently in your client workspace p4 files clientnam all the files in the depot that are mapped p4 files clientname through your current client workspace view a particular set of files in the current working p4 files filespec directory a particular file at a particular revision number p4 files filespec revison all files at change n whether or not the file p4 files n was actually included in change n a particular file within a particular label p4 files filespec labelnam File
189. to open the file p4 revert removes it from the changelist but leaves the client workspace file intact If the reverted file was originally opened with p4 edit the last synced version will be written back to the client workspace overwriting the newly edited version of the file In this case you may want to save a copy of the file before running p4 revert Basic Reporting Commands PERFORCE provides some 20 reporting commands Each chapter in this manual ends with a description of the reporting commands relevant to the chapter topic All the reporting commands are discussed in greater detail in the reporting chapter chapter 12 Perforce 97 3 User s Manual 25 Chapter 3 Perforce Basics Quick Start The most basic PERFORCE commands are p4 help and p4 info Command Meaning p4 p4 p4 p4 p4 p4 help commands help command help usage help views help info Lists all PERFORCE commands with a brief description of each For any command provided gives detailed help about that command For example p4 help sync provides detailed in formation about the p4 sync command Describes command line flags common to all PERFORCE commands Gives a discussion of PERFORCE view syntax Describes all the arguments that can be given to p4 help Reports information about the current PERFORCE system the server address client root directory client name user name PERFORCE version and a few other tidbits
190. to the client workspace file eds_elm nls gencat README Types of Mappings By changing the View field it s possible to map only part of a depot to a client workspace It s even possible to map files within the same depot directory to different client work space directories or to have files named differently in the depot and the client workspace This section discusses PERFORCE s mapping methods Direct Client to Depot Views The default view in the form presented by p4 client maps the entire client workspace tree into an identical directory tree in the depot For example the default view depot eds_elm indicates that any file in the directory tree under the client eds_e1m will be stored in the identical subdirectory in the depot This view is usually considered to be overkill most users only need to see a subset of the files in the depot Mapping the Full Client to only Part of the Depot Usually only a portion of the depot is of interest to a particular client The left hand side of the View field can be changed to point to only the portion of the depot that s relevant Bettie is rewriting the documentation for Elm which is found in the depot within its doc subdirectory Her client is named e1m_docs and her client root is usr bes docs she types p4 client and sets the View field as follows depot elm_proj doc elm_docs Mapping Files in the Depot to a Different Part of the
191. ubmitted it becomes a permanent part of the depot s metadata and is unchangeable except by PERFORCE superusers Creating Numbered Changelists Manually A user can create a changelist in advance of submission with p4 change This command brings up the same form seen during p4 submit All files in the default changelist are moved to this new changelist when the user quits from the form the changelist is assigned the next changelist number in sequence and this changelist must be subsequently referred to by this change number Files can be deleted from the changelist by editing the form files deleted from this changelist are moved to the next default changelist The status for a changelist created by this method is pending until the form is submitted Any client file may be included in only one pending changelist Perforce 97 3 User s Manual 55 Chapter 7 Changelists 3 Example Working with multiple changelists Working With Numbered Changelists Commands such as p4 edit filename which by default adds the files to the default changelist can be used to append a file to a pending numbered changelist with the c changenum flag For example to edit a file and submit it in change number 4 use p4 edit c 4 filename Files can be moved from one changelist to another with p4 reopen c changenum filenames where changenum is the number of the moving to changelist If files are being moved to the default changelist use
192. ugh the client view compares the result against the current client contents and then adds updates or deletes files in the client workspace as needed to bring the client contents in sync with the depot p4 sync can take filenames as parameters with or without wildcards to limit the files it retrieves p4 sync s job is to match the state of the client workspace to that of the depot thus if a file has been deleted from the depot p4 sync will delete it from the client workspace Reverting Files to their Unopened States Any file opened for add edit or delete can be removed from its changelist with p4 revert This command will revert the file in the client workspace back to its unopened state Ed wants to edit a set of files in his src directory leavembox c limit c and sig nals c He opens the files for edit cd elm src S p4 edit leavembox c limit c signals c depot elm_proj src leavembox c 2 opened for edit depot elm_proj src limit c 2 opened for edit depot elm_proj src signals c 1 opened for edit and then realizes that signa1s c is not one of the files he will be working on and that he didn t mean to open it He can revert signals c to its unopened state with p4 revert S p4 revert signals c depot elm_proj src signals c l was edit reverted Ifp4 revert is used on a file that had been opened with p4 delete it will appear back in the client workspace immediately If p4 add was used
193. us sign For example to allow a client workspace to ac cess all the files in the depot except for the file called secret the view might look like this depot depot secret a_client a_client secret A permission that denies access on the specified files For example the fol lowing permission denies Ed write permissions on all files in the directory secret write edk E depot secret See PERFORCE Perforce 97 3 User s Manual 119 Chapter APPENDIX B Glossary file file conflict file pattern file reference file repository file revision file tree file type fix form full file storage get GNU have list head revision integrate integration record 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 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 An argument on a P4 command line specifying files using wildcards 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 The master copy of all files shared by all users In PERFORCE this is called the de pot A specific version of a file within the depot Each revision is assigned a number in sequ
194. with the p flag when start ing P4D example p4d p 1818 or the port can be set with the P4PORT environment variable Chances are that your P4D host is not named perforce but you can simplify life somewhat for your P4 users by setting perforce as an alias to the true host name in the host s etc hosts file or by doing so via Sun s NIS or Internet DNS Telling P4 Where The P4D Server Is The P4 client program needs to know on which TCP IP port the P4D server program is lis tening P4 can be told which host and port the P4D server program is listening on by setting each P4 user s P4PORT environment variable to host port where host is the name of the host that P4D is running on and port is the port that P4D is listening on Examples If P4PORT is Then dogs 3435 P4 will communicate with the P4D server on host dogs listening at port 3435 x com 1818 P4 will communicate with the P4D server on host x com listening on port 1818 The definition of P4PORT can be shortened if P4 is running on the same host as P4D In this case only the P4D port number need be provided to P4 If P4D is running on a host named or aliased perforce listening on port 1666 the definition of P4PORT for the P4 client can be dispensed with altogether e Examples If P4PORT is Then 3435 P4 will communicate with the P4D server on its local host listening at port 3435 lt not set gt P4 will communicate with the P4D server on the host named
195. y by the server version that created them a new check point should be taken every time the P4D server is upgraded Regular checkpointing is important if journaling is turned on to keep the journal from get ting too long Making a checkpoint just before dumping the file system is simply good practice Turning Journaling On and Off By default the journal is written to the file journal in the P4D root directory The name and location of this file can be changed by specifying the name of the journal file in the envi ronment variable P 4 JOURNAL or by providing a J filename flag to P4D In either case the journal file name can be provided as an absolute path or as a path relative to the P4D server root To create a journal do one of the following e Create an empty journal file in the server root then start P4D e Set the P4JOURNAL environment variable to point to any file then start P4D or e Start P4D with the J filename flags Be sure to create a new checkpoint with the p4d jc flag immediately after taking a checkpoint since a journal without a checkpoint is useless Since there is no sure protec tion against disk crashes the journal file and the P4D root directory should be located on different disks To disable journaling remove the existing default journal file if it exists unset the envi ronment variable P4 JOURNAL and type the P4D command again without the J flag Recovering If the database files become corru
196. ys contains a single mapping This single mapping for mat changes depending on whether or not the depot being defined is local or remote e If a local depot is being defined the mapping should contain a subdirectory relative to the file space of the P4D server root directory For example graphics gui maps to the graphics gui subdirectory of the P4D server root e If a remote depot is being defined the mapping should contain a subdirectory relative to the remote depot namespace For example depot graphic gui would map to the graphic gui subdirectory of the remote server depot named depot Note that the mapping subdirectory must always contains the wildcard on its right side Naming Depots Depot names share the same namespace as branches clients and labels For example f oo refers unambiguously to either the depot foo the client foo the branch foo or the label foo Accessing Files In Other Depots Files from any remote or local depot known to the default P4D server can be accessed sim ply by using the depot s name wherever the default depot name depot is usually used This means that any defined depot name can be used in the following ways e As part of any P4 command that takes depot syntax For example the following com mand will retrieve all files in the subdirectory foo of depot bar p4 sync bar foo Perforce 97 3 User s Manual 110 Chapter 15 System Administration Superuser Comma

Perforce 97.3 Command Line User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents