- <HTML><HEAD><TITLE>P4Web User Guide - Getting Started with Perforce and P4Web</TITLE></HEAD><BODY><FONT SIZE=-1><B>P4Web Release 2012.1 User Guide</B></FONT><BR>
- <FONT SIZE=-1><B><A HREF="quickstart.html">[Getting Started]</A> <A HREF="howto.html">[How To...]</A> <A HREF="tips.html">[Browser Tips]</A> <A HREF="defs.html">[Glossary]</A> <A HREF="roadmap.html">[Road Map]</A> </B></FONT><BR>
- <H3>Getting Started with Perforce and P4Web</H3>
-
- <P> This page is for users who are new to Perforce and P4Web. It describes how
- to use P4Web in <a href="helper.html">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.html#setup"> Setting up a workspace </A>
- <P><LI>
- <A HREF="quickstart.html#filling"> Filling a workspace with files ("syncing")</A>
- <UL>
- <LI><A HREF="quickstart.html#updating"> Updating a workspace ("re-syncing") </A>
- </UL>
- <P><LI>
- <A HREF="quickstart.html#working"> Working on files </A>
- <UL>
- <LI><A HREF="quickstart.html#editing"> Editing files </A>
- <LI><A HREF="quickstart.html#deleting"> Deleting files </A>
- <LI><A HREF="quickstart.html#adding"> Adding new files </A>
- <LI><A HREF="quickstart.html#reverting"> Reverting files </A>
- </UL>
- <P><LI>
- <A HREF="quickstart.html#submitting"> Submitting a changelist </A>
- <UL>
- <LI><A HREF="quickstart.html#submit_errors"> Submit errors </A>
- <LI><A HREF="quickstart.html#resolving"> Resolving files </A>
- <LI><A HREF="quickstart.html#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.html#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.html#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:\ws" path,
- enter "c:\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=
- "../icons/gotree.gif"> 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="../icons/runsync.gif" 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="../icons/synced.gif" 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.html#working">working on them</A>).
- <p>
- <li> Perforce will sync to the <A HREF="defs.html#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="../icons/runsync.gif" 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.html#changelist"><i>changelist</i></a>.
- As you open files, they go in your changelist.
- You have to <a href="quickstart.html#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="../icons/runedit.gif" alt="Open for Edit">
- </TD>
- <TD>
- Shortcut to "Open for Edit"
- </TD>
- </TR>
- <TR>
- <TD ALIGN=right>
- <img src="../icons/edit.gif" 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="../icons/rundelete.gif" alt="Open for Delete">
- </TD><TD>
- Shortcut to "Open for Delete"
- </TD></TR>
- <TR><TD ALIGN=right>
- <img src="../icons/delete.gif" 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="../icons/gotree.gif" 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="../icons/add.gif" 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="../icons/edit.gif" alt="Opened for Edit">
- </TD><TD>
- "Opened for Edit" icon
- </TD></TR>
- <TR><TD>
- <img src="../icons/runrevert.gif" 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.html#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="../icons/runsubmit.gif" 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.html#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.html#resolving">resolve your files</A> and
- <a href="quickstart.html#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.html#updating">re-synced your workspace</a> periodically and
- <a href="quickstart.html#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—5047,
- in this example—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.html#updating">re-sync your workspace</a>, or get a
- <a href="quickstart.html#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="../icons/resolve.gif" 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:\ws\jam\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>>>>></code>,
- <code>====</code>, or <code><<<<</code>. For example:
- <pre>
- <font color=red> >>>> ORIGINAL
- </font> i = i + j
- <font color=red> ==== THEIRS
- </font> if ( i < n ) then i = i + j
- <font color=red> ==== YOURS
- </font> if ( i <= n ) then i = i + j
- <font color=red> <<<< </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.html#submitting">Submitting a Changelist</A>.
-
-
-
-
-
-
-
-
-
-
-
-
- <P>
- <HR>
- <FONT SIZE=-1><I>
- Copyright 2012 <A HREF="http://www.perforce.com">Perforce Software</A>.
- All rights reserved.
- </I></FONT>
- </BODY></HTML>