pkgdb -F is an extremely useful, interactive tool that fixes inconsistencies in your package database. It should be run before undertaking a large (i.e. portupgrade -akO) upgrade or after a portupgrade fails. Although this page is by no means intended to be exhaustive, I'm going to walk through some of this tool's basic usage with you:
fongsaiyuk# pkgdb -F
---> Checking the package registry database
Stale origin: 'print/cups-lpr': perhaps moved or obsoleted.
-> The port 'print/cups-lpr' was moved to 'print/cups-base' on 2006-06 because:
"Merged cups-lpr into cups-base"
Fixed. (-> print/cups-base)
The first message we received was about cups-lpr being obsoleted, and its functionality merged into cups-base (lines 3-5) of the above output.
Stale origin: 'net-im/kopete-devel': perhaps moved or obsoleted.
Skip this for now? [yes] yes
To skip it without asking in future, please list it in HOLD_PKGS.
This second message deals with a package that was installed non-traditionally, i.e. one that is not in Ports. Because this package is not in Ports and thus I cannot specify its correct place or replacement package name, but I nevertheless wanted to keep this particular package, I answered "yes" when asked if I wanted to skip this package. Skip is a good rule of thumb when you don't understand something, or when something that pkgdb -F doesn't think is supposed to be there is in fact there by your design.
Stale origin: 'emulators/winetools': perhaps moved or obsoleted.
Skip this for now? [yes] no
Browse CVSweb for the port's history? [no] no
Guessing...
emulators/linux-winetools (linux-winetools-1.30_1): Change the origin to this? [yes] yes
Fixed. (-> emulators/linux-winetools)
Here, we received the same prompt about a package showing up that is no longer named the same thing in Ports. We want to correct that to ensure that portupgrading this package in the future goes smoothly. When asked whether I wanted to skip this package, I answered "no", which brought up a prompt asking me if I wanted to change the package origin from winetools to linux-winetools. Because I happen to know that this is the new name for this package, I accepted pkgdb -F's suggestion and answered "yes", changing the origin of this package from winetools to linux-winetools.
Alternatively, we might want to change the origin of the package but the suggestion given by pkgdb -F might not be correct. In this case, simply answer "no" when asked whether you want to change the origin to pkgdb -F's suggestion, and when prompted type in the correct new name of the package (with version number--you'll probably have to run a pkg_info | grep [package_name] in a separate screen or terminal window in order to look this up).
Duplicated origin: print/cups-base - cups-base-1.1.23.0_9 cups-lpr-1.1.23.0_1
Unregister any of them? [no] yes
Unregister cups-base-1.1.23.0_9 keeping the installed files intact? [no] no
Unregister cups-lpr-1.1.23.0_1 keeping the installed files intact? [no] yes
--> Saving the cups-lpr-1.1.23.0_1's +CONTENTS file as /var/db/pkg/cups-base-1.1.23.0_9/+CONTENTS.cups-lpr-1.1.23.0_1
--> Unregistering cups-lpr-1.1.23.0_1
--> Done.
Do you remember that message we received from pkgdb -F at the beginning of this process telling us that cups-lpr had been merged into cups-base? It is time to fix that. We are first told that cups-base and cups-lpr are a duplicated origin--they provide the same functionality. When asked whether we want to unregister any of them, instead of accepting the default answer of [no], type "yes" and hit 'Enter'. We will then be asked whether we want to unregister cups-base. Because we know from the earlier message that cups-lpr has been merged into cups-base, not the other way around, we know that we want to keep cups-base and remove cups-lpr. Therefore, we answer "no" when asked whether we want to unregister cups-base. We are then asked whether we want to unregister cups-lpr, to which we answer "yes".
[Updating the pkgdb
Stale dependency: cups-1.1.23.0_1 -> cups-lpr-1.1.23.0_1 (print/cups-lpr):
Fixed. (-> cups-base-1.1.23.0_9)
fongsaiyuk#
Lastly, we receive a message about our package database (pkgdb) being updated, see a list of how many packages we have in that database, and then a note about pkgdb -F replacing cups-lpr with cups-base as a dependency for cups. After this particular example has been completed, it would now be safe to portupgrade cups in order to upgrade cups from 1.1.x to 1.2.x.
Another scenario you might run into running pkgdb -F is this:
Stale dependency: en-openoffice.org-US-2.0.3 -> openssl-beta-0.9.8b_1 (security/openssl-beta):
openslp-1.2.1_2 (score:26%) ? ([y]es/[n]o/[a]ll) [no]
A package that is listed as a dependency of OpenOffice.org (openssl-beta) is missing with no perceivable negative impact, and pkgdb -F wants to replace it with a new dependency. We can tell quite easily by the name and a little personal knowledge, however, that openslp has nothing whatsoever to do with openssl-beta, and is not a suitable replacement for it.
Accept the default answer of "no" by hitting 'Enter'. You will then be prompted as follows:
Install stale dependency? ([y]es/[n]o/[a]ll) [yes]
Type "no" and hit 'Enter'. You will then receive the following prompt:
New dependency? (? to help):
Type 'Ctrl'+'D' to receive the following prompt:
Delete this? ([y]es/[n]o/[a]ll) [yes]
At which point you will type "all" and hit 'Enter'. This will remove the openssl-beta dependency from every application that had it listed as a dependency, as we do not have it on our system and do not seem to need it.