quickstart.html #1

<TITLE>Getting Started with Perforce and P4Web</TITLE>

<P> This page is for users who are new to Perforce and P4Web. It describes how 
  to use P4Web in <a href="helper?help">Standard mode</a> to do the common Perforce 
  tasks: setting up a workspace, filling a workspace ("syncing"), working with 
  files, and submitting files (in a "changelist"), and resolving files. Read this 
  page first to get the most out of P4Web. 
<OL>
<P><LI>
       <A HREF="quickstart?help#setup"> Setting up a workspace </A>
<P><LI>
       <A HREF="quickstart?help#filling"> Filling a workspace with files ("syncing")</A>
	   <UL>
	   <LI><A HREF="quickstart?help#updating"> Updating a workspace ("re-syncing") </A>
	   </UL>
<P><LI>
       <A HREF="quickstart?help#working"> Working on files </A>
	   <UL>
	   <LI><A HREF="quickstart?help#editing"> Editing files </A>
	   <LI><A HREF="quickstart?help#deleting"> Deleting files </A>
	   <LI><A HREF="quickstart?help#adding"> Adding new files </A>
	   <LI><A HREF="quickstart?help#reverting"> Reverting files </A>
	   </UL>
<P><LI>
       <A HREF="quickstart?help#submitting"> Submitting a changelist </A>
	   <UL>
	   <LI><A HREF="quickstart?help#submit_errors"> Submit errors </A>
	   <LI><A HREF="quickstart?help#resolving"> Resolving files </A>
       <LI><A HREF="quickstart?help#re-submitting"> Re-submitting a changelist </A>
	   </UL>
</OL>


<A NAME="setup"><H3>Setting up a Workspace</H3></A>

<p>
The first thing you do in Perforce is to set up a personal
<a href="defs?help#clientworkspace"><i>client workspace</i></a>
on your local machine.
You only have to do this once.
You can't work with Perforce files until you've created a
client workspace specification, or
<a href="defs?help#clientspec"><i>client spec</i></a>.
<P><b>To set up a workspace:</b>
<P>Select the <B>Clients</B> tab. At the top of that page, click on the <B>Edit 
  current client</B> link. 
<P>
This brings up the Edit Client page, which contains a form.
The important field to enter is the <B>Root</B>, which tells
Perforce where on your local filesystem to put your workspace, or where to copy depot files to on
your local filesystem.
For example, if you want your workspace to be located in the "c:&#92;ws" path,
enter "c:&#92;ws" in the <B>Root</B> field.
<P>
After entering the workspace root,
go to the bottom of the page and click <b>Save</b>.
(There are other fields you can edit, but you can come
back to them later when you have a better idea of how
Perforce works.)
You'll see the message "Client [<i>name</i>] saved."

<P>
If you ever need to change your client spec, just bring up this
form again using the <B>Clients</B> tab.



<A NAME="filling"><H3>Filling a workspace ("syncing")</H3>
</A> 
<P> After you have set up your workspace, you can fill it with files from the 
  depot. In Perforce, this is called "syncing" your workspace. To sync your workspace 
  for the first time, 
<OL>
  <LI>Click the <B>Files</B> tab. If you do not see a tree view of the depot, 
    click <img src=
"/gotree?icon"> to display it. 
    <p>
<LI>Navigate through the tree to the depot path you want to work on.
The current path is shown in the header at the top of the page. Navigate down until the path shown
is the one you want to sync.
It will look something like this:
<P>
    <BLOCKQUOTE>
	<SMALL><B>Current path:</B> //depot/projects/gizmo/</SMALL>
    </BLOCKQUOTE>
<LI>Click the "Sync to Head Revisions" shortcut button.
<P>
	<BLOCKQUOTE>
	<TABLE>
	<TR><TD ALIGN=RIGHT >
    <img src="/runsync?icon" alt="Sync to Head Revisions">
	</TD><TD>
	Shortcut to "Sync to Head Revisions"
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>
</LI>

<LI>
<P>
This displays a command result page that shows you which files are
being copied from the depot onto your workspace.
When the result page is completely loaded,
your workspace is "in sync" with the depot.
Return to the tree view where you'll see icons
showing that your files are synced.

	<BLOCKQUOTE>
	<TABLE>
	<TR><TD ALIGN=right>
    <img src="/synced?icon" alt="Synced File">
	</TD><TD>
	"Synced File" icon
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>

</LI>
</OL>

<p>
<i>Note:</i>
<p>
<ul type=square>
<li> Synced files have read-only permission in your workspace (until you start
<A HREF="quickstart?help#working">working on them</A>).
<p>
<li> Perforce will sync to the <A HREF="defs?help#headrevision"><i>head revisions</i></A>
of depot files, by default.
</ul>

<p>
<a name="updating">
<h3>Updating ("re-syncing") a workspace</h3>
</a>
<p>
After you sync your workspace it can eventually get out of date because other people
are submitting changes to depot files.
You can re-sync your workspace to update it.
Navigate to the path you want to update and click
the "Sync" shortcut:

<P>
<BLOCKQUOTE>
<img src="/runsync?icon" alt="Sync"> Shortcut to "Sync Files"
</BLOCKQUOTE>

<P>
When you sync, Perforce gets the files from the depot that are newer
than the ones in your workspace.
If you run sync more than once, nothing will happen
the second time unless there are newer versions in the depot that are not
yet in your workspace.
Files that have
already been copied to your workspace will not be copied a second time.
<P>
You should use sync regularly to
update your workspace with the
latest revisions of files.
The files you are working on will be untouched when you sync.
Read on to find out more about this.

<A NAME="working"><H3>Working on Files</H3></A>

Once you have synced your workspace,
you can work on files.
You can edit files, add files, and delete files,
but first you must "open" them for these operations.
You can also revert opened files to their original state.
<p>
<i>Note:</i>
<ul type=square>
<li>Opening files does not affect files in the depot.
    All it does is allow you to work on files in your workspace.
<p>
<li>You can open a file individually, by navigating to the directory that
contains the file, then clicking on the file.
You can then run commands on just that file.
Most of the examples below describe opening a single
file at a time.
<p>
<li>You can also open several files at once by navigating to the path that contains the files you
want to open, then running commands from there.
Commands run from the directory level can operate on all
the files at or below the current path level.
<P>
<LI>Perforce tracks the files you're working on in a
    <a href="defs?help#changelist"><i>changelist</i></a>.
    As you open files, they go in your changelist.
    You have to <a href="quickstart?help#submitting">
	submit your changelist</A>
    to get your changes into the depot. Before a changelist is submitted, it is described as
    "pending." Submitting changelists is described a little further on.

</ul>


<P>
<A NAME=editing><h3>Editing files</h3></A>

To open a file for edit, navigate to that file
    and click the "Open for Edit" shortcut button.
	A page showing the result of the edit command will appear. You can return to the tree view to
	see a visual icon next to the file to remind you that you have it opened for
	edit.

	<BLOCKQUOTE>
	<TABLE>
	<TR>
	<TD>
    <img src="/runedit?icon" alt="Open for Edit">
	</TD>
	<TD>
	Shortcut to "Open for Edit"
	</TD>
	</TR>
	<TR>
	<TD ALIGN=right>
    <img src="/edit?icon" alt="Opened for Edit">
	</TD>
	<TD>
	"Opened for Edit" icon
	</TD>
	</TR>
	</TABLE>
	</BLOCKQUOTE>

    <P>
	Once a file is opened for edit, it becomes writeable by you.
	Now you can use an editor or any other tool to modify the file.

<P>
<A NAME=deleting><h3>Deleting files</h3></A>

To delete a depot file, first you have to "open it for delete"
in your workspace.
To open a file for delete, navigate to the file
    and click the "Open for Delete" shortcut.
	A page showing the result of the delete command will appear.
	In the tree view, you'll see a visual icon
	next to the file to remind you that you have it opened for
	delete.

	<BLOCKQUOTE>
	<TABLE>
	<TR><TD>
    <img src="/rundelete?icon" alt="Open for Delete">
	</TD><TD>
	Shortcut to "Open for Delete"
	</TD></TR>
	<TR><TD ALIGN=right>
    <img src="/delete?icon" alt="Opened for Delete">
	</TD><TD>
	"Opened for Delete" icon
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>

    <P>
	When you open a file for delete, P4Web removes it from your workspace
	and lets the Perforce server know you are planning on deleting it from
	the depot. When you delete a file from Perforce, the file itself is not actually
	"deleted." The file remains in the depot, but it is marked as deleted at the
	head revision.

<A NAME=adding><H3>Adding new files</h3></A>
To add new files to the Perforce depot, you will need to be in the Workspace tree. To do
this, first select the <B>Files</B> tab and then click the "Display tree view" shortcut.
    <BLOCKQUOTE>
	<TABLE>
	<TR><TD>
    <img src="/gotree?icon" alt="Display tree view">
	</TD><TD>
	Shortcut to "Display tree view"
	</TD></TR>
    </TABLE>
	</BLOCKQUOTE>

If the label at the top of the
tree says<B> Depot Tree</B>, click the <B>Switch
to workspace tree</B> link. If it says <B>Workspace Tree</B>, you're in the right
place. (The files must exist below your workspace root in order for you to add them to the depot.)
	
<p> Select <B>Open for add...</B> from the <b>Action</b> menu. 
<BLOCKQUOTE>
		<TABLE>
		<TR> <TD>
		<SELECT>
		<OPTION>Open for add...
		</SELECT>
		</TD></TR>
		</TABLE>
	</BLOCKQUOTE>

	In the form that appears, select "By path" and click
	"Continue".
	Now you'll see a list of the files in your workspace
	path that aren't already in the depot.
	If there are any in that list that you <i>don't</i> want to
	add, uncheck them.
	<p>
	Click the "Add New Files" button.
	The files you entered will now be listed in the tree view with
	visual icons showing that they are opened for add.

	<BLOCKQUOTE>
	<TABLE>
	<TR><TD>
    <img src="/add?icon" alt="Opened for Add">
	</TD><TD>
	"Opened for Add" icon
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>

    <P>
	Opening files for add tells
    Perforce you plan to add them to the depot.
	It doesn't create the files, however. You must have done that previously,
	with an editor or any other tool.

<p>


<A NAME=reverting> <H3>Reverting files</H3></A>

Sometimes after opening files you realize you don't need to change
them after all. In that case,
you can use "Revert" to
restore opened files to their original condition.
You can use "Revert" either from a folder or file level. The former reverts all opened files in a
particular
path; the latter reverts a particular file.

<P>
The "Revert if Unchanged"
shortcut can be used to automatically revert files you have <i>opened for
edit</i> as long as you haven't changed them.
Navigate to the path or file in question and
click the "Revert if Unchanged" button.

	<BLOCKQUOTE>
	<TABLE>
	<TR><TD ALIGN=right>
    <img src="/edit?icon" alt="Opened for Edit">
	</TD><TD>
	"Opened for Edit" icon
	</TD></TR>
	<TR><TD>
    <img src="/runrevert?icon" alt="Revert if Unchanged">
	</TD><TD>
	Shortcut to "Revert if Unchanged"
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>

<P> Neither files that you have modified nor files opened for add or delete can 
  be reverted using a shortcut. To revert those files, navigate to the path or 
  file in question and select <B>Revert...</B> from the <b>Action</b> menu. Click 
  <B>Revert</B> to run the command after you've selected your options. 
<P>
	<BLOCKQUOTE>
	<TABLE>
	<TR><TD >
	<SELECT>
	<OPTION>Revert...
	</SELECT>
	</TD></TR>
	<TR><TD >
	<INPUT TYPE=reset VALUE="Revert">
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>
<P>
Caution:
<BLOCKQUOTE>
In the Revert options page, you must leave the "Restrict to unchanged files"
checkbox blank if you want to revert files opened for add or delete.
Files you have opened for add remain intact after they are reverted so you don't
have to worry about losing them.
However,
<FONT COLOR=red><I>P4Web overwrites files opened for edit when
you run revert this way, discarding any workspace changes you have made to them.
</I></FONT>
Use the "Selected Files" option in the form to de-select any files with changes you
don't want discarded:
</BLOCKQUOTE>

<P>
<BLOCKQUOTE>
	<TABLE>
	<TR><TD >
	<INPUT TYPE=checkbox>
	Restrict to unchanged files
	</TD></TR>
	<TR><TD >
	<INPUT TYPE=radio CHECKED>
	Selected Files
	</TD></TR>
	</TABLE>
</BLOCKQUOTE>



<A NAME="submitting"><H3>Submitting a changelist</H3></A>

<p> As you open files you are building up a <a href="defs?help#changelist"><i>changelist</i></a>. 
  When you are satisfied with your changelist, you can submit it into the depot. 
  "Submitting" copies opened files from your workspace to the depot. Until then, 
  files in the depot are unaffected by your work. To submit your changelist, use 
  the "Submit Default Changelist" shortcut button. 
<p>
	<BLOCKQUOTE>
	<TABLE>
	<TR><TD ALIGN=RIGHT >
    <img src="/runsubmit?icon" alt="Submit Default Changelist">
	</TD><TD>
	Shortcut to "Submit Default Changelist"
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>

<P>
In the form that comes up, enter a description that explains
why you are submitting these files.
This description
is stored permanently in Perforce and will be visible to anyone who
looks at the history of any of the files in your changelist.
<P>
You don't have to fill in the Jobs field.
It is used to associate <A HREF="defs?help#job"><i>jobs</i></A> with changelists.
<P>
At the bottom of the form you'll see a checkbox list of all your
opened files. If there are any you <i>don't</i> want to submit,
uncheck them now. Then click the "Submit" button.
A results page will show you whether or not your submit succeeded.
<P>
	<BLOCKQUOTE>
	<TABLE>
	<TR><TD COLSPAN=2 >
	<INPUT TYPE=reset VALUE="Submit">
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>

<P>
<i>Note:</i>
     If any of the files you submit have been changed by someone else
     first, you'll get a submit error, as described below.
	 This is perfectly normal.
     When it happens all you have to do is
     <A HREF="quickstart?help#resolving">resolve your files</A> and
     <a href="quickstart?help#re-submitting">re-submit your changelist</a>.
<P>

<a name="submit_errors"><h3>Submit errors</h3></a>
<p>
Sometimes when you've been working on files, other people will have
submitted changes to the same files. If you haven't
<a href="quickstart?help#updating">re-synced your workspace</a> periodically and
<a href="quickstart?help#resolving">resolved files</a>, you'll get a submit error
when you try to submit your changelist.
<p>
Here's an example of what a submit error looks like:
<pre>
	Submitting change 5047.
	//depot/dev/omni/svr/dynch.c - must resolve before submitting
	//socks-whitehouse/dev/omni/svr/dynch.c - must resolve //depot/dev/omni/svr/dynch.c#7
	Out of date files must be resolve or reverted.
	Merges still pending -- use 'resolve' to merge files.
	Submit failed -- fix problems above them use 'submit -c 5047'
</pre>
What this means is that your changelist has been assigned a number&#151;5047, 
in this example&#151;but it has not been submitted. You'll have to resolve your 
files before you can re-submit your changelist. 
<p>
<A NAME="resolving"><H3>Resolving files</H3></A>

<p>
Resolving files is how you merge someone else's changes with your
changes, when you've both been working on the same files.
<P>
For example, say you synced the file <code>main.c</code> to your workspace
when it was at revision #6 in the depot. Then you opened it for edit.
Then someone else
submitted revision #7 into the depot.
Resolving allows you to merge the changes from the depot's
<code>main.c#7</code>
into the opened copy of <code>main.c</code> in your workspace.

<p>
Note that
files in your workspace don't actually need resolving until you either
<a href="quickstart?help#updating">re-sync your workspace</a>, or get a
<a href="quickstart?help#submit_errors">submit error</a> trying to submit files that
have been changed in the depot by someone else.
You can tell which of your files need to be resolved by looking for the
"Needs Resolve" icon on files listed in the tree view.

	<BLOCKQUOTE>
	<TABLE>
	<TR><TD >
    <img src="/resolve?icon" alt="Needs Resolve">
	</TD><TD>
	"Needs Resolve" icon
	</TD></TR>
	</TABLE>
	</BLOCKQUOTE>

<p> You can resolve your files with the <B>Resolve...</B> option in the <b>Action</b> 
  menu. Selecting this takes you to the <b>Resolve</b> options page. 
<P>
Select "Interactively" to launch a resolve application in a separate window. If you have specified a resolve program to use with Perforce, P4Web launches that.
If not, the default Perforce resolve program is launched.
It prompts you through your unresolved files
and lets you choose what to do.
For each file, you'll see information like:
<pre>
	c:&#92;ws&#92;jam&#92;main.c - merging //depot/proj/jam/main.c#7
	Diff chunks: 0 yours + 2 theirs + 0 both + 0 conflicting
</pre>
...and a prompt like:
<pre>
	Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) [at]:
</pre>
Follow the prompt's advised action by hitting return. The prompt shows <code>[</code>in 
square brackets<code>]</code> which action it advises you to take. If there are 
no conflicting diffs (differences), the merged result is saved in your workspace 
file, and the <b>resolve</b> program goes on to the next file. 
<p> If there <i>are</i> conflicting diffs, you are put into an editor to resolve 
  the conflicts. The conflicts are marked by lines beginning with <code>&gt;&gt;&gt;&gt;</code>, 
  <code>====</code>, or <code>&lt;&lt;&lt;&lt;</code>. For example: 
<pre>
    <font color=red> &gt;&gt;&gt;&gt; ORIGINAL
    </font> i = i + j
    <font color=red> ==== THEIRS
    </font> if ( i &lt; n ) then i = i + j
    <font color=red> ==== YOURS
    </font> if ( i &lt;= n ) then i = i + j
    <font color=red> &lt;&lt;&lt;&lt; </font>
    </pre>
While in the editor, your job is to look for the conflicts, remove the conflict 
markers (shown here in <font color=red>red</font>), and modify the remaining text 
in a way that makes sense. When you exit the editor, the prompt advises you to 
accept the edited result. 
<p>
You can choose to skip any
    file and resolve it later. Your workspace
    file will remain untouched if you choose to skip the file.


<a name="re-submitting">
<h3>Re-submitting a changelist
</h3></a>
<P>
A submit error will cause your changelist to be assigned a number.
After you've resolved the files that caused the submit error, you
can re-submit your numbered changelist by selecting the <B>Pending</B> tab
and clicking on the changelist number you want to submit.
Now you can submit your changelist following the instructions in
<A HREF="quickstart?help#submitting">Submitting a Changelist</A>.