Basic Perforce FAQ

Note - the intended audience for this FAQ is a person using Perforce for software development. There's a separate FAQ for system administrators, and eventually we'll have one for advanced Perforce users.

This FAQ assumes that there is a Perforce Administrator who knows some of the more complex parts of Perforce, who can provide help, counseling, and deal with policy-specific issues.  This FAQ is taken from an initial set of questions provided by Richard Geiger and Jeff Bowles.
 

    Initial List

  1. Where do I begin?
  2. What is S.C.M.?
  3. Getting and modifying files

  4. How do I check out a source tree?
  5. How do I make a change to a file and check it in?
  6. What if I have a favorite editor and want to use it when I do a change submission?
  7. How do I add a new directory?
  8. How do I remove a directory?
  9. How do I check out some older version of a file?
  10. How do I check out an entire tree as of some date?
  11. How do I check out an entire tree corresponding to some build or release?
  12. Comparing what you've gotten to the reference copy

  13. How do I compare a working file to the base?
  14. How do I compare a whole tree to the base?
  15. How do I get my favorite diff behaviors with p4 diff?
  16. How do I update a tree from the base?
  17. How do I compare a working file to an older version (other than the base)?
  18. Getting information about a file or workspace

  19. How do I get a list of all files I have open on all my client workspaces?
  20. How do I examine the change log for a file?
  21. Abandoning work and starting over

  22. How do I abandon my changes and pick up a clean copy from the base?
  23. How do I propagate an individual change made in one branch to another?
  24. I created a file that begins with a dash, and want to 'p4 delete' it and cannot. What can I do?
  25. Changing your workspace (moving it, deleting it)

  26. How do I delete a client workspace?
  27. How do I move a client workspace?
  28. Miscellaneous problems

  29. I can't "p4 sync" a particular file. What might be going on?

  1. Where do I begin?

  2. Start with chapters #3-5 of the user's guide - that's referred to as the Quick Start to the product.  All of the documentation is on-line.

    It's probably best to create a small workspace (the term is "client") to play in, so that you can experiment with a few files and not necessarily the 16,000 files that you're planning to manage with source control.
     


  3. What is S.C.M.?

  4. Short answer: it's a way to maintain revisions of files so that you can easily recreate a version of a file from any moment in time.

    The "S.C.M." translates to "Source Code Management" or perhaps "Software Code Management" or "Software Control Management" - the better systems let you manage large sets of files, have multiple people working with the same body of files (a development team of 1 person isn't much fun),  and work on different platforms (such as Windows/NT and Unix) transparently.

    There are a lot of S.C.M. products around - this FAQ won't try to spend a lot of time enumerating them or contrasting them.  


  5. How do I check out a source tree?

  6.  
    Another way to phrase the question is "How do I get files and begin editing them?".  This question will answer the first part of the question - the next FAQ will answer the rest.
     
    To get a set of files...
    Each of the following cases assumes you have a "Perforce client" (a.k.a. 'workspace') already. If not, see the FAQ to create one.
     
    Case #1: you need to get all the files - the most recent revision of each file.
      Case #2: You need to get the files in a specific directory - the most recent revision of each file.
      Case #3: You need to get the files from some `label' someone made for you.
       
     
  7. How do I make a change to a file and check it in?

  8.  
    To edit a set of files...
    Normally, you will edit a file using three steps:  
    Step #1:
    Step #2:
    Step #3:

  9. What if I have a favorite editor and want to use it when I do a change submission?

  10.  
    You can either set the environment variable "P4EDITOR" to be the name of the editor you want to run, or if you're on Windows/NT, use: 


        p4  set  P4EDITOR=commandname
     
  11. How do I add a new directory?

  12.  
    You don't need to add a directory, explicitly.  You simply add files in that directory, using

         cd   directoryname
         p4   add   filename

    or,

         p4   add   directoryname/filename1  directoryname/filename2    (and so on)

    The final step, which is to run   p4 submit , will make these new files available to other Perforce clients.

    Perforce infers the existence of new directories whenever it sees a new directory it hasn't seen before.  


  13. How do I remove a directory?
  14.  
    You don't need to remove a directory, explicitly.  You simply remove files in that directory, using
     
         cd   directoryname
         p4   delete   filename

     
    or,
         p4   delete   directoryname/filename1  directoryname/filename2    (and so on)

    and occasionally,
     
         p4   delete   directoryname/...        (remove all files in `directoryname' and its subdirectories)

    The penultimate step, which is to run   p4 submit , will these deletions to other Perforce clients.

    The final step is to remove the empty directories on your client: "p4 delete / p4 submit" removed the files, but not the directories.  


  15. How do I check out some older version of a file?

  16.  
    You'll need to retrieve that revision first, then  p4 edit the file. That's the easy part. The hard part is deciding how to submit the change. (Let's save that for later in the answer.)

    For example, if you want to edit revision #12 of xyz.java, you'll need to type:
     
         p4   sync  xyz.java#12
         p4   edit  xyz.java

    The first command, of course, isn't needed if you already have revision #12 of xyz.java. (You can tell which revision you have by typing  p4 files  xyz.java .

    You'll be told, when you run p4   edit  xyz.java, that you're not editing the most recent revision and that you'll need to resolve later revisions prior to submitting your changes.  (If you think about it, that makes sense.)
    Now the file's opened for "edit", and you can do whatever you want to the file. Submitting it, however, is going to be a problem: you don't want to inadvertently overwrite the contents of later revisions of the files.

    Case #1: you really do want to overwrite the later revisions for some reason.
     

    Case #2: You don't want to overwrite anything - you were just experimenting with an old version of a file to debug something.
     
  17. How do I check out an entire tree as of some date?

  18.  
    For release 98.2...
     
    For releases prior to 98.2...
     
  19. How do I check out an entire tree corresponding to some build or release?
  20. In general, you'll need to have a piece of data from your build person: the label name used for that build.  (You can always hunt for it, using the command     p4 labels .)

    If the label is  release3.2label, you can update your client area to this by typing:

           p4 sync  @release3.2label

    This will update your client to this label, removing local copies of files that aren't in the label.
     
    If you want subdirectory xyz to be updated, but no other directories on your client, you would type:

           p4 sync  xyz/...@release3.2label
     


  21. How do I compare a working file to the base?

  22.  
    Use  p4 diff filename , which will compare the local copy of a file you've opened for edit or an integrate operation against the revision of the file you were original given.

    For example, say you've opened  xyz.java using the command:
     
         p4   edit   xyz.java
     
    To see your modifications, type:
     
         p4   diff   xyz.java
     
    Note that this is not comparing your local  copy of the file against the most recent changes that other people have checked in - it's comparing against the revision you were working against. (That's  p4 diff filename#head .)


  23. How do I compare a whole tree to the base?

  24.  
    Use  p4 diff directory/... , which will compare the local copy of every file in directory that is opened for edit or an integrate operation against the revision of the file you were original given.

    For example, say you've opened  xyz.java  and z.java in directory dir1 using the command:
     
         p4   edit   dir1/xyz.java  dir1/z.java
     
    To see your modifications, type:
     
         p4   diff   dir1/...
     
    Note that this is not comparing your local  copy of the file against the most recent changes that other people have checked in - it's comparing against the revision you were working against. (That's  p4 diff dir1/...#head .)  


  25. How do I get my favorite diff behaviors with p4 diff?

  26.  
    The environment variable $DIFF is the command line that's run when you run:

           p4 diff  file1  file2

    If, for example, the command "diff -c"  produces "context output format", then the sequence:

           DIFF="diff -c"
           export DIFF
           p4 diff  file1  file2

    will produce that type of output for the differences between the two files.

    Note that  p4 diff2  file1  file2 doesn't honor this variable,  because the "diff" operation is run on the server and only the formatted output is returned to the user.
     


  27. How do I update a tree from the base?

  28.  
    Use  p4 sync directory/... , which will retrieve the most recent revision of every file in directory (and its subdirectories!) that you haven't already got a copy of.
     
    This makes several assumptions:  
  29. How do I compare a working file to an older version (other than the base)?

  30.  
    Use  p4 diff filename#revision , which will compare the working copy of a file you've opened for edit or an integrate operation against the revision of the file you specify using "#revision".

    For example, say you've opened  xyz.java using the command:
     
         p4   edit   xyz.java
     
    Various "diff" commands follow:
     


  31. How do I get a list of all files I have open on all my client workspaces?

  32.  
    If your username is joe, then the following command will show you your opened files for all workspaces:

          p4 opened -a | grep joe

    If you don't have "grep" (i.e. you're on Windows) you'll need to search the output of  p4 opened for this.
     


  33. How do I examine the change log for a file?

  34.  
    Use  p4 filelog filename to get the list of revisions since a file was created in a particular codeline.

    Use  p4 changes -i directory/... to get the list of change numbers since a file stored originally in Perforce.

    You'll recall that the difference between a revision and a change number is that the revision is specific to a file...
        x.c#1            (revision #1 of file x.c)
        x.c#2            (revision #2 of file x.c)
        y.java#1         (revision #1 of file y.java)
        y.java#2         (revision #2 of file y.java)
        y.java#3         (revision #3 of file y.java)
    The change number is a list of revisions that got changed as part of one atomic change to the Perforce depot. For example, change #12345 might be a change to add comments to x.c and y.java, and this change might've created revision #2 of x.c and #3 of y.java.


  35. How do I abandon my changes and pick up a clean copy from the base?

  36.  
    Use  p4 revert filename to discard the modifications you've made to filename and retrieve a fresh copy of the exact same revision you had prior to typing  p4 edit filename .

    Use  p4 revert directory/... to discard all the modifications you've made to any file in directory (or its subdirectories).


  37. How do I propagate an individual change made in one branch to another?
  38. Let's say you have a main codeline, and a child codeline ("branch") called methusalah.

    If you wanted to propogate change #900 from the main codeline to methusalah, you'd type:
     

      p4 integrate -b methusalah  @900,900

    Of course, if you wanted to propogate change #902 from methusalah to the main codeline, you'd type:
     

      p4 integrate -b methusalah  -r @902,902

    The subsequent  resolve/submit combination is left as an exercise.

    It's a good idea to include the original change number in the change description for the integration.
     


  39. I created a file that begins with a dash, and want to 'p4 delete' it and cannot. What can I do?

    Let's say that the name of the file is "-filename".

    Run "p4 delete dummy -filename" to delete the file - ignore the comment about the dummy filename, its purpose is to stop the option/argument processing and let everything else on the command line be interpreted as filenames.

    Or, you could run "p4 delete ./-filename", which uses the Unix directory separator ('/') to construct a filename that refers to the same file, but doesn't begin with a dash. (NT uses might use '\'.)


  40.  
  41. How do I delete a client workspace?

  42.  
    Use   p4 client -d  workspacename   to do this. The steps are:  
  43. How do I move a client workspace?
  44. It's easy, but requires a little planning.
     

    1. Figure out the new client "root". Let's say it's "/home/jojo/newroot".
    2. If you're using the Windows GUI program against this particular Perforce client, exit the GUI.
    3. Move the entire subtree from its old place to "/home/jojo/newroot".

    4. Run  p4 client  , which will dump you into the editor - you'll be changing the client specification. Change the "Root:" field to the name "/home/jojo/newroot" and save the file.
       

  • I can't "p4 sync" a particular file. What might be going on?
  • Let's say that you can retrieve all the files in the directory (using the depot name syntax) //bas/BIN/src/krn/rsec/ except the file //bas/BIN/src/krn/rsec/rsecstoc.c.

    It could be several things:

    1. The other files it gets are in the directory //bas/bin/src/krn/rsec/... If that's the case, you're up against upper-case/lower-case issues. (The NT version of the server ignores case; the Unix version of the server does not.) If this is the case, it'll be easiest to go to a Unix client and rename the file to be in the same directory as the files that are succeeding. ("p4 help rename" gives the steps for renaming a file.)
    2. You might not have permissions on this file from this IP address for this user. Use "p4 protect -o" and "p4 where" to make sure that isn't the case.
    3. The client spec might not be mapping that file as you expect. The command "p4 where //bas/BIN/src/krn/rsec/rsecstoc.c " will process the argument filename through the client spec [processing] code to tell you where it would be mapped.
    4. The top-most revision of that file might be a "delete" revision, so that there's nothing to get(!). ("p4 files //bas/BIN/src/krn/rsec/rsecstoc.c " will tell you the type of the top-most revision of the file.)
    5. There might be nothing to get, because it thinks you have the most recent revision. "p4 have //bas/BIN/src/krn/rsec/rsecstoc.c" will tell you if you already have a revision for that file, or at least whether the database thinks you do. ("p4 sync -f //bas/BIN/src/krn/rsec/rsecstoc.c " will force getting a fresh revision.)

    Last modified on 11 November 1998.