diff options
author | Gordon Tetlow <gordon@FreeBSD.org> | 2018-05-20 23:11:23 +0000 |
---|---|---|
committer | Gordon Tetlow <gordon@FreeBSD.org> | 2018-05-20 23:11:23 +0000 |
commit | 6fb81b7dfb611996a60b7d5c3933ee8fe7bf7ca5 (patch) | |
tree | 561ed7ecf99a64f78a3655bf7964137bd7d2a0a4 | |
parent | 0b7204ef6c17f6f19492f12a7bc52b1ed604b436 (diff) |
Notes
-rw-r--r-- | en_US.ISO8859-1/articles/Makefile | 1 | ||||
-rw-r--r-- | en_US.ISO8859-1/articles/committers-guide/article.xml | 6 | ||||
-rw-r--r-- | en_US.ISO8859-1/articles/p4-primer/Makefile | 19 | ||||
-rw-r--r-- | en_US.ISO8859-1/articles/p4-primer/article.xml | 910 | ||||
-rw-r--r-- | en_US.ISO8859-1/books/dev-model/book.xml | 20 | ||||
-rw-r--r-- | en_US.ISO8859-1/htdocs/administration.xml | 18 | ||||
-rw-r--r-- | en_US.ISO8859-1/htdocs/cgi/cgi-style.pl | 1 | ||||
-rw-r--r-- | en_US.ISO8859-1/htdocs/docs/books.xml | 6 | ||||
-rw-r--r-- | en_US.ISO8859-1/htdocs/internal/developer.xml | 2 | ||||
-rw-r--r-- | en_US.ISO8859-1/share/xml/teams.ent | 2 | ||||
-rw-r--r-- | share/xml/header.ent | 1 |
11 files changed, 4 insertions, 982 deletions
diff --git a/en_US.ISO8859-1/articles/Makefile b/en_US.ISO8859-1/articles/Makefile index 20c41e0aac..d0359cbc1c 100644 --- a/en_US.ISO8859-1/articles/Makefile +++ b/en_US.ISO8859-1/articles/Makefile @@ -24,7 +24,6 @@ SUBDIR+= linux-users SUBDIR+= mailing-list-faq SUBDIR+= nanobsd SUBDIR+= new-users -SUBDIR+= p4-primer SUBDIR+= pam SUBDIR+= pgpkeys SUBDIR+= port-mentor-guidelines diff --git a/en_US.ISO8859-1/articles/committers-guide/article.xml b/en_US.ISO8859-1/articles/committers-guide/article.xml index 28ae2ea898..ab7062c89d 100644 --- a/en_US.ISO8859-1/articles/committers-guide/article.xml +++ b/en_US.ISO8859-1/articles/committers-guide/article.xml @@ -658,8 +658,8 @@ You need a Passphrase to protect your secret key.</screen> <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 @@ You need a Passphrase to protect your secret key.</screen> <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 diff --git a/en_US.ISO8859-1/articles/p4-primer/Makefile b/en_US.ISO8859-1/articles/p4-primer/Makefile deleted file mode 100644 index 97d792df95..0000000000 --- a/en_US.ISO8859-1/articles/p4-primer/Makefile +++ /dev/null @@ -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" diff --git a/en_US.ISO8859-1/articles/p4-primer/article.xml b/en_US.ISO8859-1/articles/p4-primer/article.xml deleted file mode 100644 index 53e245bf0a..0000000000 --- a/en_US.ISO8859-1/articles/p4-primer/article.xml +++ /dev/null @@ -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: - <enter description here> - 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><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 - 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 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>\! -type 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> diff --git a/en_US.ISO8859-1/books/dev-model/book.xml b/en_US.ISO8859-1/books/dev-model/book.xml index e0cef1ae9f..722fb2ee92 100644 --- a/en_US.ISO8859-1/books/dev-model/book.xml +++ b/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> @@ -2101,24 +2101,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> <para> diff --git a/en_US.ISO8859-1/htdocs/administration.xml b/en_US.ISO8859-1/htdocs/administration.xml index 7e912e830a..63e5e5d747 100644 --- a/en_US.ISO8859-1/htdocs/administration.xml +++ b/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> @@ -449,22 +447,6 @@ <li>&a.kuriyama.email;</li> </ul> - <h3><a name="t-perforce-admin">Perforce Repository Administrators</a> - <<a href="mailto:perforce-admin@FreeBSD.org">perforce-admin@FreeBSD.org</a>></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 Administrators</a> <<a href="mailto:phabric-admin@FreeBSD.org" >phabric-admin@FreeBSD.org</a>></h3> diff --git a/en_US.ISO8859-1/htdocs/cgi/cgi-style.pl b/en_US.ISO8859-1/htdocs/cgi/cgi-style.pl index beb88240b9..917cd9244d 100644 --- a/en_US.ISO8859-1/htdocs/cgi/cgi-style.pl +++ b/en_US.ISO8859-1/htdocs/cgi/cgi-style.pl @@ -152,7 +152,6 @@ $i_topbar = qq` <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> diff --git a/en_US.ISO8859-1/htdocs/docs/books.xml b/en_US.ISO8859-1/htdocs/docs/books.xml index ccd5ce91a5..35b2f45be1 100644 --- a/en_US.ISO8859-1/htdocs/docs/books.xml +++ b/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> diff --git a/en_US.ISO8859-1/htdocs/internal/developer.xml b/en_US.ISO8859-1/htdocs/internal/developer.xml index 1b92f9c392..1a2426c8f6 100644 --- a/en_US.ISO8859-1/htdocs/internal/developer.xml +++ b/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> diff --git a/en_US.ISO8859-1/share/xml/teams.ent b/en_US.ISO8859-1/share/xml/teams.ent index 5dc9c67557..85aa9b9c8f 100644 --- a/en_US.ISO8859-1/share/xml/teams.ent +++ b/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>"> diff --git a/share/xml/header.ent b/share/xml/header.ent index 600a6c21ac..93c97b5fb5 100644 --- a/share/xml/header.ent +++ b/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> |