summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndrew Fyfe <andrew@neptune-one.net>2007-07-01 17:58:46 -0400
committerDan McGee <dan@archlinux.org>2007-07-09 13:47:55 -0400
commit2f7d2485f5c23223dad2b827d5c384837c878c5a (patch)
treeedb9a3039a473ed6e7ac84d975b2a4837eac5314
parent168b795f9eb12c08d70d05f2ee313165004564e3 (diff)
downloadpacman-2f7d2485f5c23223dad2b827d5c384837c878c5a.tar.xz
Add two asciidoc manpages to the doc/ dir
Add the pacman.8 and pacman.conf.5 asciidoc manpages to the GIT tree, with the rest to follow. Signed-off-by: Dan McGee <dan@archlinux.org>
-rw-r--r--doc/pacman.8.txt302
-rw-r--r--doc/pacman.conf.5.txt135
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[]