Page MenuHomeFreeBSD
Files F144848577

D15392.id42782.diff
No OneTemporary
Actions

D15392.id42782.diff
View Options

Index: head/en_US.ISO8859-1/articles/Makefile
===================================================================
--- head/en_US.ISO8859-1/articles/Makefile
+++ head/en_US.ISO8859-1/articles/Makefile
@@ -24,7 +24,6 @@
SUBDIR+= mailing-list-faq
SUBDIR+= nanobsd
SUBDIR+= new-users
-SUBDIR+= p4-primer
SUBDIR+= pam
SUBDIR+= pgpkeys
SUBDIR+= port-mentor-guidelines
Index: head/en_US.ISO8859-1/articles/committers-guide/article.xml
===================================================================
--- head/en_US.ISO8859-1/articles/committers-guide/article.xml
+++ head/en_US.ISO8859-1/articles/committers-guide/article.xml
@@ -658,8 +658,8 @@
<listitem>
<para><emphasis>/projects</emphasis> and
- <emphasis>/user</emphasis> feature a branch work area,
- like in Perforce. As above, the
+ <emphasis>/user</emphasis> feature a branch work area.
+ As above, the
<emphasis>/user</emphasis> directory does not contain
branches itself.</para>
</listitem>
@@ -868,7 +868,7 @@
<sect3 xml:id="svn-daily-use-editing-and-committing">
<title>Editing and Committing</title>
- <para>Unlike Perforce, <acronym>SVN</acronym> does not need to
+ <para><acronym>SVN</acronym> does not need to
be told in advance about file editing.</para>
<para>To commit all changes in
Index: head/en_US.ISO8859-1/articles/p4-primer/Makefile
===================================================================
--- head/en_US.ISO8859-1/articles/p4-primer/Makefile
+++ head/en_US.ISO8859-1/articles/p4-primer/Makefile
@@ -1,19 +0,0 @@
-#
-# $FreeBSD$
-#
-# Perforce in FreeBSD Development article.
-
-DOC?= article
-
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-SRCS= article.xml
-
-URL_RELPREFIX?= ../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
Index: head/en_US.ISO8859-1/articles/p4-primer/article.xml
===================================================================
--- head/en_US.ISO8859-1/articles/p4-primer/article.xml
+++ head/en_US.ISO8859-1/articles/p4-primer/article.xml
@@ -1,910 +0,0 @@
-<?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">
-
- <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>
- </authorgroup>
-
- <legalnotice xml:id="trademarks" role="trademarks">
- &tm-attrib.freebsd;
- &tm-attrib.general;
- </legalnotice>
-
- <pubdate>$FreeBSD$</pubdate>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
- </info>
-
- <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/downloads/helix#clients">http://www.perforce.com/downloads/helix#clients</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="https://www.perforce.com/perforce/doc.current/manuals/p4guide/index.html">https://www.perforce.com/perforce/doc.current/manuals/p4guide/index.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>
-&prompt.user; <userinput>export P4PASSWD=<replaceable>password</replaceable></userinput></screen>
-
- <para>Test that this works by running the following
- command:</para>
-
- <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>
-
- <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/...
- //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>
-
- <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>
-
- <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>
-
- <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>
-&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>
-
- <programlisting>Description:
- &lt;enter description here&gt;
- PR:
- Submitted by:
- Reviewed by:
- Approved by:
- 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>&lt;enter description here&gt;</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
- that you had will be lost. This is quite useful when you have a
- made changes to a file but later decide that you do not want to
- keep them.</para>
-
- <para>When a file is synced, it is marked read-only in the
- filesystem. When you tell the server to open it for editing, it
- is changed to read-write on the filesystem. While these
- permissions can easily be overridden by hand, they are meant to
- gently remind you that you should being using <command>p4
- edit</command>. Files that have local changes but are not in
- the edit state may get overwritten when doing a <command>p4
- sync</command>.</para>
- </sect1>
-
- <sect1 xml:id="changes">
- <title>Changes, Descriptions, and History</title>
-
- <para>Changes to the <application>Perforce</application> depot can
- be listed via <command>p4 changes</command>. This 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 <command>p4 describe
- <replaceable>changenumber</replaceable></command>. This will
- provide the submit log and the diffs of the actual
- change.</para>
-
- <para>Commonly, <command>p4&nbsp;describe</command> is used in one
- of three ways:</para>
-
- <variablelist>
- <varlistentry>
- <term><command>p4 describe -s
- <replaceable>CHANGE</replaceable></command></term>
-
- <listitem>
- <para>List a short description of changeset
- <emphasis>CHANGE</emphasis>, including the commit log of
- the particular changeset and a list of the files it
- affected.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>p4 describe -du
- <replaceable>CHANGE</replaceable></command></term>
-
- <listitem>
- <para>List a description of changeset
- <emphasis>CHANGE</emphasis>, including the commit log of
- the particular changeset, a list of the files it affected
- and a patch for each modified file, in a format similar to
- <quote>unified diff</quote> patches (but not exactly the
- same).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>p4 describe -dc
- <replaceable>CHANGE</replaceable></command></term>
-
- <listitem>
- <para>List a description of changeset
- <emphasis>CHANGE</emphasis>, including the commit log of
- the particular changeset, a list of the files it affected
- and a patch for each modified file, in a format similar to
- <quote>context diff</quote> patches (but not exactly the
- same).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The history of a file, including all submits, integrations,
- and branches of it will be shown by <command>p4 filelog
- <replaceable>filename</replaceable></command>.</para>
- </sect1>
-
- <sect1 xml:id="diffs">
- <title>Diffs</title>
-
- <para>There are two methods of producing file diffs in
- <application>Perforce</application>, either against local
- changes that have not been submitted yet, or between two trees
- (or within a branch) in the depot. These are done with
- different commands, <option>diff</option> and
- <option>diff2</option>:</para>
-
- <variablelist>
- <varlistentry>
- <term><command>p4 diff</command></term>
-
- <listitem>
- <para>This generates a diff of the local changes to files in
- the edit state. The <option>-du</option> and
- <option>-dc</option> flags can be used to create unified
- or context diffs, respectively, or the
- <envar>P4DIFF</envar> environment variable can be set to a
- local diff command to be used instead. It is a very good
- idea to use this command to review your changes before
- submitting them.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>p4 diff2</command></term>
-
- <listitem>
- <para>This creates a diff between arbitrary files in the
- depot, or between files specified in a branch spec. The
- diff operation takes place on the server, so
- <envar>P4DIFF</envar> variable has no effect, though the
- <option>-du</option> and <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>
-
- <para>and</para>
-
- <screen>&prompt.user; <userinput>p4 diff2 //depot/<replaceable>path1</replaceable> //depot/<replaceable>path2</replaceable></userinput></screen>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>In all cases the diff will be written to the standard
- output. Unfortunately, <application>Perforce</application>
- produces a diff format that is slightly incompatible with the
- traditional Unix diff and patch tools. Using the
- <envar>P4DIFF</envar> variable to point to the real &man.diff.1;
- tool can help this, but only for <command>p4 diff</command>.
- The output of <option>diff2</option> command must be
- post-processed to be useful (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:
- <uri
- xlink:href="https://svnweb.freebsd.org/base/head/tools/tools/perforce/awkdiff?view=co">https://svnweb.freebsd.org/base/head/tools/tools/perforce/awkdiff?view=co</uri>.</para>
- </sect1>
-
- <sect1 xml:id="add-rm-files">
- <title>Adding and Removing Files</title>
-
- <para>Integrating a branch will bring existing files into your
- tree, but you may still want to add new files or remove existing
- ones. Adding files is easily done be creating the file and then
- running <command>p4 add</command> like so:</para>
-
- <screen>&prompt.user; <userinput>p4 add <replaceable>filename</replaceable></userinput></screen>
-
- <para>If you want to add a whole tree of files, run a command
- like:</para>
-
- <screen>&prompt.user; <userinput>find . -type f | xargs p4 add</userinput></screen>
-
- <note>
- <para><application>Perforce</application> can track UNIX
- symlinks too, so you can probably use
- <quote><command>\!&nbsp;-type&nbsp;d</command></quote> as the
- matching expression in &man.find.1; above. We do not commit
- symlinks into the source tree of &os; though, so this should
- not be necessary.</para>
- </note>
-
- <para>Doing a <command>p4 submit</command> will then copy the file
- to the depot on the server. It is very important to only add
- files, not directories. Explicitly adding a directory will
- cause <application>Perforce</application> to treat it like a
- file, which is not what you want.</para>
-
- <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>
-
- <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 the file, so beware.</para>
-
- <para>Of course, deleting a file does not actually remove it from
- the repository.</para>
-
- <para>Deleted files can be resurrected by syncing them to a prior
- version. The only way to permanently remove a file is to use
- <command>p4 obliterate</command>. This command is irreversible
- and expensive, so it is only available to those with admin
- access.</para>
- </sect1>
-
- <sect1 xml:id="working-with-diffs">
- <title>Working with Diffs</title>
-
- <para>Sometimes you might need to apply a diff from another source
- to a tree under <application>Perforce</application> control. If
- it is a large diff that affects lots of files, it might be
- inconvenient to manually run <command>p4 edit</command> on each
- file. There is a trick for making this easier. First, make
- sure that no files are open on your client and that your tree is
- synced and up to date. Then apply the diff using the normal
- tools, and coerce the permissions on the files if needed. Then
- run the following commands:</para>
-
- <screen>&prompt.user; <userinput>p4 diff -se ... | xargs p4 edit</userinput>
-&prompt.user; <userinput>p4 diff -sd ... | xargs p4 delete</userinput>
-&prompt.user; <userinput>find . -type f | xargs p4 add</userinput></screen>
-
- <para>The first command tells <application>Perforce</application>
- to look for files that have changed, even if they are not open.
- The second command tells <application>Perforce</application> to
- look for files that no longer exist on the local machine but do
- exist on the server. The third command then attempts to add all
- of the files that it can find locally. This is a very
- brute-force method, but it works because
- <application>Perforce</application> will only add the files that
- it does not already know about. The result of running these
- commands will be a set of files that are opened for edit,
- removal, or add, as appropriate.</para>
-
- <para>Verify the active changelist with:</para>
-
- <screen>&prompt.user; <userinput>p4 changelist</userinput>
-&prompt.user; <userinput>p4 diff -du</userinput></screen>
-
- <para>and just do a <command>p4 submit</command> after
- that.</para>
- </sect1>
-
- <sect1 xml:id="renaming-files">
- <title>Renaming Files</title>
-
- <para><application>Perforce</application> does not have a built-in
- way of renaming files or moving them to a different part of the
- tree. Simply copying a file to the new location, doing a
- <command>p4 add</command> on it, and a <command>p4
- delete</command> on the old copy, works, but does not preserve
- change history of the file. This can make future integrations
- with parents and children very bumpy, in fact. A better method
- of 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>
-&prompt.user; <userinput>p4 resolve</userinput>
-&prompt.user; <userinput>p4 delete <replaceable>oldfile</replaceable></userinput>
-&prompt.user; <userinput>p4 submit</userinput></screen>
-
- <para>The integration will force
- <application>Perforce</application> to keep a record of the
- relationship between the old and new names, which will assist it
- in future integrations. The <option>-i</option> flag tells it
- that it is a <quote>baseless</quote> integration, meaning that
- there is no branch history available for it to use in the
- integration. That is perfect for an integration like this, but
- should not be used for normal branch-based integrations.</para>
- </sect1>
-
- <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> repositories are
- completely separate. However, changes to Subversion are 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>//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,
- depending on the needs), and periodic integrations and syncs
- should be done so that your tree stays up to date and avoids
- conflicts with mainline development.</para>
-
- <para>The bridge between Subversion and
- <application>Perforce</application> is one-way; changes to
- Subversion will be reflected in
- <application>Perforce</application>, but changes in Perforce
- will not be reflected in Subversion.</para>
- </sect1>
-
- <sect1 xml:id="offline-ops">
- <title>Offline Operation</title>
-
- <para>One weakness of <application>Perforce</application> is that
- it assumes that network access to the server is always
- available. Most state, history, and metadata is saved on the
- server, and there is no provision for replicating the server
- like there is with SVN. It is possible to run a proxy server,
- but it only provides very limited utility for offline
- operation.</para>
-
- <para>The best way to work offline is to make sure that your
- client has no open files and is fully synced before going
- offline. Then when editing a file, manually change the
- permissions to read-write. When you get back online, run the
- commands listed in the <xref linkend="working-with-diffs"/> to
- automatically identify files that have been edited, added, and
- removed. It is quite common to be surprised by
- <application>Perforce</application> overwriting a locally
- changed file that was not opened for edit, so be extra vigilant
- with this.</para>
- </sect1>
-
- <sect1 xml:id="soc">
- <title>Notes for Google Summer of Code</title>
-
- <para>Most &os; projects under the Google Summer of Code program
- are located on the &os; <application>Perforce</application>
- server under one of the following locations:</para>
-
- <itemizedlist>
- <listitem>
- <para><filename>//depot/projects/soc2005/<replaceable>project-name</replaceable>/...</filename></para>
- </listitem>
- <listitem>
- <para><filename>//depot/projects/soc2006/<replaceable>project-name</replaceable>/...</filename></para>
- </listitem>
- <listitem>
- <para><filename>//depot/projects/soc2007/<replaceable>project-name</replaceable>/...</filename></para>
- </listitem>
- <listitem>
- <para><filename>//depot/projects/soc2008/<replaceable>project-name</replaceable>/...</filename></para>
- </listitem>
- </itemizedlist>
-
- <para>The project mentor is responsible for choosing a suitable
- project name and getting the student going with
- <application>Perforce</application>.</para>
-
- <para>Access to the &os; <application>Perforce</application>
- server does not imply access to subversion, though we happily
- encourage all students to consider
- joining the project when the time is appropriate.</para>
- </sect1>
-</article>
Index: head/en_US.ISO8859-1/books/dev-model/book.xml
===================================================================
--- head/en_US.ISO8859-1/books/dev-model/book.xml
+++ head/en_US.ISO8859-1/books/dev-model/book.xml
@@ -2054,7 +2054,7 @@
<para>
The major support tools for supporting the development process are
- Perforce, Bugzilla, Mailman, and OpenSSH. These are externally
+ Bugzilla, Mailman, and OpenSSH. These are externally
developed tools and are commonly used in the open source world.
</para>
@@ -2100,24 +2100,6 @@
</para>
</section>
-
- <section xml:id="tool-perforce" xreflabel="Perforce">
- <title>Perforce</title>
- <para>
- Perforce is a commercial software configuration management
- system developed by Perforce
- Systems that is available on over 50 operating systems. It
- is a collection of clients built around the Perforce server
- that contains the central file repository and
- tracks the operations done upon it. The clients are both
- clients for accessing the repository and administration of
- its configuration.
-
- <!-- REF: http://www.perforce.com/perforce/products.html -->
-
- </para>
- </section>
-
<section xml:id="tool-pgp" xreflabel="PGP">
<title>Pretty Good Privacy</title>
Index: head/en_US.ISO8859-1/htdocs/administration.xml
===================================================================
--- head/en_US.ISO8859-1/htdocs/administration.xml
+++ head/en_US.ISO8859-1/htdocs/administration.xml
@@ -69,8 +69,6 @@
Testing Administrators</a></li>
<li><a href="#t-mirror-admin">FTP/WWW Mirror Site
Coordinators</a></li>
- <li><a href="#t-perforce-admin">Perforce Repository
- Administrators</a></li>
<li><a href="#t-phabric-admin">Phabricator Code Review
Administration</a></li>
<li><a href="#t-postmaster">Postmaster Team</a></li>
@@ -447,22 +445,6 @@
<ul>
<li>&a.kuriyama.email;</li>
- </ul>
-
- <h3><a name="t-perforce-admin">Perforce Repository Administrators</a>
- &lt;<a href="mailto:perforce-admin@FreeBSD.org">perforce-admin@FreeBSD.org</a>&gt;</h3>
-
- <p>The Perforce Repository Administrators are responsible for
- administrating the FreeBSD perforce source repository and setting up new
- perforce accounts. All requests concerning new perforce accounts
- for non-committers should be directed to the perforce
- administrators.</p>
-
- <ul>
- <li>&a.gibbs.email;</li>
- <li>&a.gordon.email;</li>
- <li>&a.rwatson.email;</li>
- <li>&a.peter.email;</li>
</ul>
<h3><a name="t-phabric-admin">Phabricator Code Review Application
Index: head/en_US.ISO8859-1/htdocs/cgi/cgi-style.pl
===================================================================
--- head/en_US.ISO8859-1/htdocs/cgi/cgi-style.pl
+++ head/en_US.ISO8859-1/htdocs/cgi/cgi-style.pl
@@ -152,7 +152,6 @@
<ul>
<li><a href="$hsty_base/projects/ideas/ideas.html">Project Ideas</a></li>
<li><a href="//svnweb.FreeBSD.org">SVN Repository</a></li>
- <li><a href="//p4web.FreeBSD.org">Perforce Repository</a></li>
</ul>
</li>
</ul>
Index: head/en_US.ISO8859-1/htdocs/docs/books.xml
===================================================================
--- head/en_US.ISO8859-1/htdocs/docs/books.xml
+++ head/en_US.ISO8859-1/htdocs/docs/books.xml
@@ -199,12 +199,6 @@
Steps</a> (new-users)<br/>
For people coming to FreeBSD and &unix; for the first time.</p>
- <p><a href="&url.articles;/p4-primer/index.html">Perforce in
- FreeBSD Development</a> (p4-primer)<br/>
- A guide to the Perforce version control system. It also
- describes how to manage experimental projects with the FreeBSD
- Perforce server.</p>
-
<p><a href="&url.articles;/pam/index.html">Pluggable
Authentication Modules</a> (pam)<br/>
A guide to the PAM system and modules under FreeBSD.</p>
Index: head/en_US.ISO8859-1/htdocs/internal/developer.xml
===================================================================
--- head/en_US.ISO8859-1/htdocs/internal/developer.xml
+++ head/en_US.ISO8859-1/htdocs/internal/developer.xml
@@ -79,8 +79,6 @@
<li><a
href="../copyright/copyright.html">Copyright</a></li>
<li><a href="http://wiki.FreeBSD.org">&os; Wiki</a></li>
- <li><a href="http://perforce.FreeBSD.org">Perforce Repository
- for works in progress</a></li>
</ul>
<p><a href="internal.html">&os; Internal Home</a></p>
Index: head/en_US.ISO8859-1/share/xml/teams.ent
===================================================================
--- head/en_US.ISO8859-1/share/xml/teams.ent
+++ head/en_US.ISO8859-1/share/xml/teams.ent
@@ -37,8 +37,6 @@
<!ENTITY a.ncvs "CVS src Repository Meisters <email xmlns='http://docbook.org/ns/docbook'>ncvs@FreeBSD.org</email>">
-<!ENTITY a.perforce-admin "Perforce Repository Meisters <email xmlns='http://docbook.org/ns/docbook'>perforce-admin@FreeBSD.org</email>">
-
<!ENTITY a.pcvs "CVS ports Repository Meisters <email xmlns='http://docbook.org/ns/docbook'>pcvs@FreeBSD.org</email>">
<!ENTITY a.portmgr "Ports Management Team <email xmlns='http://docbook.org/ns/docbook'>portmgr@FreeBSD.org</email>">
Index: head/share/xml/header.ent
===================================================================
--- head/share/xml/header.ent
+++ head/share/xml/header.ent
@@ -137,7 +137,6 @@
<li><a href="https://wiki.FreeBSD.org/IdeasPage">Project Ideas</a></li>
<li><a href="https://svnweb.FreeBSD.org">SVN Repository</a></li>
<li><a href="https://github.com/freebsd">GIT Repository</a></li>
- <li><a href="http://p4web.FreeBSD.org">Perforce Repository</a></li>
</ul>
</li>
</ul>

File Metadata

Mime Type
text/plain
Expires
Sat, Feb 14, 9:40 AM (4 h, 22 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
28694919
Default Alt Text
D15392.id42782.diff (47 KB)

Event Timeline