Date: Sun, 25 May 2014 14:40:41 +0000 (UTC) From: Benedict Reuschling <bcr@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44950 - head/en_US.ISO8859-1/articles/p4-primer Message-ID: <201405251440.s4PEefUE091335@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>scottl@FreeBSD.org</email> - </address> - </affiliation></author> + <author> + <personname> + <firstname>Scott</firstname> + <surname>Long</surname> + </personname> + <affiliation> + <address> + <email>scottl@FreeBSD.org</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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201405251440.s4PEefUE091335>