From owner-svn-doc-head@FreeBSD.ORG Sat Nov 17 05:26:13 2012 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 93651230; Sat, 17 Nov 2012 05:26:13 +0000 (UTC) (envelope-from pgj@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 761408FC08; Sat, 17 Nov 2012 05:26:13 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.5/8.14.5) with ESMTP id qAH5QDHj035817; Sat, 17 Nov 2012 05:26:13 GMT (envelope-from pgj@svn.freebsd.org) Received: (from pgj@localhost) by svn.freebsd.org (8.14.5/8.14.5/Submit) id qAH5QDME035815; Sat, 17 Nov 2012 05:26:13 GMT (envelope-from pgj@svn.freebsd.org) Message-Id: <201211170526.qAH5QDME035815@svn.freebsd.org> From: Gabor Pali Date: Sat, 17 Nov 2012 05:26:13 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40050 - in head/en_US.ISO8859-1/books/handbook: cutting-edge mirrors X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 17 Nov 2012 05:26:13 -0000 Author: pgj (ports committer) Date: Sat Nov 17 05:26:13 2012 New Revision: 40050 URL: http://svnweb.freebsd.org/changeset/doc/40050 Log: - Add information on how to update the source code using Subversion, and therefore deprecate CVS and CVSup as ways of updating. Reviewed by: gavin, brd, eadler Approved by: gjb Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Fri Nov 16 19:50:44 2012 (r40049) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Sat Nov 17 05:26:13 2012 (r40050) @@ -70,6 +70,7 @@ How to keep your system up to date with freebsd-update, + Subversion, CVSup, CVS, or CTM. @@ -82,7 +83,7 @@ How to keep your documentation up to date with - CVSup or documentation + Subversion or documentation ports. @@ -112,15 +113,10 @@ - Throughout this chapter, the cvsup - command is used to obtain and update &os; sources. To use it, - you will need to install the port or the package for - net/cvsup (if you do not - want to install the graphical cvsup client, - you can just install the port - net/cvsup-without-gui). You may wish to - substitute this with &man.csup.1;, which is part of the base - system. + Throughout this chapter, the svn command + is used to obtain and update &os; sources. To use it, you will + need to install the port or the package for devel/subversion. @@ -1405,10 +1401,13 @@ Fetching 133 new ports or files... done. Grab the sources from a &os; mirror site. You can do - this in one of two ways: + this in one of three ways: + svn + + cvsup @@ -1422,21 +1421,33 @@ Fetching 133 new ports or files... done. + Use the svn program to + check out the desired development or release branch. + This is the recommended method, providing access to + &os; development as it occurs. The preferred URL + prefix for Subversion + checkout of the -CURRENT base system is + http://svn.freebsd.org/base/head/; + because of the size of the repository, it is + recommended that only desired subtrees be checked out. + + + + Use the cvsup program with the supfile named standard-supfile available from /usr/share/examples/cvsup. - This is the most recommended method, since it allows - you to grab the entire collection once and then only - what has changed from then on. Many people run - cvsup from - cron and keep their sources - up-to-date automatically. You have to customize the - sample supfile above, and - configure + You have to customize the sample + supfile above, and configure cvsup for your environment. + + cvsup has been deprecated by + the Project, and is not recommended. + + The sample standard-supfile is intended @@ -1473,9 +1484,8 @@ Fetching 133 new ports or files... done. which again increases the chance of it not working for fairly long periods of time. We recommend using CVSup for - anybody with a 9600 bps modem or faster - connection. + linkend="svn">Subversion for + any system with Internet connectivity. @@ -1599,8 +1609,8 @@ Fetching 133 new ports or files... done. Join the relevant SVN list for the branch you are tracking. For example, if - you are tracking the 7-STABLE branch, join the - &a.svn-src-stable-7.name; list. This will allow you to + you are tracking the 9-STABLE branch, join the + &a.svn-src-stable-9.name; list. This will allow you to view the commit log entry for each change as it is made, along with any pertinent information on possible side-effects. @@ -1629,10 +1639,13 @@ Fetching 133 new ports or files... done. &os; and wish to upgrade via sources then you can easily do so from &os; mirror site. This can be - done in one of two ways: + done in one of three ways: + svn + + cvsup @@ -1641,24 +1654,42 @@ Fetching 133 new ports or files... done. -STABLE syncing with - CVSup + Subversion + Use the svn program to + check out the desired development or release branch. + This is the recommended method, providing access to + &os; development as it occurs. Branch names include + head for the current development + head, and branches identified in , such as + stable/9 or + stable/9.0. The preferred URL + prefix for Subversion + checkout of the base system is + http://svn.freebsd.org/base/; + because of the size of the repository, it is + recommended that only desired subtrees be checked out. + + + + Use the cvsup program with the supfile named stable-supfile from the directory /usr/share/examples/cvsup. - This is the most recommended method, since it allows - you to grab the entire collection once and then only - what has changed from then on. Many people run - cvsup from - cron to keep their sources - up-to-date automatically. You have to customize the + You have to customize the sample supfile above, and configure cvsup for your environment. + + + cvsup has been deprecated by + the Project, and is not recommended. + @@ -1713,6 +1744,7 @@ Fetching 133 new ports or files... done. connection to stay up-to-date with any given area of the &os; project sources, or all areas, depending on what interests you. The primary services we offer are + Subversion, Anonymous CVS, CVSup, and CTM. @@ -1734,25 +1766,25 @@ Fetching 133 new ports or files... done. anonymous - Anonymous CVS and - CVSup use the - pull model of updating sources. In the - case of CVSup the user (or a - cron script) invokes the - cvsup program, and it interacts with a - cvsupd server somewhere to bring your files - up-to-date. The updates you receive are up-to-the-minute and + Subversion, Anonymous + CVS and CVSup use the + pull model of updating sources. For + Subversion, + the user (or a cron script) invokes the + svn program, and it brings files up-to-date. + Subversion is the preferred means of + updating local source trees. + cvsup and cvs work under + similar principles, but are now deprecated in favour of Subversion. + The updates you receive are up-to-the-minute and you get them when, and only when, you want them. You can easily restrict your updates to the specific files or directories that are of interest to you. Updates are generated on the fly by the server, according to what you have and what you want to have. - Anonymous CVS is quite a bit more - simplistic than CVSup in that it is - just an extension to CVS which allows - it to pull changes directly from a remote CVS repository. - CVSup can do this far more - efficiently, but Anonymous CVS is - easier to use. + Unless the reason is truly compelling, + Subversion should be used in preference + to other synchronization mechanisms, which have been deprecated + and will be discontinued in the future. CTM Modified: head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml Fri Nov 16 19:50:44 2012 (r40049) +++ head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml Sat Nov 17 05:26:13 2012 (r40050) @@ -245,331 +245,18 @@ , burncd. - - Subversion Sites - - - svn - - - As of July 2012, &os; uses - Subversion - (svn) as the primary version control system - for storing all of &os;'s source code, documentation, and the - Ports Collection. - - - Subversion is generally a developer tool. Most users - should use - FreeBSD - Update to update the &os; base system, and - Portsnap - to update the &os; Ports Collection. - - - The &os; svn mirror network is still in its early days, and - will likely change. Do not count on this list of mirrors being - static. In particular, the SSL certificates of the servers will - likely change at some point. - - In Subversion, URLs are used to designate a repository, - taking the form of protocol://hostname/path. - Mirrors may support different protocols as specified below. The - first component of the path is the &os; repository to access. - There are three different repositories, base - for the &os; base system source code, ports - for the Ports Collection, and doc for - documentation. For example, the URL - svn://svn0.us-east.FreeBSD.org/ports/head/ - specifies the main branch of the ports repository on the - svn0.us-east.FreeBSD.org mirror, - using the svn protocol. - - All mirrors carry all repositories. - - The master &os; Subversion server, - svn.FreeBSD.org, is publicly - accessible, read-only. That may change in the future, so users - are encouraged to use one of the official mirrors. To view the - &os; Subversion repositories through a browser, use http://svnweb.FreeBSD.org/. - - - - - - - - - - Name - - Protocols - - Location - - SSL fingerprint - - - - - - svn0.us-west.FreeBSD.org - - svn, http, - https - - USA, California - - SHA1 - 79:35:8F:CA:6D:34:D9:30:44:D1:00:AF:33:4D:E6:11:44:4D:15:EC - - - - svn0.us-east.FreeBSD.org - - svn, http, - https - - USA, New Jersey - - SHA1 - 06:D1:23:DE:5E:7A:F7:2B:7A:7E:74:95:5F:54:8D:5C:B0:D6:2E:8F - - - - - - Anonymous CVS + Anonymous CVS (Deprecated) - <anchor id="anoncvs-intro"/>Introduction - - - CVS - anonymous - - - Anonymous CVS (or, as it is otherwise known, - anoncvs) is a feature provided by the CVS - utilities bundled with &os; for synchronizing with a remote - CVS repository. Among other things, it allows users of &os; - to perform, with no special privileges, read-only CVS - operations against one of the &os; project's official anoncvs - servers. To use it, one simply sets the - CVSROOT environment variable to point at the - appropriate anoncvs server, provides the well-known password - anoncvs with the cvs login - command, and then uses the &man.cvs.1; command to access it - like any local repository. + Warning - - The cvs login command, stores the - passwords that are used for authenticating to the CVS server - in a file called .cvspass in your - HOME directory. If this file does not exist, - you might get an error when trying to use - cvs login for the first time. Just make - an empty .cvspass file, and retry to - login. - - - While it can also be said that the - CVSup and - anoncvs services both perform essentially - the same function, there are various trade-offs which can - influence the user's choice of synchronization methods. In a - nutshell, CVSup is much more - efficient in its usage of network resources and is by far the - most technically sophisticated of the two, but at a price. To - use CVSup, a special client must - first be installed and configured before any bits can be - grabbed, and then only in the fairly large chunks which - CVSup calls - collections. - - Anoncvs, by contrast, can be - used to examine anything from an individual file to a specific - program (like ls or - grep) by referencing the CVS module name. - Of course, anoncvs is also only - good for read-only operations on the CVS repository, so if it - is your intention to support local development in one - repository shared with the &os; project bits then - CVSup is really your only - option. - - - - <anchor id="anoncvs-usage"/>Using Anonymous CVS - - Configuring &man.cvs.1; to use an Anonymous CVS repository - is a simple matter of setting the CVSROOT - environment variable to point to one of the &os; project's - anoncvs servers. At the time of this - writing, the following servers are available: - - - - France: - :pserver:anoncvs@anoncvs.fr.FreeBSD.org:/home/ncvs - (For pserver mode, use cvs login and - enter the password anoncvs when prompted. - For ssh, no password is required.) - - - - Taiwan: - :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs - (For pserver mode, use cvs login and - enter any password when prompted. For ssh, no password - is required.) - - SSH2 HostKey: 1024 02:ed:1b:17:d6:97:2b:58:5e:5c:e2:da:3b:89:88:26 /etc/ssh/ssh_host_rsa_key.pub -SSH2 HostKey: 1024 e8:3b:29:7b:ca:9f:ac:e9:45:cb:c8:17:ae:9b:eb:55 /etc/ssh/ssh_host_dsa_key.pub - - - - - - Since CVS allows one to check out virtually - any version of the &os; sources that ever existed (or, in some - cases, will exist), you need to be familiar with the revision - () flag to &man.cvs.1; and what some of the - permissible values for it in the &os; Project repository - are. - - There are two kinds of tags, revision tags and branch - tags. A revision tag refers to a specific revision. Its - meaning stays the same from day to day. A branch tag, on the - other hand, refers to the latest revision on a given line of - development, at any given time. Because a branch tag does not - refer to a specific revision, it may mean something different - tomorrow than it means today. - - contains revision tags that - users might be interested in. Again, none of these are valid - for the Ports Collection since the Ports Collection does not - have multiple branches of development. - - When you specify a branch tag, you normally receive the - latest versions of the files on that line of development. If - you wish to receive some past version, you can do so by - specifying a date with the flag. See - the &man.cvs.1; manual page for more details. - - - - Examples - - While it really is recommended that you read the manual - page for &man.cvs.1; thoroughly before doing anything, here - are some quick examples which essentially show how to use - Anonymous CVS: - - - Checking Out Something from -CURRENT - (&man.ls.1;): - - &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs -&prompt.user; cvs login -At the prompt, enter any word for password. -&prompt.user; cvs co ls - - - - Using SSH to Check Out the <filename>src/</filename> - Tree: - - &prompt.user; cvs -d anoncvs@anoncvs1.FreeBSD.org:/home/ncvs co src -The authenticity of host 'anoncvs1.freebsd.org (216.87.78.137)' can't be established. -DSA key fingerprint is 53:1f:15:a3:72:5c:43:f6:44:0e:6a:e9:bb:f8:01:62. -Are you sure you want to continue connecting (yes/no)? yes -Warning: Permanently added 'anoncvs1.freebsd.org' (DSA) to the list of known hosts. - - - - Checking Out the Version of &man.ls.1; in the 8-STABLE - Branch: - - &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs -&prompt.user; cvs login -At the prompt, enter any word for password. -&prompt.user; cvs co -rRELENG_8 ls - - - - Creating a List of Changes (as Unified Diffs) to - &man.ls.1; - - &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs -&prompt.user; cvs login -At the prompt, enter any word for password. -&prompt.user; cvs rdiff -u -rRELENG_8_0_0_RELEASE -rRELENG_8_1_0_RELEASE ls - - - - Finding Out What Other Module Names Can Be - Used: - - &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs -&prompt.user; cvs login -At the prompt, enter any word for password. -&prompt.user; cvs co modules -&prompt.user; more modules/modules - - - - - Other Resources - - The following additional resources may be helpful in - learning CVS: - - - - CVS - Tutorial from California Polytechnic State - University. - - - - CVS - Home, the CVS development and support - community. - - - - CVSweb - is the &os; Project web interface for CVS. - - + + CVS has been deprecated by the project, and its use is not + recommended. Subversion should be + used instead. + @@ -933,12 +620,234 @@ Warning: Permanently added 'anoncvs1.fre + + Using <application>Subversion</application> + + + Introduction + + As of July 2012, &os; uses Subversion + (svn) as the primary version control system + for storing all of &os;'s source code, documentation, and the + Ports Collection. + + + Subversion is generally a developer tool. Most users + should use FreeBSD + Update to update the &os; base system, and Portsnap to + update the &os; Ports Collection. + + + In Subversion, URLs are used to + designate a repository, taking the form of + protocol://hostname/path. Mirrors may + support different protocols as specified below. The first + component of the path is the &os; repository to access. There + are three different repositories, base for + the &os; base system source code, ports for + the Ports Collection, and doc for + documentation. For example, the URL + svn://svn0.us-east.FreeBSD.org/ports/head/ + specifies the main branch of the ports repository on the svn0.us-east.FreeBSD.org mirror, using the + svn protocol. + + + + Installation + + Subversion must be installed + before it can be used to check out the contents of any of the + repositories. If a copy of the ports tree is already present, + one can install Subversion like + this: + + &prompt.root; cd /usr/ports/devel/subversion +&prompt.root; make install clean + + If the ports tree is not available, + Subversion can be installed as a + package: + + &prompt.root; pkg_add -r subversion + + If pkgng is being used to manage + packages, Subversion can be installed + with it instead: + + &prompt.root; pkg install devel/subversion + + + + Running <application>Subversion</application> + + The svn command can be used to fetch a + clean copy of the sources from a given repository by + typing: + + &prompt.root; svn checkout svn://svn.FreeBSD.org/repository/branch root + + where: + + + + repository is one of the + Project repositories, i.e. base, + ports, or doc. + + + + branch depends on the + repository used. ports and + doc are mostly updated in the + head branch, while + base maintains the latest version of + -CURRENT under head and the respective + latest versions of the -STABLE branches under + stable/8 (for + 8.x) and + stable/9 + (9.x). + + + + root is the target directory + where the contents of the specified branch should be placed. + This is usually /usr/ports for + ports, /usr/src for + base, and /usr/doc for + doc. + + + + Note that the initial download of the sources may take a + while. Let it run until it completes. + + Future updates of the downloaded sources may be fetched by + running: + + &prompt.root; svn update root + + After checking out the sources, an alternative way of + updating the documentation is supported by the + Makefile of the root + directory by running: + + &prompt.root; cd root +&prompt.root; make update SVN_UPDATE=yes + + + + For More Information + + For other information about using + Subversion, please see the + Subversion Book, titled Version Control with + Subversion, or the Subversion + Documentation. + + + + <application>Subversion</application> Sites + + + svn + + + All mirrors carry all repositories. + + The master &os; Subversion + server, svn.FreeBSD.org, is publicly + accessible, read-only. That may change in the future, so users + are encouraged to use one of the official mirrors. To view the + &os; Subversion repositories through + a browser, use http://svnweb.FreeBSD.org/. + + + The &os; svn mirror network is still in its early days, and + will likely change. Do not count on this list of mirrors being + static. In particular, the SSL certificates of the servers will + likely change at some point. + + + + + + + + + + + Name + + Protocols + + Location + + SSL fingerprint + + + + + + svn0.us-west.FreeBSD.org + + svn, http, + https + + USA, California + + SHA1 + 79:35:8F:CA:6D:34:D9:30:44:D1:00:AF:33:4D:E6:11:44:4D:15:EC + + + + svn0.us-east.FreeBSD.org + + svn, http, + https + + USA, New Jersey + + SHA1 + 06:D1:23:DE:5E:7A:F7:2B:7A:7E:74:95:5F:54:8D:5C:B0:D6:2E:8F + + + + + + + + - Using CVSup + Using CVSup (Deprecated) Introduction + + cvsup has been deprecated by the + project, and its use is not recommended. + Subversion should be used + instead. + + CVSup is a software package for distributing and updating source trees from a master CVS repository on a remote server host. The &os; sources are @@ -2485,6 +2394,12 @@ doc/zh_* CVS Tags + + CVS has been deprecated by the project, and its use is not + recommended. Subversion should be + used instead. + + When obtaining or updating sources using cvs or CVSup, a revision tag must be