Commit 791f93fc authored by Timo Teräs's avatar Timo Teräs

man pages: make more friendly for help generation

Also few minor fixups added.
parent 5258b484
......@@ -13,6 +13,12 @@ apk add - add packages to _world_ and commit changes
*apk add* adds the requested packages to _world_ and installs (or upgrades)
them if not already present, ensuring all dependencies are met.
To upgrade individual packages without modifying _world_ use *apk-fix*(8).
By default *apk* tries to select a set of packages so that all dependencies
are satisfied. This means that some packages can be held back in an older
version if there is direct or implicit dependencies to the older version.
# OPTIONS
*apk add* supports the commit options described in *apk*(8), as well as the
......@@ -22,22 +28,25 @@ following options:
Initialize a new package database.
*-l, --latest*
Disables normal heuristics for choosing which repository to install a
package from, preferring only repositories from which the latest
version is available. This has no effect on pinned packages.
Always choose the latest package by version. However, the versions
considered are based on the package pinning. Primarily this overrides
the default heuristic and will cause an error to displayed if all
dependencies cannot be satisfied.
*-u, --upgrade*
When adding packages which are already installed, upgrade them rather
than considering the requirement fulfilled by the current installation.
Upgrade _packages_ and it's dependencies. Normally *apk add* will
avoid changing installed package unless it is required by the newly
added _packages_ or their dependencies. This changes the default
preference to upgrading the package to the latest installable version.
*-t, --virtual* _NAME_
Instead of adding the specified packages to _world_, create a new
virtual package with the listed packages as its dependencies, then add
that package to _world_.
Create virtual package _NAME_ with given dependencies. This new package
will get the _packages_ as dependencies instead of _world_. Finally the
_NAME_ is added to _world_.
The packages requested are added as transitive dependencies of the
virtual package, and by deleting that package the *apk add* operation
may be easily reverted later.
One can use this to ensure that selected set of packages are installed,
and later the temporary modification be undone with *apk-del*(8) _NAME_
without removing packages that were installed earlier.
*--no-chown*
Do not change file owner or group. By default apk will manage the file
......
......@@ -10,10 +10,17 @@ apk audit - audit directories for changes
# DESCRIPTION
*apk audit* audits the specified directories for changes from the package
database. By default, the output format is one file per line, for each affected
file. A character is printed indicating the change detected, followed by a
space, then the affected path. The changes detected are:
*apk audit* audits the system or specified directories for changes compared to
the package database.
The audit can be done against configuration files only (--backup) to generate
list of files needed to be stored in the overlay in run-from-tmps configuration.
Alternatively, it can audit all installed files (--system) to e.g. detect
unauthorized modifications of system files.
By default, the output format is one file per line, for each modified file.
A character is printed indicating the change detected, followed by a space,
then the affected path. The changes detected are:
|[ A
:< File added
......@@ -34,17 +41,26 @@ space, then the affected path. The changes detected are:
# OPTIONS
*--backup*
Audit configuration files only (default). The list of files to be
audited is generated from the masks in protected_paths.d.
*--check-permissions*
In addition to checking file contents, check the uid, gid, and file
mode as well.
Check file permissions too. Namely, the uid, gid and file mode will
be checked in addition to the file content.
*--packages*
Instead of printing each modified file, print the names and versions of
the packages which own the affected files.
Print only the packages with changed files. Instead of the full output
each modification, the set of packages with at least one modified file
is printed.
To repair all packages with modified files, one could use:
apk audit --packages -q | xargs apk fix
*--system*
List all modified configuration files (in protected_paths.d) that need
to be backed up.
Audit all system files. All files provided by packages are verified
for integrity with the exception of configuration files (listed in
protected_paths.d). This is useful detecting unauthorized file changes.
*-r, --recursive*
Descend into directories and audit them as well.
......
......@@ -14,6 +14,9 @@ apk cache - manage a local cache of package files
# DESCRIPTION
Manage local package cache by removing obsolete packages, or downloading
missing or newer packages from the repositories.
*apk cache download* will fetch package files from the repositories and store
them in the cache, which must be enabled upfront (see *apk-cache*(5)).
......@@ -26,14 +29,16 @@ depended on by packages in _world_.
# OPTIONS
*-l, --latest*
Disables normal heuristics for choosing which repository to install a
package from, preferring only repositories from which the latest
version is available. This has no effect on pinned packages.
Always choose the latest package by version. However, the versions
considered are based on the package pinning. Primarily this overrides
the default heuristic and will cause an error to displayed if all
dependencies cannot be satisfied.
*-u, --upgrade*
When caching packages which are already installed, prefer their upgrades
rather than considering the requirement fulfilled by the current
installation.
Upgrade _packages_ and it's dependencies. Normally *apk add* will
avoid changing installed package unless it is required by the newly
added _packages_ or their dependencies. This changes the default
preference to upgrading the package to the latest installable version.
# AUTHORS
......
......@@ -10,15 +10,16 @@ apk dot - generate graphviz graphs
# DESCRIPTION
*apk dot* generates graphviz dependency graphs for packages matching the masks
specified, or for every known package if unspecified (this will generate a
large and unwieldy graph).
*apk dot* renders package dependencies as graphviz graphs.
The graph is generated for the packages matching the masks given, or for every
known package if unspecified (this will generate a large and unwieldy graph).
# OPTIONS
*--errors*
Graph only relationships considered erroneous, e.g. cycles and missing
packages.
Consider only packages with errors. This is useful for visually reporting
e.g. cyclic dependencies and missing packages.
*--installed*
Consider only installed packages.
......
......@@ -35,6 +35,9 @@ specified.
*--simulate*
Simulate the requested operation without making any changes.
*Note*: this option is unreliable if needed indexes are not up-to-date
as this omits refresing or downloading of missing indexes.
# AUTHORS
Natanael Copa <ncopa@alpinelinux.org>++
......
......@@ -25,8 +25,8 @@ following options:
Reinstall packages (default).
*-u, --upgrade*
When fixing packages which are already installed, upgrade them rather
than considering the requirement fulfilled by the current installation.
Upgrade name _PACKAGE_ if an upgrade exists and does not break
dependencies.
*-x, --xattr*
Fix packages with broken xattrs.
......
......@@ -31,15 +31,16 @@ display the appropriate information, then an empty line terminates that field.
Print the package description.
*-e, --installed*
Check if the package is installed, printing its name and exiting with
status code zero if so, or exiting with a nonzero status code otherwise.
Check package installed status. For each installed package, print it's
name. The exit status is the number of given packages not installed.
Thus, zero (or success) is returned if all named packages are installed.
*-L, --contents*
List files included in the package.
*-i, --install-if*
List the package's install_if rule, if configured (i.e. the conditions
under which this package will be installed automatically).
List the package's install_if rule. When the dependencies in this list
are satisfied, the package will be installed automatically.
*-I, --rinstall-if*
List other packages whose install_if rules refer to this package.
......
......@@ -11,8 +11,10 @@ apk list - list packages matching a pattern or other criteria
# DESCRIPTION
*apk list* searches package indicies for packages matching the given patterns
and prints any matching packages. The patterns are matched with *fnmatch*(3),
which behaves similarly to shell globbing.
and prints any matching packages.
The patterns are matched with *fnmatch*(3), which behaves similarly to shell
globbing.
# OPTIONS
......
......@@ -10,8 +10,12 @@ apk update - update repository indexes
# DESCRIPTION
*apk update* fetches the index from all configured package repositories. See
*apk-repositories*(5) for more information on configuring package repositories.
*apk update* forces updating of the indexes from all configured package
repositories. This command is not needed in normal operation as all applets
requiring indexes will automatically refresh them after caching time expires.
See *apk-repositories*(5) for more information on configuring package
repositories.
# OPTIONS
......
......@@ -19,14 +19,19 @@ configured package repositories (see *apk-repositories*(5)).
following options:
*-a, --available*
Resets version constraints in _world_ (see *apk-world*(5)) and prefers
replacing or downgrading packages if the currently installed package is
no longer available from any repository (instead of holding them).
Reset all packages to versions available from current repositories.
This resets all versioned dependencies in _world_ (see *apk-world*(5)).
Additionally, packages are selected from active repositories if possible
even if it means replacing or downgrading the package.
This is useful to reset system against new set of packages after updating
repositories.
*-l, --latest*
Disables normal heuristics for choosing which repository to install a
package from, preferring only repositories from which the latest
version is available. This has no effect on pinned packages.
Always choose the latest package by version. However, the versions
considered are based on the package pinning. Primarily this overrides
the default heuristic and will cause an error to displayed if all
dependencies cannot be satisfied.
*--no-self-upgrade*
Do not do an early upgrade of the 'apk-tools' package.
......
......@@ -10,18 +10,20 @@ apk version - compare package versions
*apk version* -c _versions_...
*apk version* -t _left_ _right_
*apk version* -t _version1_ _version2_
*apk version* -I
# DESCRIPTION
*apk version* compares the versions of installed packages against package
versions available from repositories (see *apk-repositories*(5)). If no
packages are specified, all installed packages are considered. Otherwise,
the comparison is limited to the explicitly listed packages. A summary is
printed on stdout, with the difference between package versions being
represented as *>*, *=*, or *<*.
versions available from repositories (see *apk-repositories*(5)). It can also
be used to validate and compare version strings.
In default mode, if no packages are specified, all installed packages are
considered. Otherwise, the comparison is limited to the explicitly listed
packages. A summary is printed on stdout, with the difference between package
versions being represented as *>*, *=*, or *<*.
*apk version -c* tests the specified version string(s) for validity and prints
a list of _invalid_ version strings. If all version strings are valid, nothing
......@@ -44,8 +46,8 @@ specified).
Consider packages from all repository tags.
*-l* _operand_
Limit output to packages whose comparison is among the given operands,
specified as any combination of *>*, *=*, and *<*.
Limit to packages with output matching given _operand_. The _operand_
can be specified as any combination of *>*, *=*, and *<*.
# AUTHORS
......
......@@ -10,9 +10,10 @@ apk - Alpine Package Keeper
# DESCRIPTION
*apk* manages packages installed on the system. The set of installed packages
is called the _world_ (see *apk-world*(5)). *apk* supports various sub-commands
to query and manipulate _world_ and local & remote package repositories.
*apk* manages packages installed on the system. The set of top level packages
to install is called the _world_ (see *apk-world*(5)). *apk* supports various
sub-commands to query and manipulate _world_ and local & remote package
repositories.
# COMMANDS
......@@ -28,13 +29,13 @@ Each command is documented in detail on its manual page.
## SYSTEM MAINTENANCE
|[ *apk-fix*(8)
:< Check _world_ against the system and ensure consistency
:< Fix, reinstall or upgrade packages without modifying _world_
| *apk-update*(8)
: Update repository indexes
| *apk-upgrade*(8)
: Install upgrades available from repositories
| *apk-cache*(8)
: Commands related to the management of an offline package cache
: Manage the local package cache
## QUERYING PACKAGE INFORMATION
......@@ -43,7 +44,7 @@ Each command is documented in detail on its manual page.
| *apk-list*(8)
: List packages matching a pattern or other criteria
| *apk-dot*(8)
: Generate graphviz graphs
: Render dependencies as graphviz graphs
| *apk-policy*(8)
: Show repository policy for packages
......@@ -61,7 +62,7 @@ Each command is documented in detail on its manual page.
## MISCELLANEOUS
|[ *apk-audit*(8)
:< Audit directories for changes
:< Audit system for changes
| *apk-stats*(8)
: Show statistics about repositories and installations
| *apk-version*(8)
......@@ -77,8 +78,8 @@ The following options are available for all commands.
*-i, --interactive*
Ask confirmation before performing certain operations.
*-p, --root* <_DIR_>
Install packages to _DIR_.
*-p, --root* <_ROOT_>
Manage file system at _ROOT_.
*-q, --quiet*
Print less information.
......@@ -93,7 +94,8 @@ The following options are available for all commands.
Print program version and exit.
*-X, --repository* <_REPO_>
Use packages only from the specified repository.
Specify additional package repository. This option can be specified
multiple times.
*--allow-untrusted*
Install packages with untrusted signature or no signature.
......@@ -102,10 +104,11 @@ The following options are available for all commands.
Temporarily override architecture, to be combined with --root.
*--cache-dir* _CACHEDIR_
Temporarily override the cache directory.
Temporarily override the cache directory. _CACHEDIR_ is treated relative
to the _ROOT_.
*--cache-max-age* _AGE_
Maximum AGE (in minutes) for index in cache before it's refresh.
Maximum AGE (in minutes) for index in cache before it's refreshed.
*--force-binary-stdout*
Continue even if binary data will be printed to the terminal.
......@@ -114,7 +117,8 @@ The following options are available for all commands.
Continue even if _world_ cannot be satisfied.
*--force-non-repository*
Continue even if packages may be lost on reboot.
Continue even if packages may be lost on reboot. This can happen when
running in run-from-tmpfs mode, and installing non-repository package.
*--force-old-apk*
Continue even if packages use unsupported features.
......@@ -126,7 +130,7 @@ The following options are available for all commands.
Do not use cached files (local or from proxy).
*--keys-dir* _KEYSDIR_
Override directory of trusted keys.
Override directory of trusted keys. This is treated relative to _ROOT_.
*--no-cache*
Do not use any local cache path.
......@@ -151,7 +155,9 @@ The following options are available for all commands.
packages from cache on cache clean.
*--repositories-file* _REPOFILE_
Override repositories file, see *apk-repositories*(8).
Override repositories file, see *apk-repositories*(8). This directory
is relative to _ROOT_. This can be used to override normal system
repositories.
*--wait* _TIME_
Wait for TIME seconds to get an exclusive repository lock before
......@@ -168,16 +174,20 @@ The following options are available for all commands which commit the database.
Do not create .apk-new files in configuration directories.
*--overlay-from-stdin*
Read list of overlay files from stdin.
Read list of overlay files from stdin. Normally this is used only during
initramfs when booting run-from-tmpfs installation.
*--no-scripts*
Do not execute any scripts.
Do not execute any scripts. Useful for extracting a system image for
different architecture on alternative _ROOT_.
*--no-commit-hooks*
Skip pre/post hook scripts (but not other scripts).
*--initramfs-diskless-boot*
Enables options for diskless initramfs boot (e.g. skip hooks).
Used by initramfs when it's recreating root tmpfs. This enables selected
force options to minimize failure, and disables commit hooks, among
other features.
# NOTES
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment