diff options
Diffstat (limited to 'doc/pacman.8.asciidoc')
| -rw-r--r-- | doc/pacman.8.asciidoc | 568 |
1 files changed, 568 insertions, 0 deletions
diff --git a/doc/pacman.8.asciidoc b/doc/pacman.8.asciidoc new file mode 100644 index 00000000..b6f4dd76 --- /dev/null +++ b/doc/pacman.8.asciidoc @@ -0,0 +1,568 @@ +pacman(8) +========= + +Name +---- +pacman - package manager utility + + +Synopsis +-------- +'pacman' <operation> [options] [targets] + + +Description +----------- +Pacman is a package management utility that tracks installed packages on a Linux +system. It features dependency support, package groups, install and uninstall +scripts, and the ability to sync your local machine with a remote repository to +automatically upgrade packages. Pacman packages are a zipped tar format. + +Since version 3.0.0, pacman has been the front-end to linkman:libalpm[3], the +``Arch Linux Package Management'' library. This library allows alternative +front-ends to be written (for instance, a GUI front-end). + +Invoking pacman involves specifying an operation with any potential options and +targets to operate on. A 'target' is usually a package name, file name, URL, or +a search string. Targets can be provided as command line arguments. +Additionally, if stdin is not from a terminal and a single hyphen (-) is passed +as an argument, targets will be read from stdin. + + +Operations +---------- +*-D, \--database*:: + Operate on the package database. This operation allows you to modify + certain attributes of the installed packages in pacman's database. It + also allows you to check the databases for internal consistency. + See <<DO,Database Options>> below. + +*-Q, \--query*:: + Query the package database. This operation allows you to view installed + packages and their files, as well as meta-information 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 package files. In the first case, if no package names + are provided in the command line, all installed packages will be + queried. Additionally, various filters can be applied on the package + list. See <<QO,Query Options>> below. + +*-R, \--remove*:: + Remove package(s) from the system. Groups can also be specified to be + removed, in which case every package in that group will be removed. + Files belonging to the specified package will be deleted, and the + database will be updated. Most configuration files will be saved + with a '.pacsave' extension unless the '\--nosave' option is used. + See <<RO,Remove Options>> below. + +*-S, \--sync*:: + Synchronize packages. Packages are installed directly from the remote + repositories, including all dependencies required to run the packages. For + example, `pacman -S qt` will download and install qt and all the + packages it depends on. If a package name exists in more than one + repository, the repository can be explicitly specified to clarify the + package to install: `pacman -S testing/qt`. You can also specify version + requirements: `pacman -S "bash>=3.2"`. Quotes are needed, otherwise the + shell interprets ">" as redirection to a file. ++ +In addition to packages, groups can be specified as well. For example, if +gnome is a defined package group, then `pacman -S gnome` will provide a +prompt allowing you to select which packages to install from a numbered list. +The package selection is specified using a space- and/or comma-separated list of +package numbers. Sequential packages may be selected by specifying the first +and last package numbers separated by a hyphen (`-`). Excluding packages is +achieved by prefixing a number or range of numbers with a caret (`^`). ++ +Packages that provide other packages are also handled. For example, `pacman -S +foo` will first look for a foo package. If foo is not found, packages that +provide the same functionality as foo will be searched for. If any package is +found, it will be installed. A selection prompt is provided if multiple packages +providing foo are found. ++ +You can also use `pacman -Su` to upgrade all packages that are out-of-date. See +<<SO,Sync Options>> below. When upgrading, pacman performs version comparison +to determine which packages need upgrading. This behavior operates as follows: + + Alphanumeric: + 1.0a < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0 < 1.0.a < 1.0.1 + Numeric: + 1 < 1.0 < 1.1 < 1.1.1 < 1.2 < 2.0 < 3.0.0 ++ +Additionally, version strings can have an 'epoch' value defined that will +overrule any version comparison, unless the epoch values are equal. This is +specified in an `epoch:version-rel` format. For example, `2:1.0-1` is always +greater than `1:3.6-1`. + +*-T, \--deptest*:: + Check dependencies; this is useful in scripts such as makepkg to check + installed packages. This operation will check each dependency specified and + return a list of dependencies that are not currently satisfied on the system. + This operation accepts no other options. Example usage: `pacman -T qt + "bash>=3.2"`. + +*-U, \--upgrade*:: + Upgrade or add package(s) to the system and install the required + dependencies from sync repositories. Either a URL or file path can be + specified. This is a ``remove-then-add'' process. See <<UO,Upgrade + Options>> below; also see <<HCF,Handling Config Files>> for an explanation + on how pacman takes care of configuration files. + +*-F, \--files*:: + Query the files database. This operation allows you to look for packages + owning certain files or display files owned by certain packages. Only + packages that are part of your sync databases are searched. See + <<FO,File Options>> below. + +*-V, \--version*:: + Display version and exit. + +*-h, \--help*:: + Display syntax for the given operation. If no operation was supplied, + then the general syntax is shown. + + +Options +------- +*-b, \--dbpath* <path>:: + Specify an alternative database location (the default is + +{localstatedir}/lib/pacman+). This should not be used unless you know what + you are doing. + *NOTE*: If specified, this is an absolute path, and the root path is + not automatically prepended. + +*-v, \--verbose*:: + Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc. + +*\--arch* <arch>:: + Specify an alternate architecture. + +*\--cachedir* <dir>:: + Specify an alternative package cache location (the default is + +{localstatedir}/cache/pacman/pkg+). Multiple cache directories can be + specified, and they are tried in the order they are passed to pacman. + *NOTE*: This is an absolute path, and the root path is not automatically + prepended. + +*\--color* <when>:: + Specify when to enable coloring. Valid options are 'always', 'never', or + 'auto'. 'always' forces colors on; 'never' forces colors off; and 'auto' only + automatically enables colors when outputting onto a tty. + +*\--config* <file>:: + Specify an alternate configuration file. + +*\--debug*:: + Display debug messages. When reporting bugs, this option is recommended + to be used. + +*\--gpgdir* <dir>:: + Specify a directory of files used by GnuPG to verify package signatures + (the default is +{sysconfdir}/pacman.d/gnupg+). This directory should contain + two files: `pubring.gpg` and `trustdb.gpg`. `pubring.gpg` holds the public keys + of all packagers. `trustdb.gpg` contains a so-called trust database, which + specifies that the keys are authentic and trusted. *NOTE*: This is an absolute + path, and the root path is not automatically prepended. + +*\--hookdir* <dir>:: + Specify a alternative directory containing hook files (the default is + +{sysconfdir}/pacman.d/hooks+). Multiple hook directories can be specified + with hooks in later directories taking precedence over hooks in earlier + directories. *NOTE*: This is an absolute path, and the root path is not + automatically prepended. + +*\--logfile* <file>:: + Specify an alternate log file. This is an absolute path, regardless of + the installation root setting. + +*\--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. + +*\--confirm*:: + Cancels the effects of a previous '\--noconfirm'. + +*\--disable-download-timeout*:: + Disable defaults for low speed limit and timeout on downloads. Use this + if you have issues downloading files with proxy and/or security gateway. + +*\--sysroot* <dir>:: + Specify an alternative system root. Pacman will chroot and chdir into the + system root prior to running. This allows mounted guest systems to be + properly operated on. Any other paths given will be interpreted as relative + to the system root. Requires root privileges. + + +Transaction Options (apply to '-S', '-R' and '-U') +-------------------------------------------------- +*-d, \--nodeps*:: + Skips dependency version checks. Package names are still checked. 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. Specify this option twice to skip all dependency checks. + +*\--assume-installed* <package=version>:: + Add a virtual package "package" with version "version" to the transaction + to satisfy dependencies. This allows to disable specific dependency checks + without affecting all dependency checks. To disable all dependency + checking, see the '\--nodeps' option. + +*\--dbonly*:: + Adds/removes the database entry only, leaving all files in place. + +*\--noprogressbar*:: + Do not show a progress bar when downloading files. This can be useful + for scripts that call pacman and capture the output. + +*\--noscriptlet*:: + If an install scriptlet exists, do not execute it. Do not use this + unless you know what you are doing. + +*-p, \--print*:: + Only print the targets instead of performing the actual operation (sync, + remove or upgrade). Use '\--print-format' to specify how targets are + displayed. The default format string is "%l", which displays URLs with + '-S', file names with '-U', and pkgname-pkgver with '-R'. + +*\--print-format* <format>:: + Specify a printf-like format to control the output of the '\--print' + operation. The possible attributes are: "%n" for pkgname, "%v" for pkgver, + "%l" for location, "%r" for repository, and "%s" for size. Implies '\--print'. + + +Upgrade Options (apply to '-S' and '-U')[[UO]] +---------------------------------------------- +*\--asdeps*:: + Install packages non-explicitly; in other words, fake their install reason + to be installed as a dependency. This is useful for makepkg and other + build-from-source tools that need to install dependencies before building + the package. + +*\--asexplicit*:: + Install packages explicitly; in other words, fake their install reason to + be explicitly installed. This is useful if you want to mark a dependency + as explicitly installed so it will not be removed by the '\--recursive' + remove operation. + +*\--ignore* <package>:: + Directs pacman to ignore upgrades of package even if there is one + available. Multiple packages can be specified by separating them + with a comma. + +*\--ignoregroup* <group>:: + Directs pacman to ignore upgrades of all packages in 'group', even if + there is one available. Multiple groups can be specified by + separating them with a comma. + +*\--needed*:: + Do not reinstall the targets that are already up-to-date. + +*\--overwrite* <glob>:: + Bypass file conflict checks and overwrite conflicting files. If the + package that is about to be installed contains files that are already + installed and match 'glob', this option will cause all those files to be + overwritten. Using '\--overwrite' will not allow overwriting a directory + with a file or installing packages with conflicting files and directories. + Multiple patterns can be specified by separating them with a comma. May be + specified multiple times. Patterns can be negated, such that files + matching them will not be overwritten, by prefixing them with an + exclamation mark. Subsequent matches will override previous ones. A leading + literal exclamation mark or backslash needs to be escaped. + + +Query Options (apply to '-Q')[[QO]] +----------------------------------- +*-c, \--changelog*:: + View the ChangeLog of a package if it exists. + +*-d, \--deps*:: + Restrict or filter output to packages installed as dependencies. This + option can be combined with '-t' for listing real orphans - packages that + were installed as dependencies but are no longer required by any + installed package. + +*-e, \--explicit*:: + Restrict or filter output to explicitly installed packages. This option + can be combined with '-t' to list explicitly installed packages that + are not required by any other package. + +*-g, \--groups*:: + Display all packages that are members of a named group. If a name is not + specified, list all grouped packages. + +*-i, \--info*:: + Display information on a given package. The '-p' option can be used if + querying a package file instead of the local database. Passing two + '\--info' or '-i' flags will also display the list of backup files and + their modification states. + +*-k, \--check*:: + Check that all files owned by the given package(s) are present on the + system. If packages are not specified or filter flags are not provided, + check all installed packages. Specifying this option twice will perform + more detailed file checking (including permissions, file sizes, and + modification times) for packages that contain the needed mtree file. + +*-l, \--list*:: + List all files owned by a given package. Multiple packages can be + specified on the command line. + +*-m, \--foreign*:: + Restrict or filter output to packages that were not found in the sync + database(s). Typically these are packages that were downloaded manually + and installed with '\--upgrade'. + +*-n, \--native*:: + Restrict or filter output to packages that are found in the sync + database(s). This is the inverse filter of '\--foreign'. + +*-o, \--owns* <file>:: + Search for packages that own the specified file(s). The path can be + relative or absolute, and one or more files can be specified. + +*-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 in combination with '\--info' and '\--list'. + +*-q, \--quiet*:: + Show less information for certain query operations. This is useful when + pacman's output is processed in a script. Search will only show package + names and not version, group, and description information; owns will + only show package names instead of "file is owned by pkg" messages; group + will only show package names and omit group names; list will only show + files and omit package names; check will only show pairs of package names + and missing files; a bare query will only show package names + rather than names and versions. + +*-s, \--search* <regexp>:: + Search each locally-installed package for names or descriptions that + match `regexp`. When including multiple search terms, only packages + with descriptions matching ALL of those terms are returned. + +*-t, \--unrequired*:: + Restrict or filter output to print only packages neither required nor + optionally required by any currently installed package. Specify this + option twice to include packages which are optionally, but not directly, + required by another package. + +*-u, \--upgrades*:: + Restrict or filter output to packages that are out-of-date on the local + system. Only package versions are used to find outdated packages; + replacements are not checked here. This option works best if the sync + database is refreshed using '-Sy'. + + +Remove Options (apply to '-R')[[RO]] +------------------------------------ +*-c, \--cascade*:: + Remove all target packages, as well as all packages that depend on one + or more target packages. This operation is recursive and must be used + with care, since it can remove many potentially needed packages. + +*-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. + +*-s, \--recursive*:: + Remove each target specified including all of their dependencies, provided + that (A) they are not required by other packages; and (B) they were not + explicitly installed by the user. This operation is recursive and analogous + to a backwards '\--sync' operation, and it helps keep a clean system without + orphans. If you want to omit condition (B), pass this option twice. + +*-u, \--unneeded*:: + Removes targets that are not required by any other packages. + This is mostly useful when removing a group without using the '-c' option, + to avoid breaking any dependencies. + + +Sync Options (apply to '-S')[[SO]] +---------------------------------- +*-c, \--clean*:: + Remove packages that are no longer installed from the cache as well as + currently unused sync databases to free up disk space. When pacman + downloads packages, it saves them in a cache directory. In addition, + databases are saved for every sync DB you download from and are not + deleted even if they are removed from the configuration file + linkman:pacman.conf[5]. Use one '\--clean' switch to only remove + packages that are no longer installed; use two to remove all files + from the cache. In both cases, you will have a yes or no option to + remove packages and/or unused downloaded databases. ++ +If you use a network shared cache, see the 'CleanMethod' option in +linkman:pacman.conf[5]. + +*-g, \--groups*:: + Display all the members for each package group specified. If no group + names are provided, all groups will be listed; pass the flag twice to + view all groups and their members. + +*-i, \--info*:: + Display information on a given sync database package. Passing two '\--info' + or '-i' flags will also display those packages in all repositories that + depend on this package. + +*-l, \--list*:: + List all packages in the specified repositories. Multiple repositories + can be specified on the command line. + +*-q, \--quiet*:: + Show less information for certain sync operations. This is useful when + pacman's output is processed in a script. Search will only show package + names and not repository, version, group, and description information; list + will only show package names and omit databases and versions; group will + only show package names and omit group names. + +*-s, \--search* <regexp>:: + This will search each package in the sync databases for names or + descriptions that match `regexp`. When you include multiple search + terms, only packages with descriptions matching ALL of those terms will + be returned. + +*-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. ++ +Pass this option twice to enable package downgrades; in this case, pacman will +select sync packages whose versions do not match with the local versions. This +can be useful when the user switches from a testing repository to a stable one. ++ +Additional targets can also be specified manually, so that '-Su foo' will do a +system upgrade and install/upgrade the "foo" package in the same operation. + +*-w, \--downloadonly*:: + Retrieve all packages from the server, but do not install/upgrade anything. + +*-y, \--refresh*:: + Download a fresh copy of the master package database from the server(s) + defined in linkman:pacman.conf[5]. This should typically be used each time + you use '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags + will force a refresh of all package databases, even if they appear to be + up-to-date. + + +Database Options (apply to '-D')[[QO]] +-------------------------------------- +*\--asdeps* <package>:: + Mark a package as non-explicitly installed; in other words, set their install + reason to be installed as a dependency. + +*\--asexplicit* <package>:: + Mark a package as explicitly installed; in other words, set their install + reason to be explicitly installed. This is useful it you want to keep a + package installed even when it was initially installed as a dependency + of another package. + +*-k, \--check*:: + Check the local package database is internally consistent. This will + check all required files are present and that installed packages have + the required dependencies, do not conflict and that multiple packages + do not own the same file. Specifying this option twice will perform + a check on the sync databases to ensure all specified dependencies + are available. + +*-q, \--quiet*:: + Suppress messages on successful completion of database operations. + +File Options (apply to '-F')[[FO]] +---------------------------------- +*-y, --refresh*:: + Download fresh package databases from the server. Use twice to force a + refresh even if databases are up to date. + +*-l, \--list*:: + List the files owned by the queried package. + +*-s, \--search*:: + Search package file names for matching strings. + +*-x, --regex*:: + Treat arguments to '--search' as regular expressions. + +*-o, \--owns*:: + Search for packages that own a particular file. + +*-q, \--quiet*:: + Show less information for certain file operations. This is useful when + pacman's output is processed in a script, however, you may want to use + '--machinereadable' instead. + +*--machinereadable*:: + Use a machine readable output format for '--list', '--search' and + '--owns'. The format is 'repository\0pkgname\0pkgver\0path\n' with '\0' + being the NULL character and '\n' a linefeed. + +Handling Config Files[[HCF]] +---------------------------- +Pacman uses the same logic as 'rpm' to determine action against files that are +designated to be backed up. During an upgrade, three 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 is about to be installed, and one for the +actual file existing on the file system. After comparing these three hashes, the +follow scenarios can result: + +original=X, current=X, new=X:: + All three files are the same, so overwrites are not an issue. Install the + new file. + +original=X, current=X, new=Y:: + 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 bug fixes, install the new file. + +original=X, current=Y, new=X:: + Both package versions contain the exact same file, but the one on the + file system has been modified. Leave the current file in place. + +original=X, current=Y, new=Y:: + The new file is identical to the current file. Install the new file. + +original=X, current=Y, new=Z:: + 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. + +original=NULL, current=Y, new=Z:: + The package was not previously installed, and the file already exists on the + file system. 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. + + +Examples +-------- + +pacman -Ss ne.hack:: + Search for regexp "ne.hack" in package database. + +pacman -S gpm:: + Download and install gpm including dependencies. + +pacman -U /home/user/ceofhack-0.6-1-x86_64.pkg.tar.gz:: + Install ceofhack-0.6-1 package from a local file. + +pacman -Syu:: + Update package list and upgrade all packages afterwards. + +pacman -Syu gpm:: + Update package list, upgrade all packages, and then install gpm if it + wasn't already installed. + + +Configuration +------------- +See linkman:pacman.conf[5] for more details on configuring pacman using the +'pacman.conf' file. + + +See Also +-------- +linkman:alpm-hooks[5], linkman:libalpm[3], linkman:makepkg[8], +linkman:pacman.conf[5] + +include::footer.asciidoc[] |