Bug 171759
| Summary: | portsnap man page is misleading | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | phoffman |
| Component: | Books & Articles | Assignee: | Isabell Long <issyl0> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | ||
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
Responsible Changed From-To: freebsd-doc->issyl0 I'll take it. I don't want to give an example of "portsnap cron update" in portsnap(8) since people often copy examples blindly and I've had complaints from people who have caused themselves problems that way. Clarifying the text, on the other hand (perhaps by adding "this way it will be fast when you next run 'portsnap update'" or something along those lines) would be perfectly fine, though. -- Colin Percival Security Officer Emeritus, FreeBSD | The power to serve Founder, Tarsnap | www.tarsnap.com | Online backups for the truly paranoid > I don't want to give an example of "portsnap cron update" in = portsnap(8) > since people often copy examples blindly and I've had complaints from > people who have caused themselves problems that way. >=20 > Clarifying the text, on the other hand (perhaps by adding "this way it > will be fast when you next run 'portsnap update'" or something along > those lines) would be perfectly fine, though. This is still a bit misleading for folks who are migrating from cvsup, = which many people are about to do (and I just did, which triggered this = bug report). In cvsup, the one command pulls *and installs* the changes; = portsnap requires two commands. If you really don't want to update the example to be something that = works (albeit unreliably in the extremely rare care where someone is = installing a port by hand in the middle of the night), please consider = adding the following separate paragraph after the paragraph in the first = bullet of the TIPS section: Note that *portsnap cron* does not apply the changes that were received: it only pulls them. To apply the changes, you must follow this command with *portsnap update*. The *portsnap update* command is normally run by hand at a time when you are sure that no one is manually working in the ports tree. That should cover the normal case of someone reading the doc when they = initially set up portsnap, or when the look at the man page in an = emergency when they can't figure out why an important security update = has not been applied. --Paul Hoffman= On 09/22/12 17:24, Paul Hoffman wrote: > If you really don't want to update the example to be something that works (albeit unreliably in the extremely rare care where someone is installing a port by hand in the middle of the night), please consider adding the following separate paragraph after the paragraph in the first bullet of the TIPS section: > > Note that *portsnap cron* does not apply the changes that were > received: it only pulls them. To apply the changes, you must > follow this command with *portsnap update*. The *portsnap update* > command is normally run by hand at a time when you are sure > that no one is manually working in the ports tree. This looks great to me, subject to changing "*portsnap cron* does not" to "*portsnap cron* and *portsnap fetch* do not" and s/it only pulls them/they only download the changes/. > That should cover the normal case of someone reading the doc when they initially set up portsnap, or when the look at the man page in an emergency when they can't figure out why an important security update has not been applied. Agreed. -- Colin Percival Security Officer Emeritus, FreeBSD | The power to serve Founder, Tarsnap | www.tarsnap.com | Online backups for the truly paranoid On Sep 26, 2012, at 8:54 PM, Colin Percival <cperciva@freebsd.org> = wrote: > On 09/22/12 17:24, Paul Hoffman wrote: >> If you really don't want to update the example to be something that = works > (albeit unreliably in the extremely rare care where someone is = installing a port > by hand in the middle of the night), please consider adding the = following > separate paragraph after the paragraph in the first bullet of the TIPS = section: >>=20 >> Note that *portsnap cron* does not apply the changes that were >> received: it only pulls them. To apply the changes, you must >> follow this command with *portsnap update*. The *portsnap update* >> command is normally run by hand at a time when you are sure >> that no one is manually working in the ports tree. >=20 > This looks great to me, subject to changing "*portsnap cron* does not" = to > "*portsnap cron* and *portsnap fetch* do not" and s/it only pulls = them/they > only download the changes/. >=20 >> That should cover the normal case of someone reading the doc when = they > initially set up portsnap, or when the look at the man page in an = emergency when > they can't figure out why an important security update has not been = applied. >=20 > Agreed. Looks good to me. You have commit privs and I don't; please make it so. --Paul Hoffman= Author: issyl0 (doc committer) Date: Fri Sep 28 11:11:42 2012 New Revision: 241024 URL: http://svn.freebsd.org/changeset/base/241024 Log: Add a note to portsnap(8) about the behaviour of the example cron command. PR: docs/171759 Submitted by: Paul Hoffman (phoffman at proper dot com) Approved by: cperciva, gabor (mentor) MFC after: 3 days Modified: head/usr.sbin/portsnap/portsnap/portsnap.8 Modified: head/usr.sbin/portsnap/portsnap/portsnap.8 ============================================================================== --- head/usr.sbin/portsnap/portsnap/portsnap.8 Fri Sep 28 10:49:41 2012 (r241023) +++ head/usr.sbin/portsnap/portsnap/portsnap.8 Fri Sep 28 11:11:42 2012 (r241024) @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 5, 2012 +.Dd September 28, 2012 .Dt PORTSNAP 8 .Os FreeBSD .Sh NAME @@ -180,6 +180,23 @@ can quickly be extracted into If your clock is set to UTC, please pick a random time other than 3AM, to avoid overly imposing an uneven load on the server(s) hosting the snapshots. +.Pp +Note that running +.Nm +.Cm cron +or +.Nm +.Cm fetch +does not apply the changes that were received: they only only download +them. +To apply the changes, you must follow these commands with +.Nm +.Cm update . +The +.Nm +.Cm update +command is normally run by hand at a time when you are sure that +no one is manually working in the ports tree. .It Running .Nm _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" State Changed From-To: open->patched Fix committed in r241024. Awaiting MFC. Author: issyl0 (doc committer) Date: Mon Oct 1 16:34:12 2012 New Revision: 241106 URL: http://svn.freebsd.org/changeset/base/241106 Log: MFC r241024 and r241026 from HEAD: - Add a note to portsnap(8) about the behaviour of the example cron command. - Change "only only" to "only" in portsnap(8). PR: docs/171759 Approved by: gjb (mentor) Modified: stable/9/usr.sbin/portsnap/portsnap/portsnap.8 Directory Properties: stable/9/usr.sbin/portsnap/ (props changed) Modified: stable/9/usr.sbin/portsnap/portsnap/portsnap.8 ============================================================================== --- stable/9/usr.sbin/portsnap/portsnap/portsnap.8 Mon Oct 1 15:50:18 2012 (r241105) +++ stable/9/usr.sbin/portsnap/portsnap/portsnap.8 Mon Oct 1 16:34:12 2012 (r241106) @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 15, 2008 +.Dd September 28, 2012 .Dt PORTSNAP 8 .Os FreeBSD .Sh NAME @@ -174,6 +174,23 @@ can quickly be extracted into If your clock is set to UTC, please pick a random time other than 3AM, to avoid overly imposing an uneven load on the server(s) hosting the snapshots. +.Pp +Note that running +.Nm +.Cm cron +or +.Nm +.Cm fetch +does not apply the changes that were received: they only download +them. +To apply the changes, you must follow these commands with +.Nm +.Cm update . +The +.Nm +.Cm update +command is normally run by hand at a time when you are sure that +no one is manually working in the ports tree. .It Running .Nm _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" State Changed From-To: patched->closed This is now fixed. |
The first tip in the portsnap man page says: o If your clock is set to local time, adding the line 0 3 * * * root /usr/sbin/portsnap cron to /etc/crontab is a good way to make sure you always have an up-to- date snapshot of the ports tree available which can quickly be extracted into /usr/ports. "extracted" is wrong: it should be "updated". However, it is misleading because it doesn't tell you *how* you can quickly update the ports, which is obviously what most people want to do. Fix: o If your clock is set to local time, adding the line 0 3 * * * root /usr/sbin/portsnap cron update to /etc/crontab is a good way to make sure you always have an up-to- date snapshot of the ports tree in /usr/ports.