summaryrefslogtreecommitdiffstats
path: root/doc/pacman.8.asciidoc
diff options
context:
space:
mode:
authorEli Schwartz <eschwartz@archlinux.org>2018-05-03 06:10:21 +0200
committerAllan McRae <allan@archlinux.org>2018-05-14 01:59:17 +0200
commit076b6184de2b20e9b26225d93f6f3a7030504109 (patch)
treeca0e375b9fd89d6b6ce40026b732985c4b335841 /doc/pacman.8.asciidoc
parent860e4c4943ad062bd0eff99f28e7d64804b3c08e (diff)
downloadpacman-076b6184de2b20e9b26225d93f6f3a7030504109.tar.gz
pacman-076b6184de2b20e9b26225d93f6f3a7030504109.tar.xz
Ensure better text editor automatic filetype detection
Since we no longer use vim-specific modelines, use the .asciidoc file extension which is, well, reserved for asciidoc formatted files. This should presumably work everywhere without needing editor-specific workarounds and configuration. Also add a shebang to makepkg.conf to indicate it contains bash content. Signed-off-by: Eli Schwartz <eschwartz@archlinux.org> Signed-off-by: Allan McRae <allan@archlinux.org>
Diffstat (limited to 'doc/pacman.8.asciidoc')
-rw-r--r--doc/pacman.8.asciidoc568
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[]