.Dd March 09, 2020
.Dt AA 1
.Os macOS
.Sh NAME
.Nm aa
.Nd Manipulate Apple Archives
.Sh SYNOPSIS
aa \fBcommand\fR [\fBoptions\fR]
.Sh DESCRIPTION
aa creates and manipulates Apple Archives
.Sh COMMANDS
\fBarchive\fR\ \ \ \ \ \ \ \ \ \ \ Archive the contents of the target directory
.br
\fBappend\fR\ \ \ \ \ \ \ \ \ \ \ \ Archive the contents of the target directory, append to an existing archive file
.br
\fBextract\fR\ \ \ \ \ \ \ \ \ \ \ Extract the contents of an archive to the target directory
.br
\fBlist\fR\ \ \ \ \ \ \ \ \ \ \ \ \ \ List the contents of an archive
.br
\fBconvert\fR\ \ \ \ \ \ \ \ \ \ \ Convert an archive into another archive
.br
\fBmanifest\fR\ \ \ \ \ \ \ \ \ \ Alias for 'archive -manifest'
.br
\fBverify\fR\ \ \ \ \ \ \ \ \ \ \ \ Compare the contents of the target directory with a manifest
.br
\fBcheck-and-fix\fR\ \ \ \ \ Verify and fix the contents of the target directory using an error correcting manifest
.Sh OPTIONS
.Bl -tag -width indent
.It Fl v
Increase verbosity.
Default is silent operation.
.It Fl h
Print usage and exit.
.It Fl d \fIdir\fR
Target directory for archive/extract.
Default is the current directory.
.It Fl i \fIinput_file\fR
Input file.
Default is \fIstdin\fR.
.It Fl o \fIoutput_file\fR
Output file.
Default is \fIstdout\fR.
.It Fl subdir \fIsubdir\fR
Path to archive under \fIdir\fR.
\fIsubdir\fR will be included in the archived paths, and extracted.
Default is empty.
.It Fl D \fIdir_and_subdir\fR
Set both \fIdir\fR to `dirname \fIdir_and_subdir\fR` and \fIsubdir\fR to `basename \fIdir_and_subdir\fR`.
.It Fl x
Do not cross volume boundaries when archiving.
.It Fl p
Generate destination path automatically based on source path.
For example 'aa archive -d foo -p' becomes 'aa archive -d foo -o foo.aar'.
.It Fl a \fIalgorithm\fR
Compression algorithm used when creating archives.
One of \fIlzfse\fR, \fIlzma\fR, \fIlz4\fR, \fIzlib\fR, \fIraw\fR.
Default is \fIlzfse\fR.
.It Fl b \fIblock_size\fR
Block size used when compressing archives, a number with optional \fIb\fR, \fIk\fR, \fIm\fR, \fIg\fR suffix (bytes are assumed if no suffix
is specified).
Default is \fI4m\fR for \fIarchive\fR and \fI1m\fR for the other commands.
.It Fl t \fIworker_threads\fR
Number of worker threads compressing/decompressing data.
Default is the number of physical CPU on the running machine.
.It Fl wt \fIwriter_threads\fR
Number of writer threads extracting archive content.
Default is to match \fIworker_threads\fR.
.It Fl enable-dedup (-no-enable-dedup)
If set, and SLC fields (the SLC field identifies a cluster of regular files with identical content) are present in the archive, files with same data will be extracted as clones.
.Pp
Note that to create such an archive, you have to manually add the SLC field, for example `aa archive -o archive.aa -include-field SLC ...`.
In this case, aa marks files with identical content as a cluster and shows a summary at the end.
.Pp
There is no way to deduplicate the data in the archive (by storing the data only once) from the command line.
To achieve this, use the API and pass the `AA_FLAG_ARCHIVE_DEDUPLICATE_DAT` flag.
.It Fl enable-holes (-no-enable-holes)
If set, and the filesystem supports it, detect and create holes in files to store 0-filled segments
.It Fl ignore-eperm (-no-ignore-eperm)
If set, ignore EPERM (operation not permitted) errors when setting files attributes
.It Fl manifest
Alias for the following options:
.br
\fB\-exclude\-field\fR \fIdat\fR
.br
\fB\-include\-field\fR \fIsh2,siz,idx,idz\fR
.br
\fB\-a\fR \fIlzfse\fR \fB\-b\fR \fI1m\fR
.It Fl imanifest \fIinput_manifest_file\fR
Manifest matching the input archive.
Can be used in conjonction with the entry selection options to accelerate processing
.It Fl omanifest \fIoutput_manifest_file\fR
Receives a manifest of the output archive
.It Fl list-format \fIformat\fR
Output format for the \fBlist\fR command, one of \fItext\fR, \fIjson\fR.
Default is \fItext\fR
.El
.Sh ENTRY SELECTION OPTIONS
\fB-include-path\fR and \fB-include-path-list\fR options are applied first to select an initial set of entries,
then \fB-exclude-path\fR, \fB-exclude-path-list\fR, \fB-exclude-name\fR, \fB-exclude-regex\fR are applied to remove entries from this set.
.Pp
If no \fB-include-path\fR or \fB-include-path-list\fR option is given, all entries are included in the initial set.
If a directory is included/excluded, the entire sub-tree is included/excluded.
.Bl -tag -width indent
.It Fl include-path \fIpath\fR
Include entry paths having \fIpath\fR as a prefix.
This option can be given multiple times.
.It Fl exclude-path \fIpath\fR
Exclude entry paths having \fIpath\fR as a prefix.
This option can be given multiple times.
.It Fl include-path-list \fIpath_list_file\fR
File containing a list of paths to include, one entry per line.
This option can be given multiple times.
.It Fl exclude-path-list \fIpath_list_file\fR
File containing a list of paths to exclude, one entry per line.
This option can be given multiple times.
.It Fl include-regex \fIexpr\fR
Include entry paths matching regular expression \fIexpr\fR, see \fIre_format(7)\fR.
This option can be given multiple times.
.It Fl exclude\-regex \fIexpr\fR
Exclude entry paths matching regular expression \fIexpr\fR, see \fIre_format(7)\fR.
This option can be given multiple times.
.It Fl exclude\-name \fIname\fR
Exclude entry paths where a single component of the path matches exactly \fIname\fR.
This option can be given multiple times.
.It Fl -include-type \fI<type_spec>\fR
Include only entries matching the given types.
\fI<type_spec>\fR is a word containing one or more of the entry type characters listed below.
.It Fl exclude-type \fI<type_spec>\fR
Include only entries not matching the given types.
\fI<type_spec>\fR is a word containing one or more of the entry type characters listed below.
.It Fl include-field \fI<field_spec>\fR
Add the given fields to the set of field keys.
This option can be given multiple times.
\fI<field_spec>\fR is a comma separated list of entry field keys listed below.
.It Fl exclude-field \fI<field_spec>\fR
Remove the given fields from the set of field keys.
This option can be given multiple times.
\fI<field_spec>\fR is a comma separated list of entry field keys listed below.
.El
.Sh ENCRYPTION OPTIONS
When archiving, encryption is selected by one of the \fI\-password...\fR, \fI\-key...\fR, or \fI\-recipient\-pub\fR options.
.Pp
The archive will be signed if a private key is specified with \fI\-sign\-priv\fR.
.Pp
With the currently available profiles, public/private keys are on the Elliptic Curve P-256, and symmetric keys are 256-bit long.
.Bl -tag -width indent
.It Fl keychain
Use Keychain to load/store symmetric keys and passwords
.It Fl password \fIfile\fR
File containing encryption password.
When encrypting, and if \fI\-password\-gen\fR is passed,
receives the generated password.
Can be \fI\-\fR to print the password to standard output.
.It Fl -password-value \fIpassword\fR
Password.
.It Fl password-gen
When encrypting, generate a new random password.
It is recommended to always use this option,
in conjonction with \fI-keychain\fR to store the password in the Keychain, or \fI-password\fR to store the password in a file or print it.
.It Fl key \fIfile\fR
File containing encryption symmetric key.
When encrypting, and if \fI\-key\-gen\fR is passed,
receives the generated key.
.It Fl key-value \fIkey\fR
Symmetric key, either "hex:<64 hex digits>" or "base64:<32 bytes encoded using base64>".
.It Fl key-gen
When encrypting, generate a new random symmetric key.
.It Fl recipient-pub \fIfile\fR
Recipient public key for encryption.
The corresponding private key is required to decrypt the archive.
.It Fl recipient-priv \fIfile\fR
Recipient private key for decryption.
The archive must have been encrypted against the corresponding public key.
.It Fl sign-pub \fIfile\fR
Signing public key for decryption.
The archive must have been signed with the corresponding private key.
.It Fl sign-priv \fIfile\fR
Signing private key for encryption.
The corresponding public key is required to decrypt and authenticate the archive.
.El
.Sh ENTRY TYPES
\fBb\fR block special
.br
\fBc\fR character special
.br
\fBd\fR directory
.br
\fBf\fR regular file
.br
\fBl\fR symbolic link
.br
\fBm\fR metadata
.br
\fBp\fR fifo
.br
\fBs\fR socket
.Sh ENTRY FIELDS
\fBtyp\fR entry type
.br
\fBpat\fR path
.br
\fBlnk\fR link path
.br
\fBdev\fR device id
.br
\fBuid\fR user id
.br
\fBgid\fR group id
.br
\fBmod\fR access permissions
.br
\fBflg\fR flags
.br
\fBmtm\fR modification time
.br
\fBctm\fR creation time
.br
\fBbtm\fR backup time
.br
\fBxat\fR extended attributes
.br
\fBacl\fR access control list
.br
\fBcks\fR CRC32 checksum
.br
\fBsh1\fR SHA1 digest
.br
\fBsh2\fR SHA2-256 digest
.br
\fBdat\fR file contents
.br
\fBsiz\fR file size
.br
\fBduz\fR disk usage
.br
\fBidx\fR entry index in main archive
.br
\fByec\fR file data error correcting codes
.br
\fByaf\fR Apple Archive fields (in metadata entry)
.br
\fBall\fR alias for all fields (exclude only)
.br
\fBattr\fR alias for \fIuid,gid,mod,flg,mtm,btm,ctm\fR
.Sh EXAMPLES
Archive the contents of directory \fIfoo\fR into archive \fIfoo.aar\fR, using LZMA compression with 8 MB blocks
.Pp
.Rs
\ aa archive -d foo -o foo.aar -a lzma -b 8m
.Re
.Pp
Extract the contents of \fIfoo.aar\fR in directory \fIdst\fR
.Pp
.Rs
\ aa extract -d dst -i foo.aar
.Re
.Pp
Create a manifest of the contents of directory \fIfoo\fR into \fIfoo.manifest\fR, using LZFSE compression with 1 MB blocks
.Pp
.Rs
\ aa manifest -d foo -o foo.manifest -a lzfse -b 1m
.Re
.Pp
Verify the contents of \fIdst\fR match the manifest \fIfoo.manifest\fR
.Pp
.Rs
\ aa verify -i foo.manifest -d dst -v
.Re
.Pp
Print all entry paths in \fIfoo.manifest\fR
.Pp
.Rs
\ aa list -i foo.manifest
.Re
.Pp
Print all entry paths, uid, gid for regular files in \fIfoo.manifest\fR
.Pp
.Rs
\ aa list -v -i foo.manifest -include-type f -exclude-field all -include-field uid,gid,pat
.Re
.Pp
Create a manifest of the contents of archive \fIfoo.aar\fR in \fIfoo.manifest\fR
.Pp
.Rs
\ aa convert -manifest -v -i foo.aar -o foo.manifest
.Re
.Pp
Extract a subset of entries matching prefix \fIApplications/Mail.app\fR from archive \fIfoo.aar\fR in directory \fIdst\fR
.Pp
.Rs
\ aa extract -i foo.aar -include-path Applications/Mail.app -d dst
.Re
.Pp
Archive and encrypt directory \fIfoo\fR to archive \fIfoo.aea\fR, generating a random password and storing it in the Keychain
.Pp
.Rs
\ aa archive -d foo -o foo.aea -keychain -password-gen
.Re
.Pp
Decrypt and extract archive \fIfoo.aea\fR to directory \fIdst\fR, obtaining the password from the Keychain (requires local authentication)
.Pp
.Rs
\ aa extract -o foo.aea -d dst -keychain
.Re
.Pp
Archive directory \fIfoo\fR to archive \fIfoo.aar\fR
.Pp
.Rs
\ aa archive -p -d foo
.Re
.Pp
Extract archive \fIfoo.aar\fR to directory \fIfoo\fR
.Pp
.Rs
\ aa extract -p -i foo.aar
.Re