diff --git a/doc/apk-add.8.scd b/doc/apk-add.8.scd index 7959a9983c558175b67917e3c85e1026672c4cf2..8e0ec0f4c9d7b65941aa6de61fde0a8c18935343 100644 --- a/doc/apk-add.8.scd +++ b/doc/apk-add.8.scd @@ -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 diff --git a/doc/apk-audit.8.scd b/doc/apk-audit.8.scd index 838895bad6fa60e0c033fb3f228990ca2cc77c89..8b46c32530678a16e0bf0003c4ae58e887c115de 100644 --- a/doc/apk-audit.8.scd +++ b/doc/apk-audit.8.scd @@ -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. diff --git a/doc/apk-cache.8.scd b/doc/apk-cache.8.scd index 8675b350a2c60861d4fb89a4d5f168b5d5fafbee..baff1e7a45534d03fbf95335053bbaecb38b5f81 100644 --- a/doc/apk-cache.8.scd +++ b/doc/apk-cache.8.scd @@ -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 diff --git a/doc/apk-dot.8.scd b/doc/apk-dot.8.scd index 03c4ca008e62ec64c6cba5b3fb158e048995cf5f..3e3b117483eee834fe6854d5377d365c7d23cafa 100644 --- a/doc/apk-dot.8.scd +++ b/doc/apk-dot.8.scd @@ -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. diff --git a/doc/apk-fetch.8.scd b/doc/apk-fetch.8.scd index 1fc826e37c1de3b7398c8f1f3e2e43d745b677cb..fea1e41fd0874ac0f1efc3e088fbee113a2f8a0f 100644 --- a/doc/apk-fetch.8.scd +++ b/doc/apk-fetch.8.scd @@ -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>++ diff --git a/doc/apk-fix.8.scd b/doc/apk-fix.8.scd index 98d7345db8f4e875e0952bdbfa560aa90c531a2e..f7e6b359c37226c0b5263965fc9736ae28d644a7 100644 --- a/doc/apk-fix.8.scd +++ b/doc/apk-fix.8.scd @@ -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. diff --git a/doc/apk-info.8.scd b/doc/apk-info.8.scd index 99744498eeb15fa82c30190ca9ef6cad308bb8ad..a4903c90f0e0d74e5761397b9c633775e831533e 100644 --- a/doc/apk-info.8.scd +++ b/doc/apk-info.8.scd @@ -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. diff --git a/doc/apk-list.8.scd b/doc/apk-list.8.scd index 99babf256c7eed0b4bd0a5cfd85cb7758cb31ac4..fbcdb32c7414290557135e0c9f1ae39989ee9eed 100644 --- a/doc/apk-list.8.scd +++ b/doc/apk-list.8.scd @@ -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 diff --git a/doc/apk-update.8.scd b/doc/apk-update.8.scd index 8045345d6668a493f51313164ab3b0cf54d8c5e7..a28358d593f60f761296b19639f5b1674372f933 100644 --- a/doc/apk-update.8.scd +++ b/doc/apk-update.8.scd @@ -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 diff --git a/doc/apk-upgrade.8.scd b/doc/apk-upgrade.8.scd index 49b9cb05e50936f906810ba7a58220e7ff760ea7..8825dc58e7fbca687c562b294fcea15594ce8942 100644 --- a/doc/apk-upgrade.8.scd +++ b/doc/apk-upgrade.8.scd @@ -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. diff --git a/doc/apk-version.8.scd b/doc/apk-version.8.scd index add4871ad3872e38d74764167d7e031965a91a01..1e29b1e88964f7b62029bc7d0127316732950dac 100644 --- a/doc/apk-version.8.scd +++ b/doc/apk-version.8.scd @@ -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 diff --git a/doc/apk.8.scd b/doc/apk.8.scd index 5fdc16d6992c3b38c9136efa039031d047861eef..7c9440933fd7d2cb63428c31539f76231f4c0183 100644 --- a/doc/apk.8.scd +++ b/doc/apk.8.scd @@ -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