zielen.1¶

SYNOPSIS¶

zielen [global_options] command [command_args]

DESCRIPTION¶

zielen is a program that distributes files between a local and remote directory based on how frequently they’re accessed with the intent of conserving disk space. This remote directory can be on a separate hard drive or a separate machine entirely as long as it is accessible through the filesystem.

Files are prioritized based on how frequently and recently they’ve been accessed as well as the file size. The highest-priority files are kept in the local directory for quick access, while lower priority files are moved to the remote directory to conserve disk space. It uses symbolic links to allow files in the remote directory to be accessible from the local one. The user can specify how much data they want to remain in the local directory at any given point in time. Since local directories on different machines can pair with the same remote directory, zielen can be used to sync files between machines.

Terminology¶

Local Directory: A local directory is a directory on your local machine that you want to contain only the files that it has space for.
Remote Directory: A remote directory is a directory, either on your local machine or elsewhere, that you want to contain a master copy of all of your files to be synced with one or more local directories.
Client: A client is any computer containing a local directory that syncs with a remote directory on another computer.
Profile: For every pair of directories you wish to sync, a profile must first be generated by using the init command on the machine containing the local directory. Each profile has a config file that stores information about the two directories and settings that can be used to configure the syncing behavior (see FILES).
Priority: The priority is an internal value assigned to each file that is used to determine which should stay in the local directory. It is based on how frequently the file is accessed (weighted toward more recent access) and the size of the file (favoring smaller files). Priority values are independent for each client.
Storage Limit: The storage limit is the user-defined amount of data that will remain in the local directory. The program will fill the local directory until it reaches this size, starting with the highest priority files. File size is calculated based on disk usage as opposed to apparent size. Excluded files don’t count toward the storage limit (See EXCLUDING).

GLOBAL OPTIONS¶

–help: Print a usage message and exit.
–version: Print the version number and exit.
–debug: Print a full stack trace instead of an error message if an error occurs.
-q, –quiet: Suppress all non-error output.

COMMANDS¶

init [options] name

Create a new profile, called name, representing a pair of directories to sync. Move files from the local directory to the remote one.

-e, –exclude file

Get patterns from file representing files and directories to exclude from syncing.

See EXCLUDING.

-t, –template file: Get settings for the profile from the template file instead of prompting the user interactively. The user will still be prompted for any mandatory information that is missing from the template. A blank template can usually be found at /usr/share/zielen/config-template.

-a, –add-remote: Instead of moving local files to an empty remote directory, start with an existing remote directory and an empty local directory. Using this option, it is possible for two or more profiles to share a remote directory.

sync name|path: Bring the local and remote directories in sync and redistribute files based on their priorities. This command is run automatically at regular intervals by the daemon. This command accepts the name of a profile or the absolute path of its local directory.

reset [options] name|path

Retrieve all files from the remote directory and de-initialize the local directory. This command accepts the name of a profile or the absolute path of its local directory.

-k, –keep-remote: Copy files from the remote directory to the local one instead of moving them. This is useful when the remote directory is shared with other profiles that may also want to retrieve the files.

-n, –no-retrieve: Don’t retrieve files from the remote directory. Symbolic links to remote files are removed from the local directory. This option supersedes –keep-remote.

list: Print a table containing data about each profile.

empty-trash name|path

Permanently delete all files in the remote trash directory. This command accepts the name of a profile or the absolute path of its local directory.

See TRASH.

SYNCING¶

A sync conflict occurs when a file has been modified in both the local and remote directories since the last sync. These conflicts are handled by renaming the file that was modified the least recently. The new file name contains the word “conflict” and the date and time of the sync.

When calculating which files to store locally, zielen considers whole directory trees. If a directory is kept in the local directory, than all of its subdirectories are kept as well.

During a sync, local files that are new since the last sync have their priority increased in order to keep them in the local directory longer. This is to prevent files from being removed from the local directory as soon as they’re created, when they’re likely still being used. This behavior can be changed in the profile config file.

EXCLUDING¶

Files and directories can be excluded from syncing using the exclude pattern file (see FILES). Each line in the file specifies a shell globbing pattern that represents files to exclude. Excluded files stay in the local directory and still count toward the storage limit. If an excluded file is not already in the local directory, it is copied from the remote directory during the next sync.

When only one client is using a remote directory, files are removed from the remote directory once they are excluded. When multiple clients are sharing a remote directory, a file is removed from the remote directory only when it has been excluded by each client that shares that remote directory. Until then, a copy remains in the remote directory and all copies of the file stay in sync.

Patterns have the following format:

Lines starting with a hash symbol ‘#’ serve as comments.
An asterisk ‘*’ matches anything, but stops at slashes.
A double asterisk ‘**’ matches anything, including slashes.
A question mark ‘?’ matches any single character.
A set of brackets ‘[]’ matches any one of the characters contained within the brackets.
Any of the above meta-characters can be matched literally by wrapping them in brackets.
File names starting with a dot ‘.’ (hidden files) are not matched unless the pattern explicitly includes a dot.
Patterns ending with a slash only match directory paths.
Patterns starting with a slash match file paths relative to the root of the sync directory.
Patterns not starting with a slash match the ends of file paths anywhere in the tree. This is the equivalent of starting the pattern with a double asterisk.

TRASH¶

Files that are not kept in the local directory are replaced with symbolic links that point to files in the remote directory. If a normal file is removed from the local directory, then it is removed from the remote directory as well. If one of these symbolic links is removed from the local directory, then the file in the remote directory is moved to the remote trash directory. This directory is ‘.zielen/Trash’ in the remote directory. This feature exists to prevent deleted files from becoming unrecoverable.

This feature can be disabled in the profile config file. Files in the remote trash directory are automatically deleted after 30 days, but this can be customized in the profile config file. The command empty-trash can be used to permanently delete all files in the remote trash directory.

FILES¶

~/.config/zielen/

This is the zielen program directory. The program will respect XDG_CONFIG_HOME and, if it is set, put the directory there instead.

profiles/<name>/

This directory exists for each profile that the user has created, where <name> is the name of the profile.

config: This is the configuration file for the profile. It contains required information that the user is prompted for when the init command is run as well as additional settings that can be configured.
exclude: This is the exclude pattern file for the profile. It contains a list of patterns representing files and directories to be excluded from syncing (see EXCLUDING).