summaryrefslogtreecommitdiffstats
path: root/doc/pacman.8
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pacman.8')
-rw-r--r--doc/pacman.8334
1 files changed, 334 insertions, 0 deletions
diff --git a/doc/pacman.8 b/doc/pacman.8
new file mode 100644
index 00000000..15f48b60
--- /dev/null
+++ b/doc/pacman.8
@@ -0,0 +1,334 @@
+.TH pacman 8 "January 21, 2006" "pacman @PACKAGE_VERSION@" ""
+.SH NAME
+pacman \- package manager utility
+.SH SYNOPSIS
+\fBpacman <operation> [options] <package> [package] ...\fP
+.SH DESCRIPTION
+\fBpacman\fP is a \fIpackage management\fP utility that tracks installed
+packages on a linux system. It has simple dependency support and the ability
+to connect to a remote ftp server and automatically upgrade packages on
+the local system. pacman package are \fIgzipped tar\fP format.
+.SH OPERATIONS
+.TP
+.B "\-A, \-\-add"
+Add a package to the system. Package will be uncompressed
+into the installation root and the database will be updated.
+.TP
+.B "\-F, \-\-freshen"
+This is like --upgrade except that, unlike --upgrade, this will only
+upgrade packages that are already installed on your system.
+.TP
+.B "\-Q, \-\-query"
+Query the package database. This operation allows you to
+view installed packages and their files, as well as meta-info
+about individual packages (dependencies, conflicts, install date,
+build date, size). This can be run against the local package
+database or can be used on individual .tar.gz packages. See
+\fBQUERY OPTIONS\fP below.
+.TP
+.B "\-R, \-\-remove"
+Remove a package from the system. Files belonging to the
+specified package will be deleted, and the database will
+be updated. Most configuration files will be saved with a
+\fI.pacsave\fP extension unless the \fB--nosave\fP option was
+used.
+.TP
+.B "\-S, \-\-sync"
+Synchronize packages. With this function you can install packages
+directly from the ftp servers, complete with all dependencies required
+to run the packages. For example, \fBpacman -S qt\fP will download
+qt and all the packages it depends on and install them. You could also use
+\fBpacman -Su\fP to upgrade all packages that are out of date (see below).
+.TP
+.B "\-U, \-\-upgrade"
+Upgrade a package. This is essentially a "remove-then-add"
+process. See \fBHANDLING CONFIG FILES\fP for an explanation
+on how pacman takes care of config files.
+.TP
+.B "\-V, \-\-version"
+Display version and exit.
+.TP
+.B "\-h, \-\-help"
+Display syntax for the given operation. If no operation was
+supplied then the general syntax is shown.
+.SH OPTIONS
+.TP
+.B "\-d, \-\-nodeps"
+Skips all dependency checks. Normally, pacman will always check
+a package's dependency fields to ensure that all dependencies are
+installed and there are no package conflicts in the system. This
+switch disables these checks.
+.TP
+.B "\-f, \-\-force"
+Bypass file conflict checks, overwriting conflicting files. If the
+package that is about to be installed contains files that are already
+installed, this option will cause all those files to be overwritten.
+This option should be used with care, ideally not at all.
+.TP
+.B "\-r, \-\-root <path>"
+Specify alternative installation root (default is "/"). This
+should \fInot\fP be used as a way to install software into
+e.g. /usr/local instead of /usr. Instead this should be used
+if you want to install a package on a temporary mounted partition,
+which is "owned" by another system. By using this option you not only
+specify where the software should be installed, but you also
+specify which package database to use.
+.TP
+.B "\-v, \-\-verbose"
+Output more status and error messages.
+.TP
+.B "\-\-config <path>"
+Specify an alternate configuration file.
+.TP
+.B "\-\-noconfirm"
+Bypass any and all "Are you sure?" messages. It's not a good idea to do this
+unless you want to run pacman from a script.
+.TP
+.B "\-\-noprogressbar"
+Do not show a progress bar when downloading files. This can be useful for
+scripts that call pacman and capture the output.
+.SH SYNC OPTIONS
+.TP
+.B "\-c, \-\-clean"
+Remove old packages from the cache. When pacman downloads packages,
+it saves them in \fI/var/cache/pacman/pkg\fP. If you need to free up
+diskspace, you can remove these packages by using the --clean option.
+Using one --clean (or -c) switch will only remove \fIold\fP packages.
+Use it twice to remove \fIall\fP packages from the cache.
+.TP
+.B "\-g, \-\-groups"
+Display all the members for each package group specified. If no group
+names are provided, all groups will be listed.
+.TP
+.B "\-i, \-\-info"
+Display dependency information for a given package. This will search
+through all repositories for a matching package and display the
+dependencies, conflicts, etc.
+.TP
+.B "\-l, \-\-list"
+List all files in the specified repositories. Multiple repositories can
+be specified on the command line.
+.TP
+.B "\-p, \-\-print-uris"
+Print out URIs for each package that will be installed, including any
+dependencies that have yet to be installed. These can be piped to a
+file and downloaded at a later time, using a program like wget.
+.TP
+.B "\-s, \-\-search <regexp>"
+This will search each package in the package list for names or descriptions
+that matches <regexp>.
+.TP
+.B "\-u, \-\-sysupgrade"
+Upgrades all packages that are out of date. pacman will examine every
+package installed on the system, and if a newer package exists on the
+server it will upgrade. pacman will present a report of all packages
+it wants to upgrade and will not proceed without user confirmation.
+Dependencies are automatically resolved at this level and will be
+installed/upgraded if necessary.
+.TP
+.B "\-w, \-\-downloadonly"
+Retrieve all packages from the server, but do not install/upgrade anything.
+.TP
+.B "\-y, \-\-refresh"
+Download a fresh copy of the master package list from the ftp server
+defined in \fI/etc/pacman.conf\fP. This should typically be used each
+time you use \fB--sysupgrade\fP.
+.TP
+.B "\-\-ignore <pkg>"
+This option functions exactly the same as the \fBIgnorePkg\fP configuration
+directive. Sometimes it can be handy to skip some package updates without
+having to edit \fIpacman.conf\fP each time.
+.SH REMOVE OPTIONS
+.TP
+.B "\-c, \-\-cascade"
+Remove all target packages, as well as all packages that depend on one
+or more target packages. This operation is recursive.
+.TP
+.B "\-k, \-\-keep"
+Removes the database entry only. Leaves all files in place.
+.TP
+.B "\-n, \-\-nosave"
+Instructs pacman to ignore file backup designations. Normally, when
+a file is about to be \fIremoved\fP from the system the database is first
+checked to see if the file should be renamed to a .pacsave extension. If
+\fB--nosave\fP is used, these designations are ignored and the files are
+removed.
+.TP
+.B "\-s, \-\-recursive"
+For each target specified, remove it and all its dependencies, provided
+that (A) they are not required by other packages; and (B) they were not
+explicitly installed by the user.
+This option is analagous to a backwards --sync operation.
+.SH QUERY OPTIONS
+.TP
+.B "\-e, \-\-orphans"
+List all packages that were explicitly installed (ie, not pulled in
+as a dependency by other packages) and are not required by any other
+packages.
+.TP
+.B "\-g, \-\-groups"
+Display all package members of a named group, or all grouped packages if
+no name is specified.
+.TP
+.B "\-i, \-\-info"
+Display information on a given package. If it is used with the \fB-p\fP
+option then the .PKGINFO file will be printed.
+.TP
+.B "\-l, \-\-list"
+List all files owned by <package>. Multiple packages can be specified on
+the command line.
+.TP
+.B "\-m, \-\-foreign"
+List all packages that were not found in the sync database(s). Typically these
+are packages that were downloaded manually and installed with --add.
+.TP
+.B "\-o, \-\-owns <file>"
+Search for the package that owns <file>.
+.TP
+.B "\-p, \-\-file"
+Tells pacman that the package supplied on the command line is a
+file, not an entry in the database. Pacman will decompress the
+file and query it. This is useful with \fB--info\fP and \fB--list\fP.
+.TP
+.B "\-s, \-\-search <regexp>"
+This will search each locally-installed package for names or descriptions
+that matches <regexp>.
+.SH HANDLING CONFIG FILES
+pacman uses the same logic as rpm to determine action against files
+that are designated to be backed up. During an upgrade, it uses 3
+md5 hashes for each backup file to determine the required action:
+one for the original file installed, one for the new file that's about
+to be installed, and one for the actual file existing on the filesystem.
+After comparing these 3 hashes, the follow scenarios can result:
+.TP
+original=\fBX\fP, current=\fBX\fP, new=\fBX\fP
+All three files are the same, so we win either way. Install the new file.
+.TP
+original=\fBX\fP, current=\fBX\fP, new=\fBY\fP
+The current file is un-altered from the original but the new one is
+different. Since the user did not ever modify the file, and the new
+one may contain improvements/bugfixes, we install the new file.
+.TP
+original=\fBX\fP, current=\fBY\fP, new=\fBX\fP
+Both package versions contain the exact same file, but the one
+on the filesystem has been modified since. In this case, we leave
+the current file in place.
+.TP
+original=\fBX\fP, current=\fBY\fP, new=\fBY\fP
+The new one is identical to the current one. Win win. Install the new file.
+.TP
+original=\fBX\fP, current=\fBY\fP, new=\fBZ\fP
+All three files are different, so we install the new file with a .pacnew
+extension and warn the user, so she can manually move the file into place
+after making any necessary customizations.
+.SH CONFIGURATION
+pacman will attempt to read \fI/etc/pacman.conf\fP each time it is invoked. This
+configuration file is divided into sections or \fIrepositories\fP. Each section
+defines a package repository that pacman can use when searching for packages in
+--sync mode. The exception to this is the \fIoptions\fP section, which defines
+global options.
+.TP
+.SH Example:
+.RS
+.nf
+[options]
+NoUpgrade = etc/passwd etc/group etc/shadow
+NoUpgrade = etc/fstab
+
+Include = /etc/pacman.d/current
+
+[custom]
+Server = file:///home/pkgs
+
+.fi
+.RE
+.SH CONFIG: OPTIONS
+.TP
+.B "DBPath = path/to/db/dir"
+Overrides the default location of the toplevel database directory. The default is
+\fIvar/lib/pacman\fP.
+.B "CacheDir = path/to/cache/dir"
+Overrides the default location of the package cache directory. The default is
+\fIvar/cache/pacman\fP.
+.TP
+.TP
+.B "HoldPkg = <package> [package] ..."
+If a user tries to \fB--remove\fP a package that's listed in HoldPkg, pacman
+will ask for confirmation before proceeding.
+.TP
+.B "IgnorePkg = <package> [package] ..."
+Instructs pacman to ignore any upgrades for this package when performing a
+\fB--sysupgrade\fP.
+.TP
+.B "Include = <path>"
+Include another config file. This config file can include repositories or
+general configuration options.
+.TP
+.B "ProxyServer = <host|ip>[:port]"
+If set, pacman will use this proxy server for all ftp/http transfers.
+.TP
+.B "XferCommand = /path/to/command %u"
+If set, pacman will use this external program to download all remote files.
+All instances of \fB%u\fP will be replaced with the URL to be downloaded. If
+present, instances of \fB%o\fP will be replaced with the local filename, plus a
+".part" extension, which allows programs like wget to do file resumes properly.
+
+This option is useful for users who experience problems with pacman's built-in http/ftp
+support, or need the more advanced proxy support that comes with utilities like
+wget.
+.TP
+.B "NoPassiveFtp"
+Disables passive ftp connections when downloading packages. (aka Active Mode)
+.TP
+.B "NoUpgrade = <file> [file] ..."
+All files listed with a \fBNoUpgrade\fP directive will never be touched during a package
+install/upgrade. \fINote:\fP do not include the leading slash when specifying files.
+.TP
+.B "NoExtract = <file> [file] ..."
+All files listed with a \fBNoExtract\fP directive will never be extracted from
+a package into the filesystem. This can be useful when you don't want part of
+a package to be installed. For example, if your httpd root uses an index.php,
+then you would not want the index.html file to be extracted from the apache
+package.
+.TP
+.B "UseSyslog"
+Log action messages through syslog(). This will insert pacman log entries into your
+/var/log/messages or equivalent.
+.TP
+.B "LogFile = /path/to/file"
+Log actions directly to a file, usually /var/log/pacman.log.
+
+.SH CONFIG: REPOSITORIES
+Each repository section defines a section name and at least one location where the packages
+can be found. The section name is defined by the string within square brackets (eg, the two
+above are 'current' and 'custom'). Locations are defined with the \fIServer\fP directive and
+follow a URL naming structure. Currently only ftp is supported for remote servers. If you
+want to use a local directory, you can specify the full path with a 'file://' prefix, as
+shown above.
+The order of repositories in the file matters; repositories listed first will
+take precidence over those listed later in the file when packages in two
+repositories have identical names, regardless of version number.
+.SH USING YOUR OWN REPOSITORY
+Let's say you have a bunch of custom packages in \fI/home/pkgs\fP and their respective PKGBUILD
+files are all in \fI/var/abs/local\fP. All you need to do is generate a compressed package database
+in the \fI/home/pkgs\fP directory so pacman can find it when run with --refresh.
+
+.RS
+.nf
+# gensync /var/abs/local /home/pkgs/custom.db.tar.gz
+.fi
+.RE
+
+The above command will read all PKGBUILD files in /var/abs/local and generate a compressed
+database called /home/pkgs/custom.db.tar.gz. Note that the database must be of the form
+\fI{treename}.db.tar.gz\fP, where {treename} is the name of the section defined in the
+configuration file.
+That's it! Now configure your \fIcustom\fP section in the configuration file as shown in the
+config example above. Pacman will now use your package repository. If you add new packages to
+the repository, remember to re-generate the database and use pacman's --refresh option.
+.SH SEE ALSO
+\fBmakepkg\fP is the package-building tool that comes with pacman.
+.SH AUTHOR
+.nf
+Judd Vinet <jvinet@zeroflux.org>
+.fi