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

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