diff options
Diffstat (limited to 'en_US.ISO8859-1/articles/p4-primer/article.xml')
| -rw-r--r-- | en_US.ISO8859-1/articles/p4-primer/article.xml | 151 |
1 files changed, 66 insertions, 85 deletions
diff --git a/en_US.ISO8859-1/articles/p4-primer/article.xml b/en_US.ISO8859-1/articles/p4-primer/article.xml index d93580c45b..8b9eb87dad 100644 --- a/en_US.ISO8859-1/articles/p4-primer/article.xml +++ b/en_US.ISO8859-1/articles/p4-primer/article.xml @@ -1,24 +1,19 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + -<article lang='en'> - <title>Perforce in &os; Development</title> - - <articleinfo> + <info><title>Perforce in &os; Development</title> <authorgroup> - <author> - <firstname>Scott</firstname> - <surname>Long</surname> - <affiliation> + <author><personname><firstname>Scott</firstname><surname>Long</surname></personname><affiliation> <address><email>scottl@FreeBSD.org</email> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.general; @@ -27,25 +22,24 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> -<sect1 id="intro"> +<sect1 xml:id="intro"> <title>Introduction</title> <para>The &os; project uses the <application>Perforce</application> version control system to manage experimental projects that are not ready for the main Subversion repository.</para> - <sect2 id="resources"> + <sect2 xml:id="resources"> <title>Availability, Documentation, and Resources</title> <para>While <application>Perforce</application> is a commercial product, the client software for interacting with the server is freely available from Perforce. It can be easily installed on - &os; via the <filename role="package">devel/p4</filename> + &os; via the <package>devel/p4</package> port or can be downloaded from the <application>Perforce</application> - web site at <ulink - url="http://www.perforce.com/perforce/loadprog.html"></ulink>, + web site at <uri xlink:href="http://www.perforce.com/perforce/loadprog.html">http://www.perforce.com/perforce/loadprog.html</uri>, which also offers client applications for other OS's.</para> <para>While there is a GUI client available, most people use the @@ -53,8 +47,7 @@ document is written from the point of view of using this command.</para> - <para>Detailed documentation is available online at <ulink - url="http://www.perforce.com/perforce/technical.html"></ulink>.</para> + <para>Detailed documentation is available online at <uri xlink:href="http://www.perforce.com/perforce/technical.html">http://www.perforce.com/perforce/technical.html</uri>.</para> <para>Reading the <quote>Perforce User's Guide</quote> and <quote>Perforce Command Reference</quote> is highly recommended. @@ -63,28 +56,25 @@ help</command> command.</para> <para>The &os; <application>Perforce</application> server is - hosted on <hostid role="fqdn">perforce.freebsd.org</hostid>, + hosted on <systemitem class="fqdomainname">perforce.freebsd.org</systemitem>, port <literal>1666</literal>. The repository is browsable - online at <ulink url="http://p4web.freebsd.org"></ulink>. + online at <uri xlink:href="http://p4web.freebsd.org">http://p4web.freebsd.org</uri>. Some portions of the repository are also automatically exported to a number of legacy <application>CVSup</application> servers.</para> </sect2> </sect1> -<sect1 id="start"> +<sect1 xml:id="start"> <title>Getting Started</title> <para>The first step to using <application>Perforce</application> is - to obtain an account on the server. If you already have a <hostid - role="domainname">FreeBSD.org</hostid> account, log into <hostid - role="hostname">freefall</hostid>, run the following command, and + to obtain an account on the server. If you already have a <systemitem class="fqdomainname">FreeBSD.org</systemitem> account, log into <systemitem class="fqdomainname">freefall</systemitem>, run the following command, and enter a password that is not the same as your &os; login or any other SSH passphrase:</para> <screen>&prompt.user; <userinput>/usr/local/bin/p4newuser</userinput></screen> - <para>Of course if you do not have a <hostid - role="domainname">FreeBSD.org</hostid> account, you will need to + <para>Of course if you do not have a <systemitem class="fqdomainname">FreeBSD.org</systemitem> account, you will need to coordinate with your sponsor.</para> <warning> @@ -104,8 +94,7 @@ <screen>&prompt.user; <userinput>export P4PORT=perforce.freebsd.org:1666</userinput></screen> <note> - <para>Users with shell access on the <hostid - role="domainname">FreeBSD.org</hostid> cluster may wish to tunnel + <para>Users with shell access on the <systemitem class="fqdomainname">FreeBSD.org</systemitem> cluster may wish to tunnel the <application>Perforce</application> client-server protocol via an SSH tunnel, in which case the above string should be set to <literal>localhost</literal>.</para> @@ -115,8 +104,8 @@ and <envar>P4PASSWD</envar> variables be set. Use the username and password from above, like so:</para> - <screen>&prompt.user; <userinput>export P4USER=<replaceable>username</replaceable></userinput> -&prompt.user; <userinput>export P4PASSWD=<replaceable>password</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>export P4USER=username</userinput> +&prompt.user; <userinput>export P4PASSWD=password</userinput></screen> <para>Test that this works by running the following command:</para> @@ -127,7 +116,7 @@ variable set correctly.</para> </sect1> -<sect1 id="clients"> +<sect1 xml:id="clients"> <title>Clients</title> <para><application>Perforce</application> provides access to the @@ -156,7 +145,7 @@ you want, but it must be unique within the <application>Perforce</application> server. A naming convention that is commonly used is - <literal><replaceable>username</replaceable>_<replaceable>machinename</replaceable></literal>, + <literal>username_machinename</literal>, which makes it easy to identify clients when browsing them. A default name will be filled in that is just the machine name.</para> @@ -217,13 +206,12 @@ <para>This will map the entire <application>Perforce</application> repository to the - <filename class="directory">Root</filename> directory of your + <filename>Root</filename> directory of your client. <emphasis>DO NOT USE THIS DEFAULT!</emphasis> The &os; repo is huge, and trying to map and sync it all will take an enormous amount of resources. Instead, only map the section of the repo that you intend to work on. For - example, there is the smpng project tree at <filename - class="directory">//depot/projects/smpng</filename>. A + example, there is the smpng project tree at <filename>//depot/projects/smpng</filename>. A mapping for this might look like:</para> <programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/...</programlisting> @@ -264,14 +252,14 @@ <para>Existing clients can be listed via the <command>p4 clients</command> command. They can be viewed without being modified via the <command>p4 client -o - <replaceable>clientname</replaceable></command> command.</para> + clientname</command> command.</para> <para>Whenever you are interacting with files in <application>Perforce</application>, the <envar>P4CLIENT</envar> environment variable must be set to the name of the client that you are using, like so:</para> - <screen>&prompt.user; <userinput>export P4CLIENT=<replaceable>myclientname</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>export P4CLIENT=myclientname</userinput></screen> <para>Note that client mappings in the repository are not exclusive; multiple clients can map in the same part of the repository. This @@ -280,7 +268,7 @@ code.</para> </sect1> -<sect1 id="syncing"> +<sect1 xml:id="syncing"> <title>Syncing</title> <para>Once you have a client specification defined and the @@ -304,18 +292,18 @@ <para>You can sync a subset of your tree or client by specifying a relative path to the sync command. For example, to only sync the - <filename class="directory">ufs</filename> directory of the + <filename>ufs</filename> directory of the <literal>smpng</literal> project, you might do the following:</para> - <screen>&prompt.user; <userinput>cd <replaceable>projectroot</replaceable>/smpng</userinput> + <screen>&prompt.user; <userinput>cd projectroot/smpng</userinput> &prompt.user; <userinput>p4 sync src/sys/ufs/...</userinput></screen> <para>Specifying a local relative path works for many other <command>p4</command> commands.</para> </sect1> -<sect1 id="branches"> +<sect1 xml:id="branches"> <title>Branches</title> <para>One of the strongest features of @@ -335,10 +323,9 @@ <application>Perforce</application> repository (the <quote>depot</quote>) is a single flat tree. Every file, whether a unique creation or a derivative from a branch, is accessible via - a simple path under the server <filename - class="directory">//depot</filename> directory. When you create a + a simple path under the server <filename>//depot</filename> directory. When you create a branch, all you are doing is creating a new path under the - <filename class="directory">//depot</filename>. This is in sharp + <filename>//depot</filename>. This is in sharp contrast to systems like CVS, where each branch lives in the same path as its parent. With <application>Perforce</application>, the server tracks the relationship between the files in the parent and @@ -347,7 +334,7 @@ <para>The first step to creating a branch is to create a branch specification. This is similar to a client specification, but is created via the command <command>p4 branch - <replaceable>branchname</replaceable></command>.</para> + branchname</command>.</para> <para>The following important fields are explained:</para> @@ -411,7 +398,7 @@ command, as described in the next section.</para> </sect1> -<sect1 id="Integrations"> +<sect1 xml:id="Integrations"> <title>Integrations</title> <para><quote>Integration</quote> is the term used by @@ -431,7 +418,7 @@ <para>The common way to do an integration is with the following command:</para> - <screen>&prompt.user; <userinput>p4 integrate -b <replaceable>branchname</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 integrate -b branchname</userinput></screen> <para><replaceable>branchname</replaceable> is the name given to a branch spec, as discussed in the previous section. This command @@ -467,7 +454,7 @@ section.</para> </sect1> -<sect1 id="submit"> +<sect1 xml:id="submit"> <title>Submit</title> <para>Changes that are made locally should be committed back to the @@ -521,7 +508,7 @@ case-by-case basis.</para> </sect1> -<sect1 id="editing"> +<sect1 xml:id="editing"> <title>Editing</title> <para>The state of each file in the client is tracked and saved on @@ -534,7 +521,7 @@ <para>To open a file for editing, use the <command>p4 edit</command> command like so:</para> - <screen>&prompt.user; <userinput>p4 edit <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 edit filename</userinput></screen> <para>This marks the file on the server as being in the <emphasis>edit</emphasis> state, which then allows it to be submitted after changes are made, or @@ -558,7 +545,7 @@ your changes and revert it to its original state, run the <command>p4 revert</command> command like so:</para> - <screen>&prompt.user; <userinput>p4 revert <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 revert filename</userinput></screen> <para>This resyncs the file to the contents of the server, and removes the edit attribute from the server. Any local changes @@ -576,7 +563,7 @@ sync</command>.</para> </sect1> -<sect1 id="changes"> +<sect1 xml:id="changes"> <title>Changes, Descriptions, and History</title> <para>Changes to the <application>Perforce</application> depot can @@ -584,7 +571,7 @@ will provide a brief description of each change, who made the change, and what its change number was. A change can be examined in detail via the <command>p4 describe - <replaceable>changenumber</replaceable></command> command. This + changenumber</command> command. This will provide the submit log and the diffs of the actual change.</para> <para>Commonly, the <command>p4 describe</command> command is used in one @@ -592,7 +579,7 @@ <variablelist> <varlistentry> - <term><command>p4 describe -s <replaceable>CHANGE</replaceable></command></term> + <term><command>p4 describe -s CHANGE</command></term> <listitem> <para>List a short description of @@ -602,7 +589,7 @@ </varlistentry> <varlistentry> - <term><command>p4 describe -du <replaceable>CHANGE</replaceable></command></term> + <term><command>p4 describe -du CHANGE</command></term> <listitem> <para>List a description of changeset <emphasis>CHANGE</emphasis>, @@ -614,7 +601,7 @@ </varlistentry> <varlistentry> - <term><command>p4 describe -dc <replaceable>CHANGE</replaceable></command></term> + <term><command>p4 describe -dc CHANGE</command></term> <listitem> <para>List a description of changeset <emphasis>CHANGE</emphasis>, @@ -627,12 +614,12 @@ </variablelist> <para>The <command>p4 filelog - <replaceable>filename</replaceable></command> command will show + filename</command> command will show the history of a file, including all submits, integrations, and branches of it.</para> </sect1> -<sect1 id="diffs"> +<sect1 xml:id="diffs"> <title>Diffs</title> <para>There are two methods of producing file diffs in @@ -667,11 +654,11 @@ <option>-dc</option> flags do work. The two forms of this command are:</para> - <screen>&prompt.user; <userinput>p4 diff2 -b <replaceable>branchname</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 diff2 -b branchname</userinput></screen> <para>and</para> - <screen>&prompt.user; <userinput>p4 diff2 //depot/<replaceable>path1</replaceable> //depot/<replaceable>path2</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 diff2 //depot/path1 //depot/path2</userinput></screen> </listitem> </varlistentry> </variablelist> @@ -686,11 +673,10 @@ (the <option>-u</option> flag of <option>diff2</option> will produce unified diffs that are somewhat compatible, but it does not include files that have been added or deleted). There is a - post-processing script at: <ulink - url="http://people.freebsd.org/~scottl/awkdiff"></ulink>.</para> + post-processing script at: <uri xlink:href="http://people.freebsd.org/~scottl/awkdiff">http://people.freebsd.org/~scottl/awkdiff</uri>.</para> </sect1> -<sect1 id="add-rm-files"> +<sect1 xml:id="add-rm-files"> <title>Adding and Removing Files</title> <para>Integrating a branch will bring existing files into your tree, @@ -698,7 +684,7 @@ Adding files is easily done be creating the file and then running the <command>p4 add</command> command like so:</para> - <screen>&prompt.user; <userinput>p4 add <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 add filename</userinput></screen> <para>If you want to add a whole tree of files, run a command like:</para> @@ -723,7 +709,7 @@ <para>Removing a file is just as easy with the <command>p4</command> delete command like so:</para> - <screen>&prompt.user; <userinput>p4 delete <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 delete filename</userinput></screen> <para>This will mark the file for deletion from the depot the next time that a submit is run. It will also remove the local copy of @@ -739,7 +725,7 @@ admin access.</para> </sect1> -<sect1 id="working-with-diffs"> +<sect1 xml:id="working-with-diffs"> <title>Working with diffs</title> <para>Sometimes you might need to apply a diff from another source @@ -775,7 +761,7 @@ <para>and just do a <command>p4 submit</command> after that.</para> </sect1> -<sect1 id="renaming-files"> +<sect1 xml:id="renaming-files"> <title>Renaming files</title> <para><application>Perforce</application> does not have a built-in @@ -788,9 +774,9 @@ dealing with this is to do a one-time, in-tree integration, like so:</para> - <screen>&prompt.user; <userinput>p4 integrate -i <replaceable>oldfile</replaceable> <replaceable>newfile</replaceable></userinput> + <screen>&prompt.user; <userinput>p4 integrate -i oldfile newfile</userinput> &prompt.user; <userinput>p4 resolve</userinput> -&prompt.user; <userinput>p4 delete <replaceable>oldfile</replaceable></userinput> +&prompt.user; <userinput>p4 delete oldfile</userinput> &prompt.user; <userinput>p4 submit</userinput></screen> <para>The integration will force <application>Perforce</application> @@ -803,7 +789,7 @@ for normal branch-based integrations.</para> </sect1> -<sect1 id="freebsd-cvs-and-p4"> +<sect1 xml:id="freebsd-cvs-and-p4"> <title>Interactions between &os; Subversion and Perforce</title> <para>The &os; <application>Perforce</application> and <application>Subversion</application> @@ -811,8 +797,7 @@ tracked at near-real-time in <application>Perforce</application>. Every 2 minutes, the Subversion server is polled for updates in the HEAD branch, and those updates are committed to - <application>Perforce</application> in the <filename - class="directory">//depot/vendor/freebsd/...</filename> tree. This + <application>Perforce</application> in the <filename>//depot/vendor/freebsd/...</filename> tree. This tree is then available for branching and integrating to derivative projects. Any project that directly modifies that &os; source code should have this tree as its branch parent (or grandparent, @@ -831,7 +816,7 @@ something that you are interested in.</para> </sect1> -<sect1 id="offline-ops"> +<sect1 xml:id="offline-ops"> <title>Offline Operation</title> <para>One weakness of <application>Perforce</application> is that it @@ -853,7 +838,7 @@ so be extra vigilant with this.</para> </sect1> -<sect1 id="soc"> +<sect1 xml:id="soc"> <title>Notes for Google Summer of Code</title> <para>Most &os; projects under the Google Summer of Code program @@ -862,20 +847,16 @@ <itemizedlist> <listitem> - <para><filename - class="directory">//depot/projects/soc2005/<replaceable>project-name</replaceable>/...</filename></para> + <para><filename>//depot/projects/soc2005/project-name/...</filename></para> </listitem> <listitem> - <para><filename - class="directory">//depot/projects/soc2006/<replaceable>project-name</replaceable>/...</filename></para> + <para><filename>//depot/projects/soc2006/project-name/...</filename></para> </listitem> <listitem> - <para><filename - class="directory">//depot/projects/soc2007/<replaceable>project-name</replaceable>/...</filename></para> + <para><filename>//depot/projects/soc2007/project-name/...</filename></para> </listitem> <listitem> - <para><filename - class="directory">//depot/projects/soc2008/<replaceable>project-name</replaceable>/...</filename></para> + <para><filename>//depot/projects/soc2008/project-name/...</filename></para> </listitem> </itemizedlist> |