From owner-p4-projects@FreeBSD.ORG Sun Feb 19 12:17:44 2012 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id A356C1065673; Sun, 19 Feb 2012 12:17:44 +0000 (UTC) Delivered-To: perforce@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 650451065670 for ; Sun, 19 Feb 2012 12:17:44 +0000 (UTC) (envelope-from rene@FreeBSD.org) Received: from skunkworks.freebsd.org (skunkworks.freebsd.org [IPv6:2001:4f8:fff6::2d]) by mx1.freebsd.org (Postfix) with ESMTP id 50D148FC17 for ; Sun, 19 Feb 2012 12:17:44 +0000 (UTC) Received: from skunkworks.freebsd.org (localhost [127.0.0.1]) by skunkworks.freebsd.org (8.14.4/8.14.4) with ESMTP id q1JCHiHM031904 for ; Sun, 19 Feb 2012 12:17:44 GMT (envelope-from rene@FreeBSD.org) Received: (from perforce@localhost) by skunkworks.freebsd.org (8.14.4/8.14.4/Submit) id q1JCHhK2031901 for perforce@freebsd.org; Sun, 19 Feb 2012 12:17:43 GMT (envelope-from rene@FreeBSD.org) Date: Sun, 19 Feb 2012 12:17:43 GMT Message-Id: <201202191217.q1JCHhK2031901@skunkworks.freebsd.org> X-Authentication-Warning: skunkworks.freebsd.org: perforce set sender to rene@FreeBSD.org using -f From: Rene Ladan To: Perforce Change Reviews Precedence: bulk Cc: Subject: PERFORCE change 206534 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 19 Feb 2012 12:17:44 -0000 http://p4web.freebsd.org/@@206534?ac=10 Change 206534 by rene@rene_acer on 2012/02/19 12:17:32 IFC Affected files ... .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/committers-guide/article.sgml#48 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml#126 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml#76 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.develalumni.sgml#11 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/explaining-bsd/article.sgml#6 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/developers-handbook/testing/chapter.sgml#3 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/faq/book.sgml#42 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml#2 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml#3 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/audit/chapter.sgml#5 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/basics/chapter.sgml#9 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.sgml#13 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/config/chapter.sgml#20 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml#32 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml#34 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/disks/chapter.sgml#25 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml#31 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml#11 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/firewalls/chapter.sgml#18 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/install/chapter.sgml#27 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/jails/chapter.sgml#10 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml#17 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml#13 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml#13 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/mac/chapter.sgml#11 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/mail/chapter.sgml#10 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml#42 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/ports/chapter.sgml#15 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/security/chapter.sgml#22 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml#14 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/users/chapter.sgml#3 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/virtualization/chapter.sgml#13 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/x11/chapter.sgml#23 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/porters-handbook/book.sgml#130 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/share/sgml/authors.ent#69 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/book.sgml#23 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/boot/chapter.sgml#16 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/config/chapter.sgml#36 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/desktop/chapter.sgml#56 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/disks/chapter.sgml#35 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/geom/chapter.sgml#21 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/install/chapter.sgml#36 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/kernelconfig/chapter.sgml#29 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/linuxemu/chapter.sgml#21 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/mac/chapter.sgml#19 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/mail/chapter.sgml#19 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/printing/chapter.sgml#13 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/security/chapter.sgml#33 integrate .. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/x11/chapter.sgml#42 integrate .. //depot/projects/docproj_nl/www/en/developers.sgml#70 integrate .. //depot/projects/docproj_nl/www/en/releases/8.3R/schedule.sgml#2 integrate .. //depot/projects/docproj_nl/www/en/releng/index.sgml#49 integrate .. //depot/projects/docproj_nl/www/share/sgml/commercial.isp.xml#28 integrate .. //depot/projects/docproj_nl/www/share/sgml/commercial.software.xml#14 integrate .. //depot/projects/docproj_nl/www/share/sgml/news.xml#131 integrate .. //depot/projects/docproj_nl/www/share/sgml/usergroups.xml#30 integrate Differences ... ==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/committers-guide/article.sgml#48 (text+ko) ==== @@ -9,7 +9,7 @@ The &os; Documentation Project - $FreeBSD: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v 1.309 2012/01/14 11:48:00 crees Exp $ + $FreeBSD: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v 1.310 2012/02/17 22:34:05 gjb Exp $ 1999 @@ -1049,6 +1049,1313 @@ + + Subversion Primer + + + Introduction + + The &os; source repository switched from + CVS to Subversion on May 31st, 2008. The + first real SVN commit is + r179447. + + There are mechanisms in place to automatically merge + changes back from the Subversion repository to the + CVS one, so regular users should not notice + a difference, however developers most certainly will. + + Subversion is not that different from + CVS when it comes to daily use, but there + are differences. Subversion has a number of features that + should make developers' lives easier. The most important + advantage to Subversion (and the reason why &os; switched) is + that it handles branches and merging much better than CVS + does. Some of the principal differences are: + + + + Commits are atomic. + + + Revision numbers apply across the repository—all + files that were modified in the same commit have the same + revision number. + + + Branching and tagging are namespace operations. + + + Directories are versioned. + + + Files and directories can have arbitrary, versioned + metadata attached to them. + + + Files and directories can be copied, with full history + tracking. + + + No more contortions due to CVS + weakness such as applying &man.patch.1; files at compile + time in order to avoid touching vendor branch code. + + + No more repo-copies. + + + + Subversion can be installed from the &os; Ports + Collection, by issuing the following commands: + + &prompt.root; cd /usr/ports/devel/subversion +&prompt.root; make clean install + + + + Getting Started + + There are three ways to obtain a working copy of the tree + from Subversion. This section will explain them. + + + Direct Checkout + + The first is to check out directly from the main + repository: + + &prompt.user; svn checkout svn+ssh://svn.freebsd.org/base/head /usr/src + + The above command will check out a + CURRENT source tree as /usr/src/, + which can be any target directory on the local filesystem. + Omitting the final argument of that command causes the + working copy, in this case, to be named head, + but that can be renamed safely. + + svn+ssh means the + SVN protocol tunnelled over + SSH. The name of the server is + svn.freebsd.org, base + is the path to the repository, and head + is the subdirectory within the repository. + + If your &os; login name is different from your login + name on your local machine, you must either include it in + the URL (for example + svn+ssh://jarjar@svn.freebsd.org/base/head), + or add an entry to your ~/.ssh/config + in the form: + + Host svn.freebsd.org + User jarjar + + This is the simplest method, but it's hard to tell just + yet how much load it will place on the repository. + Subversion is much faster than CVS, + however. + + + The svn diff does not require + access to the server as SVN stores a + reference copy of every file in the working copy. This, + however, means that Subversion working copies are very + large in size. + + + + + Checkout from a Mirror + + You can check out a working copy from a mirror by simply + substituting the mirror's URL for + svn+ssh://svn.freebsd.org/base. This can + be an official mirror or a mirror you maintain yourself + using svnsync or similar. + + There is a serious disadvantage to this method: every + time something is to be committed, a svn switch + --relocate to the master repository has to be + done, remembering to svn switch back to + the mirror after the commit. Also, since svn + switch only works between repositories that have + the same UUID, some hacking of the local repository's UUID + has to occur before it is possible to start using it. + + Unlike with CVS and + csup, the hassle of a local + svnsync mirror probably is not worth it + unless the network connectivity situation or other factors + demand it. If it is needed, see the end of this chapter for + information on how to set one up. + + + + Checkout from a Local Mirror Using + <acronym>SVK</acronym> + + The third alternative is to use SVK + to maintain a local mirror. It is a version control system + build on top of Subversion's storage engine. It is + identical to Subversion in most respects, except that it + allows for setting up parts of repositories as mirrors of + other repositories, and keeping local branches for merging + back into the upstream repositories. There are extensions + that allow SVK to mirror + CVS and Perforce repositories in addition + to Subversion ones. + + Like everything, SVK has its + disadvantages, one being that local revision numbers will + not match upstream revision numbers. This makes it + difficult to svk log, svk + diff, or svk update to an + arbitrary upstream revision. + + To set up a mirror of the &os; repository, do: + + &prompt.user; svk mirror svn+ssh://svn.freebsd.org/base //freebsd/base + + The local SVK repository will be + stored in ~/.svk/local/, but can be + moved to whereever suits. If it is moved, + ~/.svk/config should be amended + manually to reflect the move. + + Any path can be used, not just the one in the example + above. A common pattern is to place mirrors under + //mirror, e.g. + //mirror/freebsd/base/, and + local branches under //local. + + To pull down the contents of the repository to the + mirror: + + &prompt.user; svk sync //freebsd/base + + + svk sync will take a very long + time, possibly several days over a slow network + connection. &a.peter; has a tarball that can be used to + jumpstart the mirror, but only if one does not exist + already. + + + To use &a.peter;'s tarball mentioned in the note + above: + + &prompt.user; cd ~ +&prompt.user; scp freefall:/home/peter/dot_svk_r179646.tbz2 . +&prompt.user; tar xf dot_svk_r179646.tbz2 + + Then edit ~/.svk/config and replace + /scratch/tmp/peter/.svk/local/ + with the equivalent of /home/jarjar/.svk/local/. + + You can check out files directly from your mirror, once + it has been created: + + &prompt.user; svk checkout //freebsd/base/head /usr/src + + Unlike SVN, SVK + does not store metadata or reference copies in the working + copy. All metadata is recorded in + ~/.svk/config; reference copies are not + used at all because SVK always operates + on a local repository. + + When committing from a working copy like the one above, + SVN will commit directly to the upstream + repository, then syncronise the mirror. + + However, the killer app for + SVK is the ability to work without a + network connection. To do that, a local branch must be set + up: + + &prompt.user; svk mkdir //local/freebsd +&prompt.user; svk copy //freebsd/base/head //local/freebsd/head + + Once again, any path can be used, it does not have to + specifically be the one in the example. + + Before use, the local branch has to be synchronised, + like so: + + &prompt.user; svk pull //local/freebsd/head + + Then check out from the newly created local + branch: + + &prompt.user; svk checkout //local/freebsd/head /usr/src + + The point of this exercise is showing that it is + possible to commit work-in-progress to a local branch, and + only push it to the upstream repository when work is + complete. The easy way to push is with svk + push, but there is a serious disadvantage to it: + it will push every single commit made to the local branch + incrementally instead of lumping them all into a single + commit. Therefore, using svk smerge is + preferable. + + + + <literal>RELENG_*</literal> Branches and General + Layout + + In svn+ssh://svn.freebsd.org/base, + base refers to the source tree. + Similarly, ports refers to the ports + tree, and so on. These are separate repositories with their + own change number sequences, access controls and commit + mail. + + For the base repository, HEAD refers to the -CURRENT + tree. For example, head/bin/ls is what + would go into /usr/src/bin/ls in a + release. Some other key locations are: + + + + /stable/n + which corresponds to + RELENG_n. + + + /releng/n.n + which corresponds to + RELENG_n_n. + + + /release/n.n.n + which corresponds to + RELENG_n_n_n_RELEASE. + + + /vendor* is the vendor branch + import work area. This directory itself does not + contain branches, however its subdirectories do. This + contrasts with the stable, + releng and + release directories. + + + /projects and + /user feature a branch work area, + like in Perforce. As above, the + /user directory does not contain + branches itself. + + + + + + + Daily Use + + This section will explain how to perform common day-to-day + operations with Subversion. There should be no difference + between SVN and SVK in + daily use, except for the revision renumbering mentioned + earlier. + + + SVN and SVK + commands that have direct CVS equivalents + usually have the same name and abbreviations. For example: + checkout and co, + update and up, and + commit and + ci. + + + + Help + + Both SVN and SVK + have built in help documentation. It can be accessed by + typing the following command: + + &prompt.user; svn help + + + + Checkout + + As seen earlier, to check out the &os; head + branch: + + &prompt.user; svn checkout svn+ssh://svn.freebsd.org/base/head /usr/src + + At some point, more than just HEAD + will probably be useful, for instance when merging changes + to stable/7. Therefore, it may be useful to have a partial + checkout of the complete tree (a full checkout would be very + painful). + + To do this, first check out the root of the + repository: + + &prompt.user; svn checkout --depth=immediates svn+ssh://svn.freebsd.org/base + + This will give base with all the + files it contains (at the time of writing, just + ROADMAP.txt) and empty subdirectories + for head, stable, + vendor and so on. + + Expanding the working copy is possible. Just change the + depth of the various subdirectories: + + &prompt.user; svn up --set-depth=infinity base/head +&prompt.user; svn up --set-depth=immediates base/release base/releng base/stable + + The above command will pull down a full copy of + head, plus empty copies of every + release tag, every + releng branch, and every + stable branch. + + If at a later date merging to + 7-STABLE is required, expand the working + copy: + + &prompt.user; svn up --set-depth=infinity base/stable/7 + + Subtrees do not have to be expanded completely. For + instance, expanding only stable/7/sys and + then later expand the rest of + stable/7: + + &prompt.user; svn up --set-depth=infinity base/stable/7/sys +&prompt.user; svn up --set-depth=infinity base/stable/7 + + Updating the tree with svn update + will only update what was previously asked for (in this + case, head and + stable/7; it will not pull down the whole + tree. + + It is useful to note that decreasing the depth of a + working copy is not possible. + + + + Anonymous Checkout + + It is possible to anonymously check out the &os; + repository with Subversion. This will give access to a + read-only tree that can be updated, but not committed + to. To do this, use one of the following commands: + + &prompt.user; svn co svn://svn.freebsd.org/base/head /usr/src +&prompt.user; svn co http://svn.freebsd.org/base/head /usr/src + + + + Updating the Tree + + To update a working copy to either the latest revision, + or a specific revision: + + &prompt.user; svn update +&prompt.user; svn update -r12345 + + + + Status + + To view the local changes that have been made to the + working copy: + + &prompt.user; svn status + + CVS has no direct equivalent of this + command. The nearest would be cvs up -N + which shows local changes and files that are out-of-date. + Doing this in SVN is possible too, + however: + + &prompt.user; svn status --show-updates + + + + Editing and Committing + + Like CVS but unlike Perforce, + SVN and SVK do not + need to be told in advance about file editing. + + svn commitworks like the equivalent + CVS command. To commit all changes in + the current directory and all subdirectories: + + &prompt.user; svn commit + + To commit all changes in, for example, the lib/libfetch/ + and usr/bin/fetch/ + in a single operation: + + &prompt.user; svn commit lib/libfetch usr/bin/fetch + + + + Adding and Removing Files + + + Before adding files, get a copy of auto-props.txt + and add it to ~/.subversion/config + according to the instructions in the file. If you added + something before you've read this, you may use + svn rm --keep-local for just added + files, fix your config file and re-add them again. The + initial config file is created when you first run a svn + command, even something as simple as svn + help. + + + As with CVS, files are added to a + SVN repository with svn + add. To add a file named + foo, edit it, then: + + &prompt.user; svn add foo + + Files can be removed with svn + remove: + + &prompt.user; svn remove foo + + Subversion does not require rming the + file before svn rming it, and indeed + complains if that happens. + + It is possible to add directories with svn + add: + + &prompt.user; mkdir bar +&prompt.user; svn add bar + + Although svn mkdir makes this + easier by combining the creation of the directory and the + adding of it: + + &prompt.user; svn mkdir bar + + In CVS, the directory is immediately + created in the repository when you cvs + add it; this is not the case in Subversion. + Furthermore, unlike CVS, Subversion + allows directories to be removed using svn + rm, however there is no svn + rmdir: + + &prompt.user; svn rm bar + + + + Copying and Moving Files + + The following (obviously) creates a copy of + foo.c, named + bar.c: + + &prompt.user; svn copy foo.c bar.c + + To move and rename a file: + + &prompt.user; svn move foo.c bar.c + + The above command is the exact equivalent of: + + &prompt.user; svn copy foo.c bar.c +&prompt.user; svn remove foo.c + + Neither of these operations have equivalents in + CVS. + + + + Log and Annotate + + svn log will show all the + revisions that affect a directory and files within that + directory in reverse chronological order, if run on a + directory. This contrasts with cvs log + in that CVS shows the complete log for + each file in the directory, including duplicate entries for + revisions that affect multiple files. + + svn annotate, or equally svn + praise or svn blame, is + equivalent to cvs annotate in everything + but output format. + + + + Diffs + + The svn diff displays changes to the + working copy of the repository. SVN's + diffs are unified by default, unlike + CVS's, and SVN's + include new files by default in the diff output. + + Like cvs diff, svn + diff can show the changes between two revisions + of the same file: + + &prompt.user; svn diff -r179453:179454 ROADMAP.txt + + It can also show all changes for a specific changeset. + The following will show what changes were made to the + current directory and all subdirectories in changeset + 179454: + + &prompt.user; svn diff -c179454 . + + + + Reverting + + Local changes (including additions and deletions) can be + reverted using svn revert. Unlike + cvs up -C, it does not update out-of-date + files—it just replaces them with pristine copies of + the original version. + + + + Conflicts + + If a svn update resulted in a merge + conflict, Subversion will remember which files have + conflicts and refuse to commit any changes to those files + until explicitly told that the conflicts have been resolved. + The simple, not yet deprecated procedure is the + following: + + &prompt.user; svn resolved foo + + However, the preferred procedure is: + + &prompt.user; svn resolve --accept=working foo + + The two examples are equivalent. Possible values for + --accept are: + + + + working: use the version in your + working directory (which one presumes has been edited to + resolve the conflicts). + + + base: use a pristine copy of the + version you had before svn update, + discarding your own changes, the conflicting changes, + and possibly other intervening changes as well. + + + mine-full: use what you had + before svn update, including your own + changes, but discarding the conflicting changes, and + possibly other intervening changes as well. + + + theirs-full: use the version that + was retrieved when you did svn + update, discarding your own changes. + + + + + + + Advanced Use + + + Sparse Checkouts + + The equivalent to cvs checkout -l, + which checks out a directory without its subdirectories, is + svn checkout -N. Unlike + CVS, SVN remembers the + -N so that a svn + update does not end up pulling down the + subdirectories. In Subversion 1.5 and newer, + -N has been deprecated in favour of the + --depth option which allows for precise + control. Therefore: + + &prompt.user; svn checkout -N svn+ssh://svn.freebsd.org/base ~/freebsd + + is equivalent to: + + &prompt.user; svn checkout --depth=empty svn+ssh://svn.freebsd.org/base ~/freebsd + + Valid arguments to --depth + are: + + + + empty: the directory itself + without any of its contents. + + + files: the directory and any + files it contains. + + + immediates: the directory and any + files and directories it contains, but none of the + subdirectories' contents. + + + infinity: anything. + + + + The --depth option applies to many + other commands, including svn commit, + svn revert, and svn + diff. + + Since --depth is sticky, there is a + --set-depth option for svn + update that will change the selected depth. + Thus, given the working copy produced by the previous + example: + + &prompt.user; cd ~/freebsd +&prompt.user; svn update --set-depth=immediates . + + The above command will populate the working copy in + ~/freebsd with + ROADMAP.txt and empty subdirectories, + and nothing will happen when svn update + is executed on the subdirectories. However, the following + command will set the depth for head (in this case) to + infinity, and fully populate it: + + &prompt.user; svn update --set-depth=infinity head + + + + Direct Operation + + Certain operations can be performed directly on the + repository, without touching the working copy. + Specifically, this applies to any operation that does not + require editing a file, including: + + + + log, + diff. + + + mkdir. + + + remove, copy, + rename. + + + propset, + propedit, + propdel. + + + merge. + + + + Branching is very fast. The following command would be + used to branch RELENG_8: + + &prompt.user; svn copy svn+ssh://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/stable/8 + + This is equivalent to the following set of + commands which take minutes and hours as opposed to seconds, + depending on your network connection: + + &prompt.user; svn checkout --depth=immediates svn+ssh://svn.freebsd.org/base +&prompt.user; cd base +&prompt.user; svn update --depth=infinity head +&prompt.user; svn copy head stable/8 +&prompt.user; svn commit stable/8 + + + + Merging with <acronym>SVN</acronym> + + This section deals with merging code from one branch to + another (typically, from head to a stable branch). For + information about vendor imports, see the next section in + this primer. + + + In all examples below, $FSVN + refers to the location of the &os; Subversion repository, + svn+ssh://svn.freebsd.org/base/. + + + + About Merge Tracking + + From the user's perspective, merge tracking + information (or mergeinfo) is stored in a property called + svn:mergeinfo, which is a + comma-separated list of revisions and ranges of revisions + that have been merged. When set on a file, it applies + only to that file. When set on a directory, it applies to + that directory and its descendants (files and directories) + except for those that have their own + svn:mergeinfo. + + It is not inherited. For + instance, stable/6/contrib/openpam/ + does not implicitly inherit mergeinfo from stable/6/, or stable/6/contrib/. Doing + so would make partial checkouts very hard to manage. + Instead, mergeinfo is explicitly propagated down the tree. + For merging something into branch/foo/bar/, the + following rules apply: + + + + If branch/foo/bar/ doesn't + already have a mergeinfo record, but a direct ancestor + (for instance, branch/foo/) does, + then that record will be propagated down to + branch/foo/bar/ + before information + about the current merge is recorded. + + + Information about the current merge will + not be propagated back up that + ancestor. + + + If a direct descendant of branch/foo/bar/ (for + instance, branch/foo/bar/baz/) + already has a mergeinfo record, information about the + current merge will be propagated down to it. + + + + If you consider the case where a revision changes + several separate parts of the tree (for example, branch/foo/bar/ and + branch/foo/quux/), + but you only want to merge some of it (for example, + branch/foo/bar/), + you will see that these rules make sense. If mergeinfo + was propagated up, it would seem like that revision had + also been merged to branch/foo/quux/, when in + fact it had not been. + + + + Selecting the Source and Target + + Because of mergeinfo propagation, it is important to + choose the source and target for the merge carefully to + minimise property changes on unrelated directories. + + The rules for selecting the merge target (the + directory that you will merge the changes to) can be + summarised as follows: + + + + Never merge directly to a file. + + + Never, ever merge directly to a file. + + + Never, ever, ever merge + directly to a file. + + + Changes to kernel code should be merged to + sys/. For + instance, a change to the &man.ichwd.4; driver should + be merged to sys/, not sys/dev/ichwd/. + Likewise, a change to the TCP/IP stack should be + merged to sys/, + not sys/netinet/. + + + Changes to code under etc/ should be merged + at etc/, not + below it. + + + Changes to vendor code (code in contrib/, crypto/ and so on) + should be merged to the directory where vendor imports + happen. For instance, a change to crypto/openssl/util/ + should be merged to crypto/openssl/. This + is rarely an issue, however, since changes to vendor + code are usually merged wholesale. + + + Changes to userland programs should as a general + rule be merged to the directory that contains the + Makefile for that program. For instance, a change to + usr.bin/xlint/arch/i386/ + should be merged to usr.bin/xlint/. + + + Changes to userland libraries should as a general + rule be merged to the directory that contains the + Makefile for that library. For instance, a change to + lib/libc/gen/ + should be merged to lib/libc/. + + + There may be cases where it makes sense to deviate + from the rules for userland programs and libraries. + For instance, everything under lib/libpam/ is merged + to lib/libpam/, + even though the library itself and all of the modules + each have their own Makefile. + + + Changes to man pages should be merged to share/man/manN/, + for the appropriate value of + N. + + + Changes to a top-level file in the source tree + such as UPDATING or + Makefile.inc1 should be merged + directly to that file rather than to the root of the + whole tree. Yes, this is an exception to the first + three rules. + + >>> TRUNCATED FOR MAIL (1000 lines) <<<