diff --git a/doc/apk-adbdump.8.scd b/doc/apk-adbdump.8.scd
new file mode 100644
index 0000000..716bff1
--- /dev/null
+++ b/doc/apk-adbdump.8.scd
@@ -0,0 +1,31 @@
+apk-adbdump(8)
+
+# NAME
+
+apk adbdump - dump v3 files in textual representation
+
+# SYNOPSIS
+
+*apk adbdump* [<_options_>...] _files_...
+
+# DESCRIPTION
+
+*apk adbdump* will dump the metadata portion of given _files_ (packages,
+indexes, installeddb) to its textual representation.
+
+The output can be:
+ - yaml with annotations as comment
+ - json data blob
+
+*apk-adbgen*(8) can convert the YAML textual representation back to
+the binary format with certain limitations (nested ADB and DATA blocks
+are not supported).
+
+# OPTIONS
+
+*--format* _FORMAT_
+ Specify the output format (options: *json*, *yaml*)
+
+# SEE ALSO
+
+*apk-adbgen*(8), *apk-package*(5), *apk-v3*(5)
diff --git a/doc/apk-adbgen.8.scd b/doc/apk-adbgen.8.scd
new file mode 100644
index 0000000..c3f24bc
--- /dev/null
+++ b/doc/apk-adbgen.8.scd
@@ -0,0 +1,18 @@
+apk-adbgen(8)
+
+# NAME
+
+apk adbgen - generate v3 files from text representation
+
+# SYNOPSIS
+
+*apk adbgen* [<_options_>...]
+
+# DESCRIPTION
+
+*apk adbgen* takes in *apk-adbdump*(8) output and convert it back to the
+corresponding binary format.
+
+# SEE ALSO
+
+*apk-adbdump*(8), *apk-package*(5), *apk-v3*(5)
diff --git a/doc/apk-adbsign.8.scd b/doc/apk-adbsign.8.scd
new file mode 100644
index 0000000..6ed144e
--- /dev/null
+++ b/doc/apk-adbsign.8.scd
@@ -0,0 +1,22 @@
+apk-adbsign(8)
+
+# NAME
+
+apk adbsign - sign, resign or recompress apk v3 packages or indexes
+
+# SYNOPSIS
+
+*apk adbsign* [<_options_>...] _files_...
+
+# DESCRIPTION
+
+*apk adbsign* will process specified _files_ and add or replace
+the signatures in addition to recompressing it. The original compression
+algorithm and level is used unless specified.
+
+# OPTIONS
+
+See also *apk*(8) for additional package generation options.
+
+*--reset-signatures*
+ Remove all existing signatures.
diff --git a/doc/apk-add.8.scd b/doc/apk-add.8.scd
index 9ae4778..ce2e428 100644
--- a/doc/apk-add.8.scd
+++ b/doc/apk-add.8.scd
@@ -28,19 +28,33 @@ following options:
*--initdb*
Initialize a new package database.
-*-l, --latest*
+*--latest*, *-l*
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*
- Upgrade _packages_ and it's dependencies. Normally *apk add* will
+*--no-chown*
+ Deperecated alias for --usermode.
+
+*--upgrade*, *-u*
+ Upgrade _packages_ and their 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_
+*--usermode*
+ Create usermode database with --initdb. In usermode, apk will operate
+ in such a way that root access is not required. Currently this implies:
+ - checking that we are running as non-root
+ - not changing file owner or group
+ - not setting system xattrs
+
+ This implies that the installation might not be fully functional.
+ However, this is useful mode for testing purposes or to create
+ chroot where some specific applications can run as non-root.
+
+*--virtual*, *-t* _NAME_
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_. An optional version specifier for the virtual
@@ -50,9 +64,3 @@ following options:
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
- ownership when running as root. However, this option is turned on when
- running as non-root user, as changing file ownership is not permitted
- by the system then.
diff --git a/doc/apk-audit.8.scd b/doc/apk-audit.8.scd
index 52e8733..e1b0172 100644
--- a/doc/apk-audit.8.scd
+++ b/doc/apk-audit.8.scd
@@ -59,10 +59,9 @@ then the affected path or details. The changes detected are:
Enable reporting of detail records.
*--full*
- Audit all system files. Same as *--system*, but in addition reports
- all added directories and files. A built-in default override for
- protected paths is used, unless a *--protected-paths* is explicitly
- specified.
+ Same as *--system*, but in addition reports all added directories and
+ files. A built-in default override for protected paths is used, unless
+ a *--protected-paths* is explicitly specified.
*--ignore-busybox-symlinks*
Ignore symlinks whose target is the busybox binary.
@@ -79,11 +78,15 @@ then the affected path or details. The changes detected are:
Use given FILE for protected paths listings. This also makes apk ignore
the regular protected_paths.d directories.
+*--recursive*, *-r*
+ Descend into directories and audit them as well.
+
*--system*
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.
New files or directories are not reported.
-*-r, --recursive*
- Descend into directories and audit them as well.
+# SEE ALSO
+
+*apk-protected_paths*(5)
diff --git a/doc/apk-cache.8.scd b/doc/apk-cache.8.scd
index 4c620e8..3759bd9 100644
--- a/doc/apk-cache.8.scd
+++ b/doc/apk-cache.8.scd
@@ -39,7 +39,7 @@ disk installations.
Add the argument dependencies to _world_ dependencies when determining
which packages to download.
-*-a, --available*
+*--available*, *-a*
Selected packages to be downloaded from active repositories even if
it means replacing or downgrading the installed package.
@@ -47,16 +47,16 @@ disk installations.
Ignore conflicts when resolving dependencies. This can be useful when
pre-populating cache for creation of multiple images in one go.
-*-l, --latest*
+*--latest*, *-l*
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*
+*--upgrade*, *-u*
When caching packages which are already installed, prefer their upgrades
rather than considering the requirement fulfilled by the current
installation.
-*-s, --simulate*
+*--simulate*[=_BOOL_], *-s*
Simulate the requested operation without making any changes.
diff --git a/doc/apk-convdb.8.scd b/doc/apk-convdb.8.scd
new file mode 100644
index 0000000..16d3a97
--- /dev/null
+++ b/doc/apk-convdb.8.scd
@@ -0,0 +1,19 @@
+apk-convdb(8)
+
+# NAME
+
+apk convdb - convert v2 installed database to v3 format
+
+# SYNOPSIS
+
+*apk convdb*
+
+# DESCRIPTION
+
+*apk convdb* converts to current installed database to v3 format and
+outputs a corresponding *installed.adb* file.
+
+# OPTIONS
+
+*apk convdb* does not support any specific options. See *apk*(8) for global
+options.
diff --git a/doc/apk-convndx.8.scd b/doc/apk-convndx.8.scd
new file mode 100644
index 0000000..de005ce
--- /dev/null
+++ b/doc/apk-convndx.8.scd
@@ -0,0 +1,19 @@
+apk-convndx(8)
+
+# NAME
+
+apk convndx - convert v2 indexes to v3 format
+
+# SYNOPSIS
+
+*apk convndx* _indexes_...
+
+# DESCRIPTION
+
+*apk convndx* reads the specifed _indexes_ and generates and merges them.
+The resulting data is written out to stdout in apkv3 index format.
+
+# OPTIONS
+
+*apk convndx* does not support any specific options. See *apk*(8) for global
+options.
diff --git a/doc/apk-del.8.scd b/doc/apk-del.8.scd
index ebb12c0..ae7ec2a 100644
--- a/doc/apk-del.8.scd
+++ b/doc/apk-del.8.scd
@@ -19,5 +19,5 @@ but may also cause other changes to the installed packages.
*apk del* supports the commit options described in *apk*(8), as well as the
following options:
-*-r, --rdepends*
+*--rdepends*, *-r*
Recursively delete all top-level reverse dependencies, too.
diff --git a/doc/apk-dot.8.scd b/doc/apk-dot.8.scd
index 6125bc7..60b4e3c 100644
--- a/doc/apk-dot.8.scd
+++ b/doc/apk-dot.8.scd
@@ -17,9 +17,9 @@ known package if unspecified (this will generate a large and unwieldy graph).
# OPTIONS
+In addition to the global options (see *apk*(8)), and query options
+(see *apk-query*(8)) the following options are supported:
+
*--errors*
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-extract.8.scd b/doc/apk-extract.8.scd
new file mode 100644
index 0000000..08b1f96
--- /dev/null
+++ b/doc/apk-extract.8.scd
@@ -0,0 +1,26 @@
+apk-extract(8)
+
+# NAME
+
+apk extract - Extract package file contents
+
+# SYNOPSIS
+
+*apk extract* [<_options_>...] _files_...
+
+# DESCRIPTION
+
+*apk extract* will extract package contents of specified package file
+to the current or to an explicitly specified directory.
+Each package is extracted without checking dependencies or other metadata.
+
+If extract is ran as non-root user the file owners and xattrs are not
+preserved.
+
+# OPTIONS
+
+*--destination* _PATH_
+ Extract files to _PATH_.
+
+*--no-chown*
+ Do not preserve file owner.
diff --git a/doc/apk-fetch.8.scd b/doc/apk-fetch.8.scd
index 495c3d4..7736d49 100644
--- a/doc/apk-fetch.8.scd
+++ b/doc/apk-fetch.8.scd
@@ -17,33 +17,35 @@ specified.
# OPTIONS
+In addition to the global options (see *apk*(8)), and query options
+(see *apk-query*(8)) the following options are supported:
+
*--built-after* _TIMESPEC_
Only fetch packages that have buildtime more recent than TIMESPEC.
TIMESPEC can be a "YYYY-MM-DD HH:MM:SS" date, or seconds since epoch.
-*-l, --link*
+*--link*, *-l*
Create hard links if possible.
-*-o, --output* _DIR_
+*--pkgname-spec* _PKGNAME_SPEC_
+ Generate downloaded package names with _PKGNAME_SPEC_ specification.
+ Does not work with *--prune* unless the specification starts with
+ *${name}[-\_.]*.
+
+*--output*, *-o* _DIR_
Write the downloaded file(s) to _DIR_.
-*-R, --recursive*
- Fetch packages and all of their dependencies.
+*--simulate*[=_BOOL_], *-s*
+ 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.
-*-s, --stdout*
+*--stdout*, *-s*
Dump the .apk file(s) to stdout.
*Note*: this option is incompatible with *-o*, *-R*, and the global
*--progress* option.
-*-w, --world*
- Download packages needed to satisfy _world_. Implies *--recursive*.
-
-*--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.
-
*--url*
Print the full URL for downloaded packages.
diff --git a/doc/apk-fix.8.scd b/doc/apk-fix.8.scd
index 4a82c74..c315b57 100644
--- a/doc/apk-fix.8.scd
+++ b/doc/apk-fix.8.scd
@@ -18,18 +18,18 @@ the specified packages, or all installed packages if none are specified.
*apk fix* supports the commit options described in *apk*(8), as well as the
following options:
-*-d, --depends*
+*--depends*, *-d*
Also fix dependencies of specified packages.
-*-r, --reinstall*
+*--directory-permissions*
+ Reset all directory permissions.
+
+*--reinstall*, *-r*
Reinstall packages (default).
-*-u, --upgrade*
+*--upgrade*, *-u*
Upgrade name _PACKAGE_ if an upgrade exists and does not break
dependencies.
-*-x, --xattr*
+*--xattr*, *-x*
Fix packages with broken xattrs.
-
-*--directory-permissions*
- Reset all directory permissions.
diff --git a/doc/apk-index.8.scd b/doc/apk-index.8.scd
index d81a2f7..59a3d3e 100644
--- a/doc/apk-index.8.scd
+++ b/doc/apk-index.8.scd
@@ -11,37 +11,37 @@ apk index - create repository index file from packages
# DESCRIPTION
*apk index* creates a repository index from a list of package files. See
-*apk-repositories*(8) for more information on repository indicies.
+*apk-repositories*(5) for more information on repository indicies.
Generally, the resulting index must be cryptographically signed before *apk*
will accept it. See *abuild-sign*(1) for details.
# OPTIONS
-*-d, --description* _TEXT_
+*--description*, *-d* _TEXT_
Add a description to the index. Upstream, this is used to add version
information based on the git commit SHA of aports HEAD at the time of
index generation.
+*--index*, *-x* _INDEX_
+ Read an existing index from _INDEX_ to speed up the creation of the new
+ index by reusing data when possible.
+
*--merge*
Merge _packages_ into the existing _INDEX_.
-*-o, --output* _FILE_
+*--no-warnings*
+ Disable the warning about missing dependencies. This happens when A,
+ depends on package B, that does not have a provider in the indexed
+ repository.
+
+*--output*, *-o* _FILE_
Output generated index to _FILE_.
*--prune-origin*
Prune packages from the existing _INDEX_ with same origin as any of
the new _packages_ during merge.
-*-x, --index* _INDEX_
- Read an existing index from _INDEX_ to speed up the creation of the new
- index by reusing data when possible.
-
-*--no-warnings*
- Disable the warning about missing dependencies. This happens when A,
- depends on package B, that does not have a provider in the indexed
- repository.
-
*--rewrite-arch* _ARCH_
Set all package's architecture to _ARCH_.
diff --git a/doc/apk-info.8.scd b/doc/apk-info.8.scd
index bbd703b..a774af7 100644
--- a/doc/apk-info.8.scd
+++ b/doc/apk-info.8.scd
@@ -24,38 +24,27 @@ display the appropriate information, then an empty line terminates that field.
# OPTIONS
-*-a, --all*
- List all information known about the package.
-
-*-d, --description*
- Print the package description.
+In addition to the global options (see *apk*(8)), and query options
+(see *apk-query*(8)) the following options are supported:
-*-e, --installed*
- 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.
+*--all*, *-a*
+ List all information known about the package.
-*-L, --contents*
+*--contents*, *-L*
List files included in the package.
-*-P, --provides*
- List what the package provides.
-
-*-r, --rdepends*
- List reverse dependencies of the package (all other packages which
- depend on the package).
-
-*-R, --depends*
+*--depends*, *-R*
List the dependencies of the package.
-*-s, --size*
- Print the package's installed size.
-
-*-w, --webpage*
- Print the URL for the package's upstream webpage.
+*--description*, *-d*
+ Print the package description.
-*-W, --who-owns*
- Print the package which owns the specified file.
+*--exists*, *--installed*, *-e*
+ 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.
+ NOTE: *--installed* is deprecated and will be removed to allow
+ the same option in *query* group to function.
*--install-if*
List the package's install_if rule. When the dependencies in this list
@@ -64,6 +53,13 @@ display the appropriate information, then an empty line terminates that field.
*--license*
Print the package SPDX license identifier.
+*--provides*, *-P*
+ List what the package provides.
+
+*--rdepends*, *-r*
+ List reverse dependencies of the package (all other packages which
+ depend on the package).
+
*--replaces*
List the other packages for which this package is marked as a
replacement.
@@ -71,5 +67,14 @@ display the appropriate information, then an empty line terminates that field.
*--rinstall-if*
List other packages whose install_if rules refer to this package.
-*-t, --triggers*
+*--size*, *-s*
+ Print the package's installed size.
+
+*--triggers*, *-t*
Print active triggers for the package.
+
+*--webpage*, *-w*
+ Print the URL for the package's upstream webpage.
+
+*--who-owns*, *-W*
+ Print the package which owns the specified file.
diff --git a/doc/apk-keys.5.scd b/doc/apk-keys.5.scd
index 1cbd898..afd6c8f 100644
--- a/doc/apk-keys.5.scd
+++ b/doc/apk-keys.5.scd
@@ -6,8 +6,16 @@ apk-keys(5)
# DESCRIPTION
-The */etc/apk/keys* directory stores RSA public keys which are trusted by apk
-to verify cryptographic signatures for packages. To trust a new key, simply add
-the armored public key to this directory. See *abuild-keygen*(1) for
-information on generating new keys, *abuild-sign*(1) for using these keys to
-sign files, and *apk-verify*(8) for verifying keys against the apk trust store.
+The */etc/apk/keys* directory stores the public keys which are trusted by apk
+to verify cryptographic signatures for packages.
+
+To trust a new key, simply add the armored public key to this directory. The
+keys can be generated with *openssl*.
+
+The APKv2 packages require the filename of public key to match the signing
+key name in the package. APKv3 files are matched using the public key identity
+and filename is not signifcant.
+
+# SEE ALSO
+
+*abuild-keygen*(1), *abuild-sign*(1), *apk-adbsign*(8), *apk-verify*(8)
diff --git a/doc/apk-list.8.scd b/doc/apk-list.8.scd
index e09577d..cd04003 100644
--- a/doc/apk-list.8.scd
+++ b/doc/apk-list.8.scd
@@ -18,23 +18,29 @@ globbing.
# OPTIONS
-*-I, --installed*
- Consider only installed packages.
-
-*-O, --orphaned*
- Consider only orphaned packages.
+In addition to the global options (see *apk*(8)), and query options
+(see *apk-query*(8)) the following options are supported:
-*-a, --available*
+*--available*, *-a*
Consider only available packages.
-*-u, --upgradable, --upgradeable*
- Consider only upgradable packages.
+*--depends*, *-d*
+ List packages by dependency.
+
+*--installed*, *-I*
+ Consider only installed packages.
+
+*--manifest*
+ List installed packages in format `<name> <version>`.
-*-o, --origin*
+*--origin*, *-o*
List packages by origin.
-*-d, --depends*
- List packages by dependency.
+*--orphaned*, *-O*
+ Consider only orphaned packages.
-*-P, --providers*
+*--providers*, *-P*
List packages by provider.
+
+*--upgradable*, *--upgradeable*, *-u*
+ Consider only upgradable packages.
diff --git a/doc/apk-mkndx.8.scd b/doc/apk-mkndx.8.scd
new file mode 100644
index 0000000..7301299
--- /dev/null
+++ b/doc/apk-mkndx.8.scd
@@ -0,0 +1,69 @@
+apk-mkndx(8)
+
+# NAME
+
+apk mkndx - create apkv3 repository index file from packages
+
+# SYNOPSIS
+
+*apk mkndx* [<_options_>...] _packages_...
+
+# DESCRIPTION
+
+*apk mkndx* creates a repository index from a list of package files. See
+*apk-repositories*(5) for more information on repository indicies.
+
+# OPTIONS
+
+*--description*, *-d* _TEXT_
+ Add a description to the index. Upstream, this is used to add version
+ information based on the git commit SHA of aports HEAD at the time of
+ index generation.
+
+*--filter-spec* _PKGNAME_SPEC_
+ Filter previous index only. Each argument should be _PKGNAME_SPEC_ formatted
+ name of a package to include from the index. This can be used to create
+ a subset of existing index.
+
+*--hash* _HASH_
+ Use _HASH_ as the algorithm for apk v3 integrity. Currently supported:
+ - sha256 (default)
+ - sha256-160
+
+ The *sha256-160* is allowed to generate index compatible with old
+ prereleases of apkv3 that do no handle longer hashes correctly.
+
+*--index*, *-x* _INDEX_
+ Read an existing index from _INDEX_ to speed up the creation of the new
+ index by reusing data when possible.
+
+*--output*, *-o* _FILE_
+ Output generated index to _FILE_.
+
+*--pkgname-spec* _PKGNAME_SPEC_
+ Specify package name specification for downloading the packages.
+ APK will construct the download URL relative to index file by expanding
+ this specification with package specific values.
+
+ If the specification contains :// it is considered an absolute URL instead
+ of relative. This is not recommended for public repositories as using
+ absolute package name specification would prevent mirroring. However, this
+ is useful in build environment to create a subset of an index and have it
+ refer to packages in another repository.
+
+ If not specified, the default will be determined by *apk* at runtime based
+ on how the repository is referenced:
+ - ${arch}/${name}-${version}.apk if referenced by repository base path URL
+ - ${name}-${version}.apk if referenced by repository index file URL
+
+ Currently supported substitution variables are:
+ - name
+ - version
+ - arch
+ - hash
+
+ Additionally a prefix of the variable can used with syntax: *${name:4}*. This
+ truncates the substition to maximum of 4 characters.
+
+ The specification writer should ensure that the repository does not contain
+ multiple packages that would expand to same package filename.
diff --git a/doc/apk-mkpkg.8.scd b/doc/apk-mkpkg.8.scd
new file mode 100644
index 0000000..d2d96ff
--- /dev/null
+++ b/doc/apk-mkpkg.8.scd
@@ -0,0 +1,49 @@
+apk-mkpkg(8)
+
+# NAME
+
+apk mkpkg - create apkv3 package files
+
+# SYNOPSIS
+
+*apk mkpkg* [<_options_>...]
+
+# DESCRIPTION
+
+*apk mkpkg* creates a package file from given metadata and data files.
+
+# OPTIONS
+
+*--compat* _APK_VERSION_
+ Produces packages comptable with given apk versions. The default
+ currently is *3.0.0_pre1*.
+
+*--files*, *-F* _PATH_
+ Specify the build root path from where the files are collected
+ from to be included in the package.
+
+*--info*, *-I* _KEY:VALUE_
+ Specify metadata for the package. Assigns a metadata field _KEY_
+ with the value _VALUE_. Refer to *apk-package*(5) for the list
+ of APKv3 metadata fields. This can assign to either "package info"
+ or "package" metadata field.
+
+*--output*, *-o* _FILE_
+ Specify the _FILE_ as the output file name. If not specified,
+ a default name will be deduced from the package metadata fields.
+
+*--rootnode*[=*BOOL*]
+ Deprecated alias to set compat version. *yes* resolves to
+ *--compat=3.0.0_pre1* and *no* to *--compat=3.0.0_pre3*.
+
+*--script*, *-s* _TYPE:SCRIPT_
+ Add the specified *SCRIPT* with the *TYPE*. Refer to *apk-package*(5)
+ *PACKAGE METADATA* / *scripts* for list of scripts types and when
+ they are executed.
+
+*--stdout*
+ Output resulting package to stdout.
+
+*--trigger*, *-t* _TRIGGER_
+ Append _TRIGGER_ path specification to list triggers which affect
+ when the *trigger* script is executed.
diff --git a/doc/apk-package.5.scd b/doc/apk-package.5.scd
new file mode 100644
index 0000000..06ddded
--- /dev/null
+++ b/doc/apk-package.5.scd
@@ -0,0 +1,306 @@
+apk-package(5)
+
+# NAME
+
+apk package - apk package metadata fields
+
+# DESCRIPTION
+
+The apk package metadata contains the package info metadata substructure
+and various other metadata fields.
+
+The package info metadata structure is the portion of package metadata which
+will be copied to the repository index when the package is being indexed.
+These fields will be available form the index even if the package is not
+installed.
+
+The rest of the package metadata is kept in the package and installed
+database. These fields are available only if the package is installed.
+
+The remainder of the document explains each field with the notation:
+*v3-field-name* (*v2-pkginfo-field-name*, *v2-index-character*).
+
+It is mentioned explicitly if APK uses each fields for something meaningful.
+Some fields are not used internally by APK and from the APK point of view
+are just blobs of data associated with specified name which are meaningful
+the user.
+
+# PACKAGE NAMES AND VERSIONS
+
+APK will often display concatenation of *name*-*version* in its verbose
+output mode. The rule below on how a valid version number is defined allow
+that this format can be uniquely splitted back to the two components by
+finding the *last* occurance of *-[0-9]*. The dash in the beginning of this
+match is the splitting point: first portion is the *name* and second
+portion is the *version*.
+
+Unfortunately it is not possible to deduce if a given string is of format
+*name* or *name-version* (*name* alone can also contain *-[:digit:]* in it).
+
+# PACKAGE INFO METADATA
+
+*name* (*pkgname*, *P*)
+ Package name. This is the primary package name. The name shall
+ consist only of the following characters [a-zA-Z0-9.\_+-].
+ The name must start with an alphanumeric character [a-zA-Z0-9].
+
+*version* (*pkgver*, *V*)
+ Package version. The Alpine version specification originally
+ followed the Gentoo package version specification.
+
+ Currently the APK version specification is as follows:
+ *number{.number}...{letter}{\_suffix{number}}...{~hash}{-r#}*
+
+ Each *number* component is a sequence of digits (0-9).
+
+ The *letter* portion can follow only after end of all the numeric
+ version components. The *letter* is a single lower case letter (a-z).
+
+ Optionally one or more *\_suffix{number}* components can follow.
+ The list of valid suffixes (and their sorting order) is:
+ *alpha*, *beta*, *pre*, *rc*, <no suffix>, *cvs*, *svn*, *git*, *hg*, *p*.
+
+ This can be followed with an optional *{~hash}* to indicate a commit
+ hash from where it was built. This can be any length string of
+ lower case hexdecimal digits (0-9a-f).
+
+ Finally an optional package build component *-r{number}* can follow.
+
+*hashes* (*C*)
+ Hash of the package meta data. This field is present only in
+ the index copy of the package info.
+
+ APK uses this fields in multiple ways:
+ - authenticate and verify the package against an index
+ - determine if same identical package is available from multiple
+ repositories
+ - make package filename unique when storing a copy in the package
+ cache
+
+*description* (*pkgdesc*, *T*)
+ The description is a single line describing the package.
+ APK displays this string in various command querying information about
+ the package, repository or installed database.
+
+*arch* (*arch*, *A*)
+ Package architecture for which the package was built. Currently apk
+ uses the following default architectures:
+ - noarch
+ - aarch64
+ - arc700
+ - archs
+ - armeb
+ - armel
+ - armhf
+ - armv7
+ - mips
+ - mipsel
+ - mips64
+ - mips64el
+ - ppc
+ - ppc64
+ - ppc64le
+ - riscv32
+ - riscv64
+ - s390x
+ - sh2eb
+ - sh3
+ - sh4
+ - loongarchx32
+ - loongarch64
+ - wasi32
+ - wasi64
+ - x86
+ - x86_64
+
+ The arch field can be part of the repository download URL. See
+ *apk-mkndx*(8) *--pkgname-spec* for additional details.
+
+ Package is not eligible for installation unless the arch matches
+ one of the values in *etc/apk/arch*.
+
+*license* (*license*, *L*)
+ Package license. This is informative field for the user and APK does
+ not validate or use this field internally. It is recommended to use
+ standard license descriptors such as SPDX.
+
+*origin* (*origin*, *o*)
+ Package's source package name. APK uses this field as follows:
+ - If two separate binary packages share same source package, APK allows
+ overwriting the package to overwrite files from another package. This
+ serves the purpose of moving files from one subpackage to another.
+ - Several query commands allow printing or matching the original package name.
+ - Indexing command (when updating index incrementally) uses this field
+ determine when to delete old package (that is to delete subpackages
+ that no longer exist).
+
+*maintainer* (*maintainer*, *m*)
+ Package's maintainer information. Usually the name and email address.
+
+*url* (*url*, *U*)
+ Package URL. A link to website containing information about the package.
+
+*repo-commit* (*commit*, *c*)
+ Repository commit hash from which the package was built from.
+
+*build-time* (*builddate*, *t*)
+ UNIX timestamp when the package was built. Apk fetch can filter packages
+ to download based on the build time. This is useful to download incremental
+ repository snapshots.
+
+*installed-size* (*size*, *I*)
+ Estimate of how much disk space is required when the package is installed.
+ APK displays this information in various places, and based the commit
+ transaction disk usage changed on this information.
+
+ Packages with the installed size being zero as meta packages that do not
+ have any other data than indexed data. APK may choose to not download the
+ package and handle everything based on the data available in the index.
+
+*file-size* (*S*)
+ This field is present meaningful only in the repository index copy of
+ the package info. APK index will fill this field at indexing time with the
+ size of the package file (.apk). Technically this field should be a repository
+ index specific field, and such change might be done in the future.
+
+*provider-priority* (*provider_priority*, *k*)
+ This determines the default installation priority for the non-versioned
+ package names the packages lists in the *provides* field. By default
+ a non-versioned provides will not be selected automatically for installation.
+ But specifying *provider-priority* enables this automatic selection, and is
+ used to determine which of the packages to install in case multiple packages
+ provide the same non-versioned package name.
+
+*depends* (*depend*, *D*)
+ List of dependencies for the package. Installing this package will
+ require APK to first satisfy the list of all its dependencies.
+
+ The dependencies are used by various APK components:
+ - The solver will try to find a solution that all package dependencies
+ are satisfied (as well as the world dependencies)
+ - When apk is committing changes to the file system, it will install
+ or remove packages in such order that all dependencies of the package
+ will be satisfied (assuming there are no circular dependencies)
+ - When apk runs the package trigger scripts, they will be ordered
+ so that the triggers of all dependencies before running the trigger
+ for this package
+
+*provides* (*provides*, *p*)
+ List of package names (and optionally its version) this package
+ provides in addition to its primary name and version. The provided
+ name can contain additionally characters: comma (,), brackets ([]),
+ colons (:) and slashes (/) in the name. This allows using namespaces
+ for automatically generated names.
+
+ If the provided name contains a version number:
+ - the solver will treat it as-if a real package with the provided
+ name is installed
+ - the package becomes automatically selectable by anything depending
+ on the provided name
+ - the package will automatically become the single possible owner
+ for the provided name
+ - the package will automatically conflict with any package with
+ the same primary or provided package name
+
+ If the provided name does not include version:
+ - the package is not automatically selectable for installation
+ by that fact that there is a dependency on the provided name
+ - specifying *provides_priority* will allow automatic selection
+ - otherwise user is expected to manually select one of the
+ concrete package names in world which allows selection
+ - the package is not considered to own provided name
+ - multiple packages provided the same name without a version are
+ allowed to be installed simultaneously
+ - apk internally considers a package name with only non-versioned
+ providers as a "virtual package name"
+
+*replaces* (*r*)
+ List of package names this package is allowed to replace files from.
+ Normally apk treats it as an error if multiple packages contain the
+ same file. Specifying a replaces declartion allows the package to
+ silently overwrite files from the listed packages.
+
+*install-if* (*install_if*, *i*)
+ APK will automatically select and install the package if all of
+ the install-if dependencies are satisfied. There should be at least
+ two dependencies in *install_if* dependencies, and one of them must
+ have a equality (*=*) operator.
+
+ Typical use case is that there is a global repository meta package
+ e.g. *docs*. And then there are multiple packages that have a subpackage
+ like *package-doc*. These *-doc* packages can then have a *install-if*
+ rule to get automatically installed if such as "*package=$name-$ver docs*"
+ to install the documentation package automatically if the main package
+ and the documentation meta package is installed.
+
+*recommends*
+ List of dependencies recommended to install along with this package.
+ This is currently not used by APK for anything, but is stored, dumped
+ and queryable.
+
+*layer*
+ An integer specifying the database layer this package installs to:
+ - *root* (0) is the default and indicates the normal file system
+ - *uvol* (1) indicates that the package contains an uvol image and
+ the uvol volume manager should be used to install the images
+
+ In addition to controlling where the package content goes, this also
+ affects the installad database where the metadata of these packages
+ go. Each layer has a separate installed database.
+
+*tags*
+ List of tags that this package will match against. Apk does not do
+ anything with the tags, but the distribution vendors can define their
+ own tags to associate custom metadata with the package. The tags can
+ be queried and dumped using the *apk-query*(8) applet.
+ Each tag consists of the following characters [a-zA-Z0-9.\_+-,:/\[\]=].
+ Custom tags should contain a distribution or vendor specific prefix
+ such as e.g. "alpine:".
+
+# PACKAGE METADATA
+
+*info*
+ This is the logical structure containing the package info metadata
+ as defined in the previous section.
+
+*paths*
+ This contains listing of all the paths and files along with the file
+ specific metadata (owner, permissions, xattrs, content hashes).
+
+*scripts*
+ Scripts contains the executable files (usually shell scripts) that
+ are executed before or after package installation, removal, upgrade
+ as well as to handle trigger conditions.
+
+ Currently defined script types and their arguments:
+ - trigger <matched-trigger>...
+ - pre-install <new-version>
+ - post-install <new-version>
+ - pre-deinstall <old-version>
+ - post-deinstall <old-version>
+ - pre-upgrade <new-version> <old-version>
+ - post-upgrade <new-version> <old-version>
+
+ See also the ENVIRONMENT section in *apk*(8) for the environment variables.
+
+*triggers*
+ List of directory globs. APK will execute the trigger script with
+ list of matched directories when any action (package installation,
+ removal) has modified content of that directory. When package is
+ being fixed or installed it will get list of all matching directories.
+
+ Trigger globs may start with *+*, which means that the path should
+ only be passed to the trigger script when the directory was modified
+ during the transaction. It does not affect whether the trigger is
+ invoked or not. Without the prefix, the path will also be passed
+ when present in the system and the package providing the trigger
+ script is updated or reinstalled.
+
+*replaces-priority*
+ If two packages both contain the same file, and they both have replaces
+ directive allow them to overwrite packages. This priority determines
+ which packages file is takes precedence.
+
+# SEE ALSO
+
+*abuild*(1), *apk*(8), *apk-v2*(5), *apk-v3*(5)
diff --git a/doc/apk-policy.8.scd b/doc/apk-policy.8.scd
index fa3b858..44bb1d8 100644
--- a/doc/apk-policy.8.scd
+++ b/doc/apk-policy.8.scd
@@ -16,5 +16,5 @@ repositories (see *apk-repositories*(5)), sorted by ascending version.
# OPTIONS
-*apk policy* does not support any specific options. See *apk*(8) for global
-options.
+The global options (see *apk*(8)) and query options (see *apk-query*(8))
+are supported.
diff --git a/doc/apk-protected_paths.5.scd b/doc/apk-protected_paths.5.scd
new file mode 100644
index 0000000..2aa0177
--- /dev/null
+++ b/doc/apk-protected_paths.5.scd
@@ -0,0 +1,70 @@
+apk-protected_paths(5)
+
+# NAME
+
+*/etc/apk/protected_paths.d/\*.list* - paths with special treatement by apk
+
+# DESCRIPTION
+
+Files in _/etc/apk/protected_paths.d/\*.list_ enumerate files are protected and
+are not overwritten by *apk*(8). Generally, these are configuration files that
+are expected to be modified by the system administrator. These files also
+receive special treatment by *apk-audit*(8).
+
+If *apk*(8) would install a file into a protected path which has been modified,
+it shall intend write the file into a file with the _.apk-new_ suffix.
+
+For example, once the file _/etc/passwd_ is modified by the local administrator,
+*apk*(8) should not overwrite it when upgrading or fixing packages. Likewise,
+protected files modified by any automation (including post-install scripts) are
+not overwritten.
+
+*apk-audit(8)* shall report protected paths by default. When using
+*apk audit --system* or *apk audit --full*, protected files shall be omitted
+from the output. When using *apk audit --backup*, matching files are always
+reported. This is in turn used by *lbu commit*.
+
+# FILE FORMAT
+
+Each line is a single rule composed of one symbol followed with a glob
+expression, which shall be evaluated relative to the root directory.
+
+The initial symbol must be one of:
+
+*+*
+ Protect matching paths only if the file's checksum does not match the
+ one in the apk database.
+
+*-*
+ Do not protect matching paths, even if it matched a previous rule.
+
+*@*
+ Protect matching paths only if they are symlinks which have been
+ modified.
+
+*!*
+ Protect matching path unconditionally.
+
+Lines starting with *#* and empty lines are ignored.
+
+# EXAMPLES
+
+```
+# This line is ignored; it is a comment.
++etc/
+@etc/init.d
+!etc/apk
+\-etc/ssl/certs/ca-cert-\*.pem
+```
+
+# CAVEATS
+
+If a file is modified, and its contents eventually become the same as what was
+originally installed by apk, the file is considered to have been unmodified.
+
+Wildcard patterns are not taken into account by *apk*(8) when creating
+*.apk-new* files instead of overwriting files.
+
+# SEE ALSO
+
+*apk*(8), *apk-audit*(8)
diff --git a/doc/apk-query.8.scd b/doc/apk-query.8.scd
new file mode 100644
index 0000000..f20ecf9
--- /dev/null
+++ b/doc/apk-query.8.scd
@@ -0,0 +1,137 @@
+apk-query(8)
+
+# NAME
+
+apk query - query information about packages by various criteria
+
+# SYNOPSIS
+
+*apk query* [<_options_>...] _query_...
+
+*apk query* [<_options_>...] *--recursive* _constraints_...
+
+# DESCRIPTION
+
+*apk query* searches for matching packages from selected sources.
+
+In the default mode, _query_ specifiers are interpreted as follows:
+ *name{[<>~=]version}*
+ Select packages by *name* and optional *version* match.
+ *text*
+ Select packages by selected fields matching *text*.
+
+In the *--recursive* mode, the _constraints_ specify a list of dependencies
+to satisfy and the solver algorithm is used to determine a list of packages
+that fullfill these constraints.
+
+The query executes in the following steps:
+. Each _query_ string is executed independently to select candidate packages
+. If *--all-matches* is not specified, the best candidate for given term
+ is added to the list of result packages
+. The resulting package list is sorted
+
+# QUERY OPTIONS
+
+The applets supporting query specifiers recognize the following options:
+
+*--all-matches*
+ Select all matched packages. By default only best match for each query
+ element is selected.
+
+*--available*
+ Filter selection to available packages.
+
+*--fields* _FIELDS_[:_REVERSE_FIELD_]
+ A comma separated list of fields to include in the output. An optional
+ specification to specify the field to output for the synthetic reverse
+ dependency fields can be specifed (*name*, *package* or *origin*).
+
+*--format* _FORMATSPEC_
+ Specify output format from *default*, *yaml* or *json*. The *default*
+ format is human readable text output.
+
+*--from* _FROMSPEC_
+ Search packages from: *system* (all system sources), *repositories*
+ (exclude installed database), *installed* (exclude normal repositories)
+ or *none* (commandline repositories only).
+
+*--installed*
+ Filter selection to installed packages.
+
+*--match* _FIELDS_
+ A comma separated list of fields to match the query against.
+
+*--recursive*
+ Run solver algorithm with given _constraints_ to select packages.
+
+*--summarize* _FIELD_[:_REVERSE_FIELD_]
+ Produce a summary of the specified field from all matches.
+ Summary is available on the following fields: *package*, *name*,
+ *origin*, *depends*, *provides*, *replaces*, *install_if*,
+ *recommends*, *reverse-depends*, and *reverse-install-if*.
+
+*--upgradable*
+ Filter selection to upgradable packages.
+
+*--world*
+ Include *apk-world*(5) dependencies in constraints. Implies *--recursive*.
+
+*--orphaned*
+ Filter selection to orphaned packages.
+
+# FIELDS
+
+The field names are all small letters for *--match* and *--fields* options
+and for the machine parseable output (json and yaml). For the human readable
+default format the fields are capitalized.
+
+The following package metadata fields are available:
+*name*, *version*, *description*, *arch*, *license*, *origin*, *maintainer*,
+*url*, *commit*, *build-time*, *installed-size*, *file-size*, *provider-priority*,
+*depends*, *provides*, *replaces*, *install-if*, *layer*, *tags*, *triggers*,
+*scripts*, and *replaces-priority*.
+See *apk-package*(8) *package info metadata* and *package metadata* sections
+for the description of these fields.
+
+Additionally the following fields are available:
+
+*contents*
+ File names contained in a package.
+
+*download-url*
+ Full URL to download the package from.
+
+*owner*
+ Lookup owner package for given path name. (*--match* only)
+
+*package*
+ The package identifier in format *name*-*version* (e.g.
+ package-1.0-r0).
+
+*repositories*
+ List of repositories the package is available from.
+
+*status*
+ Status of an installed package. List of one or more of following
+ keywords:
+ - *installed*
+ - *broken-files*
+ - *broken-scripts*
+ - *broken-xattr*
+
+# EXAMPLES
+
+\# search all packages starting with apk++
+apk query "apk\*"
+
+\# show owner package of sensors executable in json++
+apk query --format json --match owner /usr/bin/sensors
+
+\# show apk-tools and its dependencies in yaml++
+apk query --format yaml --recursive apk-tools
+
+\# print source packages for all packages providing cmd:apk++
+apk query --match name,provides cmd:apk --fields origin
+
+\# print source packages with specific dependency name++
+apk query --match dependency so:libapk.so.2.14.9 --fields origin
diff --git a/doc/apk-repositories.5.scd b/doc/apk-repositories.5.scd
index 7b3d3ca..ece451b 100644
--- a/doc/apk-repositories.5.scd
+++ b/doc/apk-repositories.5.scd
@@ -2,35 +2,111 @@ apk-repositories(5)
# NAME
-*/etc/apk/repositories*, */etc/apk/repositories.d/\*.list* - list of package
-repositories
+*/etc/apk/repositories*++
+*/etc/apk/repositories.d/\*.list*++
+*/lib/apk/repositories.d/\*.list*++
+ list of package repositories
# DESCRIPTION
-/etc/apk/repositories is the list of package repositories *apk*(8) uses to
-retrieve package files for installation. Each line of this file specifies the
-location of a package repository, and optionally a tag.
+*apk*(8) loads repository definitions from the above mentioned files.
-The location may be an _http://_, _https://_, or _ftp://_ URL, or the path to a
-directory on the local filesystem. A tagged repository is prefixed with the
-*@tag* specifier, followed by a space and the repository location. For more
-information about repository tags, see *apk-world*(5).
+The *repositories* file is first loaded. The *repositories.d* paths are
+then processed if *--repositories-file* option was not used. The directories
+are enumerated in the above mentioned order. Once a *.list* file of given
+name is seen, any file of the same name in subsequent directories is ignored.
+
+# FILE FORMAT
+
+Each line follows one of the following syntax:
+
+*\# comment*
+ A comment line which is ignored.
+
+*set \[-default\] key=value*
+ Set the variable named *key* to given *value*.
+
+ The *key* is limited to letters, numbers and the underscore (\_) character,
+ and must start with a letter. The *APK_* prefixed variable names are
+ reserved for built-in variables and cannot be defined by the user.
+
+ A variable expansion is perfomered on the *value* before assignment.
+
+ If the option *-default* is specified, the *key* value is not changed
+ if it already exists.
+
+ Currently the following variables are defined:
+ - *APK_ARCH*, the primary architecture of the database
+
+*ndx \[@tag\] url*++
+*\[v2|v3\] \[@tag\] url \[component...\]*
+ If a repository declaration omits the type field it defaults to the type
+ defined in latest *default* command, or if absent, to *v2* (or *ndx* if *url*
+ ends with *.adb* or *.tar.gz*). If the format is *v3* or the *ndx* filename
+ ends with *.adb* a v3 format index file required.
+
+ The optional *@tag* can be present to indicate that the repository should
+ not be used by default. Refer to *apk-world*(5) on how to enable installation
+ of packages from tagged repositories.
+
+ A variable expansion is performed on the *url* and *component* portions
+ individually at the time of parsing the line.
+
+ The *url* refers to an index file or a repository path. Currently supported
+ schemes are:
+ - _http://_
+ - _https://_
+ - _file://_
+ - absolute filesystem path (must start with `/`)
+
+ The *component* list specifies a list of repository components. If specifies,
+ the line is expanded to multiple URLs: one for each component, and the *component*
+ is appended to the *url*. Specifying *component* with *ndx* type is not valid.
+
+# EXAMPLES
+
+To define a distribution provided repository list, the distribution can
+ship e.g */lib/apk/repositories.d/distribution.list* with the contents:
+
+ set -default distro_mirror=https://example.com/distro++
+v3 ${distro_mirror} main community
+
+In */etc/apk/repositories.d/00-vars.list* the mirror can be overridden with:
+
+ set distro_mirror=https://mirror.example.com/distro
# REPOSITORY LAYOUT
-Each repository must store an index at *$repository/$arch/APKINDEX.tar.gz*. See
-*apk-index*(8) for information about generating this file. The packages
-themselves are stored at *$repository/$arch/$pkgname-$pkgver-r$pkgrel.apk*.
+If the *type* is *ndx*, the layout and path resolution is as follows:
+ - *url* is a URL to the index file
+ - *base_url* is *url* with last component stripped off
+ - default package path: *$base_url/$name-$version.apk*
+
+Otherwise the *type* is one of the repository types, and the path resolution
+works as follows:
+ - *url* is the *base_url* to the repository
+ - index (*v3*) is at *$base_url/$arch/Packages.adb*
+ - index (*v2*) is at *$base_url/$arch/APKINDEX.tar.gz*
+ - default package path: *$base_url/$arch/$name-$version.apk*
+
+If the index file has a *pkgname-spec* set, it is used to construct the package path.
+Otherwise the default package path based on above rules is used.
+
+# CREATING INDEXES AND REPOSITORIES
+
+See *apk-mkndx*(8) on how to create index files and *apk-adbsign*(8) on modifying
+signatures.
+
+For the legacy index format refer to *apk-index*(8) for index files, *abuild-keygen*(1)
+for information about generating keys, *abuild-sign*(1) for information about using
+these keys to sign files.
+
+*apk-verify*(8) can verify both new and old style index and package files.
-*apk*(8) verifies that each of these files has a valid cryptographic signature
-unless explicitly told not to via the *--allow-untrusted* flag. See
-*abuild-keygen*(1) for information about generating keys, *apk-keys*(5) to add
-keys to the list of trusted keys, *abuild-sign*(1) for information about using
-these keys to sign files, and *apk-verify*(8) for information about verifying
-those signatures.
+# CLIENT INDEX UPDATING
-# UPDATING INDICIES
+*apk*(8) fetches and stores the index for each repository at a local cache
+in */etc/apk/cache* or */var/cache/apk*. Refer to *apk-cache*(5) for more details.
-*apk*(8) fetches and stores the index for each package repository at
-*/var/cache/apk*. To fetch fresh indicies for all configured repositories, use
-*apk-update*(8).
+Refer to *apk-keys*(5) on how the client needs to be configured for verifying
+the index signatures.
diff --git a/doc/apk-search.8.scd b/doc/apk-search.8.scd
index b2617da..99c0e5d 100644
--- a/doc/apk-search.8.scd
+++ b/doc/apk-search.8.scd
@@ -17,27 +17,27 @@ case-insensitive substring of the package name.
# OPTIONS
-In addition to the global options (see *apk*(8)), *apk search* supports the
-following options:
+In addition to the global options (see *apk*(8)), and query options
+(see *apk-query*(8)) the following options are supported:
-*-a, --all*
+*--all*, *-a*
Print all matching package versions. By default, *apk* only shows the
latest version.
-*-d, --description*
+*--description*, *-d*
Also search for _pattern_ in the package description. By default, *apk*
does not search package descriptions.
-*-e, -x, --exact*
+*--exact*, *-e*, *-x*
Match package names exactly.
*--has-origin*
Match by package origin. Shows all packages whose base package name
matches _pattern_ exactly. Implies *--all* and *--exact*.
-*-o, --origin*
+*--origin*, *-o*
Print base package name.
-*-r, --rdepends*
+*--rdepends*, *-r*
Print reverse dependencies (other packages which depend on the
package).
diff --git a/doc/apk-upgrade.8.scd b/doc/apk-upgrade.8.scd
index 10b245a..43bce07 100644
--- a/doc/apk-upgrade.8.scd
+++ b/doc/apk-upgrade.8.scd
@@ -15,12 +15,21 @@ configured package repositories (see *apk-repositories*(5)). When no packages
are specified, all packages are upgraded if possible. If list of packages is
provided, only those packages are upgraded along with needed dependencies.
+If dependencies mentioned in *--preupgrade-depends* (see *apk*(8)) match
+an upgradabable package, a preupgrade step is performed. During the preupgrade
+step, the installed packages matching the preupgrade dependencies are upgraded
+if possible - their dependencies are enforced (but not upgraded unless required
+by the dependencies in the new package).
+
+An implicit preupgrade dependency is generated for the package owning the apk
+executable.
+
# OPTIONS
*apk upgrade* supports the commit options described in *apk*(8), as well as the
following options:
-*-a, --available*
+*--available*, *-a*
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
@@ -33,18 +42,18 @@ following options:
Upgrade all other packages than the ones listed. This inverts the given
package name list to mean packages that should not be upgraded.
-*-l, --latest*
+*--latest*, *-l*
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.
+*--preupgrade*[=_BOOL_]
+ If turned off, disables the preupgrade step.
+
+*--preupgrade-only*
+ Perform only the preupgrade.
*--prune*
Prune the _world_ by removing packages which are no longer available
from any configured repository.
-
-*--self-upgrade-only*
- Only perform a self-upgrade of the 'apk-tools' package.
diff --git a/doc/apk-v2.5.scd b/doc/apk-v2.5.scd
new file mode 100644
index 0000000..bed1196
--- /dev/null
+++ b/doc/apk-v2.5.scd
@@ -0,0 +1,87 @@
+apk-v2(5)
+
+# NAME
+
+apk v2 - overview of apk v2 format
+
+# DESCRIPTION
+
+A v2 .apk file contains a single package's contents, some metadata, and
+some signatures. The .apk file contains three concatenated gzip streams,
+which together form a single tar archive. The tar archive contains three
+sections: the signatures, the control section, and the data section.
+
+# THE SIGNATURES
+
+The signatures are a sequence of files whose names start with ".SIGN.",
+which must come before any other data in the tarball. These filenames
+look like:
+
+ *.SIGN.<algorithm>.<keyid>*
+
+where <algorithm> must be one of *DSA*, *RSA*, *RSA256*, and *RSA512*
+and <keyid> must be the name of the key's file in /etc/apk/keys (see
+*apk-keys*(5)).
+
+The signature can be computed over either the metadata (if the metadata
+contains a data hash for the data), or over the metadata and data
+together (if the metadata contains no data hash).
+
+A single signature from a trusted key is sufficient, so an apk can be
+signed by multiple different keys if need be, as long as clients trust
+at least one of them.
+
+# THE CONTROL SECTION
+
+In a v2 apk file, the package metadata is stored in a single file called
+.PKGINFO. That file uses a key-value format, in which keys and values
+are separated by " = " and lines beginning with "#" are comments. There
+are many allowed keys and there is no centralized list of known keys;
+the source of *abuild*(1) is the best reference.
+
+One key is important for understanding the v2 format because it affects
+the interpretation of the signature: if there is a "datahash" key in
+PKGINFO, its value is the sha256 hash of the data part of the apk.
+Packages are supposed to have a datahash, but indexes do not.
+
+The control section is also where pre/post hook scripts for install, deinstall,
+and upgrade live, and where triggers live.
+
+# THE DATA SECTION
+
+The data section is simply a tar archive of the package's contents, as
+produced by the build process. These files are postprocessed by
+*abuild-tar*(1) and use pax extended headers to include per-file
+checksums in a header named APK-TOOLS.checksum.*<hash>*.
+
+# EXAMPLE
+
+As an example, the v2 apk for *scdoc*(1) itself contains these files in
+this order:
+
+```
+.SIGN.RSA.alpine-devel@lists.alpinelinux.org-6165ee59.rsa.pub
+.PKGINFO
+usr/
+usr/bin/
+usr/bin/scdoc
+usr/share/
+usr/share/pkgconfig/
+usr/share/pkgconfig/scdoc.pc
+```
+
+Since v2 apk files are simply tarballs (broken into multiple gzip
+streams), they can be inspected and unpacked with *tar*(1), although
+care must be taken when changing them not to reorder the sections or
+invalidate the signature. It is better to use *abuild*(1) to modify
+them. If you want to take them apart into their constituent gzip
+streams, you can use *abuild-gzsplit*(1).
+
+# NOTES
+
+Only the "RSA" (meaning RSA + SHA1) signature scheme is currently used
+by *abuild*(1).
+
+# SEE ALSO
+
+*abuild*(1), *apk*(8), *apk-package*(5), *apk-v3*(5)
diff --git a/doc/apk-v3.5.scd b/doc/apk-v3.5.scd
new file mode 100644
index 0000000..1fc155a
--- /dev/null
+++ b/doc/apk-v3.5.scd
@@ -0,0 +1,169 @@
+apk-v3(5)
+
+# NAME
+
+apk v3 - overview of apk v3 format
+
+# DESCRIPTION
+
+A v3 .apk file contains a single package's contents, some metadata, and
+some signatures. The .apk file contains a tree of objects, represented
+in a custom binary format and conforming overall to a pre-defined
+schema. This file format is referred to inside *apk*(5) as "adb".
+
+# WIRE FORMAT
+
+A v3 apk file is composed of sequences of serialized values, each of
+which begins with a 32-bit little-endian word - the value's tag. The
+high 4 bits of the tag are a type code, and the low 28 bits are used for
+an immediate value. Defined type codes are:
+
+|[ 0x0
+:[ Special
+:[ (direct)
+| 0x1
+: Int
+: (direct)
+| 0x2
+: Int32
+: (indirect)
+| 0x3
+: Int64
+: (indirect)
+| 0x8
+: Blob8
+: (indirect)
+| 0x9
+: Blob16
+: (indirect)
+| 0xa
+: Blob32
+: (indirect)
+| 0xd
+: Array
+: (indirect)
+| 0xe
+: Object
+: (indirect)
+
+A direct value is packed into the low 28 bits of the tag word; an
+indirect value is instead stored elsewhere in the file, and the offset
+of that indirect value is packed into the low 28 bits of the tag word.
+
+Arrays and objects are represented with a sequence of numbered slots;
+the value packed into their tag word is the offset at which this
+sequence starts. The first slot is always the total number of slots, so
+all arrays and objects contain at least one item.
+
+The only real difference between arrays and objects in the wire encoding
+is that arrays are homogenous, whereas objects are heterogenous with a
+separate defined type for each slot.
+
+The special type is used to represent three atoms:
+
+|[ 0x0
+:[ NULL
+| 0x1
+: TRUE
+| 0x2
+: FALSE
+
+# FILE SCHEMAS
+
+A schema is a representation of what data elements are expected in an
+adb file. Schemas form a tree, where nodes are either scalar schemas
+(which are leaves in the tree) or array/object schemas, which themselves
+have children. For example, the schema for a package object might
+declare that it contains fields which themselves conform to the string
+array schema, or the pkginfo schema, or similar.
+
+The schemas themselves are not represented in the adb file in any way;
+they exist in the parts of *apk*(1) that read and write such files. A
+full description of all of apk's schemas would be lengthy, but as an
+example, here is the schema for a single file inside a package:
+
+|[ ADBI_FI_NAME
+:[ "name"
+:[ string
+| ADBI_FI_ACL
+: "acl"
+: acl
+| ADBI_FI_SIZE
+: "size"
+: int
+| ADBI_FI_MTIME
+: "mtime"
+: int
+| ADBI_FI_HASHES
+: "hash"
+: hexblob
+| ADBI_FI_TARGET
+: "target"
+: hexblob
+
+Here, all of the fields except for "acl" are scalars, and acl is itself
+a schema looking like:
+
+|[ ADBI_ACL_MODE
+:[ "mode"
+:[ oct
+| ADBI_ACL_USER
+: "user"
+: string
+| ADBI_ACL_GROUP
+: "group"
+: string
+
+# BLOCKS
+
+An actual adb file is composed of a sequence of typed blocks; a block
+also begins with a 32-bit little-endian tag word, which has two bits of
+type and 30 bits of size. The two type bits are:
+
+|[ 0x0
+:[ ADB
+| 0x1
+: SIG
+| 0x2
+: DATA
+| 0x3
+: DATAX
+
+The adb file must begin with one ADB block, then optionally one or more
+SIG blocks, then one or more DATA blocks. The ADB block must begin with a
+magic number indicating the schema for the entire ADB block's root
+object. The ADB block also contains, outside the root object, some
+metadata describing the version of the adb format in use.
+
+The SIG block contains one or more signatures of the ADB block. Signatures
+of the same version should be in the same SIG block. If in future, a new
+signature version is specified, and package should contain for compatibility
+reasons two different versions of signature during transiton time, then there
+should be two signature blocks, one of each version.
+
+Unlike the v2 format, the key name used for the signature is not
+explicitly specified. Instead an intrisic ID of the key is used for the
+lookup, so verifiers must find the key based in the key ID. Also unlike
+the v2 format, the ADB block is not signed directly, but it is hashed
+first by a secure digest (currently SHA512). After this a small payload
+with this pre-calculated digest is signed by given algorithm (usually
+the payload is then hashed again by the signing process with a secure
+digest based on the signature algorithm).
+
+The DATA blocks are used to store package file data only; all file
+metadata, including content hashes, is stored in the ADB block instead.
+The contents of the DATA blocks are therefore protected by the hashes
+given in the ADB block, which is itself protected by the signature in
+the SIG block.
+
+It is currently illegal for a DATAX block to appear.
+
+# NOTES
+
+The v3 file format is entangled with C struct layout, since it sometimes
+directly writes structs into the adb section, including any
+compiler-added padding and such.
+
+# SEE ALSO
+
+*abuild*(1), *apk*(8), *apk-package*(5), *apk-v2*(5)
diff --git a/doc/apk-version.8.scd b/doc/apk-version.8.scd
index acd0d47..e0ad5f8 100644
--- a/doc/apk-version.8.scd
+++ b/doc/apk-version.8.scd
@@ -33,23 +33,23 @@ These options only apply when checking installed package versions against
packages available from the repositories (when neither *-c*, *-t*, nor *-I* are
specified).
-*-a, --all*
+*--all*, *-a*
Consider packages from all repository tags.
-*-c, --check*
+*--check*, *-c*
Check versions for validity. If a given version is invalid, it is
printed. Exits with status code zero if all versions are valid, and
non-zero otherwise.
-*-I, --indexes*
+*--indexes*, *-I*
Print the version and description for each repository's index. See
*apk-repositories*(5) for more information.
-*-l, --limit* _operand_
+*--limit*, *-l* _operand_
Limit to packages with output matching given _operand_. The _operand_
can be specified as any combination of *>*, *=*, and *<*.
-*-t, --test*
+*--test*, *-t*
Compare two version strings. Does not consult the database. Prints one
of *>*, *=*, or *<*, if _version1_ is, respectively, greater than,
equal to, or lesser than _version2_.
diff --git a/doc/apk-world.5.scd b/doc/apk-world.5.scd
index 4a185bd..0dcb4bc 100644
--- a/doc/apk-world.5.scd
+++ b/doc/apk-world.5.scd
@@ -15,7 +15,7 @@ changes.
# PACKAGE SPECIFICATION
This is a plaintext file with one constraint using dependency notation per line.
-Each line has the format: *name{@tag}{[<>~=]version}*.
+Each line has the format: *[!]name{@tag}{[<>~=]version}*.
When modifying existing installation, the installed version is preferred unless
an upgrade is requested or a world constraint or package dependency requires
@@ -36,6 +36,10 @@ equal to, less than, greater than, greater than or equal, prefix match, greater
than or prefix match, or less than or prefix match to the specified version.
The *~* operator constrains the package to the prefix match of the version number.
+The optional *!* in front of the name changes the dependency constraint to
+a conflict and ensures that any package matching the specification is not
+installed.
+
*busybox*
Installs busybox from the untagged repository from which it is
available.
@@ -45,6 +49,9 @@ The *~* operator constrains the package to the prefix match of the version numbe
tagged with "edge". Tagged repositories will not be prioritized. If a
version from an untagged repository is a better fit it will be used.
+*!unwanted*
+ Prevents installation of unwanted as a dependency by creating a conflict.
+
*busybox=1.6.1*
Install busybox version 1.6.1.
diff --git a/doc/apk.8.scd b/doc/apk.8.scd
index 8fa7dc6..f9ce0ec 100644
--- a/doc/apk.8.scd
+++ b/doc/apk.8.scd
@@ -6,7 +6,7 @@ apk - Alpine Package Keeper
# SYNOPSIS
-*apk* [<_options_>...] _command_ [<_arguments_>...]
+*apk* [<_global options_>...] _command_ [<_options_>...] [<_arguments_>...]
# DESCRIPTION
@@ -16,9 +16,15 @@ on system packages is called the _world_ (see *apk-world*(5)).
*apk* supports various sub-commands to query and manipulate _world_ and package
repositories.
+All apk commands which modify the database are logged to /var/log/apk.log.
+
By default apk is non-interactive. See *FILES* or *--interactive* on changing
this default to be interactive.
+Only _global options_ should be specified before _command_. For backwards
+compatilibity a best effort attempt is made to parse applet specific options
+before the _command_, but this is deprecated and subject to be removed.
+
# COMMANDS
Each command is documented in detail on its manual page.
@@ -43,8 +49,8 @@ Each command is documented in detail on its manual page.
## QUERYING PACKAGE INFORMATION
-|[ *apk-info*(8)
-:< Give detailed information about packages or repositories
+|[ *apk-query*(8)
+:< Query information about packages by various criteria
| *apk-list*(8)
: List packages matching a pattern or other criteria
| *apk-dot*(8)
@@ -53,17 +59,27 @@ Each command is documented in detail on its manual page.
: Show repository policy for packages
| *apk-search*(8)
: Search for packages by name or description
+| *apk-info*(8)
+:< Give detailed information about packages or repositories
-## REPOSITORY MAINTENANCE
+## REPOSITORY AND PACKAGE MAINTENANCE
-|[ *apk-index*(8)
-:< Create repository index file from packages
+|[ *apk-mkndx*(8)
+:< Create repository index (v3) file from packages
+| *apk-mkpkg*(8)
+: Create package (v3)
+| *apk-index*(8)
+: Create repository index (v2) file from packages
| *apk-fetch*(8)
: Download packages from repositories to a local directory
| *apk-manifest*(8)
: Show checksums of package contents
+| *apk-extract*(8)
+: Extract package file contents
| *apk-verify*(8)
: Verify package integrity and signature
+| *apk-adbsign*(8)
+: Sign, resign or recompress v3 packages and indexes
## MISCELLANEOUS
@@ -73,44 +89,44 @@ Each command is documented in detail on its manual page.
: Show statistics about repositories and installations
| *apk-version*(8)
: Compare package versions or perform tests on version strings
+| *apk-adbdump*(8)
+: Dump v3 files in textual representation
+| *apk-adbgen*(8)
+: Generate v3 files from text representation
+| *apk-convdb*(8)
+: Convert v2 installed database to v3 format
+| *apk-convndx*(8)
+: Convert v2 indexes to v3 format
+
+# OPTION SYNTAX
+
+The _BOOL_ argument for options is '*yes*' or '*no*'.
+The _AUTO_ argument for options is '*yes*', '*no*' or '*auto*'.
+The default value for these arguments is options specific.
+
+For options with an _AUTO_ or _BOOL_ argument, the argument must be specified
+with the *--option=argument* format (that is, the *--option argument* format
+is not supported). Additionally the following aliases are available:
+ - *--option* equals *--option=yes*
+ - *--no-option* equals *--option=no*
# GLOBAL OPTIONS
The following options are available for all commands.
-*-f, --force*
- Enable selected --force-\* options (deprecated).
-
-*-i, --interactive*
- Ask confirmation before performing certain operations.
- Interactive mode can be made the default when running on a tty,
- by creating /etc/apk/interactive as an empty file.
-
-*-p, --root* _ROOT_
- Manage file system at _ROOT_.
-
-*-q, --quiet*
- Print less information.
-
-*-U, --update-cache*
- Alias for '--cache-max-age 0'.
-
-*-v, --verbose*
- Print more information (can be specified twice).
-
-*-V, --version*
- Print program version and exit.
-
-*-X, --repository* _REPO_
- Specify additional package repository. This option can be specified
- multiple times.
-
*--allow-untrusted*
Install packages with untrusted signature or no signature.
*--arch* _ARCH_
- Temporarily override architecture. When used with --root the
- architecture will be saved.
+ Temporarily override architectures. The first given *--arch* will be used
+ as the primary architecture. It will be used to determine the paths where
+ to download package indexes from. The additional architectures specify
+ compatible packages which are considered for installation.
+
+ When used with --root the architecture will also be saved.
+
+*--cache*[=_BOOL_]
+ When disabled, prevents using any local cache paths.
*--cache-dir* _CACHEDIR_
Temporarily override the cache directory. _CACHEDIR_ is treated relative
@@ -120,6 +136,20 @@ The following options are available for all commands.
Maximum AGE (in minutes) for index in cache before it's refreshed. *0*
means always refresh.
+*--cache-packages*[=_BOOL_]
+ Store a copy of packages at installation time to cache. Enabled automatically
+ if */etc/apk/cache* symlink exists.
+
+*--cache-predownload*[=_BOOL_]
+ Download needed packages to cache before starting to commit a transtaction.
+ Requires cache to be configured to be functional. Implies *--cache-packages*.
+
+*--check-certificate*[=_BOOL_]
+ When disabled, omits the validation of the HTTPS server certificate.
+
+*--force*, *-f*
+ Enable selected --force-\* options (deprecated).
+
*--force-binary-stdout*
Continue even if binary data will be printed to the terminal.
@@ -141,6 +171,11 @@ The following options are available for all commands.
*--force-missing-repositories*
Continue even if some of the repository indexes are not available.
+*--force-no-chroot*
+ Disable chroot for scripts. This can be used for rootfs creation when
+ chroot is not available. Scripts running outside a chroot environment
+ may modify and damage the host system.
+
*--force-non-repository*
Continue even if packages may be lost on reboot. This can happen when
running in run-from-tmpfs mode, and installing non-repository package.
@@ -154,49 +189,117 @@ The following options are available for all commands.
*--force-refresh*
Do not use cached files (local or from proxy).
-*--keys-dir* _KEYSDIR_
- Override directory of trusted keys. This is treated relative to _ROOT_.
+*--help*, *-h*
+ Print the list of all commands with descriptions.
-*--no-cache*
- Do not use any local cache path.
+*--interactive*[=_AUTO_]
+ Determine if questions can be asked before performing certain operations.
+ In *auto* mode, the interactive mode is enabled if running on a tty.
+ Defaults to *no*, or *auto* if */etc/apk/interactive* exists.
-*--no-check-certificate*
- Do not validate the HTTPS server certificates.
-
-*--no-interactive*
- Disable interactive mode.
-
-*--no-network*
- Do not use the network. The cache is still used when possible.
-
-*--no-progress*
- Disable progress bar even for TTYs.
+*--keys-dir* _KEYSDIR_
+ Override the default system trusted keys directories. If specified the
+ only this directory is processed. The _KEYSDIR_ is treated relative
+ to _ROOT_.
+
+*--legacy-info*[=_BOOL_]
+ Print output from "info" applet in legacy format or new "query" format.
+ Defaults to no currently, but the default is subject to change to yes
+ in a future release.
+
+*--logfile*[=_BOOL_]
+ If turned off, disables the writing of the log file.
+
+*--network*[=_BOOL_]
+ If turned off, does not use the network. The packages from network
+ repositories in the cache are used.
+
+*--preserve-env*[=_BOOL_]
+ Allow passing the user environment down to scripts (excluding
+ variables starting APK_ which are reserved).
+
+*--pretty-print*[=_AUTO_]
+ Determine if output should be stylized to be human readable.
+ Defaults to *auto* which resolves to *yes* if running on a tty.
+
+*--preupgrade-depends* _DEPS_
+ Add or modify preupgrade dependencies. The preupgrade dependencies
+ are used to match installed packages that are eligible for preupgrade.
+ E.g. 'apk-tools' will always preupgrade the 'apk-tools' package,
+ but 'baselayout<2' would preupgrade the 'baselayout' only if the
+ installed version of baselayout is less than 2 and an upgrade is
+ available. See also *apk-upgrade*(8).
*--print-arch*
Print default arch and exit.
-*--progress*
- Show progress.
+*--progress*[=_AUTO_]
+ Enable or disable progress bar. Defaults to *auto* which resolves
+ to *yes* if running on a tty.
*--progress-fd* _FD_
Write progress to the specified file descriptor.
-*--purge*
+*--purge*[=_BOOL_]
Purge modified configuration and cached packages. Enables deletion of
modified configuration files on package removal. On cache clean action
this enables deletion of unneeded cached packages (uninstalled packages
on tmpfs installations or all packages on disk installations).
+*--quiet*, *-q*
+ Print less information.
+
*--repositories-file* _REPOFILE_
- Override system repositories, see *apk-repositories*(8). Specifying this
+ Override system repositories, see *apk-repositories*(5). Specifying this
option overrides the normal repositories file and repositories.d directory
processing. The given _REPOFILE_ is relative to the startup directory since
apk 2.12.0_rc2.
+*--repository*, *-X* _REPO_
+ Specify additional package repository. *apk-repositories*(5) specified
+ commands are not parsed (use *--repository-config* for that).
+ Additionally, relative paths are accepted and interpreted relative
+ to the startup directory.
+
+*--repository-config* _REPOCONFIG_
+ Specify additional package repository configuration. The _REPOCONFIG_ is
+ parsed exactly the same way as if it was read from a *apk-repositories*(5)
+ specified *.list* file.
+
+*--root*, *-p* _ROOT_
+ Manage file system at _ROOT_.
+
+*--root-tmpfs*[=_AUTO_]
+ Specify if the _ROOT_ is a temporary filesystem. Defaults to *auto* which
+ determines the filesystem type automatically.
+
+ This affects:
+ - reading and creation of 'installed' index in the cache
+ - purging of packages in cache
+ - safety checks to not install non-repository packages
+
+*--sync*[=_AUTO_]
+ Determine if filesystem caches should be committed to disk. Defaults
+ to *auto* which resolves to *yes* if *--root* is not specified, the
+ database is not in usermode, and running on the root pid namespace
+ (not containerized).
+
*--timeout* _TIME_
Timeout network connections if no progress is made in TIME seconds.
The default is 60 seconds.
+*--update-cache*, *-U*
+ Alias for '--cache-max-age 0'.
+
+*--uvol-manager* _UVOL_
+ Specify the OpenWRT _uvol_ volume manager executable location.
+
+*--verbose*, *-v*
+ Print more information (can be specified twice).
+
+*--version*, *-V*
+ Print program version and exit.
+
*--wait* _TIME_
Wait for TIME seconds to get an exclusive repository lock before
failing.
@@ -205,44 +308,49 @@ The following options are available for all commands.
The following options are available for all commands which commit the database.
-*-s, --simulate*
- Simulate the requested operation without making any changes. The database
- is opened in read only mode, and auto-updating of indexes is disabled.
- You may want to run "apk update" before running a simulation to make sure
- it is done with up-to-date repository indexes.
+*--clean-protected*[=_BOOL_]
+ If disabled, prevents creation of .apk-new files in configuration directories.
-*--clean-protected*
- Do not create .apk-new files in configuration directories.
+*--commit-hooks*[=_BOOL_]
+ If disabled, skips the pre/post hook scripts (but not other scripts).
+
+*--initramfs-diskless-boot*
+ Used by initramfs when it's recreating root tmpfs. This enables selected
+ force options to minimize failure, and disables commit hooks, among
+ other features.
*--overlay-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. Useful for extracting a system image for
- different architecture on alternative _ROOT_.
+*--scripts*[=_BOOL_]
+ If disabled, prevents execution of all 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*
- Used by initramfs when it's recreating root tmpfs. This enables selected
- force options to minimize failure, and disables commit hooks, among
- other features.
+*--simulate*[=_BOOL_], *-s*
+ Simulate the requested operation without making any changes. The database
+ is opened in read only mode, and auto-updating of indexes is disabled.
+ You may want to run "apk update" before running a simulation to make sure
+ it is done with up-to-date repository indexes.
+# GENERATION OPTIONS
-# SOURCE OPTIONS
+The following options are available for all commands which generate APKv3 files.
-The following options are available for all commands which operate on the
-package indexes only.
+*--compression, -C* _ALGORITHM[:LEVEL]_
+ Compress the file with given _ALGORITHM_ and _LEVEL_. Supported algorithms:
+ - none
+ - deflate (level 1-9)
+ - zstd (level 1-22)
-*--from* _FROMSPEC_
- Search packages from: *system* (all system sources), *repositories*
- (exclude installed database), *installed* (exclude normal repositories)
- or *none* (commandline repositories only).
+*--sign-key* _KEYFILE_
+ Sign the file with a private key in the specified _KEYFILE_.
# ENVIRONMENT
+*APK_CONFIG*
+ Override the default config file name. See */etc/apk/config*
+
*LANG*
Used to determine if UTF-8 is supported, and set the default progress
character accordingly.
@@ -260,10 +368,6 @@ package indexes only.
A local IP address to which libfetch will bind all sockets it creates.
Can be useful for source routing.
-*FTP_PROXY*, *ftp_proxy*
- If set, these variables should contain the proxy URL for *ftp*
- connections.
-
*NETRC*
Specify the *.netrc* file to read for authentication secrets. If not
set, defaults to *$HOME/.netrc*.
@@ -296,10 +400,46 @@ package indexes only.
*SSL_NO_VERIFY_HOSTNAME*
If set to anything, disables the server certificate name verification.
+## Environment for the scripts APK executes
+
+Normally *apk* will execute scripts with a sanitized, minimal environment
+containing only *PATH*. See also *--preserve-env* to pass additional
+environment variables.
+
+Before executing a script, apk will set working directory as _ROOT_ and
+performs a chroot unless *--force-no-chroot* is specified. In either case,
+the script working directory should be treated as the system root.
+
+The environment variables defined by APK are the following:
+
+*APK_PACKAGE*
+ Package name (package scripts only).
+
+*APK_SCRIPT*
+ Set to one of the package or commit script types. Use this to determine
+ the script hook type if needed. The filename (\$0) is not reliable since
+ apk prefers to execute package scripts from a memfd file.
+
# FILES
## Configuration files
+*/etc/apk/config*++
+*/lib/apk/config*
+ Default global options. Only the first file existing in the above list is
+ read and parsed. The file in */lib* is intended to be for distribution default
+ options, which can be then overridden by user with the file in */etc*. See also
+ *APK_CONFIG* environment variable.
+
+ A configuration file contains one long option per line. For example:
+ no-cache++
+timeout 120
+
+*/etc/apk/interactive*
+ If this file exists it defaults *--interactive* to *auto*.
+
+## Configuration files (relative to --root)
+
*/etc/apk/arch*
The CPU architecture for this database. See *apk-package*(5) section
on package metadata field *arch* for the list.
@@ -308,30 +448,37 @@ package indexes only.
This is expected to be a symlink to directory what apk will use
as package cache. See also *apk-cache*(5) and *apk-cache*(8).
-*/etc/apk/commit_hooks.d/\**
- Hook scripts which are executed before or after changes to database are
- committed. The script executed gets as an argument the stage name
- (*pre-commit* or *post-commit*). If the script returns failure during
- *pre-commit* stage, the commit is aborted.
+*/etc/apk/commit_hooks.d/\**++
+*/lib/apk/commit_hooks.d/\**
+ Hook scripts which are executed before anything has been written to the
+ filesystem and after all the changes have been commited. The script
+ executed gets as an argument the stage name (*pre-commit* or
+ *post-commit*). If the script returns failure during *pre-commit* stage,
+ the commit is aborted.
+
+ See also the ENVIRONMENT section for the environment variables.
If *--no-scripts* or *--no-commit-hooks* option is specified, these
hook scripts are not executed.
-*/etc/apk/interactive*
- If this file exists and apk is running on a tty, *--interactive*
- mode is enabled by default.
-
-*/etc/apk/keys*
- A directory containing trusted signing keys for apk.
+*/etc/apk/keys*++
+*/lib/apk/keys*
+ Directories for trusted signing keys. The directories are enumerated in
+ the above mentioned order. Once a given filename is seen, any file of
+ the same name in subsequent directories is ignored.
*/etc/apk/protected_paths.d/\*.list*
Configuration files to specify how to treat changes to specified
- directory or file masks.
+ directory or file masks. The file format is further documented in
+ *apk-protected_paths*(5).
*/etc/apk/repositories*++
-*/etc/apk/repositories.d/\*.list*
- Configuration files to specify repositories. See *apk-repositories*(5)
- for details.
+*/etc/apk/repositories.d/\*.list*++
+*/lib/apk/repositories.d/\*.list*
+ Configuration files to specify repositories. The directories are
+ enumerated in the above mentioned order. Once a given filename is seen,
+ any file of the same name in subsequent directories is ignored.
+ See *apk-repositories*(5) for details.
*/etc/apk/world*
Top level requirements and constraints on what should be installed.
@@ -361,16 +508,25 @@ package indexes only.
*/lib/apk/db/installed*
Database of installed packages and their contents.
-*/lib/apk/db/scripts.tar*
+*/lib/apk/db/scripts.tar*++
+*/lib/apk/db/scripts.tar.gz*
Collection of all package scripts from currently installed packages.
*/lib/apk/db/triggers*
List of triggers rules for currently installed packages.
+*/lib/apk/db-uvol*
+ Database symlink or a directory with similar structure as */lib/apk/db/*,
+ but which used for package content when managed using OpenWRT *uvol*
+ volume manager.
+
*/lib/apk/exec*
Temporary directory for extraction and execution of package scripts
and triggers.
+*/var/log/apk.log*
+ Log file for changes done to the system.
+
# NOTES
This apk has coffee making abilities.