svn commit: r44950 - head/en_US.ISO8859-1/articles/p4-primer
Benedict Reuschling <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
Author: bcr
Date: Sun May 25 14:40:41 2014
New Revision: 44950
URL: http://svnweb.freebsd.org/changeset/doc/44950
Log:
Huge whitespace change to make igor happy.
Translators can ignore it.
Modified:
head/en_US.ISO8859-1/articles/p4-primer/article.xml
Modified: head/en_US.ISO8859-1/articles/p4-primer/article.xml
==============================================================================
--- head/en_US.ISO8859-1/articles/p4-primer/article.xml Sun May 25 13:39:55 2014 (r44949)
+++ head/en_US.ISO8859-1/articles/p4-primer/article.xml Sun May 25 14:40:41 2014 (r44950)
@@ -1,16 +1,25 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/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 xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:lang="en">
- <info><title>Perforce in &os; Development</title>
+ <info>
+ <title>Perforce in &os; Development</title>
<authorgroup>
- <author><personname><firstname>Scott</firstname><surname>Long</surname></personname><affiliation>
- <address><email>[email protected]</email>
- </address>
- </affiliation></author>
+ <author>
+ <personname>
+ <firstname>Scott</firstname>
+ <surname>Long</surname>
+ </personname>
+ <affiliation>
+ <address>
+ <email>[email protected]</email>
+ </address>
+ </affiliation>
+ </author>
</authorgroup>
<legalnotice xml:id="trademarks" role="trademarks">
@@ -23,446 +32,463 @@
<releaseinfo>$FreeBSD$</releaseinfo>
</info>
-<sect1 xml:id="intro">
- <title>Introduction</title>
+ <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 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 <package>devel/p4</package>
- port or can be downloaded from the <application>Perforce</application>
- 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
- command line application called <command>p4</command>. This
- document is written from the point of view of using this
- command.</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.
- The <application>p4</application> application also contains an
- extensive amount of online help accessible via <command>p4
- help</command>.</para>
-
- <para>The &os; <application>Perforce</application> server is
- hosted on <systemitem class="fqdomainname">perforce.freebsd.org</systemitem>,
- port <literal>1666</literal>. The repository is browsable
- online at <uri xlink:href="http://p4web.freebsd.org">http://p4web.freebsd.org</uri>.</para>
- </sect2>
-</sect1>
-
-<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 <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 <systemitem class="fqdomainname">FreeBSD.org</systemitem> account, you will need to
- coordinate with your sponsor.</para>
-
- <warning>
- <para>An email will be sent to your &os; address that contains
- the password you specified above in cleartext. Be sure to change
- the password once your <application>Perforce</application> account
- has been created!</para>
- </warning>
-
- <para>The next step is to set the environment variables that
- <command>p4</command> needs, and verify that it can connect to the
- server. The <envar>P4PORT</envar> variable is required to be set
- for all operations, and specifies the appropriate
- <application>Perforce</application> server to talk to. For the
- &os; project, set it like so:</para>
-
- <screen>&prompt.user; <userinput>export P4PORT=perforce.freebsd.org:1666</userinput></screen>
-
- <note>
- <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>
- </note>
-
- <para>The &os; server also requires that the <envar>P4USER</envar>
- and <envar>P4PASSWD</envar> variables be set. Use the username
- and password from above, like so:</para>
+ <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 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 <package>devel/p4</package> port or can be
+ downloaded from the <application>Perforce</application> 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
+ command line application called <command>p4</command>. This
+ document is written from the point of view of using this
+ command.</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. The <application>p4</application> application
+ also contains an extensive amount of online help accessible
+ via <command>p4 help</command>.</para>
+
+ <para>The &os; <application>Perforce</application> server is
+ hosted on <systemitem
+ class="fqdomainname">perforce.freebsd.org</systemitem>, port
+ <literal>1666</literal>. The repository is browsable online
+ at <uri
+ xlink:href="http://p4web.freebsd.org">http://p4web.freebsd.org</uri>.</para>
+ </sect2>
+ </sect1>
+
+ <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
+ <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 <systemitem
+ class="fqdomainname">FreeBSD.org</systemitem> account, you
+ will need to coordinate with your sponsor.</para>
+
+ <warning>
+ <para>An email will be sent to your &os; address that contains
+ the password you specified above in cleartext. Be sure to
+ change the password once your
+ <application>Perforce</application> account has been
+ created!</para>
+ </warning>
+
+ <para>The next step is to set the environment variables that
+ <command>p4</command> needs, and verify that it can connect to
+ the server. The <envar>P4PORT</envar> variable is required to
+ be set for all operations, and specifies the appropriate
+ <application>Perforce</application> server to talk to. For the
+ &os; project, set it like so:</para>
+
+ <screen>&prompt.user; <userinput>export P4PORT=perforce.freebsd.org:1666</userinput></screen>
+
+ <note>
+ <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>
+ </note>
+
+ <para>The &os; server also requires that the <envar>P4USER</envar>
+ 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>
+ <screen>&prompt.user; <userinput>export P4USER=<replaceable>username</replaceable></userinput>
&prompt.user; <userinput>export P4PASSWD=<replaceable>password</replaceable></userinput></screen>
- <para>Test that this works by running the following command:</para>
+ <para>Test that this works by running the following
+ command:</para>
- <screen>&prompt.user; <userinput>p4 info</userinput></screen>
+ <screen>&prompt.user; <userinput>p4 info</userinput></screen>
- <para>This should return a list of information about the server. If
- it does not, check that you have the <envar>P4PORT</envar>
- variable set correctly.</para>
-</sect1>
-
-<sect1 xml:id="clients">
- <title>Clients</title>
-
- <para><application>Perforce</application> provides access to the
- repository and tracks state on a per-client basis. In
- <application>Perforce</application> terms, a client is a
- specification that maps files and directories from the repository
- to the local machine. Each user can have multiple clients, and
- each client can access different or overlapping parts of the
- repository. The client also specifies the root directory of the
- file tree that it maps, and it specifies the machine that the tree
- lives on. Thus, working on multiple machines requires that
- multiple clients be used.</para>
-
- <para>Clients may be accessed via <command>p4 client</command>.
- Running this command with no arguments will bring up a client
- template in an editor, allowing you to create a new client
- for your work. The important fields in this template are
- explained below:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>Client:</literal></term>
+ <para>This should return a list of information about the server.
+ If it does not, check that you have the <envar>P4PORT</envar>
+ variable set correctly.</para>
+ </sect1>
+
+ <sect1 xml:id="clients">
+ <title>Clients</title>
+
+ <para><application>Perforce</application> provides access to the
+ repository and tracks state on a per-client basis. In
+ <application>Perforce</application> terms, a client is a
+ specification that maps files and directories from the
+ repository to the local machine. Each user can have multiple
+ clients, and each client can access different or overlapping
+ parts of the repository. The client also specifies the root
+ directory of the file tree that it maps, and it specifies the
+ machine that the tree lives on. Thus, working on multiple
+ machines requires that multiple clients be used.</para>
+
+ <para>Clients may be accessed via <command>p4 client</command>.
+ Running this command with no arguments will bring up a client
+ template in an editor, allowing you to create a new client for
+ your work. The important fields in this template are explained
+ below:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>Client:</literal></term>
+
+ <listitem>
+ <para>This is the name of the client spec. It can be
+ anything 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>,
+ which makes it easy to identify clients when browsing
+ them. A default name will be filled in that is just the
+ machine name.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Description:</literal></term>
+
+ <listitem>
+ <para>This can contain a simple text description to help
+ identify the client.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Root:</literal></term>
+
+ <listitem>
+ <para>This is the local directory that will serve as the
+ root directory of all the files in the client mapping.
+ This should be a unique location in your filesystem that
+ does not overlap with other files or
+ <application>Perforce</application> clients.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Options:</literal></term>
+
+ <listitem>
+ <para>Most of the default options are fine, though it is
+ usually a good idea to make sure that the
+ <option>compress</option> and <option>rmdir</option>
+ options are present and do not have a
+ <literal>no</literal> prefix on them. Details about each
+ option are in the <application>Perforce</application>
+ docs.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>LineEnd:</literal></term>
+
+ <listitem>
+ <para>This handles CR-LF conversions and should be left to
+ the default unless you have special needs for it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>View:</literal></term>
+
+ <listitem>
+ <para>This is where the server-to-local file mappings go.
+ The default is</para>
+
+ <programlisting>//depot/... //<replaceable>client</replaceable>/...</programlisting>
+
+ <para>This will map the entire
+ <application>Perforce</application> repository to the
+ <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>//depot/projects/smpng</filename>. A mapping
+ for this might look like:</para>
+
+ <programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/...</programlisting>
+
+ <para>The <literal>...</literal> should be taken literally.
+ It is a <application>Perforce</application> idiom for
+ saying <quote>this directory and all files and directories
+ below it.</quote></para>
+
+ <para>A Perforce <quote>view</quote> can contain multiple
+ mappings. Say you want to map in both the SMPng tree and
+ the NFS tree. Your View might look like:</para>
- <listitem>
- <para>This is the name of the client spec. It can be anything
- 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>,
- which makes it easy to identify clients when browsing them.
- A default name will be filled in that is just the machine
- name.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>Description:</literal></term>
-
- <listitem>
- <para>This can contain a simple text description to help
- identify the client.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>Root:</literal></term>
-
- <listitem>
- <para>This is the local directory that will serve as the root
- directory of all the files in the client mapping. This should
- be a unique location in your filesystem that does not overlap
- with other files or <application>Perforce</application>
- clients.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>Options:</literal></term>
-
- <listitem>
- <para>Most of the default options are fine, though it is
- usually a good idea to make sure that the
- <option>compress</option> and <option>rmdir</option> options
- are present and do not have a <literal>no</literal> prefix on
- them. Details about each option are in the
- <application>Perforce</application> docs.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>LineEnd:</literal></term>
-
- <listitem>
- <para>This handles CR-LF conversions and should be left to the
- default unless you have special needs for it.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>View:</literal></term>
-
- <listitem>
- <para>This is where the server-to-local file mappings go. The
- default is</para>
-
- <programlisting>//depot/... //<replaceable>client</replaceable>/...</programlisting>
-
- <para>This will map the entire
- <application>Perforce</application> repository to the
- <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>//depot/projects/smpng</filename>. A
- mapping for this might look like:</para>
-
- <programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/...</programlisting>
-
- <para>The <literal>...</literal> should be taken literally. It
- is a <application>Perforce</application> idiom for saying
- <quote>this directory and all files and directories below
- it.</quote></para>
-
- <para>A Perforce <quote>view</quote> can contain multiple
- mappings. Say you want to map in both the SMPng tree and
- the NFS tree. Your
- View might look like:</para>
-
- <programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/smpng/...
+ <programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/smpng/...
//depot/projects/nfs/... //<replaceable>client</replaceable>/nfs/...</programlisting>
- <para>Remember that the <replaceable>client</replaceable> is
- the name of the client that was specified in the
- <literal>Client</literal> section, but in the
- <literal>View</literal> it also resolves to the directory
- that was specified in the <literal>Root</literal>
- section.</para>
-
- <para>Also note that the same file or directory cannot be
- mapped multiple times in a single view. The following is
- illegal and will produce undefined results:</para>
+ <para>Remember that the <replaceable>client</replaceable> is
+ the name of the client that was specified in the
+ <literal>Client</literal> section, but in the
+ <literal>View</literal> it also resolves to the directory
+ that was specified in the <literal>Root</literal>
+ section.</para>
+
+ <para>Also note that the same file or directory cannot be
+ mapped multiple times in a single view. The following is
+ illegal and will produce undefined results:</para>
- <programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/smpng-foo/...
+ <programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/smpng-foo/...
//depot/projects/smpng/... //<replaceable>client</replaceable>/smpng-bar/...</programlisting>
- <para>Views are a tricky part of the learning experience with
- <application>Perforce</application>, so do not be afraid to
- ask questions.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Existing clients can be listed via <command>p4
- clients</command>. They can be viewed without being
- modified via <command>p4 client -o
- <replaceable>clientname</replaceable></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>
-
- <para>Note that client mappings in the repository are not exclusive;
- multiple clients can map in the same part of the repository. This
- allows multiple people to access and modify the same parts of the
- repository, allowing a team of people to work together on the same
- code.</para>
-</sect1>
-
-<sect1 xml:id="syncing">
- <title>Syncing</title>
-
- <para>Once you have a client specification defined and the
- <envar>P4CLIENT</envar> variable set, the next step is to pull the
- files for that client down to your local machine. This is done
- with <command>p4 sync</command>, which instructs
- <application>Perforce</application> to synchronize the local files
- in your client with the repository. The first time it runs, it
- will download all of the files. Subsequent runs will only
- download files that have changed since the previous run. This
- allows you to stay in sync with others whom you might be working
- with.</para>
-
- <para>Sync operations only work on files that the
- <application>Perforce</application> server knows has changed. If
- you change or delete a file locally without informing the server,
- doing a sync will not bring it back. However, doing a <command>p4
- sync -f</command> will unconditionally sync all files, regardless
- of their state. This is useful for resolving problems where you
- think that your tree might be corrupt.</para>
-
- <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>ufs</filename> directory of the
- <literal>smpng</literal> project, you might do the
- following:</para>
+ <para>Views are a tricky part of the learning experience
+ with <application>Perforce</application>, so do not be
+ afraid to ask questions.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Existing clients can be listed via <command>p4
+ clients</command>. They can be viewed without being modified
+ via <command>p4 client -o
+ <replaceable>clientname</replaceable></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>
+
+ <para>Note that client mappings in the repository are not
+ exclusive; multiple clients can map in the same part of the
+ repository. This allows multiple people to access and modify
+ the same parts of the repository, allowing a team of people to
+ work together on the same code.</para>
+ </sect1>
+
+ <sect1 xml:id="syncing">
+ <title>Syncing</title>
+
+ <para>Once you have a client specification defined and the
+ <envar>P4CLIENT</envar> variable set, the next step is to pull
+ the files for that client down to your local machine. This is
+ done with <command>p4 sync</command>, which instructs
+ <application>Perforce</application> to synchronize the local
+ files in your client with the repository. The first time it
+ runs, it will download all of the files. Subsequent runs will
+ only download files that have changed since the previous run.
+ This allows you to stay in sync with others whom you might be
+ working with.</para>
+
+ <para>Sync operations only work on files that the
+ <application>Perforce</application> server knows has changed.
+ If you change or delete a file locally without informing the
+ server, doing a sync will not bring it back. However, doing a
+ <command>p4 sync -f</command> will unconditionally sync all
+ files, regardless of their state. This is useful for resolving
+ problems where you think that your tree might be corrupt.</para>
+
+ <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>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 <replaceable>projectroot</replaceable>/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 xml:id="branches">
- <title>Branches</title>
-
- <para>One of the strongest features of
- <application>Perforce</application> is branching. Branches are
- very cheap to create, and moving changes between related branches
- is very easy (as will be explained later). Branches also allow
- you to do very experimental work in a sandbox-like environment,
- without having to worry about colliding with others or
- destabilizing the main tree. They also provide insulation against
- mistakes while learning the <application>Perforce</application>
- system. With all of these benefits, it makes sense for each
- project to have its own branch, and we strongly encourage that
- with &os;. Frequent submits of changes to the server are also
- encouraged.</para>
-
- <para>Similar to <application>Subversion</application>, the
- <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>//depot</filename> directory. When you create a
- branch, all you are doing is creating a new path under the
- <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
- child, but the files themselves live under their own paths.</para>
-
- <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>
-
- <para>The following important fields are explained:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>Branch</literal></term>
-
- <listitem>
- <para>The name of the branch. It can be any name, but must be
- unique within the repository. The common convention in &os;
- is to use
- <replaceable>username</replaceable>_<replaceable>projectname</replaceable>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>Description</literal></term>
-
- <listitem>
- <para>This can hold a simple text description to describe the
- branch.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>View</literal></term>
+ <para>Specifying a local relative path works for many other
+ <command>p4</command> commands.</para>
+ </sect1>
+
+ <sect1 xml:id="branches">
+ <title>Branches</title>
+
+ <para>One of the strongest features of
+ <application>Perforce</application> is branching. Branches are
+ very cheap to create, and moving changes between related
+ branches is very easy (as will be explained later). Branches
+ also allow you to do very experimental work in a sandbox-like
+ environment, without having to worry about colliding with others
+ or destabilizing the main tree. They also provide insulation
+ against mistakes while learning the
+ <application>Perforce</application> system. With all of these
+ benefits, it makes sense for each project to have its own
+ branch, and we strongly encourage that with &os;. Frequent
+ submits of changes to the server are also encouraged.</para>
+
+ <para>Similar to <application>Subversion</application>, the
+ <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>//depot</filename> directory. When you create a
+ branch, all you are doing is creating a new path under the
+ <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 child, but the files themselves live under their own
+ paths.</para>
+
+ <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>
+
+ <para>The following important fields are explained:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>Branch</literal></term>
+
+ <listitem>
+ <para>The name of the branch. It can be any name, but must
+ be unique within the repository. The common convention in
+ &os; is to use
+ <replaceable>username</replaceable>_<replaceable>projectname</replaceable>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Description</literal></term>
+
+ <listitem>
+ <para>This can hold a simple text description to describe
+ the branch.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>View</literal></term>
+
+ <listitem>
+ <para>This is the branch mapping. Instead of mapping from
+ the depot to the local machine like a client map, it maps
+ between the branch parent and branch child in the depot.
+ For example, you might want to create a branch of the
+ smpng project. The mapping might look like:</para>
+
+ <programlisting>//depot/projects/smpng/... //depot/projects/my-super-smpng/...</programlisting>
+
+ <para>Or, you might want to create a brand new branch off of
+ the stock &os; sources:</para>
+
+ <programlisting>//depot/vendor/freebsd/... //depot/projects/my-new-project/...</programlisting>
+
+ <para>This will map the &os; HEAD tree to your new
+ branch.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Creating the branch spec only saves the spec itself in the
+ server, it does not modify the depot or change any files. The
+ directory that you specified in the branch is empty on the
+ server until you populate it.</para>
+
+ <para>To populate your branch, first edit your client with
+ <command>p4 client</command> and make sure that the branch
+ directory is mapped in your client. You might need to add a
+ <literal>View</literal> line like:</para>
+
+ <programlisting>//depot/projects/my-new-project/... //<replaceable>myclient</replaceable>/my-new-project/...</programlisting>
+
+ <para>The next step is to run <command>p4 integrate</command>, as
+ described in the next section.</para>
+ </sect1>
+
+ <sect1 xml:id="Integrations">
+ <title>Integrations</title>
+
+ <para><quote>Integration</quote> is the term used by
+ <application>Perforce</application> to describe the action of
+ moving changes from one part of the depot to another. It is
+ most commonly done in conjunction with creating and maintaining
+ branches. An integration is done when you want to initially
+ populate a branch, and it is done when you want to move
+ subsequent changes in the branch from the parent to the child,
+ or from the child to the parent. A common example of this is
+ periodically integrating changes from the vendor &os; tree to
+ your child branch tree, allowing you to keep up to date with
+ changes in the &os; tree. The
+ <application>Perforce</application> server tracks the changes in
+ each tree and knows when there are changes that can be
+ integrated from one tree to another.</para>
+
+ <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>
+
+ <para><replaceable>branchname</replaceable> is the name given to a
+ branch spec, as discussed in the previous section. This command
+ will instruct <application>Perforce</application> to look for
+ changes in the branch parent that are not yet in the child.
+ From those changes it will prepare a list of diffs to move. If
+ the integration is being done for the first time on a branch
+ (for example doing an initial population operation), then the
+ parent files will simply be copied to the child location on the
+ local machine.</para>
+
+ <para>Once the integration operation is done, you must run
+ <command>p4 resolve</command> to accept the changes and resolve
+ possible conflicts. Conflicts can arise from overlapping
+ changes that happened in both the parent and child copy of a
+ file. Usually, however, there are no conflicts, and
+ <application>Perforce</application> can quickly figure out how
+ to merge the changes together. Use the following commands to do
+ a resolve operation:</para>
- <listitem>
- <para>This is the branch mapping. Instead of mapping from the
- depot to the local machine like a client map, it maps between
- the branch parent and branch child in the depot. For example,
- you might want to create a branch of the smpng project. The
- mapping might look like:</para>
-
- <programlisting>//depot/projects/smpng/... //depot/projects/my-super-smpng/...</programlisting>
-
- <para>Or, you might want to create a brand new branch off of
- the stock &os; sources:</para>
-
- <programlisting>//depot/vendor/freebsd/... //depot/projects/my-new-project/...</programlisting>
-
- <para>This will map the &os; HEAD tree to your new
- branch.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Creating the branch spec only saves the spec itself in the
- server, it does not modify the depot or change any files. The
- directory that you specified in the branch is empty on the server
- until you populate it.</para>
-
- <para>To populate your branch, first edit your client with
- <command>p4 client</command> and make sure that the branch
- directory is mapped in your client. You might need to add a
- <literal>View</literal> line like:</para>
-
- <programlisting>//depot/projects/my-new-project/... //<replaceable>myclient</replaceable>/my-new-project/...</programlisting>
-
- <para>The next step is to run <command>p4 integrate</command>, as
- described in the next section.</para>
-</sect1>
-
-<sect1 xml:id="Integrations">
- <title>Integrations</title>
-
- <para><quote>Integration</quote> is the term used by
- <application>Perforce</application> to describe the action of
- moving changes from one part of the depot to another. It is most
- commonly done in conjunction with creating and maintaining
- branches. An integration is done when you want to initially
- populate a branch, and it is done when you want to move subsequent
- changes in the branch from the parent to the child, or from the
- child to the parent. A common example of this is periodically
- integrating changes from the vendor &os; tree to your child branch
- tree, allowing you to keep up to date with changes in the &os;
- tree. The <application>Perforce</application> server tracks the
- changes in each tree and knows when there are changes that can be
- integrated from one tree to another.</para>
-
- <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>
-
- <para><replaceable>branchname</replaceable> is the name given to a
- branch spec, as discussed in the previous section. This command
- will instruct <application>Perforce</application> to look for
- changes in the branch parent that are not yet in the child. From
- those changes it will prepare a list of diffs to move. If the
- integration is being done for the first time on a branch (for example
- doing an initial population operation), then the parent files will
- simply be copied to the child location on the local
- machine.</para>
-
- <para>Once the integration operation is done, you must run
- <command>p4 resolve</command> to accept the changes and resolve
- possible conflicts. Conflicts can arise from overlapping changes
- that happened in both the parent and child copy of a file.
- Usually, however, there are no conflicts, and
- <application>Perforce</application> can quickly figure out how to
- merge the changes together. Use the following commands to do a
- resolve operation:</para>
-
- <screen>&prompt.user; <userinput>p4 resolve -as</userinput>
+ <screen>&prompt.user; <userinput>p4 resolve -as</userinput>
&prompt.user; <userinput>p4 resolve</userinput></screen>
- <para>The first invocation will instruct
- <application>Perforce</application> to automatically merge the
- changes together and accept files that have no conflicts. The
- second invocation will allow you to inspect each file that has a
- possible conflict and resolve it by hand if needed.</para>
-
- <para>Once all of the integrated files have been resolved, they need
- to be committed back to the repository. This is done via
- <command>p4 submit</command>, explained in the next
- section.</para>
-</sect1>
-
-<sect1 xml:id="submit">
- <title>Submit</title>
-
- <para>Changes that are made locally should be committed back to the
- <application>Perforce</application> server for safe keeping and so
- that others can access them. This is done via <command>p4
- submit</command>. When you run this command, it will open
- up a submit template in an editor. &os; has a custom template,
- and the important fields are described below:</para>
+ <para>The first invocation will instruct
+ <application>Perforce</application> to automatically merge the
+ changes together and accept files that have no conflicts. The
+ second invocation will allow you to inspect each file that has a
+ possible conflict and resolve it by hand if needed.</para>
+
+ <para>Once all of the integrated files have been resolved, they
+ need to be committed back to the repository. This is done via
+ <command>p4 submit</command>, explained in the next
+ section.</para>
+ </sect1>
+
+ <sect1 xml:id="submit">
+ <title>Submit</title>
+
+ <para>Changes that are made locally should be committed back to
+ the <application>Perforce</application> server for safe keeping
+ and so that others can access them. This is done via
+ <command>p4 submit</command>. When you run this command, it
+ will open up a submit template in an editor. &os; has a custom
+ template, and the important fields are described below:</para>
- <programlisting>Description:
+ <programlisting>Description:
<enter description here>
PR:
Submitted by:
@@ -471,394 +497,414 @@
Obtained from:
MFP4 after:</programlisting>
- <para>It is good practice to provide at least 2-3 sentences that
- describe what the changes are that you are submitting. You should
- say what the change does, why it was done that way or what
- problem is solves, and what APIs it might change or other side
- effects it might have. This text should replace the
- <literal><enter description here></literal> line in the template.
- You should wrap your lines and start each line with a TAB. The
- tags below it are &os;-specific and can be removed if not
- needed.</para>
-
- <programlisting>Files:</programlisting>
-
- <para>This is automatically populated with all of the files in your
- client that were marked in the add, delete, integrate, or edit
- states on the server. It is always a very good idea to review
- this list and remove files that might not be ready yet.</para>
-
- <para>Once you save the editor session, the submit will happen to
- the server. This also means that the local copies of the
- submitted files will be copied back to the server. If anything
- goes wrong during this process, the submit will be aborted, and
- you will be notified that the submit has been turned into a
- changelist that must be corrected and re-submitted. Submits are
- atomic, so if one file fails, the entire submit is aborted.</para>
-
- <para>Submits cannot be reverted, but they can be aborted while in
- the editor by exiting the editor without changing the
- <literal>Description</literal> text.
- <application>Perforce</application> will complain about this the
- first time you do it and will put you back in the editor. Exiting
- the editor the second time will abort the operation. Reverting a
- submitted change is very difficult and is best handled on a
- case-by-case basis.</para>
-</sect1>
-
-<sect1 xml:id="editing">
- <title>Editing</title>
-
- <para>The state of each file in the client is tracked and saved on
- the server. In order to avoid collisions from multiple people
- working on the same file at once,
- <application>Perforce</application> tracks which files are opened
- for edit, and uses this to help with submit, sync, and integration
- operations later on.</para>
-
- <para>To open a file for editing, use <command>p4 edit</command>
- like so:</para>
-
- <screen>&prompt.user; <userinput>p4 edit <replaceable>filename</replaceable></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
- marks it for special handling when doing an integration or sync
- operation. Note that editing is not exclusive in
- <application>Perforce</application>. Multiple people can have the
- same file in the edit state (you will be informed of others when
- you run <command>edit</command>), and you can submit
- your changes even when others are still editing the file.</para>
-
- <para>When someone else submits a change to a file that you are
- editing, you will need to resolve his changes with yours before
- your submit will succeed. The easiest way to do this is to either
- run a <command>p4 sync</command> or <command>p4 submit</command>
- and let it fail with the conflict, then run <command>p4
- resolve</command> to manually resolve and accept his changes into
- your copy, then run <command>p4 submit</command> to commit your
- changes to the repository.</para>
-
- <para>If you have a file open for edit and you want to throw away
- your changes and revert it to its original state, run
- <command>p4 revert</command> like so:</para>
-
- <screen>&prompt.user; <userinput>p4 revert <replaceable>filename</replaceable></userinput></screen>
-
- <para>This resyncs the file to the contents of the server, and
- removes the edit attribute from the server. Any local changes
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
_______________________________________________
[email protected] mailing list
http://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"