AF(1) General Commands Manual AF(1) NAME af - archive files SYNOPSIS af cmd [options] [par ...] af [options] [cmd [par ...]] DESCRIPTION af is a very simple file archiver. Each time it is run to create (cre‐ ate operation) a new volume, af makes a new directory in the configured destination, and copies all modified files to it. Volume directories are numbered (four digits with leading zero's followed by the creation date) and mirror the source directory structure as needed to store the files. af does not copy the files on its own. Instead, it creates the neces‐ sary cp(1) and mkdir(1) commands and executes them by passing them to sh(1). Commands may be examined with the show operation. af does not use a database and does not store files as diffs. File status information (i.e. file size and last modification date) is recorded in a status file (.archive.tab) and file operations are com‐ puted based on the comparison of that information with the present file's status. af implements some commands to retrieve information from the archive, see OPERATIONS below. restore-files(1) (located in /usr/lib/af) can be used to restore (parts of) of a particular volume. Running af without parameters shows a list of all files that have been modified since the last volume was created. These are the files that would be copied into a new volume. Configuration File If no configuration file is set with the -c option on the command line af reads configuration information from .archive-files.conf in the cur‐ rent directory. In case you are not sure what the effective configuration is or what af is going to do use $ af config to see the most important configuration options and $ af show to get the list of commands that af would have execute to create a new archive. Configuration Sections Configuration files may have sections to contain several configuration definitions for the same source location. Section names appear on one line, enclosed in angle brackets: dir /var/backups/my-user-name/archive-files [backup] dir /some/other/directory Sections inherit some parts from the main configuration (e.g. omit) but the destination settings (destination directory, destination type, GIO mount and remote login) are cleared. The section is activated from the command line $ af list backup: by giving the section's name followed by a colon. The section name may appear before or after the operation parameter. Destination Directory The only mandatory configuration option is the destination directory. It is either set with the -D command line option or using dir in the configuration file. dir /var/backups/my-user-name/archive-files directory and dst are aliases. Source Directories The source directory is configured by either src in the configuration file or the -S command line option. (The -S option is meant to be used from within scripts but not in normal user interaction.) If no source directory is configured the current directory is used. src /home/my-user-name/work/archive-file af can work with multiple source directories but rearranges them to ap‐ pear below a common directory in the archive by inserting alias names. Aliases may be computed automatically or set by the configuration by appending the directory alias separated with a colon. src /home/my-user-name/work/archive-file src /home/my-user-name/work/ssc src /home/my-user-name/work/http-server:https The first two line define source directories without an explicit alias. af uses the directory's name (archive-file and ssc) for it. The third line sets another source with the alias https. Source directories may be set also by brace grouping: src /home/my-user-name/work/{archive-files,ssc,http-server:https} and multiple brace groups may appear in a src option. Relative Directories If source directories are set as relative pathnames (directories that do not start with a slash /) and the configuration file is already set then the source directory is made relative to the directory of the con‐ figuration file (by inserting that directory as prefix). Source direc‐ tories starting with ~/ are relative to the user's HOME directory. The same adjustment is done for relative destination directories. If in doubt check with af's config operation. Mirror Destinations af's default is to store files in archives where modified files go into a new volume preserving old files. Mirror destinations - files are copied as-is into a single destination directory tree without volumes - can be configured using either the mirror or the type configuration op‐ tion and the latter offers some variants. The possible configuration values are archive sets the archive mode, which is the default. mirror switches to a mirror mode (instead of creating an archive). +read-only configures a mirror but delete commands are not executed on the mirror. +backup -copy dir | cmd [arg ...] configures a mirror but all files that would be overwritten or deleted are backed-up somewhere. With -copy the files are saved in an af archive in dir. If instead cmd is given it is run and it receives the filenames on it's standard input. GIO Destinations Non-local destination directories (e.g. on a network storage) can be configured with the gio option. The option's argument must be a valid gio(1) mount definition and the configured destination directory (dir) is a directory below that mount and may not start with a slash. [network] gio smb://my-user@network-server.local/home dir network-store/backups/archive-files af doesn't mount the remote location automatically. If the remote lo‐ cation is not connected by some other mechanism, af's mount and unmount operations may be used to connect to or disconnect from it. MTP Devices af supports non-local source directories with the mtp option. It works very much as gio but for the source side: any configured src directory is located below the gio(1) mount definition set with mtp. dir ~/phone-backup mtp mtp://phone-identifier src Interner gemeinsamer Speicher/DCIM/Camera:camera Interner gemeinsamer Speicher/Pictures:pictures The mount and unmount operations can be used to connect to of discon‐ nect from the location. This is (usually) not required for MTP devices but the mtp option may be used to connect to network drives too. The phone-identifier can be obtained by connecting the phone to the com‐ puter and auto-mounting it. Remote Source Locations af can copy files from remote ssh servers without mounting them as MTP device first. The remote option must be set, which expects an argument of the form user@host. af uses then a combination of ssh(1) and sftp(1) commands to fetch files from the configured locations from host. This operation mode should be used with ssh(1) key authentica‐ tion since multiple logins are done. Restoring Files Files can be restored with the command restore-files volume-dir/.archive.tab [pattern] restore-files lists the commands that must be executed by piping them to sh(1) to restore the files. Additional command line parameters are interpreted as regular expressions: Only files matching one of the ex‐ pressions are restored. If an expression starts with a minus (-) the filename must not match any of the veto patterns. The script is stored in the directory /usr/lib/af. restore-files display usage information if run without arguments. CONFIGURATION af reads its configuration information from the file .archive- files.conf in the the first source directory. If no source is set on the command line af uses the current directory for it. The only manda‐ tory option is dir. af-mode flags sets one of af's operation flags. mtp copies only files without trying to preserve persissions, ownership or modifacation time and supresses error messages when renaming the temporary archive directory. When mobile is set then a source directory must be configured. (Both flags are used by moba(1).) dir path sets the archive base directory. Each new version (volume) get's its own subdirectory below path. gio location defines the archive base directory to be below the configured gio(1) mount specification location. When gio is configured, the archive base directory must not begin with a slash. history file if set then each time a new volume is created file is loaded into vi to edit the version notes. Leaving vi with a non-zero exit code (try `:cq') cancels the operation. file filename|~regex adds a file by its name or all files matching regex to af's list of files. If the list of files contains at least one file or regex then only files matching the list are processed. file-list file reads files to add to af' filelist from file. Each line con‐ tains one parameter for the file configuration option. Blank lines and comments (starting with a #) are ignored. ignore file excludes file from archival. ignore-test file ignores file when checking for file modifications. mirror no|yes configures the destination as mirror instead of an archive (de‐ fault). See also type below. mtp device makes all configured src directories to appear below the gio(1) mount point device. omit regexp defines a regular expression for file exclusion; files that match are ignored. omit may be set multiple times and all pat‐ terns are combined together. remote user@host sets the ssh(1) login and host for remote source directories. type archive | mirror | +read-only | +backup sets the destination type; archive is the default. src dir sets a source directory and can be used multiple times. In addition to the configurable file exclusion, af omits files if their name ends with .tmp or .swp or if their name contains a ~ or $. Futhermore files matching the regular expression (^out(.[0-9])?|^cut$) are omitted too. Configuration Sections af supports configurations for different destinations in a single file. Each destination is configured in it's own section that starts with [name]. Section names are case-insensitive. Sections inherit settings from the global configuration (options before the first section). How‐ ever, the dir, gio, mirror and type options are cleared and must be set within the section. The src option cannot be set in a section. The configuration of a section is applied if its name is added to the command with a colon pre- or appended. `list :name' or `list name:' list the modified files in comparison to the destination configured in the section name. (Section name and operation may also be swapped.) OPERATIONS af uses the command line as user interface to create new volumes and query information about the archived files. The operation names may be abbreviated (or tab completed if installed). If more than one opera‐ tion matches an abbreviation the first is used, e.g. c matches cat, copy and create and is substituted with the first. cat fn print the last archived version of fn. config shows some major parameters from af's configuration. copy creates a new volume but ignores any file modification informa‐ tion copying only the files af reads on stdin. The copy opera‐ tion is called by af to backup files before they are modified or deleted. create creates a new volume if changes exist. If the option -f is set a new volume is created in any case. diff [version] file shows the diff between the current file and either the latest or the given version of that file. info fn prints status information about the archived versions of fn. If fn is prefixed with a ~, fn is used as regular expression and information is returned for all files with a matching filename. last prints the last volume directory. latest file ... prints the latest versions of file. list list the modified files. This is the default operation if no operation is given on the command line. modified tests if there are any modified files. af returns the exit 0 if files are modified and 1 otherwise. mount [gio|mtp] connects to the configured gio or mtp location. next prints the next version number. show show but don't execute the shell commands to create the archive. unmount disconnects from the configured gio location. version prints the current version number. FILES af creates a file status information in every archive directory. This file is named .archive.tab and used to compute the file status then next time af is run. .archive.tab is a plain-text file. Every line describes the status of one file and the fields are tab-separated. The fields are: - source file's filename, - filetype; either f for a file or d for a directory, - file permissions (symbolic), - file owner, - file group, - size in bytes, - file's last modification timestamp, and - file's latest version relative to the archive's base. af uses the latest .archive.tab it can find in the archive. OPTIONS -a only for create operation: copies all files. -b forces af to create a new version even if no file changed. -f file sets the configuration file. -d prints debug information. -D dir sets the archive's base directory. If this option is set af ig‐ nores the dir option in the configuration file. -h history-file sets the archive's history file. -H history-text sets the informative text for the archive's history file. -k cmdlist sets the shell commands for which exit codes other than 0 are accepted. cmdlist is a comma separated list of cp, mkdir, rm, rmdir or - accepting errors from that command. The default is rm,rmdir which can be cleared with -. -n name appends name to the volume's directory. -q reduces the informative output. -S dir sets the source directory. -V prints af's version and exit. EXAMPLES The following sample .archive-files.conf dir /var/backups/my-user-name/archive-files history HISTORY omit \.(tar|gz|tgz|deb|zip)$ archives all of af's script files (and manpages etc.) but omits the usual file-archive types. [net] gio smb://user@server/share dir backups/archive-files adds a GIO configuration to write files to a samba server. $ af mount net: $ af list net: connects to the remote location and lists the modified files. BUGS It is not a bug that af doesn't care about empty directories. af's scope are files and it creates directories as they are needed, i.e. when they contain files. NOTES af comes with additional scripts (see below), which are located in /usr/lib/af. SEE ALSO moba(1), delete-files(1), extract-volumes(1), restore-files(1). 21 DECEMBER 2020 AF(1)