usage: swim -q [-fpgn --dir] [targets | -S]
swim --query [-fpgn --dir] [targets | -S]
swim -qa || swim --query -a
options: [--total -t] [-i] [-l ? <[--df]>] [-d] [-c]
[--scripts] [--preinst] [--postinst] [--prerm]
[--postrm] [-v] [--dbpath <dir>] [--menu -m]
[--shlibs] [-T] [--pre_depends] [--depends]
[--recommends] [--suggests] [--conflicts]
[--replaces] [--provides] [--md5sum] [--root <dir>]
[--copyright] [--changelog] [--allgroups]
[--arch <architecture>] [--dists <distribution>]
[--ftp ? --source | --source_only ? <[--diff]>]
[--stdin] [--extract] <ALL|archive|PWD!archive>]
[-xyrz --remove ? <[--nz]>] [--purge] [--apt2df]
[--df2apt] global arguments: [targets | -S ? <\d{1,}>]
Quering almost always involves using -q or --query with
zero or one or a combination of the minor mode options
(package specification options), and one or more (only one for
-g) targets specific to the minor mode, or the results of a
search (-S). [-S can be provided a numerical argument
pertaining to the past history.] This can be combined with one or more
options. The one exception is ``swim -q --allgroups''.
--query or -q can be used by itself or with -n to query known package names or package names with versions. ``swim -q test1 test2_0.3-1'' would produce the output:
test1_1.0-2 test2_0.3-1
-a allows every package on an installed or not-installed (-n) system to be queried. ``swim -qan'' will show all the package names with versions for the not-installed system
-f allows files or directories to be queried, when used without any options the package name with version is shown. --dir will only query directories, this is useful if you are not sure whether what you are quering is a directory or a file. When a directory is queried, swim shows all packages which exist below the queried directory. ``swim -qf /'' is exactly the same as ``swim -qa''. Hint: ``swim -qf .'' and ``swim -qf *'' are quite different, the first shows all packages which exist below the current directory, and the second will show the package which each file in the current directory comes from.
-g will query a group (also called a section, see SECTION AND PRIORITY , subsection 9.5.3)) of packages. Groups represent subjects which packages with similiar characteristics are catagorized by. To view all the groups found in an installed or not-installed system use ``swim -q --allgroups'' or ``swim -qn --allgroups''. ``swim -qg hamradio'' or ``swim -qng hamradio'' shows all the package names for the hamradio group.
-p is used to query a Debian package, these packages are distinguished by their ``deb'' ending, but swim can tell whether a file is a debian package even without the ending. Called without any options the package name with version will be shown.
--arch will use the databases for the argument given, otherwise the databases pertaining to the value found in swimrc will be used.
Example: swim -qat --arch hurd-i386 --dists unstable
Assuming these databases exist this will show all packages and their versions for the unstable distribution and architecture hurd-i386 even if the values in swimrc are i386 and stable.
see A. downloading the important databases with --ftp. , section 6.1 and MAKING NOT-INSTALLED DATABASES , chapter 7 for more information about the databases.
-i provides information about each package being queried. The format differs slightly for the installed packages versus the not-installed packages. see FORMAT , section 9.5:
-l provides a listing of the files associated with a package. If the option --df is provided as an argument, all the directories associated with package will be shown. It is important to remember that many packages provide directories which become important to them after they are installed, so the option --df often provides necessary information which -l called by itself would have not.
-d shows the documentation which the package provides found in /usr/doc/*, /usr/man/*, /usr/info/*. Other documentation which the package may provide in a non-standard location will not be shown. -d takes precedence over -l, so if -l is used on the command line with -d, only the output for -d will be shown.
-v is a special option which works only with the minor
mode -p. It can be used with -l,
--df, -d, to show the packages files
and/or directories in long format (ls -
l).
-c will show the configuration files packages use. If the package does not have a configuration file then nothing will be shown. The output will show the file and its path indented one space with the MD5 checksum. This will not work with -n.
--scripts shows all scripts associated with a package with the name of the script presented before each script in this way #####scriptname######. If the scripts are called individually by using the script options --preinst, --postinst, --prerm, or --postrm no title is shown, this is nice for writing to a file. If -t is used with the individual script options a title will be shown, this makes sense because normally only individual packages would be queried to write a script to a file, and -t wouldn't be used in this situation. Scripts are the soul of Debianized packages allowing packages to be installed, configured, and removed seamlessly and cleanly under all kinds of conditions. These options do no work with -n.
--menu or -m is used to view menufiles which belong to various packages. If the package does not have a menufile nothing will be shown. This option can be useful in troubleshooting a menu entry which does not seem to work, or in finding out where the menu entry is. Joost Witteveen's Debian menu system is a centralized program which interacts with all kinds of menus. Please read the documentation ``swim -qd menu'' which comes with the menu package to find out more. This will not work with -n.
--shlibs shows a list of shared libraries certain packages supply. The Debian Packaging Manual (packaging-manual) provides detailed information about the format of a shlibs file. This will not work with -n.
--md5sum checks MD5 checksums. It can be used with -l, -d, -c, or -p. If there are checksums available the md5sum result will be either OK, FAILED, or MISSING. MISSING means that although a checksum exists, the file can not be found. The result is put after the file and its path and the MD5 checksum or the package name and version and the MD5 checksum.
--copyright does a case insensitive search for copy or license in the /usr/doc/packagename directory. This should show how the package relates to Debian's Policy Manual.
--changelog searches for any files in /usr/doc/packagename which look like changelogs. Debian packages always have a Maintainer's changelog for the package. There may be a separate changelog kept by the author of the program.
Dependencies Pre-depends - means that the pre-depended package or packages must be installed before the queried package can be installed. Most packages which have pre-dependencies are usually essential and required packages.
Depends - declares an absolute dependency to another package or packages either real or virtual. The queried package cannot function without this other package.
Recommends - declares a strong, but not absolute dependency to another package or packages either real or virtual. You would usually find the recommended package together with the queried package in a normal installation.
Suggests - can be one or more packages either real or virtual which would be useful to the queried package, but are not necessary. Alternative Packages
Conflicts - is a package or packages either real or virtual which would cause problems with the queried package, and would not be allowed to be installed while the queried package was installed.
Overwriting files and Replacing Packages
Replaces - allows the queried package to replace another package or packages by overwriting their files, after which the previous package would be considered to have disappeared. Essentially this allows the queried package to take over the package or packages. In a situation where there was a Conflict between the queried package and these packages this field would help determine which packages should be removed.
Virtual Packages
Provides - declares a virtual package which may be mentioned in Depends, Recommends, Suggests, or Conflicts. Virtual packages allow one or more packages to share the same name of another package, which means if the queried package has a reference to a virtual package in one of the before mentioned package relationship fields, then whatever packages provide the virtual package are also being listed.
Package: name Status: hold ok installed Version: 1.1-1 Essential: no Section: namers Priority: extra Installed-Size: 10 Source: generatename (2.0-1) Maintainer: name <name@name.org> Description: hostname maker A nice way to figure out a hostname nobody else has.
2) Not-installed system
Package: name Status: r> hold ok installed (1.1-1) Version: 1.1-2 Essential: no Section: names Priority: extra Installed-Size: 11 Source: generatename (2.0-1) Size: 43000 Architecture: i386 Distribution: experimental Maintainer: name <name@name.org> Description: hostname maker A nice way to figure out a hostname nobody else has.
There are several things to point out. The difference between the two outputs relates to the addition of the Distribution, Size, and Architecture fields for the not-installed query. Installed-Size is how many kilobytes the package will occupy when it is unpacked, whereas Size is the size in bytes of the package.
-g). Priority shows how important the package is to have
installed. In the case of the not-installed databases the information for
these fields is almost always available from the Packages databases, but
this is not always the case for Debian packages. For packages which do no
provide this information swim will do its best to fill in the blanks from
information found in the installed and not-installed databases. If proper
information can not be found it will be indicated as ``unavailable'' or
``unknown.'' Unavailable would indicate that information about the package
exists, but it is from a different version (includes debian-revision), and
no information exists for this version. Unknown means no similiar package
exists, and there is absolutely no information about this package in the
databases.
When a Debian package is queried using the -p option you will get output like the first example shows, the status field is also calculated.
--ftp allows the queried package, its source package, or just the source package diff to be downloaded while being queried. This is refered to as virtual downloading because the quering and the downloading are seamless as though the package already exists locally. This has to be used with the option -n because packages which which are not part of the not-installed database are considered to already have been downloaded. Packages which are already installed can be downloaded or their source retrieved by setting up a database which corresponds to these packages; if the installed packages belong to the stable distribution, set-up the not-installed stable databases.
Packages or source code are placed in an area below the default directory mirroring the remote directory they were downloaded from after their size and modification times are checked for correct values. This area is called the DF directory, and although this directory mirrors remote directories, it is not an exact mirror, but specific to the requirements of swim because code names for Release versions are not taken into account. For real mirroring capabilities there exist many excellent programs. If a package has a MD5 checksum, --md5sum will automatically be run and the value shown. Regardless of whether or not the md5sum check is OK or not, the package will still be put in the DF directory to allow the package to be looked at, so watch the output from --ftp to check for FAILED md5sums.
Packages or source code packages will not be downloaded again if they are
found in the DF directory unless their
upstream-version has changed in the not-installed database, if
the packages are not in the DF directory and the remote
upstream-version is different than the not-installed
upstream-version then the packages will not be downloaded until
the not-installed database is updated or rebuilt to reflect the version
change. Changes in the package's upstream-version indicates that
the author(s) of the program have made changes to the computer
code for the program contained in the package or the source code package.
On the other hand, swim will check for a debian-revision change
at the remote site if the package can not immediately be found. If the
package's debian-revision has changed and the package does not
exist locally in the DF directory, it will be downloaded.
This is a nice feature, especially for the unstable distribution, because
it tends to extend the time needed before the not-installed database has
to be updated or rebuilt to match the changes at remote sites.
--source is used with --ftp to download the source code package. --source_only will download the source code package without the deb package. Source packages consist of three files. The source control file which ends in ``dsc'', the original source archive which is a compressed tar file, and the unified context diff showing the changes necessary to make the original source into Debian source. The diff can be downloaded by itself if --diff is provided as an argument to --source or --source_only.
For apt users: apt allows packages to be
downloaded, but if more than one package is required for the package
relationships to be proper, apt will download all these
packages. --ftp allows specific packages to be
downloaded, packages from other architectures, and source packages to be
downloaded, here lies the advantage of this option over using -xyz
--nz (see below). If a particular package has been dowloaded into
the DF directory and it is needed by apt
for installation, simply copy or move the package from the
DF directory to /var/cache/apt/archives before
running apt, and the package will not be downloaded by
apt again; future versions of swim will
have an option to automatically accomplish this (see --df2apt).
-xyrz, --remove, and --nz can be used if apt-get from the apt package is installed. These options allow for what is refered to as virtual installation/removal. It is prudent to always test what will happen by using the -x option alone before actually proceeding with the installation with the -z option. -x will actually simulate what would happen in an installation, showing which and how many packages will be changed, which and how many new packages will need to be installed, which and how many packages will need to be removed, any conflicts, and what needs to be configured. -y will automatically answer yes to any prompts apt-get may produce allowing apt-get to run non-interactively. -z as mentioned before actually proceeds with the installation using dpkg after the apt-get gets the packages. You can append a minus sign to a package name to cause it to be removed. --nz when used as an optional argument with -xz or -xyz will only download the packages into /var/cache/apt/archives or into whatever directory you configured for holding archives for apt.
IMPORTANT: apt makes it so easy to make changes to your installation that it is highly recommended to do your research with swim first. This can be done by checking package relationships, file/dir listings, comparing the not-installed package to an installed package if such exists, checking --md5sum and -c for the installed package, and checking the Source field by running a --search (see SEARCHING , chapter 11) to check to see how the source package has been split into binary packages for the not-installed package versus an installed package if such exists. Ofcourse, there are many other things you could look at, and you can always do your research after the fact. Presently --db is run only by hand, so you can check the old state after an installation if you have not already run --db, yourself.
-r or --remove removes an installed package or packages with apt, but not the configuration files as shown with ``swim -qc packagename''. You may also append a plus sign to a package name to cause it to be installed. This option is used with -x or -x(y)z.
--stdin provides the readline capabilities
commonly found in shells allowing you to edit what is on the command line.
You can edit the command line, press enter and then recall the history,
and make more changes, or type in exit to process the changed or
unchanged command line. To find out more about what readline commands
your shell supports please read the man pages which apply to your shell.
Information for the bash shell can be found in bash(1) under the
title ``Readline Command Names''.
Example: ``swim -qgnx --stdin hamradio'' will list all the packages from the not-installed hamradio group on the command line, this list can be edited then submitted to apt-get for a simulated installation. Another instance of swim can be run at the same time, perhaps ``swim -qinTg hamradio'' to help in making editing decisions for --stdin.
--root allows a database to be found for a Debian distribution installed on a different partition. If the distribution is mounted on /New_Debian, ``/New_Debian'' would be the argument to root. The databases would be found for the Debian distribution installed on the ``/New_Debian'' partition.
--dbpath and --root can be used together. Given the previous two examples, the databases would be found on ``/New_Debian/otherstuff'', assuming ``/New_Debian/otherstuff'' actually existed.