About This Tutorial | |
About This Tutorial |
Back to Table of Contents |
The instructions in this tutorial are for registered Public Depot contributors only. See the Public Depot home page for more information.
Because the bulk of the Public Depot is populated by Perforce-related content, we expect the typical contributor to be an experienced Perforce user. However, Jam/MR contributors may not necessarily be familiar wth Perforce, so this tutorial was written to be useful to new Perforce users as well as experienced users.
Complete documentation for all Perforce commands and programs is available on our technical documentation page.
If you're using P4win, our Windows GUI, you'll want to have a copy of our p4 to P4Win Translation Guide handy so you can look up the GUI equivalents of the commands shown here. The Translation Guide can be downloaded from our technical documentation page.
Setting Up Your Workspace |
Back to Table of Contents |
The first thing you do when you use Perforce is to set up a client workspace on your local machine. This setup is only done once.
setenv P4CLIENT cary_grant | On Unix (csh) -- this also goes in your .cshrc
| export P4CLIENT=cary_grant On Unix (ksh) -- this also goes in your .login
|
|
p4 set P4CLIENT=cary_grant In MS-DOS on Windows
| |
| p4 client |
Client: cary_grant Description: Created by cary_grant. Root: C:\ Options: nomodtime noclobber View: //public/... //cary_grant/... //guest/... //cary_grant/... |
Client: cary_grant Description: Cary Grant's workspace. Root: C:\ws Options: nomodtime noclobber locked View: //guest/cary_grant/... //cary_grant/... |
Creating Your Guest Branch |
Back to Table of Contents |
When you register as a Public Depot contributor, you are given write access to your guest branch, but your guest branch is not actually created for you (because we don't know which projects you want to work on). So you must create your own guest branch. It will start out as a clone of one of the projects in the //public path, and you will submit additions or changes to it.
For example, if Cary Grant wanted to contribute enhancements to some of the Perforce utilities, he'd start out by branching the //public/perforce/utils project into his //guest/cary_grant branch. Here's how he'd do it:
First, open the files for branching:
| p4 integ -v //public/perforce/utils/... //guest/cary_grant/perforce/utils/... |
Next, submit the opened files:
| p4 submit |
Filling Your Workspace |
Back to Table of Contents |
Once you have set up your workspace and created your guest branch, you can fill your workspace with files from the depot using:
| p4 sync |
Note:
Working on Files |
Back to Table of Contents |
Once you have filled your workspace, you can work on files. You can edit files, add files, delete files, and revert files to their original state.
Note:
cd c:\ws\perforce\utils\p4db
|
p4 edit index.cgi chb.cgi |
For example, Cary Grant is adding a new file to the P4DB suite. First he creates the file with vi, then adds it:
cd c:\ws\perforce\utils\p4db
| vi jbv.cgi
|
p4 add jbv.cgi |
| p4 delete fdv.cgi fv.cgi flv.cgi |
| p4 revert fdv.cgi flv.cgi |
Warning: p4 revert is IRREVERSIBLE! When you revert a file that was opened for edit, Perforce replaces the file in your workspace with a fresh, read-only version directly from the depot. Any edits you've made to the file will be lost!
Note:
| p4 submit |
Pulling Changes into Your Branch |
Back to Table of Contents |
The files in your guest branch are insulated from the files in the //public path they were branched from. From time to time, files in //public will be added as Public Depot project curators integrate changes from guest branches. If the project you made your branch from gets updated, you will need to pull those updates into your own guest branch.
So Cary Grant, for example, has been working on his P4DB enhancement. As you recall, his guest branch files were originally branched from the //public/perforce/utils path. To find out if any changes need to be pulled from that path into his own guest branch, Cary uses:
If he sees files listed, he knows he'll have to pull changes into his guest branch. Here's how he does it:
| p4 integ //public/perforce/utils/... //guest/cary_grant/perforce/utils/... |
| p4 resolve |
| p4 submit |
Submitting A Changelist |
Back to Table of Contents |
As you open files with p4 edit, p4 add, and p4 delete, you are building up a changelist. A changelist is also created when you open files with p4 integ. However, until you submit your changelist, files in the depot are unaffected by your intended changes. "Submitting" sends modified file content from your workspace to the depot, and updates depot versions of the files.
To submit your changelist, use:
| p4 submit |
Change: new Client: cary_grant User: cary_grant Status: new Description: Added job searching to the P4DB browser. Files: //guest/cary_grant/perforce/utils/p4db/index.cgi # edit //guest/cary_grant/perforce/utils/p4db/chb.cgi # edit //guest/cary_grant/perforce/utils/p4db/jbv.cgi # add //guest/cary_grant/perforce/utils/p4db/fv.cgi # delete |
When you are done typing the description, save the file and exit the editor. Your changelist will be submitted and the depot files updated.
Note that all files in all guest branches are readable to everyone, so as soon as you submit your changelist, other contributors can see and review your changes.
Resolving Files |
Back to Table of Contents |
Resolving is how you merge specific changes from one file to another. For each file, you'll see stats like:
c:\ws\perforce\utils\p4db\index.cgi - merging //public/perforce/utils/p4db/index.cgi#7 Diff chunks: 0 yours + 2 theirs + 0 both + 0 conflicting...and a prompt like:
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [at]:Follow the prompt's advised action by hitting return. The prompt shows
[
in square brackets]
which action it advises you to take.
Note:
>>>>
, ====
,
or <<<<
.
For example:
>>>> ORIGINAL i = i + j ==== THEIRS if ( i < n ) then i = i + j ==== YOURS if ( i <= n ) then i = i + j <<<<While in the editor, your job is to look for the conflicts, remove the conflict markers (shown here in red), and modify the remaining text in a way that makes sense. When you exit the editor, the prompt will advise you to accept the merged result.
Publishing Your Changes |
Back to Table of Contents |
As a contributor, you may only submit changes to your own branch in the //guest depot. To have your changes "published", you must ask a project curator to integrate them from your branch to the //public depot.
To request publication:
Sharing Development |
Back to Table of Contents |
If you and other registered Public Depot contributors would like to share development on a project, you can designate one of your guest branches as a shared branch. The owner of the shared branch should email info@perforce.com requesting that his or her branch be opened for shared development, and naming the other contributors who should be granted write access to that branch.
For contributors working in a shared branch, all of the above instructions apply, with these caveats:
| p4 submit -c 1453 |
Being A Project Curator |
Back to Table of Contents |
If you are a curator of a project in the Public Depot (and you know who you are) your first responsibility is to maintain an index.html file at the top level of the project subdirectory in the //public path. This document should at least describe the purpose of the project, and list your name and email address. (Or, for spam-proofing, your decodable email address.)
Your second responsibility is to "publish" contributions to the project by integrating changes from guest branches into the //public project path. You'll receive email requests to publish contributions. When you receive a request:
For example, say you are the curator of the //public/perforce/utils project and you get email from Cary Grant requesting that you publish his enhancements to the P4DB browser. Here are some tips for reviewing and integrating his contribution:
p4 changes //guest/cary_grant/...
p4 flush //guest/cary_grant/perforce/utils/... p4 integ -n //public/perforce/utils/... //guest/cary_grant/perforce/utils/...If this shows unintegrated files, send Cary mail telling him he needs to pull the latest //public/perforce/utils changes into his guest branch before you can publish his contribution. (p4 flush simulates a sync without copying files to your workspace.)
p4 sync //public/perforce/utils/... p4 integ //guest/cary_grant/perforce/utils/... //public/perforce/utils/...
p4 resolve -as //public/perforce/utils/... p4 resolve -n //public/perforce/utils/...The second resolve should show that everything is already resolved. If this is not the case, either Cary did something wrong pulling in the latest changes into his branch, or you aren't synced to the latest //public/perforce/utils files.
Copyright 1998, 1999 Perforce Software info@perforce.com |
You're browsing a file stored as$Id: //public/tutorial.html#5 $ in the Perforce Public Depot. |
Back to Table of Contents |