diff options
Diffstat (limited to 'doc/pacman.8')
| -rw-r--r-- | doc/pacman.8 | 488 |
1 files changed, 206 insertions, 282 deletions
diff --git a/doc/pacman.8 b/doc/pacman.8 index 15f48b60..b9ded2e9 100644 --- a/doc/pacman.8 +++ b/doc/pacman.8 @@ -1,334 +1,258 @@ -.TH pacman 8 "January 21, 2006" "pacman @PACKAGE_VERSION@" "" +." the string declarations are a start to try and make distro independent +.ds DS Arch Linux +.ds PB PKGBUILD +.ds VR 3.0.0 +.TH pacman 8 "Feb 07, 2007" "pacman version \*(VR" "\*(DS Utilities" .SH NAME pacman \- package manager utility + .SH SYNOPSIS -\fBpacman <operation> [options] <package> [package] ...\fP +.B pacman +<\fIoperation\fR> [\fIoptions\fR] [\fIpackages\fR] + .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. +packages on a Linux system. It has dependency support, package groups, install +and uninstall hooks, and the ability to sync your local machine with a remote +ftp server to automatically upgrade packages. \fBpacman\fP packages are a +zipped tar 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" +.B \-A, --add (deprecated) +Add a package to the system. Package will be uncompressed into the installation +root and the database will be updated. The package will not be installed if +another version is already installed. Please use \fB--upgrade\fP in place of +this option. +.TP +.B \-F, --freshen +This is like \fB--upgrade\fP except it will only upgrade packages already +installed on the 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 +is used. See \fBREMOVE OPTIONS\fP below. +.TP +.B \-S, --sync +Synchronize packages. Packages are installed directly from the ftp servers, +complete with all dependencies required to run the packages. For example, +\fBpacman -S qt\fP will download and install \fBqt\fP and all the packages it +depends on. You can also use \fBpacman -Su\fP to upgrade all packages that are +out of date. See \fBSYNC OPTIONS\fP below. +.TP +.B \-U, --upgrade +Upgrade or add a package to the system. This is 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. +.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>" +.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. +.TP +.B \-f, --force +Bypass file conflict checks and overwrite 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 \fIpath\fP +Specify alternative installation root (default is "/"). However, this should +\fInot\fP be used as a way to install software into /usr/local instead of /usr, +for example. This option 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 messages, such as the Root and DBPath. +.TP +.B \--config \fIfilepath\fP 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 +.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 +.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 + +.SH QUERY 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. +.B \-e, --orphans +List all packages that were pulled in by a previously installed package but no +longer required by any installed package. .TP -.B "\-g, \-\-groups" -Display all the members for each package group specified. If no group -names are provided, all groups will be listed. +.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 dependency information for a given package. This will search -through all repositories for a matching package and display the -dependencies, conflicts, etc. +.B \-i, --info +Display information on a given package. The \fB-p\fP option can be used if +querying a package file instead of the local database. .TP -.B "\-l, \-\-list" -List all files in the specified repositories. Multiple repositories can -be specified on the command line. +.B \-l, --list +List all files owned by a given package. Multiple packages 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. +.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 \fB--upgrade\fP. .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. +.B \-o, --owns \fIfile\fP +Search for the package that owns \fIfile\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. +.B \-p, --file +Signifies that the package supplied on the command line is a file and not an +entry in the database. The file will be decompressed and queried. This is +useful with \fB--info\fP and \fB--list\fP. +.TP +.B \-s, --search \fIregexp\fP +This will search each locally-installed package for names or descriptions that +matche \fIregexp\fP. +.TP +.B \-u, --upgrades +Lists all packages that are out of date on the local system. This option works best if the sync database is refreshed using \fB-Sy\fP. + .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 +.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 "\-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. +.B \-k, --keep +Removes the database entry only. Leaves all files in place. .TP -.B "\-g, \-\-groups" -Display all package members of a named group, or all grouped packages if -no name is specified. +.B \-n, --nosave +Instructs pacman to ignore file backup designations. Normally, when a file is +removed from the system the database is checked to see if the file should be +renamed with a .pacsave extension. .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. +.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 analogous to a backwards \fB--sync\fP +operation. + +.SH SYNC OPTIONS .TP -.B "\-l, \-\-list" -List all files owned by <package>. Multiple packages can be specified on -the command line. +.B \-c, --clean +Remove old packages from the cache to free up disk space. When \fBpacman\fP +downloads packages, it saves them in \fI/var/cache/pacman/pkg\fP. Use one +\fB--clean\fP switch to remove \fIold\fP packages; use two to remove \fIall\fP +packages from the cache. .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. +.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 and other information for a given package. This will search +through all repositories for a matching package. +.TP +.B \-l, --list +List all packages in the specified repositories. Multiple repositories can be +specified on the command line. .TP -.B "\-o, \-\-owns <file>" -Search for the package that owns <file>. +.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 \fIregexp\fP +This will search each package in the sync databases for names or descriptions +that match \fIregexp\fP. .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. +.B \-u, --sysupgrade +Upgrades all packages that are out of date. Each currently-installed package +will be examined and upgraded if a newer package exists. A report of all +packages to upgrade will be presented and the operation 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 "\-s, \-\-search <regexp>" -This will search each locally-installed package for names or descriptions -that matches <regexp>. +.B \-y, --refresh +Download a fresh copy of the master package list from the server(s) defined in +\fBpacman.conf\fP. This should typically be used each time you use +\fB--sysupgrade\fP. +.TP +.B \--ignore \fIpackage\fP +Directs \fBpacman\fP to ignore upgrades of \fIpackage\fP even if there is one +available. + .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: +pacman uses the same logic as rpm to determine action against files that are +designated to be backed up. During an upgrade, 3 md5 hashes are used 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. +All three files are the same, so overwrites are not an issue 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. +The current file is the same as the original but the new one differs. Since +the user did not ever modify the file, and the new one may contain improvements +or bugfixes, 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. +Both package versions contain the exact same file, but the one on the +filesystem has been modified. 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. +The new file is identical to the current file. 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 +All three files are different, so install the new file with a .pacnew extension +and warn the user. The user must then manually merge any necessary changes into +the original file. -[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. +.SH CONFIGURATION +See +.BR pacman.conf (5) +for more details on configuring pacman using the \fBpacman.conf\fP file. -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 BUGS +Bugs? You must be kidding, there are no bugs in this software. But if we happen +to be wrong, send us an email with as much detail as possible to +<pacman-dev@archlinux.org>. -.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. +.SH SEE ALSO +.BR pacman.conf (5), +.BR makepkg (8), +.BR libalpm (3) -.RS -.nf -# gensync /var/abs/local /home/pkgs/custom.db.tar.gz -.fi -.RE +See the Arch Linux website at <http://www.archlinux.org> for more current +information on the distribution and the \fBpacman\fP family of tools. -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 +.SH AUTHORS .nf Judd Vinet <jvinet@zeroflux.org> +Aurelien Foret <aurelien@archlinux.org> +Aaron Griffin <aaron@archlinux.org> +Dan McGee <dan@archlinux.org> +See the 'AUTHORS' file for additional contributors. .fi |