yarsync.1

'\" t
.\" Automatically generated by Pandoc 3.1.12.1
.\"
.TH "YARSYNC" "1" "March 2025" "yarsync 0.3" "YARsync Manual"
.SH NAME
yarsync \- a file synchronization and backup tool
.SH SYNOPSIS
\f[B]yarsync\f[R] [\f[B]\-h\f[R]] [\f[B]\-\-config\-dir\f[R]
\f[I]DIR\f[R]] [\f[B]\-\-root\-dir\f[R] \f[I]DIR\f[R]] [\f[B]\-q\f[R] |
\f[B]\-v\f[R]] \f[I]command\f[R] [\f[I]args\f[R]]
.SH DESCRIPTION
Yet Another Rsync stores rsync configuration and synchronizes
repositories with the interface similar to git.
It is \f[I]efficient\f[R] (files in the repository can be removed and
renamed freely without additional transfers), \f[I]distributed\f[R]
(several replicas of the repository can diverge, and in that case a
manual merge is supported), \f[I]safe\f[R] (it takes care to prevent
data loss and corruption) and \f[I]simple\f[R] (see this manual).
.SH QUICK START
To create a new repository, enter the directory with its files and type
.IP
.EX
yarsync init
.EE
.PP
This operation is safe and will not affect existing files (including
configuration files in an existing repository).
Alternatively, run \f[B]init\f[R] inside an empty directory and add
files afterward.
To complete the initialization, make a commit:
.IP
.EX
yarsync commit \-m \[dq]Initial commit\[dq]
.EE
.PP
\f[B]commit\f[R] creates a snapshot of the working directory, which is
all files in the repository except \f[B]yarsync\f[R] configuration and
data.
This snapshot is very small, because it uses hard links.
To check how much your directory size has changed, run \f[B]du\f[R](1).
.PP
Commit name is the number of seconds since the Epoch (integer Unix
time).
This allows commits to be ordered in time, even for hosts in different
zones.
Though this works on most Unix systems and Windows, the epoch is
platform dependent.
.PP
After creating a commit, files can be renamed, deleted or added.
To see what was changed since the last commit, use \f[B]status\f[R].
To see the history of existing commits, use \f[B]log\f[R].
.PP
Hard links are excellent at tracking file moves or renames and storing
accidentally removed files.
Their downside is that if a file gets corrupt, this will apply to all of
its copies in local commits.
The 3\-2\-1 backup rule requires to have at least 3 copies of data, so
let us add a remote repository \[dq]my_remote\[dq]:
.IP
.EX
yarsync remote add my_remote remote:/path/on/my/remote
.EE
.PP
For local copies we still call the repositories \[dq]remote\[dq], but
their paths would be local:
.IP
.EX
yarsync remote add my_drive /mnt/my_drive/my_repo
.EE
.PP
This command only updated our configuration, but did not make any
changes at the remote path (which may not exist).
To make a copy of our repository, run
.IP
.EX
yarsync clone new\-replica\-name host:/mnt/my_drive/my_repo
.EE
.PP
\f[B]clone\f[R] copies all repository data (except configuration files)
to a new replica with the given name and adds the new repository to
remotes.
.PP
To check that we set up the repositories correctly, make a dry run with
\[aq]\f[B]\-n\f[R]\[aq]:
.IP
.EX
yarsync push \-n new\-replica\-name
.EE
.PP
If there were no errors and no file transfers, then we have a
functioning remote.
We can continue working locally, adding and removing files and making
commits.
When we want to synchronize repositories, we \f[B]push\f[R] the changes
\f[I]to\f[R] or \f[B]pull\f[R] them \f[I]from\f[R] a remote (first with
a \f[B]\-\-dry\-run\f[R]).
This is the recommended workflow, and if we work on different
repositories in sequence and always synchronize changes, our life will
be easy.
Sometimes, however, we may forget to synchronize two replicas and they
will end up in a diverged state; we may actually change some files or
find them corrupt.
Solutions to these problems involve user decisions and are described in
\f[B]pull\f[R] and \f[B]push\f[R] options.
.SH OPTION SUMMARY
.PP
.TS
tab(@);
lw(18.7n) lw(51.3n).
T{
\-\-help, \-h
T}@T{
show help message and exit
T}
T{
\-\-config\-dir=DIR
T}@T{
path to the configuration directory
T}
T{
\-\-root\-dir=DIR
T}@T{
path to the root of the working directory
T}
T{
\-\-quiet, \-q
T}@T{
decrease verbosity
T}
T{
\-\-verbose, \-v
T}@T{
increase verbosity
T}
T{
\-\-version, \-V
T}@T{
print version
T}
.TE
.SH COMMAND SUMMARY
.PP
.TS
tab(@);
lw(13.1n) lw(56.9n).
T{
T}@T{
T}
T{
\f[B]checkout\f[R]
T}@T{
restore the working directory to a commit
T}
T{
\f[B]clone\f[R]
T}@T{
clone a repository
T}
T{
\f[B]commit\f[R]
T}@T{
commit the working directory
T}
T{
\f[B]diff\f[R]
T}@T{
print the difference between two commits
T}
T{
\f[B]init\f[R]
T}@T{
initialize a repository
T}
T{
\f[B]log\f[R]
T}@T{
print commit logs
T}
T{
\f[B]pull\f[R]
T}@T{
get data from a source
T}
T{
\f[B]push\f[R]
T}@T{
send data to a destination
T}
T{
\f[B]remote\f[R]
T}@T{
manage remote repositories
T}
T{
\f[B]show\f[R]
T}@T{
print log messages and actual changes for commit(s)
T}
T{
\f[B]status\f[R]
T}@T{
print updates since last commit
T}
.TE
.SH OPTIONS
.TP
\f[B]\-\-help\f[R], \f[B]\-h\f[R]
Prints help message and exits.
Default if no arguments are given.
After a command name, prints help for that command.
.TP
\f[B]\-\-config\-dir=DIR\f[R]
Provides the path to the configuration directory if it is detached.
Both \f[B]\-\-config\-dir\f[R] and \f[B]\-\-root\-dir\f[R] support tilde
expansion for user\[cq]s home directory.
See SPECIAL REPOSITORIES for usage details.
.TP
\f[B]\-\-root\-dir=DIR\f[R]
Provides the path to the root of the working directory for a detached
repository.
Requires \f[B]\-\-config\-dir\f[R].
If not set explicitly, the default working directory is the current one.
.TP
\f[B]\-\-quiet\f[R], \f[B]\-q\f[R]
Decreases verbosity.
Does not affect error messages (redirect them if needed).
.TP
\f[B]\-\-verbose\f[R], \f[B]\-v\f[R]
Increases verbosity.
May print more rsync commands and output.
Conflicts with \f[B]\-\-quiet\f[R].
.TP
\f[B]\-\-version\f[R], \f[B]\-V\f[R]
Prints the \f[B]yarsync\f[R] version and exits.
If \f[B]\-\-help\f[R] is given, it takes precedence over
\f[B]\-\-version\f[R].
.SH COMMANDS
All commands support the \f[B]\-\-help\f[R] option.
Commands that can change a repository also support the
\f[B]\-\-dry\-run\f[R] option.
.TP
\f[B]\-\-dry\-run\f[R], \f[B]\-n\f[R]
Prints what will be transferred during a real run, but does not make any
changes.
.TP
\f[B]\-\-help\f[R], \f[B]\-h\f[R]
Prints help for a command or a subcommand.
.SH checkout
\f[B]yarsync checkout\f[R] [\f[B]\-h\f[R]] [\f[B]\-n\f[R]]
\f[I]commit\f[R]
.PP
Restores the working directory to its state during \f[I]commit\f[R].
WARNING: this will overwrite the working directory.
Make sure that all important data is committed.
Make a dry run first with \f[B]\-n\f[R].
.PP
If not the most recent commit was checked out, the repository HEAD (in
git terminology, see \f[B]git\-checkout\f[R](1)) becomes detached, which
prevents such operations as \f[B]pull\f[R] or \f[B]push\f[R].
To advance the repository to its correct state, check out the last
commit or make a new one.
.TP
\f[I]commit\f[R]
The commit name (as printed in \f[B]log\f[R] or during
\f[B]commit\f[R]).
.SH clone
\f[B]yarsync clone\f[R] [\f[B]\-h\f[R]] \f[I]name\f[R]
\f[I]path|parent\-path\f[R]
.PP
One can clone from within an existing repository \f[B]to\f[R]
\f[I]parent\-path\f[R] or clone \f[B]from\f[R] a repository at
\f[I]path\f[R].
In both cases a new directory with the repository is created, having the
same name as the original repository folder.
If that directory already exists, \f[B]clone\f[R] will fail (several
safety checks are being made).
The local repository (origin or clone) will add another one as a remote.
.PP
Note that only data (working directory, commits, logs and
synchronization information, not configuration files) will be cloned.
This command will refuse to clone \f[B]from\f[R] a repository with a
filter (see SPECIAL REPOSITORIES).
.PP
\f[I]parent\-path\f[R] is useful when we want to clone several
repositories into one directory.
It allows us to use the same command for each of them (manually or with
\f[B]mr\f[R](1)).
If one needs to have a different directory name for a repository, they
can rename it manually (we don\[cq]t require, but strongly encourage
having same directory names for all replicas).
.SS Positional arguments
.TP
\f[I]name\f[R]
Name of the new repository.
.TP
\f[I]path\f[R]
Path to the source repository (local or remote).
Trailing slash is ignored.
.TP
\f[I]parent\-path\f[R]
Path to the parent directory of the cloned repository (local or remote).
Trailing slash is ignored.
.SH commit
\f[B]yarsync commit\f[R] [\f[B]\-h\f[R]] [\f[B]\-m\f[R]
\f[I]message\f[R]] [\f[B]\[en]limit\f[R] \f[I]number\f[R]]
.PP
Commits the working directory (makes its snapshot).
See QUICK START for more details on commits.
.TP
\f[B]\-\-limit\f[R]=\f[I]number\f[R]
Maximum number of commits.
If the current number of commits exceeds that, older ones are removed
during \f[B]commit\f[R].
See SPECIAL REPOSITORIES for more details.
.TP
\f[I]message\f[R]
Commit message (used in logs).
Can be empty.
.SH diff
\f[B]yarsync diff\f[R] [\f[B]\-h\f[R]] \f[I]commit\f[R]
[\f[I]commit\f[R]]
.PP
Prints the difference between two commits (from old to the new one, the
order of arguments is unimportant).
If the second commit is omitted, compares \f[I]commit\f[R] to the most
recent one.
See \f[B]status\f[R] for the output format.
.TP
\f[I]commit\f[R]
Commit name.
.SH init
\f[B]yarsync init\f[R] [\f[B]\-h\f[R]] [\f[I]reponame\f[R]]
.PP
Initializes a \f[B]yarsync\f[R] repository in the current directory.
Creates a configuration folder with repository files.
Existing configuration and files in the working directory stay
unchanged.
Create a first commit for the repository to become fully operational.
.TP
\f[I]reponame\f[R]
Name of the repository.
If not provided on the command line, it will be prompted.
.SH log
\f[B]yarsync log\f[R] [\f[B]\-h\f[R]] [\f[B]\-n\f[R] \f[I]number\f[R]]
[\f[B]\-r\f[R]]
.PP
Prints commit logs (from newest to oldest), as well as synchronization
information when it is available.
To see changes in the working directory, use \f[B]status\f[R].
.SS Options
.TP
\f[B]\-\-max\-count\f[R]=\f[I]number\f[R], \f[B]\-n\f[R]
Maximum number of logs shown.
.TP
\f[B]\-\-reverse\f[R], \f[B]\-r\f[R]
Reverse log order.
.SS Example
To print information about the three most recent commits, use
.IP
.EX
yarsync log \-n 3
.EE
.SH pull
\f[B]yarsync pull\f[R] [\f[B]\-h\f[R]] [\f[B]\-f\f[R] |
\f[B]\-\-new\f[R] | \f[B]\-b\f[R] | \f[B]\-\-backup\-dir\f[R]
\f[I]DIR\f[R]] [\f[B]\-n\f[R]] \f[I]source\f[R]
.PP
Gets data from a remote \f[I]source\f[R].
The difference between \f[B]pull\f[R] and \f[B]push\f[R] is mostly only
the direction of transfer.
.PP
\f[B]pull\f[R] and \f[B]push\f[R] bring two repositories into the same
state.
They synchronize the working directory, that is they add to the
destination new files from source, remove those missing on source and do
all renames and moves of previously committed files efficiently.
This is done in one run, and these changes apply also to logs, commits
and synchronization.
In most cases, we do not want our existing logs and commits to be
removed though.
By default, several checks are made to prevent data loss:
.IP
.EX
\- local has no uncommitted changes,
\- local has not a detached HEAD,
\- local is not in a merging state,
\- destination has no commits missing on source.
.EE
.PP
If any of these cases is in effect, no modifications will be made.
Note that the remote may have uncommitted changes itself: always make a
dry run with \f[B]\-n\f[R] first!
.PP
To commit local changes to the repository, use \f[B]commit\f[R].
HEAD commit could be changed during \f[B]checkout\f[R] (see its section
for the solutions).
If the destination has commits missing on source, there are two options:
to \f[B]\-\-force\f[R] changes to the destination (removing these
commits) or to merge changes inside the local repository with \f[B]pull
\-\-new\f[R].
.PP
If we pull new commits from the remote, this will bring repository into
a merging state.
Merge will be done automatically if the last remote commit is among
local ones (in that case only some older commits were transferred from
there).
If some recent remote commits are not present locally, however, this
means that histories of the repositories diverged, and we will need to
merge them manually.
After we have all local and remote commits and the union of the working
directories in our local repository, we can safely choose the easiest
way for us to merge them.
To see the changes, use \f[B]status\f[R] and \f[B]log\f[R].
For example, if we added a file in a \f[I]remote_commit\f[R] before and
it was added now, we can just \f[B]commit\f[R] the changes.
If we have made many local changes, renames and removals since then, we
may better \f[B]checkout\f[R] our latest commit (remember that all files
from the working directory are present in commits, so it is always safe)
and link the new file to the working directory:
.IP
.EX
ln .ys/commits/<remote_commit>/path/to/file .
.EE
.PP
(it can be moved to its subdirectory without the risk of breaking hard
links).
If the remote commit was actually large, and local changes were recent
but small, then we shall check out the remote commit and apply local
changes by hand.
After our working directory is in the desired state, we \f[B]commit\f[R]
changes and the merge is finished.
The result shall be pushed to the remote without problems.
.SS pull options
.TP
\f[B]\-\-new\f[R]
Do not remove local data that is missing on \f[I]source\f[R].
While this option can return deleted or moved files back to the working
directory, it also adds remote logs and commits that were missing here
(for example, old or unsynchronized commits).
A forced \f[B]push\f[R] to the remote could remove these logs and
commits, and this option allows one to first \f[B]pull\f[R] them to the
local repository.
.RS
.PP
After \f[B]pull \-\-new\f[R] the local repository can enter a merging
state.
See \f[B]pull\f[R] description for more details.
.RE
.TP
\f[B]\-\-backup\f[R], \f[B]\-b\f[R]
Changed files in the working directory are renamed (appended with
\[aq]\f[B]\[ti]\f[R]\[aq]).
See \f[B]\-\-backup\-dir\f[R] for more details.
.TP
\f[B]\-\-backup\-dir\f[R] \f[I]DIR\f[R]
Changed local files are put into a directory \f[I]DIR\f[R] preserving
their relative paths.
\f[I]DIR\f[R] can be an absolute path or relative to the root of the
repository.
In contrast to \f[B]\-\-backup\f[R], \f[B]\-\-backup\-dir\f[R] does not
change resulting file names.
.RS
.PP
This option is convenient for large file trees, because it recreates the
existing file structure of the repository (one doesn\[cq]t have to
search for new backup files in all subdirectories).
For current rsync version, the command
.IP
.EX
yarsync pull \-\-backup\-dir BACKUP <remote>
.EE
.PP
will copy updated files from the remote and put them into the directory
\[dq]BACKUP/BACKUP\[dq] (this is how rsync works).
To reduce confusion, make standard \f[B]pull\f[R] first (so that during
the backup there are only file updates).
.PP
This option is available only for \f[B]pull\f[R], because it is assumed
that the user will apply local file changes after backup.
For example, suppose that after a \f[B]pull \-\-backup\f[R] one gets
files \f[I]a\f[R] and \f[I]a\[ti]\f[R] in the working directory.
One should first see, which version is correct.
If it is the local file \f[I]a\[ti]\f[R], then the backup can be
removed:
.IP
.EX
mv a\[ti] a
.EE
.PP
By local we mean the one hard linked with local commits (run \f[I]ls
\-i\f[R] to be sure).
If the remote version is correct though, you need first to overwrite the
local version not breaking the hard links.
This can be done with an rsync option \[dq]\-\-inplace\[dq]:
.IP
.EX
rsync \-\-inplace a a\[ti]
mv a\[ti] a
# check file contents and the links
ls \-i a .ys/commits/*/a
.EE
.PP
For a \f[B]\-\-backup\-dir\f[R] and for longer paths these commands will
be longer.
Finally, if you need several versions, just save one of the files under
a different name in the repository.
.PP
After you have fixed all corrupt files, push them back to the remote.
.RE
.SS pull and push options
.TP
\f[B]\-\-force\f[R], \f[B]\-f\f[R]
Updates the working directory, removing commits and logs missing on
source.
This command brings two repositories to the nearest possible states:
their working directories, commits and logs become the same.
While working directories are always identical after \f[B]pull\f[R] or
\f[B]push\f[R] (except for some of the \f[B]pull\f[R] options),
\f[B]yarsync\f[R] generally refuses to remove existing commits or logs
\- unless this option is given.
Use it if the destination has really unneeded commits or just remove
them manually (see FILES for details on the commit directory).
See also \f[B]pull \-\-new\f[R] on how to fetch missing commits.
.SH push
\f[B]yarsync push\f[R] [\f[B]\-h\f[R]] [\f[B]\-f\f[R]] [\f[B]\-n\f[R]]
\f[I]destination\f[R]
.PP
Sends data to a remote \f[I]destination\f[R].
See \f[B]pull\f[R] for more details and common options.
.SH remote
\f[B]yarsync remote\f[R] [\f[B]\-h\f[R]] [\f[B]\-v\f[R]]
[\f[I]command\f[R]]
.PP
Manages remote repositories configuration.
By default, prints existing remotes.
For more options, see \f[I].ys/config.ini\f[R] in the FILES section.
.TP
\f[B]\-v\f[R]
Verbose.
Prints remote paths as well.
.SS \f[B]add\f[R]
\f[B]yarsync remote add\f[R] [\f[B]\-h\f[R]] \f[I]repository\f[R]
\f[I]path\f[R]
.PP
Adds a new remote.
\f[I]repository\f[R] is the name of the remote in local
\f[B]yarsync\f[R] configuration (as it will be used later during
\f[B]pull\f[R] or \f[B]push\f[R]).
\f[I]path\f[R] has a standard form [user\[at]]host:[path] for an
actually remote host or it can be a local path.
Since \f[B]yarsync\f[R] commands can be called from any subdirectory,
local path should be absolute.
Tilde for user\[cq]s home directory \[aq]\f[B]\[ti]\f[R]\[aq] in paths
is allowed.
.SS rm
\f[B]yarsync remote rm\f[R] [\f[B]\-h\f[R]] \f[I]repository\f[R]
.PP
Removes an existing \f[I]repository\f[R] from local configuration.
.SS show
Prints remote repositories.
Default.
.SH show
\f[B]yarsync show\f[R] [\f[B]\-h\f[R]] \f[I]commit\f[R]
[\f[I]commit\f[R] \&...]
.PP
Prints log messages and actual changes for commit(s).
Changes are shown compared to the commit before \f[I]commit\f[R].
For the output format, see \f[B]status\f[R].
Information for several commits can be requested as well.
.TP
\f[I]commit\f[R]
Commit name.
.SH status
\f[B]yarsync status\f[R] [\f[B]\-h\f[R]]
.PP
Prints working directory updates since the last commit and the
repository status.
If there were no errors, this command always returns success
(irrespective of uncommitted changes).
.SS Output format of the updates
The output for the updates is a list of changes, including attribute
changes, and is based on the format of \f[I]rsync
\-\-itemize\-changes\f[R].
For example, a line
.IP
.EX
\&.d..t...... programming/
.EE
.PP
means that the modification time \[aq]\f[I]t\f[R]\[aq] of the directory
\[aq]\f[I]d\f[R]\[aq] \f[I]programming/\f[R] in the root of the
repository has changed (files were added or removed from that).
All its other attributes are unchanged (\[aq].\[aq]).
.PP
The output is an 11\-letter string of the format \[dq]YXcstpoguax\[dq],
where \[aq]Y\[aq] is the update type, \[aq]X\[aq] is the file type, and
the other letters represent attributes that are printed if they were
changed.
For a newly created file these would be \[aq]+\[aq], like
.IP
.EX
>f+++++++++ /path/to/file
.EE
.PP
The attribute letters are: \f[B]c\f[R]hecksum, \f[B]s\f[R]ize,
modification \f[B]t\f[R]ime, \f[B]p\f[R]ermissions, \f[B]o\f[R]wner and
\f[B]g\f[R]roup.
\f[B]u\f[R] can be in fact \f[B]u\f[R]se (access) or creatio\f[B]n\f[R]
time, or \f[B]b\f[R]oth.
\f[B]a\f[R] stands for ACL, and \f[B]x\f[R] for extended attributes.
Complete details on the output format can be found in the
\f[B]rsync\f[R](1) manual.
.SH SPECIAL REPOSITORIES
A \f[B]detached\f[R] repository is one with the \f[B]yarsync\f[R]
configuration directory outside the working directory.
To use such repository, one must provide \f[B]yarsync\f[R] options
\f[B]\-\-config\-dir\f[R] and \f[B]\-\-root\-dir\f[R] with every command
(\f[B]alias\f[R](1p) may be of help).
To create a detached repository, use \f[B]init\f[R] with these options
or move the existing configuration directory manually.
For example, if one wants to have several versions of static Web pages,
they may create a detached repository and publish the working directory
without the Web server having access to the configuration.
Alternatively, if one really wants to have both a continuous
synchronization and \f[B]yarsync\f[R] backups, they can move its
configuration outside, if that will work.
Commits in such repositories can be created or checked out, but
\f[B]pull\f[R] or \f[B]push\f[R] are currently not supported (one will
have to synchronize them manually).
A detached repository is similar to a bare repository in git, but
usually has a working directory.
.PP
A repository with a \f[B]filter\f[R] can exclude (disable tracking) some
files or directories from the working directory.
This may be convenient, but makes synchronization less reliable, and
such repository can not be used as a remote.
See \f[B]rsync\-filter\f[R] in the FILES section for more details.
.PP
A repository can have a \f[B]commit limit\f[R].
The maximum number of commits can be set during \f[B]commit\f[R].
\f[B]pull\f[R] and \f[B]push\f[R] do not check for missing commits on
the destination when we are in a repository with commit limit.
It makes a repository with commit limit more like a central repository.
If we have reached the maximum number of commits, older ones are deleted
during a new \f[B]commit\f[R].
Commit limit is stored in \f[B].ys/COMMIT_LIMIT.txt\f[R].
It can be changed or removed at any time.
Commit limit was introduced in \f[CR]yarsync v0.2\f[R] and was designed
to help against the problem of too many hard links (if it exists).
.SH FILES
All \f[B]yarsync\f[R] repository configuration and data is stored in the
hidden directory \f[B].ys\f[R] under the root of the working directory.
If the user no longer wants to use \f[B]yarsync\f[R] and the working
directory is in the desired state, they can safely remove the
\f[B].ys\f[R] directory.
.PP
Apart from the working directory, only commits, logs and synchronization
data are synchronized between the repositories.
Each repository has its own configuration and name.
.SH User configuration files
.TP
\f[B].ys/config.ini\f[R]
Contains names and paths of remote repositories.
This file can be edited directly or with \f[B]remote\f[R] commands
according to user\[cq]s preference.
.RS
.PP
\f[B]yarsync\f[R] supports synchronization only with existing remotes.
A simple configuration for a remote \[dq]my_remote\[dq] could be:
.IP
.EX
[my_remote]
path = remote:/path/on/my/remote
.EE
.PP
Several sections can be added for more remotes.
An example (non\-effective) configuration is created during
\f[B]init\f[R].
Note that comments in \f[B]config.ini\f[R] can be erased during
\f[B]remote\f[R] {\f[B]add\f[R],\f[B]rm\f[R]}.
.PP
Since removable media or remote hosts can change their paths or IP
addresses, one may use variable substitution in paths:
.IP
.EX
[my_drive]
path = $MY_DRIVE/my_repo
.EE
.PP
For the substitutions to take the effect, export these variables before
run:
.IP
.EX
$ export MY_DRIVE=/run/media/my_drive
$ yarsync push \-n my_drive
.EE
.PP
If we made a mistake in the variable or path, it will be shown in the
printed command.
Always use \f[B]\-\-dry\-run\f[R] first to ensure proper
synchronization.
.PP
Another \f[B]yarsync\f[R] remote configuration option is \f[B]host\f[R].
If both \f[B]path\f[R] and \f[B]host\f[R] are present, the effective
path will be their concatenation \[dq]<host>:<path>\[dq].
Empty \f[B]host\f[R] means local host and does not prepend the path.
.PP
It is possible to set default \f[B]host\f[R] for each section from the
section name.
For that, add a default section with an option
\f[B]host_from_section_name\f[R]:
.IP
.EX
[DEFAULT]
host_from_section_name
.EE
.PP
Empty lines and lines starting with \[aq]\f[B]#\f[R]\[aq] are ignored.
Section names are case\-sensitive.
White spaces in a section name will be considered parts of its name.
Spaces around \[aq]\f[B]=\f[R]\[aq] are allowed.
Full syntax specification can be found at \c
.UR https://docs.python.org/3/library/configparser.html
.UE \c
\&.
.RE
.TP
\f[B].ys/repo_<name>.txt\f[R]
Contains the repository name, which is used in logs and usually should
coincide with the remote name (how local repository is called on
remotes).
The name can be set during \f[B]init\f[R] or edited manually.
.RS
.PP
Each repository replica must have a unique name.
For example, if one has repositories \[dq]programming/\[dq] and
\[dq]music/\[dq] on a laptop \[dq]my_host\[dq], their names would
probably be \[dq]my_host\[dq], and the names of their copies on an
external drive could be \[dq]my_drive\[dq] (this is different from git,
which uses only the author\[cq]s name in logs).
.PP
Note that \f[B]clone\f[R] from inside a repository for technical reasons
creates a temporary file with the new repository name (which is also
written in \f[B]CLONE_TO_<name>.txt\f[R]).
If these files due to some errors remain on the system, they can be
safely removed.
.RE
.TP
\f[B].ys/rsync\-filter\f[R]
Contains rsync filter rules, which effectively define what data belongs
to the repository.
The \f[B]rsync\-filter\f[R] does not exist by default, but can be added
for flexibility.
.RS
.PP
For example, the author has a repository \[dq]\[ti]/work\[dq], but wants
to keep his presentations in \[dq]tex/\[dq] in a separate repository.
Instead of having a different directory \[dq]\[ti]/work_tex\[dq], he
adds such rules to \f[B]rsync\-filter\f[R]:
.IP
.EX
# all are in git repositories
\- /repos
# take care to sync separately
\- /tex
.EE
.PP
In this way, \[dq]\[ti]/work/tex\[dq] and contained git repositories
will be excluded from \[dq]\[ti]/work\[dq] synchronization.
Lines starting with \[aq]\f[B]#\f[R]\[aq] are ignored, as well as empty
lines.
To complicate things, one could include a subdirectory of \[dq]tex\[dq]
into \[dq]work\[dq] with an include filter \[aq]\f[B]+\f[R]\[aq].
For complete details, see FILTER RULES section of \f[B]rsync\f[R](1).
.PP
While convenient for everyday use, filters make backup more difficult.
To synchronize a repository with them, one has to remember that it has
subdirectories that need to be synchronized too.
If the remote repository had its own filters, that would make
synchronization even more unreliable.
Therefore filters are generally discouraged: \f[B]pull\f[R] and
\f[B]push\f[R] ignore remote filters (make sure you synchronize only
\f[I]from\f[R] a repository with filters), while \f[B]clone\f[R] refuses
to copy from a repository with \f[B]rsync\-filter\f[R].
.RE
.SH yarsync technical directories
.TP
\f[B].ys/commits/\f[R]
Contains local commits (snapshots of the working directory).
If some of the old commits are no longer needed (there are too many of
them or they contain a large file), they can be removed.
Make sure, however, that all remote repositories contain at least some
of the present commits, otherwise future synchronization will get
complicated.
Alternatively, remove unneeded files or folders manually: commits can be
edited, with care taken to synchronize them correctly.
.TP
\f[B].ys/logs/\f[R]
Contains text logs produced during \f[B]commit\f[R].
They are not necessary, so removing any of them will not break the
repository.
If one wants to fix or improve a commit message though, they may edit
the corresponding log (the change will be propagated during
\f[B]push\f[R]).
It is recommended to store logs even for old deleted commits, which may
be present on formerly used devices.
.TP
\f[B].ys/sync/\f[R]
Contains synchronization information for all known reposotories.
This information is transferred between replicas during \f[CR]pull\f[R],
\f[CR]push\f[R] and \f[CR]clone\f[R], and it allows \f[CR]yarsync\f[R]
repositories to better support the 3\-2\-1 backup rule.
The information is contained in empty files with names of the format
\f[B]commit_repo.txt\f[R].
Pulling (or cloning) from a repository does not affect its files and
does not update its synchronization information.
\f[B]push\f[R] (and corresponding \f[B]clone\f[R]) updates
synchronization for both replicas.
For each repository only the most recent commit is stored.
\f[B]sync\f[R] directory was introduced in \f[CR]yarsync v0.2\f[R].
See the release notes on how to convert old repositories to the new
format or do it manually, if necessary.
.RS
.PP
If a replica has been permanently removed, its synchronization data must
be removed manually and propagated with \f[B]\-\-force\f[R].
.RE
.SH EXIT STATUS
.TP
\f[B]0\f[R]
Success
.TP
\f[B]1\f[R]
Invalid option
.TP
\f[B]7\f[R]
Configuration error
.TP
\f[B]8\f[R]
Command error
.TP
\f[B]9\f[R]
System error
.TP
\f[B]2\-6\f[R],\f[B]10\-14\f[R],\f[B]20\-25\f[R],\f[B]30\f[R],\f[B]35\f[R]
rsync error
.PP
If the command could be run successfully, a zero code is returned.
Invalid option code is returned for mistakes in command line argument
syntax.
Configuration error can occur when we are outside an existing repository
or a \f[B]yarsync\f[R] configuration file is missing.
If the repository is correct, but the command is not allowed in its
current state (for example, one can not push or pull when there are
uncommitted changes or add a remote with an already present name), the
command error is returned.
It is also possible that a general system error, such as a keyboard
interrupt, is raised in the Python interpreter.
See \f[B]rsync\f[R](1) for rsync errors.
.SH DIAGNOSTICS
To check that your clocks (used for properly ordering commits) at
different hosts are synchronized well enough, run
.IP
.EX
python \-c \[aq]import time; print(time.time())\[aq]
.EE
.PP
To make sure that the local repository supports hard links instead of
creating file copies, test it with
.IP
.EX
du \-sh .
du \-sh .ys
.EE
.PP
(can be run during \f[B]pull\f[R] or \f[B]clone\f[R] if they take too
long).
The results must be almost the same.
If not, you may not use \f[B]yarsync\f[R] on this file system, have
large deleted files stored in old commits or you may have subdirectories
excluded with a \f[B]filter\f[R] (see SPECIAL REPOSITORIES section).
.PP
To test that a particular file \[dq]a\[dq] was hard linked to its
committed versions, run
.IP
.EX
ls \-i a .ys/commits/*/a
.EE
.PP
If all is correct, their inodes must be the same.
.PP
Hard links can be broken in a cloned git repository (as it could happen
with \f[B]yarsync\f[R] tests before), because git does not preserve
them.
To fix hard links for the whole repository, run \f[B]hardlink\f[R](1) in
its root.
.SH SEE ALSO
\f[B]rsync\f[R](1)
.PP
The yarsync page is \c
.UR https://github.com/ynikitenko/yarsync
.UE \c
\&.
.SH BUGS
Requires a filesystem with hard links, rsync version at least 3.1.0
(released 28 September 2013) and Python >= 3.6.
.PP
Always do a \f[B]\-\-dry\-run\f[R] before actual changes.
Occasionally Python errors are raised instead of correct return codes.
Please report any bugs or make feature requests to \c
.UR https://github.com/ynikitenko/yarsync/issues
.UE \c
\&.
.SH COPYRIGHT
Copyright © 2021\-2025 Yaroslav Nikitenko.
License GPLv3: GNU GPL version 3 \c
.UR https://gnu.org/licenses/gpl.html
.UE \c
\&.
.PD 0
.P
.PD
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH AUTHORS
Written by Yaroslav Nikitenko.