Perforce obsolete

From ITSwiki
Jump to: navigation, search

Gentle introduction to Perforce

Access to this server is administrated by Henning Christensen who can be reached at the email address hench@dtu.dk.

If you are unfamiliar with Perforce and especially with source control systems, there is a gentle introduction on the perforce website.

Any questions on how to use Perforce (beyond the scope of this document) should be directed to Tommy S. Alstrøm at tsal@dtu.dk

Installing

Download clients

Both visual and command-line clients can be downloaded for Mac, Linux, and Windows on the perforce website:

http://www.perforce.com/downloads/helix#clients

Direct links to the most common clients are found below. The links point to R15.2 of the command line clients, and R15.1 of the visual clients. Links are last updated 2015.11.28. Due to this revision difference, it is important that you install the visual clients first, and then the command line clients.

Linux Clients

32 bit visual clients

64 bit visual clients

32 bit command line

64 bit command line

Mac Clients

visual clients for OS X 10.8+

32 bit command line

64 bit command line

Windows Clients

32 bit visual clients

62 bit visual clients

32 bit command line

64 bit command line

Basic configuration

The basic setup procedure is different for the gui and for the command line. Common for both of them is the server address and establishment of trust.

The perforce server has the address

ssl:perforce.compute.dtu.dk:1666

Authentication happens using the portalen username and password.

Upon initial connection, you are asked to approve the fingerprint of the perforce server. The fingerprint should be

# 2D:2C:AA:AC:E9:D8:19:BB:CC:6F:EB:5D:3F:C0:C0:86:B2:8B:2C:20

If another fingerprint is displayed, you are connecting to the wrong server - contact IT support.

Using the graphical interface

The graphical interface is called P4V. At first connection, you are asked to trust the server. If the fingerprint corresponds to the fingerprint above check the trust button.

As workspace, the workspace should be named "<username>_<something>" (where <something> can be choosen freely).

Using the command line

The command line is configured using environmental variables. These variables are set using the perforce command line. Set the following options

# p4 set P4PORT=ssl:perforce.compute.dtu.dk:1666
# p4 set P4USER=<username>
# p4 set P4CLIENT=<username>_default
# p4 set P4CHARSET=auto
# p4 set P4CONFIG=.p4config

The current loaded settings can always be seen by typing p4 set in command line. Verify your installation by typing (example output)

# p4 set
P4CLIENT=tsal_pc (enviro)
P4CONFIG=.p4config (enviro) (config '/home/tsal/.p4config' )
P4EDITOR=vi (enviro)
P4CHARSET=auto (enviro)
P4IGNORE=.p4ignore (config '/home/tsal/.p4config')
P4PORT=ssl:perforce.compute.dtu.dk:1666 (enviro)
P4USER=tsal (config '/home/tsal/.p4config')

On linux/mac, these settings are stored in the file ~/.p4enviro. On Windows the settings are stored in the registry. The command line has many configurables, to see most of them, type

# p4 help environment

The documentation for perforce is built into the program. You can get help by typing

# p4 help 
# p4 help <command>

Excluding files from perforce

Usually, there are a lot of different and/or temporary files that you do not want to upload to the perforce server. Perforce implements a procedure using an ignore file that implements rules for which files to ignore. The file uses the same syntax as is known from the .gitignore format. A file called .p4ignore containing all rules for the files that should be ignored. A template .gitignore file can be found in the archive.

In order to use an ignore file, use

# p4 set P4IGNORE=<complete path to ignore file>

The effect of the ignore file can be explored using the p4 ignores command. E.g. to query whether or not a file is ignored, type

# p4 ignores -i -v
At least one file path must provided.
# p4 ignores -i -v .git
C:\Users\tsal\.git ignored by C:\Users\tsal\.p4ignore:40:.git
# p4 ignores -i -v .gi
C:\Users\tsal\.gi not ignored

In order to bypass the ignore list when adding files, use p4 add -I.

Read more about the p4ignore file format in the perforce command reference.

Archive structure

The perforce server can be accessed publicly using

https://archive.compute.dtu.dk

The general layout is as follows

//comp/ # the primary DTU Compute content (non-terabyte content)

//comp/courses/ # courses
//comp/courses/02450/

//comp/common/ # common folder accessible for compute staff
//comp/common/MATLAB/immoptibox/main/...
//comp/common/MATLAB/immoptibox/REL2.2/...
//comp/common/MATLAB/immoptibox/codeline.txt # information about codeline

//comp/projects/ # location of "official" projects
//comp/projects/perforce/public/ # location of perforce relevant files

//comp/sections/
//comp/sections/cogsys/projects/

//comp/tmp/ # temporary storage - files older than 30 days are deleted permenantly

//comp/users/<user>/ # content private to users

//comp-archive/ # ARCHIVE depot - contains publications in their entirety

//comp-data/ # DATA depot - 

//extern/ # external libs
//extern/MATLAB/gpml-matlab/MAIN # 
//extern/MATLAB/sgetools/MAIN # 

//public/ # public domain for papers, toolboxes etc.

The data depot comp-data is a special depot, in the sense that there exists a read-only copy of the latest revision of this depot in the folder called /dtu-compute/comp-data/ accessible from DTU Compute grid, gbar and hpc-cluster.

Common use cases

These use cases are described as commands, but most of them are as easily carried out using the graphical user interface. For any single command, you can always type p4 help <cmd> to get help.

Adding files

Adding files to perforce is a two step procedure. First the files are added using a p4 add command, then the files are uploaded using a p4 submit command. To do this in command line, type

# cd <to directory to add>
# p4 add <file>
Adding single file
# p4 add ...
Adding all files including directories recursively
# p4 add dir/...
Adding all files in <dir> recursively

To check that these files will land in the perforce depot the expected place, type

# p4 where

You will see these files are adding to the default changelist. To submit these files type

# p4 submit -d "Submit message"

The above command will submit all changes that currently reside on the default changelist. If you wish to only submit files from the current directory, use

# p4 submit -d "Submit message" ...

The "..." is a special path known to perforce that means everything from here and beneath and is very commonly used.

Deleting a file

To remove a file from perforce, a new revision of a file - namely a deletion is uploaded. As such, deleting a file will never permanently delete the file, and you can always go back and get older revisions. In that way, obsolete files can safely be deleted without loosing the history. To perform the delete, type

# p4 delete <file>
# p4 submit -d "Submit message" <file>

Renaming files

Renaming files in perforce is essentially a copy and a delete. As with the delete case, the file with the old name will continue to be in perforce. To rename a file, type

# p4 move <file>
# p4 submit -d "Submit message" <oldfile> <file>

You can also call the command p4 rename, which is a synonym for p4 move.

Merging

Merging is carried out using the p4 integrate or p4 merge command. p4 merge is a synonym for p4 integrate where certain flags are set. As such, there is truly only one merge command. This procedure is by far easiest to carry out using the GUI.

Performing copy / Branching

In Perforce, the branch model is to perform a copy. As such, any single file with the complete depot path always belongs to one particular branch. Once a file is copied, it is branched. That simply means that perforce keeps track of the origin of the file and that makes merging changes later a lot easier. Copying is carried out using the p4 copy command:

# p4 delete <file>
# p4 submit -d "Submit message" <file>

Syncronizing perforce with your current working copy

In case you make changes to files without "telling perforce", there is an easy command to get perforce up to speed. Two commands exist:, p4 status which will give you a status of what is currently out of sync, and the p4 rec which will put out changed on the default workspace. In the gui, select the option called "Reconcile offline work" to get an interactive experience.

The commands take file paths, so at any time you can always narrow down your reconcile to specific files, e.g. if you want to only add any changed matlab files to your default changelist, type

# p4 rec -e ....m

Performing server-side copy

Perforce supports two different approaches to server-side copy. Using the -v flag to p4 copy, p4 merge, or p4 integrate will perform the copy, merge, or integrate without syncing the files to the client. However, if one performs this action to a target outside the client view, perforce will give the error "File(s) not in client view"

Perforce supports server-side copy of files outside the client workspace. This is carried out using the p4 populate command:

Depot paths have to end with ... if directories are copied.
# p4 populate -d "Submit message " <source depot path> <target depot path>

Frequently Asked Questions

The client shows I don't have a file even though I do, how do I handle it?

This scenario can happen if you by other means move files/folders that are under Perforce source control. Perforce has a "have" database that contains which files are retrieved in which revision on each workspace, p4 have will show you the current "have list" for the chosen workspace. The p4 have list can be out of sync:

  1. You create a new workspace that points to files under perforce source control
  2. You move files by other means (e.g copy files to grid, or sync files using dropbox) to other machines and use different workspaces.
  3. Manually delete files

To resolve, run

# p4 sync -k

How do I sync a directory that does not exist on my computer yet?

If the directory exists on the perforce server but not on your computer, and you would like to do a narrow sync, do the following:

# p4 sync //complete/depot/path/...

Or from the directory you have - e.g. if you have a directory called perforce and you wish to sync a subdirectory called public, do the following:

# cd <path to perforce>
# p4 sync public/...

On Windows, I get the error "too long filename", how do I fix that?

The windows file system does per default only support path names of length up to 260. If you set the environmental variable

filesys.windows.lfn=1

both the command line tool and the visual client can operate with long file names. If you only use the command line, this option can be set in the configuration file (p4enviro).

You can read more about it on the perforce website.

Why are all my files read-only?

The default workflow implemented by Perforce is to set all files as read only. The idea in the workflow is

  1. Notify the Perforce server that you intend to edit the file.
  2. Once you're done editing you submit the file using a changelist.

Why do I get a "file not in view" error message?

This happens if you try to operate on files that are not defined in the workspace (also called client view). Typically the error occurs because you are copying files to a new place where you have not defined a view yet. To perform copying to destinations where you do not want to checkout the files, use the p4 populate command.

This can also happen if you unexpectedly change workspace. Use the p4 set command to verify that you are using the expected workspace, and the p4 where ... command to verify where the current location will be.

Why is my question not in the FAQ?

Nobody has asked this question before. Contact Tommy S. Alstrøm at tsal@dtu.dk with your question, and an answer will be provided.

Further reading

External material for understanding Perforce

Perforce cheat sheet.

Perforce command line reference

Guide to the visual client

Understanding the client configuration

Understanding views

Tips for subversion users

Perforce provides a list of subversion command and their perforce counterpart here: Reference: http://answers.perforce.com/articles/KB/2953

Tips for git users

There are a few approaches git users can take on perforce:

  1. Migrate to perforce
  2. Have the same repo under both perforce and git revision control
  3. Retain a complete git eco system

For a complete migration to perforce, use the git - perforce command comparison.

To have the same repo under both perforce and git revision control, one simply commits to both git and perforce. This basically means that local branching is carried out using git only and the master branch only is commited to perforce. The other approach is to set up the git client to connect to perforce. This is detailed in chapter 9 in the pro git 2 book.

Finally, once can reside in a complete git environment, and create git repos based on perforce files. This is carried out using our gitswarm server, however this server is still to be put into production mode.