diff options
| -rw-r--r-- | doc/pacman.8.txt | 302 | ||||
| -rw-r--r-- | doc/pacman.conf.5.txt | 135 |
2 files changed, 437 insertions, 0 deletions
diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt new file mode 100644 index 00000000..79c58d7d --- /dev/null +++ b/doc/pacman.8.txt @@ -0,0 +1,302 @@ +PACMAN(8) +========= + +NAME +---- +pacman - package manager utility + + +SYNOPSIS +-------- +'pacman' <operation> [options] [packages] + + +DESCRIPTION +----------- +Pacman is a package management utility that tracks installed packages on a Linux +system. It features 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. Pacman packages are a zipped tar format. + +Since version 3.0.0, pacman has been the frontend to manlink:libalpm[3], the +"Arch Linux Package Management" library. This library allows alternative front +ends to be written (for instance, a GUI front end). + + +OPERATIONS +---------- +-A, --add (deprecated):: + Add a package to the system. Either a URL or file path can be specified. + The 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. *NOTE*: please use `--upgrade` in place of + this option. + +-F, --freshen:: + This is like `--upgrade` except it will only upgrade packages already + installed on the system. + +-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 `.tar.gz` packages. See <<QO,Query Options>> below. + +-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 `.pacsave` extension unless the + `--nosave` option is used. See <<RO,Remove Options>> below. + +-S, --sync:: + Synchronize packages. Packages are installed directly from the ftp + servers, 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. You can also use `pacman -Su` to upgrade all + packages that are out of date. See <<SO,Sync Options>> below. + +-U, --upgrade:: + Upgrade or add a package to the system. Either a URL or file path can be + specified. This is a "remove-then-add" process. See + <<HCF,Handling Config Files>> for an explanation on how + pacman takes care of config files. + +-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 +------- +--ask <number>:: + Pre-specify answers to questions. It is doubtful whether this option + even works, so I would not recommend using it. *TODO*: document this + more, as I have no idea how it works or when you would use it, or if we + should just dump it. + +-b, --dbpath <path>:: + Specify an alternative database location (default is `/var/lib/pacman`). + This should not be used unless you know what you are doing. + +-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. + +-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. + +-r, --root <path>:: + Specify an alternative installation root (default is `/`). This should + not be used as a way to install software into `/usr/local` instead of + `/usr`. This option is 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 and cache location to use. + +-v, --verbose:: + Output more status messages, such as the Root and DBPath. + +--cachedir <dir>:: + Specify an alternative package cache location (default is + `/var/cache/pacman/pkg`). This should not be used unless you know what + you are doing. + +--config <file>:: + Specify an alternate configuration file. + +--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. + +--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. + + +Query Options[[QO]] +------------------- +-c, --changelog:: + View the ChangeLog of a package. Not every package will provide one but + it will be shown if available. + +-e, --orphans:: + List all packages that were pulled in by a previously installed package + but no longer required by any installed package. + +-g, --groups:: + Display all packages that are members of a named group. If not name is + 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. + +-l, --list:: + List all files owned by a given package. Multiple packages can be + specified on the command line. + +-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 + `--upgrade`. + +-o, --owns <file>:: + Search for the package that owns file. + +-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`. + +-s, --search <regexp>:: + This will search each locally-installed package for names or + descriptions that matche regexp. + +-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 `-Sy`. + + +Remove Options[[RO]] +-------------------- +-c, --cascade:: + Remove all target packages, as well as all packages that depend on one + or more target packages. This operation is recursive. + +-k, --keep:: + Removes the database entry only. Leaves all files in place. + +-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 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 `--sync` operation. + + +Sync Options[[SO]] +------------------ +-c, --clean:: + Remove old packages from the cache to free up disk space. When pacman + downloads packages, it saves them in `/var/cache/pacman/pkg`. Use one + `--clean` switch to remove old packages; use two to remove all packages + from the cache. + +-e, --dependsonly:: + Install all dependencies of a package, but not the specified package + itself. This is pretty useless and we're not sure why it even exists. + +-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 dependency and other information for a given package. This will + search through all repositories for a matching package. + +-l, --list:: + List all packages in the specified repositories. Multiple repositories + can be specified on the command line. + +-p, --print-uris:: + Print out URIs for each package that will be installed, including any + dependencies yet to be installed. These can be piped to a file and + downloaded at a later time, using a program like wget. + +-s, --search <regexp>:: + This will search each package in the sync databases for names or + descriptions that match regexp. + +-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. + +-w, --downloadonly:: + Retrieve all packages from the server, but do not install/upgrade + anything. + +-y, --refresh:: + Download a fresh copy of the master package list from the server(s) + defined in pacman.conf. 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 lists even if they are thought to be up to date. + +--ignore <package>:: + Directs pacman to ignore upgrades of package even if there is one + available. + + +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, 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: + +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 bugfixes, install the new file. + +original=X, current=Y, new=X:: + Both package versions contain the exact same file, but the one on the + filesystem 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. + + +Configuration +------------- +See manlink:pacman.conf[5] for more details on configuring pacman using the +`pacman.conf` file. + + +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. + + +See Also +-------- +manlink:pacman.conf[5], manlink:makepkg[8], manlink:libalpm[3] + +See the Arch Linux website at http://www.archlinux.org for more current +information on the distribution and the pacman family of tools. + + +include::footer.txt[] diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt new file mode 100644 index 00000000..89ca47f0 --- /dev/null +++ b/doc/pacman.conf.5.txt @@ -0,0 +1,135 @@ +pacman.conf(5) +============== + +NAME +---- +pacman.conf - pacman package manager configuration file + + +DESCRIPTION +----------- +Pacman, using manlink:libalpm[3], will attempt to read `pacman.conf` each +time it is invoked. This configuration file is divided into sections or +repositories. Each section defines a package repository that pacman can use +when searching for packages in `--sync` mode. The exception to this is the +options section, which defines global options. + + +EXAMPLE +------- +-------- +# +# pacman.conf +# +[options] +NoUpgrade = etc/passwd etc/group etc/shadow +NoUpgrade = etc/fstab + +[current] +Include = /etc/pacman.d/current + +[custom] +Server = file:///home/pkgs +-------- + + +OPTIONS +------- +DBPath = path/to/db/dir:: + Overrides the default location of the toplevel database directory. + The default is `var/lib/pacman`. + +CacheDir = path/to/cache/dir:: + Overrides the default location of the package cache directory. The + default is `var/cache/pacman`. + +HoldPkg = package ...:: + If a user tries to `--remove` a package that's listed in `HoldPkg`, + pacman will ask for confirmation before proceeding. + +IgnorePkg = package ...:: + Instructs pacman to ignore any upgrades for this package when performing + a `--sysupgrade`. + +Include = path:: + Include another config file. This file can include repositories or + general configuration options. + +XferCommand = /path/to/command %u:: + If set, an external program will be used to download all remote files. + All instances of `%u` will be replaced with the download URL. If present, + instances of `%o` 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 built-in + http/ftp support, or need the more advanced proxy support that comes with + utilities like wget. + +NoPassiveFtp:: + Disables passive ftp connections when downloading packages. (aka Active Mode) + +NoUpgrade = file ...:: + All files listed with a `NoUpgrade` directive will never be touched during + a package install/upgrade. Do not include the leading slash when specifying + files. + +NoExtract = file ...:: + All files listed with a `NoExtract` 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. + +UseSyslog:: + Log action messages through syslog(). This will insert log entries into + `/var/log/messages` or equivalent. + +LogFile = /path/to/file:: + Log actions directly to a file. Default is `/var/log/pacman.log`. + +ShowSize:: + Display the size of individual packages for `--sync` and `--query` modes. + + +Repository Sections +------------------- +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 (the two above are 'current' and 'custom'). Locations are +defined with the `Server` directive and follow a URL naming structure. 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 precedence over those listed later in the file when packages in two +repositories have identical names, regardless of version number. + +Using Your Own Repository +------------------------- +If you have numerous custom packages of your own, it is often easier to generate +your own custom local repository than install them all with the `--upgrade` +option. All you need to do is generate a compressed package database in the +directory with these packages so pacman can find it when run with `--refresh`. + + repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz + +The above command will generate a compressed database named +`/home/pkgs/custom.db.tar.gz`. Note that the database must be of the form +`{treename}.db.tar.gz`, where `{treename}` is the name of the section defined in +the configuration file. That's it! Now configure your custom 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. + +For more information on the repo-add command, use `repo-add --help`. + + +See Also +-------- +manlink:pacman[8], manlink:libalpm[3] + +See the Arch Linux website at http://www.archlinux.org for more current +information on the distribution and the pacman family of tools. + + +include::footer.txt[] |