App-FileSync

 view release on metacpan or  search on metacpan

Changes  view on Meta::CPAN

        - That advice is given only when a directory really is unwritable, so
          a full disk or a root that is a file keeps its own error.

	[ Documentation ]
        - The examples are split by machine - what to run on the
          server, on each client, and from cron - and keep the master in a
          home directory, so nothing needs sudo.
        - What a /srv/filesync root needs instead, the wrapper that
          adds --root to filesync-server, and the ssh key the first sync
          requires.
        - The backup and restore commands follow the example's master
          layout, and make the backup directory before cron mirrors into it.
        - The synopsis creates the repo first, so it runs as printed.

0.001.1 Sat Oct 24 09:52:47 AM EDT 2026
	[ Bug Fixes ]
        - Build: test on Windows with Perl 5.42 again.  Its B::Hooks::EndOfScope
          faults at exit, so the plain-Perl hook is used there.
        - filesync, filesync-server and filesync-admin select that hook for
          themselves on 5.42 for Windows, so it no longer has to be set to run
          them; an implementation already in the environment is left alone.
          A test checks the choice in a child process that starts without the

MANIFEST.SKIP  view on Meta::CPAN

\bblibdirs\.ts$         # 6.18 through 6.25 generated this

# Avoid Module::Build generated and utility files.
\bBuild$
\b_build/
\bBuild.bat$
\bBuild.COM$
\bBUILD.COM$
\bbuild.com$

# Avoid temp and backup files.
~$
\.old$
\#$
\b\.#
\.bak$
\.tmp$
\.#
\.rej$
schemas\.yml$
\.swp$

README.md  view on Meta::CPAN

    sudo mkdir -p /srv/filesync
    sudo chown -R foo /srv/filesync
```

`filesync-admin repo create documents` works as it is, and the master is
`/srv/filesync/master/documents`.

### Backup and Restore

The master directory is an ordinary directory tree, so it can be mirrored to a
backup directory from the server account's crontab.  Make the backup directory
once - rsync creates the last component only - then let cron keep it in step:

```
    # on the server, once
    mkdir -p /home/foo/backups/documents

    # crontab -e, on the server
    * * * * * ionice -c3 rsync -a --delete --exclude '.filesync-tmp-*' \
        /home/foo/filesync/master/documents/ /home/foo/backups/documents/
```

Filesync writes each file to a temporary name and renames it into place, so the
mirror never catches a half-written upload; the exclusion keeps the temporary
files themselves out of the backup.  `--delete` makes the copy a mirror: a
deletion that reaches the master also removes the backed-up file.

To restore the master from that backup, stop the client jobs (comment out their
cron lines, or disable the scheduled task) and the server's backup job, so the
backup job cannot copy a half-restored tree back into the backup.  Let any
running sync finish, then mirror the backup back:

```
    rsync -a --delete --checksum \
        /home/foo/backups/documents/ /home/foo/filesync/master/documents/
```

`--checksum` compares the contents, so a restored file is not skipped just
because its size and modification time happen to match the newer copy.  This is
a rollback rather than a merge: files created after the backup was taken
disappear from the master, and the next sync propagates that to the clients, so
copy anything you need to keep out of the tree first.  The server
would rehash the restored files on the next session anyway, but
`filesync-admin reindex` rebuilds the index immediately, before any client
reconnects; clients then pull the restored versions, merging edits they have not
synced as usual.

Before re-enabling the jobs, check that the copy is exact with a read-only
comparison against the backup:

```
    rsync -a --delete --checksum --dry-run --itemize-changes \
        /home/foo/backups/documents/ /home/foo/filesync/master/documents/
```

No output and exit 0 mean the master matches the backup.  Any line beginning
`>f` names a path that still differs, and `*deleting` names one the
rollback should have removed.  The index still describes the pre-rollback tree,
so `filesync-admin verify` may report drift at this point; that is expected.
Rebuild it and check it:

```
    filesync-admin --root ~/filesync reindex documents
    filesync-admin --root ~/filesync verify documents --deep
```

`reindex` hashes every file in the master and replaces the index atomically; it
refuses to run while a sync session holds the repo lock, and it names any paths
it could not index.  `clean` and exit 0 from `verify` confirm that the master
and its index agree.  Re-enable the jobs once that check passes.

To restore just one file or directory, copy that path back instead of mirroring
the whole tree, with the jobs paused as above so nothing changes the tree while
the copy runs:

```
    rsync -a --checksum /home/foo/backups/documents/notes/plan.txt \
        /home/foo/filesync/master/documents/notes/
    rsync -a --checksum /home/foo/backups/documents/photos/ \
        /home/foo/filesync/master/documents/photos/
```

The trailing slash on the second source copies the directory's contents; without
it rsync would put the directory itself inside the destination.  Add `--delete`
only when that directory should match the backup exactly, since it removes files
created after the backup was taken.  Everything outside the restored paths is
left alone; refresh the index with `reindex` as above, or let the next session
do it, and clients pull the restored versions.  Check the restored paths with the
matching `rsync --dry-run --itemize-changes` comparison before re-enabling the
jobs; no output means they match the backup.

Adjust `/usr/local/bin/filesync` to where the script was installed, because
cron's default PATH rarely includes a per-user Perl bin directory.

## Limitations

These are the design weaknesses a reviewer should weigh before relying on the
tool.  None of them loses data silently; most cost time or space.

- **One master.**  The topology is a star around one server.  The replica

lib/App/FileSync.pm  view on Meta::CPAN

	# on the server, as an administrator
	sudo mkdir -p /srv/filesync
	sudo chown -R foo /srv/filesync

C<filesync-admin repo create documents> works as it is, and the master is
F</srv/filesync/master/documents>.

=head2 Backup and restore

The master directory is an ordinary directory tree, so it can be mirrored to a
backup directory from the server account's crontab.  Make the backup directory
once - rsync creates the last component only - then let cron keep it in step:

	# on the server, once
	mkdir -p /home/foo/backups/documents

	# crontab -e, on the server
	* * * * * ionice -c3 rsync -a --delete --exclude '.filesync-tmp-*' \
	    /home/foo/filesync/master/documents/ /home/foo/backups/documents/

Filesync writes each file to a temporary name and renames it into place, so the
mirror never catches a half-written upload; the exclusion keeps the temporary
files themselves out of the backup.  C<--delete> makes the copy a mirror: a
deletion that reaches the master also removes the backed-up file.

To restore the master from that backup, stop the client jobs (comment out their
cron lines, or disable the scheduled task) and the server's backup job, so the
backup job cannot copy a half-restored tree back into the backup.  Let any
running sync finish, then mirror the backup back:

	rsync -a --delete --checksum \
	    /home/foo/backups/documents/ /home/foo/filesync/master/documents/

C<--checksum> compares the contents, so a restored file is not skipped just
because its size and modification time happen to match the newer copy.  This is
a rollback rather than a merge: files created after the backup was taken
disappear from the master, and the next sync propagates that to the clients, so
copy anything you need to keep out of the tree first.  The server
would rehash the restored files on the next session anyway, but
C<filesync-admin reindex> rebuilds the index immediately, before any client
reconnects; clients then pull the restored versions, merging edits they have not
synced as usual.

Before re-enabling the jobs, check that the copy is exact with a read-only
comparison against the backup:

	rsync -a --delete --checksum --dry-run --itemize-changes \
	    /home/foo/backups/documents/ /home/foo/filesync/master/documents/

No output and exit 0 mean the master matches the backup.  Any line beginning
C<< >f >> names a path that still differs, and C<*deleting> names one the
rollback should have removed.  The index still describes the pre-rollback tree,
so C<filesync-admin verify> may report drift at this point; that is expected.
Rebuild it and check it:

	filesync-admin --root ~/filesync reindex documents
	filesync-admin --root ~/filesync verify documents --deep

C<reindex> hashes every file in the master and replaces the index atomically; it
refuses to run while a sync session holds the repo lock, and it names any paths
it could not index.  C<clean> and exit 0 from C<verify> confirm that the master
and its index agree.  Re-enable the jobs once that check passes.

To restore just one file or directory, copy that path back instead of mirroring
the whole tree, with the jobs paused as above so nothing changes the tree while
the copy runs:

	rsync -a --checksum /home/foo/backups/documents/notes/plan.txt \
	    /home/foo/filesync/master/documents/notes/
	rsync -a --checksum /home/foo/backups/documents/photos/ \
	    /home/foo/filesync/master/documents/photos/

The trailing slash on the second source copies the directory's contents; without
it rsync would put the directory itself inside the destination.  Add C<--delete>
only when that directory should match the backup exactly, since it removes files
created after the backup was taken.  Everything outside the restored paths is
left alone; refresh the index with C<reindex> as above, or let the next session
do it, and clients pull the restored versions.  Check the restored paths with the
matching C<rsync --dry-run --itemize-changes> comparison before re-enabling the
jobs; no output means they match the backup.

Adjust F</usr/local/bin/filesync> to where the script was installed, because
cron's default PATH rarely includes a per-user Perl bin directory.

=head1 LIMITATIONS

These are the design weaknesses a reviewer should weigh before relying on the
tool.  None of them loses data silently; most cost time or space.

=over 4

lib/App/FileSync/Admin.pm  view on Meta::CPAN

Args: C<repo>, C<client> (a client id), optional C<role> (C<client>, the
default, or C<replica>).

Returns: C<{ client, role }>.

Side Effects: rewrites the repo config.  Allowing an existing client again
changes its role.

Usage:

	$admin->client_allow(repo => 'docs', client => 'backup', role => 'replica');

=head3 EXAMPLE

	$admin->client_allow(repo => 'docs', client => 'laptop');

=head3 API SPECIFICATION

=head4 INPUT

	{

lib/App/FileSync/Admin.pm  view on Meta::CPAN

		ok => $report->{ok} ? 1 : 0,
	});

	return $report;
}

=head2 reindex

Purpose: rebuild F<master.json> from the tree, hashing every file.

Used after a manual repair (a rollback from a backup, say) so the index
describes the restored master without waiting for the next client session.
The old index is deliberately not reused: a restored file can keep its size
and mtime while its content differs, which is exactly the case reindex exists
for.

Args: C<repo>, optional C<dry_run>.

Returns: C<{ repo, master, index, files, dirs, bytes, skipped, dry_run, written }>.

Side Effects: holds the repo lock (the same one the server takes), so it never

lib/App/FileSync/IO.pm  view on Meta::CPAN


Side Effects: creates C<$destination>'s parent directories; overwrites
C<$destination>.

Usage:

	copy_preserving($from, $to, \@stat);

=head3 EXAMPLE

	copy_preserving('/srv/a.txt', '/backup/a.txt');

=head3 API SPECIFICATION

=head4 INPUT

	[
		{ name => 'source',      type => 'string', min => 1 },
		{ name => 'destination', type => 'string', min => 1 },
		{ name => 'stat',        type => 'arrayref', optional => 1 },
	]

lib/App/FileSync/Scan.pm  view on Meta::CPAN


1;

__END__

=head1 LIMITATIONS

=over 4

=item * The cache trusts size and mtime.  A tool that rewrites a file and
restores its mtime (some backup restorers do) goes unnoticed until a
C<verify --deep>.

=item * Every run stats every file; there is no change notification.  On a
very large tree the walk, not the transfer, dominates a quiet run.

=item * Directory order is sorted, which costs an O(n log n) per directory
but makes manifests and logs reproducible.

=back

lib/App/FileSync/Transport/SSH.pm  view on Meta::CPAN

C<.bat> ssh wrapper is started through C<COMSPEC>, since CreateProcess cannot
start one directly.

Usage:

	my $transport = App::FileSync::Transport::SSH->new(%args);

=head3 EXAMPLE

	my $t = App::FileSync::Transport::SSH->new(
		server => 'backup', repo => 'photos', client => 'nas', role => 'replica', port => 2222,
	);
	print join(' ', @{ $t->command }), "\n";

=head3 API SPECIFICATION

=head4 INPUT

	{
		server            => { type => 'string', matches => $SERVER },
		repo              => { type => 'string', min => 1, max => 64 },

lib/App/FileSync/Trash.pm  view on Meta::CPAN


1;

__END__

=head1 LIMITATIONS

=over 4

=item * A same-day collision is stored as C<PATH.N>.  A real file whose name
already ends in C<.N> (C<backup.1>) deleted the same day as C<backup> is
therefore listed as a version of C<backup> too.

=item * Moving a directory across filesystems is not supported; files are
copied and removed, directories must rename.

=item * Pruning works in whole UTC days, so retention is accurate to a day.

=back

=head1 AUTHOR

lib/App/FileSync/Verify.pm  view on Meta::CPAN

__END__

=head1 LIMITATIONS

=over 4

=item * A shallow verify trusts size and mtime, so it cannot see a change that
kept both; use C<deep> or C<sample> for that.

=item * The report says what differs, not which side is right.  After a
restore from backup the index, not the tree, is usually the stale one; see
C<filesync-admin reindex>.

=back

=head1 AUTHOR

Nigel Horne, C<< <njh at nigelhorne.com> >>

=head1 LICENCE AND COPYRIGHT

t/join.t  view on Meta::CPAN

	is($stable->{summary}{pulled}, 0, 'nothing is left to pull after the rejoin');
	is($stable->{summary}{pushed}, 0, 'nothing is left to push after the rejoin');
	is_deeply(files_only($env, $env->{client}), files_only($env, master_dir($env)),
		'the rejoined client and master hold the same files');
}

# ------------------------------------- rejoining a forgotten replica
# A replica never pushes and never keeps conflict copies: after a forget it
# must still mirror the master, overwriting local edits and removing extras.
{
	my $env = TestSync->new_env(client_id => 'backup-1', role => 'replica');

	$env->write_file('server', 'a.txt', "master a\n", $T0);
	$env->write_file('server', 'sub/b.txt', "master b\n", $T0 + 1);
	make_path($env->server_path('empty'));

	my $first = $env->sync();
	is($first->{summary}{pulled}, 3, 'the replica first mirrors the files and empty dir');
	is($first->{summary}{pushed}, 0, 'and never pushes');

	my $base = $env->meta_path('clients', 'backup-1.json');
	ok(-e $base, 'the server stored a base for the replica');

	# Both sides change before the replica is forgotten: the master edits one
	# file, adds one and removes one; the replica edits the same file, adds an
	# extra and loses the empty directory.
	$env->write_file('server', 'a.txt', "master changed\n", $T0 + 300);
	$env->write_file('server', 'master-only.txt', "master only\n", $T0 + 100);
	unlink $env->server_path('sub/b.txt');

	# The replica's edit is newer than the master's, so a normal client would
	# win this path; a replica must still discard its version.
	$env->write_file('client', 'a.txt', "replica edit\n", $T0 + 400);
	$env->write_file('client', 'rogue.txt', "not on the master\n", $T0 + 200);
	rmdir $env->client_path('empty') or die "Cannot remove the replica empty dir: $!";

	my $output = `$^X $admin --root $env->{server} client forget backup-1 --repo docs 2>&1`;
	is($?, 0, 'the replica can be forgotten');
	like($output, qr/Forgot backup-1/, 'the admin command names the replica');
	ok(!-e $base, 'the stored base is gone');

	my $rejoin = $env->sync();
	is($rejoin->{summary}{pulled}, 4,
		'the rejoin pulls the changed, added and missing-directory entries');
	is($rejoin->{summary}{pushed}, 0, 'the forgotten replica still never pushes');
	is($rejoin->{summary}{deleted}, 2, 'it removes its extra and the master-deleted file');
	is($rejoin->{summary}{conflicts}, 0, 'a replica has no conflicts to resolve');
	is($rejoin->{exit}, 3, 'the removals are reported as warnings');

t/join.t  view on Meta::CPAN

	is($env->read_file('client', 'a.txt'), "master again\n",
		'the later master edit is mirrored');
	ok(!$env->exists_in('client', 'another-rogue.txt'), 'the later extra is gone');
}

# A forgotten replica must not let an empty master wipe a populated mirror.
# With no base there is no baseline for the percentage limit, so the absolute
# max_deletes guard is the protection that matters here.
{
	my $env = TestSync->new_env(
		client_id => 'backup-1', role => 'replica', max_deletes => 3,
	);

	$env->write_file('server', "file$_.txt", "master $_\n", $T0 + $_)
		for 1 .. 5;

	my $first = $env->sync();
	is($first->{summary}{pulled}, 5, 'the replica mirrors the five master files');
	my $base = $env->meta_path('clients', 'backup-1.json');
	ok(-e $base, 'the replica has a stored base');

	# The master is emptied, then the replica is forgotten.  Without a base the
	# only surviving limit is max_deletes.
	unlink $env->server_path("file$_.txt") for 1 .. 5;

	my $output = `$^X $admin --root $env->{server} client forget backup-1 --repo docs 2>&1`;
	is($?, 0, 'the replica can be forgotten');
	ok(!-e $base, 'its base is gone');

	my $before = $env->snapshot($env->{client});
	my $error;
	eval { $env->sync(); 1 } or $error = $@;
	ok($error, 'the rejoin is refused without --force');
	like($error, qr/refusing to delete 5 files \(limit is 3\)/,
		'the refusal names the deletion count and the guard');

t/merge.t  view on Meta::CPAN

	{ gone => entry($H1, 100), kept => entry($H1, 100) },
);
is($ordered->[0]{a}, 'delete_remote', 'deletions are ordered first');
is($ordered->[1]{a}, 'push', 'transfers follow');

# Replica: mirror only, never push.
my $replica = App::FileSync::Merge::plan(
	base       => { a => entry($H1, 100) },
	client     => { a => entry($H2, 200), extra => entry($H1, 100) },
	master     => { a => entry($H1, 100), b => entry($H3, 100) },
	client_id  => 'backup-1',
	role       => 'replica',
);
my %replica_actions = map { $_->{p} => $_->{a} } @{ $replica->{actions} };
is_deeply(\%replica_actions, { a => 'pull', b => 'pull', extra => 'delete_local' },
	'replica pulls what differs and removes extras, never pushes');
is($replica->{conflicts}, 0, 'a replica cannot conflict');
ok((grep { $_ =~ /changed on the replica/ } @{ $replica->{warnings} }),
	'local replica edits are reported');

# Delete guard.

t/replica.t  view on Meta::CPAN

use File::Path qw(make_path);
use File::Spec;

use lib 't/lib';
use TestSync;
use App::FileSync::Protocol;
use App::FileSync::Transport::Local;

my $T0 = 1_700_000_000;

my $env = TestSync->new_env(client_id => 'backup-1', role => 'replica');

# Populate the master (an administrator can drop files in directly).
$env->write_file('server', 'a.txt', "master a\n", $T0);
$env->write_file('server', 'sub/b.txt', "master b\n", $T0 + 1);
make_path(File::Spec->catdir($env->{server}, 'master', 'docs', 'empty'));

my $first = $env->sync();
is($first->{summary}{pulled}, 3, 'replica pulls the files and the empty directory');
is($env->read_file('client', 'a.txt'), "master a\n", 'content mirrored');
ok($env->exists_in('client', 'sub/b.txt'), 'nested file mirrored');

t/replica.t  view on Meta::CPAN


# And the replica never pushes even when the master changes.
$env->write_file('server', 'a.txt', "master changed\n", $T0 + 700);
my $pull = $env->sync();
is($pull->{summary}{pulled}, 1, 'master changes reach the replica');
is($env->read_file('server', 'a.txt'), "master changed\n", 'master content untouched by the replica');

# A hostile or confused replica cannot write, even by talking the protocol
# directly: the plan it is given contains no write actions at all.
{
	my $env = TestSync->new_env(client_id => 'backup-2', role => 'replica');
	$env->write_file('server', 'a.txt', "master\n", $T0);

	my $transport = App::FileSync::Transport::Local->new(
		root   => $env->{server},
		repo   => 'docs',
		client => 'backup-2',
		role   => 'replica',
	);

	my $conn = App::FileSync::Protocol->new(
		in  => $transport->reader(),
		out => $transport->writer(),
	);

	$conn->send({
		cmd => 'hello', proto => 2, client => 'backup-2', host => 'test', os => $^O,
		role => 'replica', repo => 'docs', case_insensitive => 0, now => time,
	});
	ok($conn->recv()->{ok}, 'the replica session opens');

	my $content = "evil\n";
	my $sha = Digest::SHA->new(256);
	$sha->add($content);
	my $hash = $sha->hexdigest();

	$conn->send({

t/replica.t  view on Meta::CPAN

	ok(!$env->exists_in('server', 'evil.txt'), 'nothing was written to the master');

	$transport->close();
}

# A replica with a surviving base is stopped by the percentage deletion guard.
# The absolute limit is set far above the deletion count, so only the share of
# the base decides; with the base still present, that rule has a baseline.
{
	my $env = TestSync->new_env(
		client_id => 'backup-3', role => 'replica', max_deletes => 500,
	);

	$env->write_file('server', "file$_.txt", "master $_\n", $T0 + $_)
		for 1 .. 10;

	my $first = $env->sync();
	is($first->{summary}{pulled}, 10, 'the replica mirrors all ten master files');

	my $base = $env->meta_path('clients', 'backup-3.json');
	ok(-e $base, 'the replica keeps its base, so the percentage rule applies');
	my $base_before = do {
		local $/;
		open my $fh, '<', $base or die "Cannot read $base: $!";
		<$fh>;
	};

	# The master loses eight of its ten files.
	unlink $env->server_path("file$_.txt") for 3 .. 10;

t/replica.t  view on Meta::CPAN

	my $stable = $env->sync();
	is($stable->{summary}{deleted}, 0, 'nothing is left to delete after --force');
	is($stable->{summary}{pulled}, 0, 'and nothing is left to pull');
	is($stable->{summary}{pushed}, 0, 'and the replica still pushes nothing');
}

# The same guard allows deletions up to the percentage limit.  Two of twenty
# files is exactly the 10% allowance, so this mirror converges without --force.
{
	my $env = TestSync->new_env(
		client_id => 'backup-4', role => 'replica', max_deletes => 500,
	);

	$env->write_file('server', sprintf('file%02d.txt', $_), "master $_\n", $T0 + $_)
		for 1 .. 20;

	my $first = $env->sync();
	is($first->{summary}{pulled}, 20, 'the replica mirrors twenty master files');

	# Deletions at the limit are allowed; only a larger share is refused.
	unlink $env->server_path('file19.txt');

t/replica.t  view on Meta::CPAN

	my $stable = $env->sync();
	is($stable->{summary}{deleted}, 0, 'the allowed deletion is not repeated');
	is($stable->{summary}{pulled}, 0, 'nothing is left to pull');
	is($stable->{summary}{pushed}, 0, 'and nothing is pushed');
}

# One deletion over the allowance is refused: three of twenty is 15%, above
# the 10% limit, so the mirror must stay put until --force says otherwise.
{
	my $env = TestSync->new_env(
		client_id => 'backup-5', role => 'replica', max_deletes => 500,
	);

	$env->write_file('server', sprintf('file%02d.txt', $_), "master $_\n", $T0 + $_)
		for 1 .. 20;

	my $first = $env->sync();
	is($first->{summary}{pulled}, 20, 'the replica mirrors twenty master files');

	my $base = $env->meta_path('clients', 'backup-5.json');
	my $base_before = do {
		local $/;
		open my $fh, '<', $base or die "Cannot read $base: $!";
		<$fh>;
	};

	unlink $env->server_path('file18.txt');
	unlink $env->server_path('file19.txt');
	unlink $env->server_path('file20.txt');

t/snapshot.t  view on Meta::CPAN

		write_file("$root/a.txt", "edited in place\n", $T0 + 600);
		is(read_file("$linked->{path}/a.txt"), "edited in place\n",
			'in-place edits show through a hardlinked snapshot (documented caveat)');
		is(read_file("$copy->{path}/a.txt"), "alpha\n",
			'a copy-mode snapshot is unaffected by in-place edits');
	}
}

# ------------------------------------------- snapshots and the replica mirror
{
	my $env = TestSync->new_env(client_id => 'backup-1', role => 'replica');

	$env->write_file('server', 'a.txt', "master a\n", $T0);
	$env->write_file('server', 'sub/b.txt', "master b\n", $T0 + 1);
	$env->sync();

	my $snapshot = $env->snapshot_create();
	is($snapshot->{created}, 1, 'the replica takes a snapshot');
	is($snapshot->{files}, 2, 'the snapshot holds the mirrored files');
	ok(-e File::Spec->catfile($env->{client}, '.filesync-snapshots', $snapshot->{date}, 'a.txt'),
		'the snapshot lives inside the replica root');

t/snapshot.t  view on Meta::CPAN


	is_deeply(
		[ map { $_->{date} } @{ $env->snapshot_list()->{snapshots} } ],
		[ $snapshot->{date} ],
		'the replica lists its snapshot',
	);
}

# ------------------------------------------------------------- command line
{
	my $env = TestSync->new_env(client_id => 'backup-1', role => 'replica');

	$env->write_file('server', 'a.txt', "master\n", $T0);
	$env->sync();

	App::FileSync::Snapshot::create(root => $env->{client}, date => '2026-01-01');
	App::FileSync::Snapshot::create(root => $env->{client}, date => '2026-01-02');

	my $output = `$^X $filesync snapshot --repo docs --keep 2 2>&1`;
	is($?, 0, 'filesync snapshot exits 0');
	like($output, qr/snapshot \d{4}-\d{2}-\d{2} taken \(1 file, 7 B\)/,

website/html/changelog.html  view on Meta::CPAN

	</ul>

	<h3>Documentation</h3>
	<ul>
		<li>The examples are split by machine &mdash; what to run on the server, on
		each client, and from cron &mdash; and keep the master in a home directory,
		so nothing needs sudo.</li>
		<li>What a <code>/srv/filesync</code> root needs instead, the wrapper that
		adds <code>--root</code> to <code>filesync-server</code>, and the ssh key the
		first sync requires.</li>
		<li>The backup and restore commands follow the example's master layout, and
		make the backup directory before cron mirrors into it.</li>
		<li>The synopsis creates the repo first, so it runs as printed.</li>
	</ul>

	<h2 id="v0-001-1">0.001.1 <span class="muted">&mdash; 24 October 2026</span></h2>

	<h3>Bug fixes</h3>
	<ul>
		<li>Build: test on Windows with Perl 5.42 again. Its
		<code>B::Hooks::EndOfScope</code> faults at exit, so the plain-Perl hook is
		used there.</li>

website/html/commands.html  view on Meta::CPAN

		<thead>
			<tr><th>Command</th><th>What it does</th></tr>
		</thead>
		<tbody>
			<tr><td><code>repo create</code></td><td>Creates the master tree, the metadata directory, the policy and an empty index. <code>--trash-days</code> sets retention, <code>--max-deletes</code> and <code>--max-delete-percent</code> the per-session del...
			<tr><td><code>repo list</code></td><td>Lists the repos under the root.</td></tr>
			<tr><td><code>repo show</code></td><td>Prints one repo's policy.</td></tr>
			<tr><td><code>client allow</code></td><td>Admits a client id to a repo, as <code>client</code> or <code>replica</code>. A repo with no listed clients admits every client.</td></tr>
			<tr><td><code>client list</code></td><td>Lists a repo's admitted clients.</td></tr>
			<tr><td><code>client forget</code></td><td>Removes a client from the list.</td></tr>
			<tr><td><code>reindex</code></td><td>Rebuilds the master index by hashing every file. Holds the repo lock. Used after a manual repair such as a rollback from backup; <code>--dry-run</code> reports without writing.</td></tr>
			<tr><td><code>verify</code></td><td>Compares the master with its index. <code>--deep</code> hashes every file; <code>--sample N</code> hashes N of them.</td></tr>
			<tr><td><code>restore</code></td><td>Puts a path back from the server trash, into the master by default or into <code>--to</code> as an export. <code>--date</code> picks the newest version from that day; <code>--list</code> lists versions. Restori...
			<tr><td><code>log</code></td><td>The server's journal, for one or more repos, with the same time, exit and warning filters as <code>filesync log</code> plus <code>--client</code>.</td></tr>
		</tbody>
	</table>
	</div>

	<p>If the server root cannot be written, <code>repo create</code> names the
	directory that blocks it and says to chown it to the running account or to use
	<code>--root</code> elsewhere. That advice is given only when a directory really

website/html/how-it-works.html  view on Meta::CPAN

			<p>Pulls are requested in chunks and pushes are sent in chunks; each
			256&nbsp;KiB chunk waits for its acknowledgement, so one request is in
			flight at a time. Files of at least 64&nbsp;KiB are sent as block deltas
			when the other side already holds an older copy.</p>
		</li>
		<li>
			<h3>Transfers are verified, then committed</h3>
			<p>An upload is checked against its SHA-256 at the end and only then
			renamed into the master. A pull is checked against the hash in the plan; a
			mismatch fails that pull and the next run retries. Temporary names carry
			a <code>.filesync-tmp-</code> prefix, which the backup example excludes.</p>
		</li>
		<li>
			<h3>State is written and the run is logged</h3>
			<p>The server rewrites the index and the client's base and appends to the
			repo journal. The client updates its cache, prunes its local trash unless
			<code>--no-prune</code> was given, and appends to
			<code>~/.filesync/logs/REPO.jsonl</code> whatever the outcome. The summary
			reports pulled, pushed, deleted and conflicted counts, the payload bytes
			in each direction, and how many files moved as a delta.</p>
		</li>

website/html/how-it-works.html  view on Meta::CPAN

	<table>
		<thead><tr><th>Path</th><th>Holds</th></tr></thead>
		<tbody>
			<tr><td><code>ROOT/master/REPO/</code></td><td>The master tree, an ordinary directory.</td></tr>
			<tr><td><code>ROOT/.filesync/repos/REPO/config.json</code></td><td>The repo policy and the admitted clients.</td></tr>
			<tr><td><code>ROOT/.filesync/repos/REPO/</code></td><td>The index, the per-client bases, the server trash and the journal.</td></tr>
		</tbody>
	</table>
	</div>

	<p>The master is a normal tree, so backup is rsync and restore is rsync plus
	<code>filesync-admin reindex</code>. The index is a JSON file rewritten whole
	at the end of each session.</p>

	<h2 id="locking">Locking and concurrency</h2>

	<p>Both the client and the server take locks, and a refusal is not an error:
	<code>filesync</code> exits <strong>2</strong> so cron can tell "a run was
	already in progress" from "a run failed". The plan is computed once, from a
	scan taken while the repo lock is held; something else writing into the master
	during a session is not seen until the next one.</p>

website/html/index.html  view on Meta::CPAN

	<p>The client reports its host name as its id; there is nothing else to name.
	An id is not a login, and it does not divide the repo: every client of a repo
	syncs the whole tree.</p>

	<h2>Where to go next</h2>

	<ul class="grid">
		<li class="card">
			<h3><a href="quickstart.html">Quick start</a></h3>
			<p>Server and client setup, the first sync, cron, Windows, and a
			backup-and-restore drill.</p>
		</li>
		<li class="card">
			<h3><a href="commands.html">Commands</a></h3>
			<p>Every option of <code>filesync</code>, <code>filesync-admin</code>
			and <code>filesync-server</code>, and what each exit code means.</p>
		</li>
		<li class="card">
			<h3><a href="settings.html">Settings</a></h3>
			<p>Process-wide settings, the client's repo list, the server's per-repo
			policy, and where each value came from.</p>

website/html/limitations.html  view on Meta::CPAN

	</ul>

	<h2>Consistency</h2>

	<ul>
		<li><strong>Clock-dependent tie-breaks.</strong> When both sides changed a
		file, the newer mtime wins (the master wins ties within two seconds). A
		client with a wrong clock picks the wrong winner; the loser is still kept as
		a conflict copy.</li>
		<li><strong>The cache trusts size and mtime.</strong> A tool that rewrites a
		file and restores its mtime &mdash; some backup restorers do &mdash; goes
		unnoticed until a <code>verify --deep</code>.</li>
		<li><strong>One scan per session.</strong> The plan is computed once, from a
		scan taken while the lock is held. Anything other than filesync writing into
		the master during a session is not seen until the next session, and a file
		it replaces may be overwritten.</li>
		<li><strong>Pulls are verified against the plan.</strong> If the master
		changes during the session (only possible if something other than filesync
		writes to it), the pull fails with a hash mismatch and the next sync
		retries.</li>
		<li><strong>Uploads are verified only at the end.</strong> A client that

website/html/limitations.html  view on Meta::CPAN


	<h2>Recovery and administration</h2>

	<ul>
		<li><strong>Trash is per repo and per client.</strong> Local trash written by
		releases before 0.001.1 sits in one shared directory. It is still searched
		by <code>restore</code> and pruned with the default 30 days, but a
		<code>restore</code> can then offer another repo's file of the same relative
		path.</li>
		<li><strong>Same-day trash collisions are numeric.</strong> A real file whose
		name already ends in <code>.N</code> (<code>backup.1</code>) deleted the same
		day as <code>backup</code> is listed as a version of <code>backup</code>
		too. Pruning works in whole UTC days, so retention is accurate to a day.</li>
		<li><strong>Trash cannot cross filesystems by rename.</strong> Files are
		copied and removed; directories must rename.</li>
		<li><strong>Admin methods mostly take no lock.</strong> Only
		<code>reindex</code> does; <code>restore</code> into the master rebuilds the
		index by walking the tree and does not take the repo lock, so a session
		running at the same moment can save an index that omits the restored file
		until its next sync.</li>
		<li><strong>The server journal is read whole.</strong> <code>filesync-admin
		log</code> loads every monthly journal into memory before filtering and

website/html/quickstart.html  view on Meta::CPAN

		<p>On this page</p>
		<ul>
			<li><a href="#server">On the server</a></li>
			<li><a href="#wrapper">The server-command wrapper</a></li>
			<li><a href="#client">On each client</a></li>
			<li><a href="#first">The first sync</a></li>
			<li><a href="#cron">From cron</a></li>
			<li><a href="#checking">Checking what happened</a></li>
			<li><a href="#windows">On Windows</a></li>
			<li><a href="#srv">A root of /srv/filesync instead</a></li>
			<li><a href="#backup">Backup and restore</a></li>
		</ul>
	</div>

	<h2 id="server">On the server</h2>

	<p>Create the repo as the account the clients log in to. A session over ssh
	carries only the repo, the client id and the role, so the client never tells
	the server which root to use: name the same <code>--root</code> on every
	server command.</p>

website/html/quickstart.html  view on Meta::CPAN

	for the account the clients log in to. Then no <code>--root</code> is needed
	on the server commands, and no <code>--server-command</code> on the client:</p>

<pre><code># on the server, as an administrator
sudo mkdir -p /srv/filesync
sudo chown -R foo /srv/filesync</code></pre>

	<p><code>filesync-admin repo create documents</code> then works as it is, and
	the master is <code>/srv/filesync/master/documents</code>.</p>

	<h2 id="backup">Backup and restore</h2>

	<p>The master directory is an ordinary directory tree, so it can be mirrored
	to a backup directory from the server account's crontab. Make the backup
	directory once &mdash; rsync creates the last component only &mdash; then let
	cron keep it in step:</p>

<pre><code># on the server, once
mkdir -p /home/foo/backups/documents

# crontab -e, on the server
* * * * * ionice -c3 rsync -a --delete --exclude '.filesync-tmp-*' \
    /home/foo/filesync/master/documents/ /home/foo/backups/documents/</code></pre>

	<p>Filesync writes each file to a temporary name and renames it into place, so
	the mirror never catches a half-written upload; the exclusion keeps the
	temporary files themselves out of the backup. <code>--delete</code> makes the
	copy a mirror: a deletion that reaches the master also removes the backed-up
	file.</p>

	<p>To restore the master from that backup, stop the client jobs (comment out
	their cron lines, or disable the scheduled task) and the server's backup job,
	so the backup job cannot copy a half-restored tree back into the backup. Let
	any running sync finish, then mirror the backup back:</p>

<pre><code>rsync -a --delete --checksum \
    /home/foo/backups/documents/ /home/foo/filesync/master/documents/</code></pre>

	<p><code>--checksum</code> compares the contents, so a restored file is not
	skipped just because its size and modification time happen to match the newer
	copy. This is a rollback rather than a merge: files created after the backup
	was taken disappear from the master, and the next sync propagates that to the
	clients, so copy anything you need to keep out of the tree first.</p>

	<p>The server would rehash the restored files on the next session anyway, but
	<code>filesync-admin reindex</code> rebuilds the index immediately, before any
	client reconnects; clients then pull the restored versions, merging edits they
	have not synced as usual.</p>

	<p>Before re-enabling the jobs, check that the copy is exact with a read-only
	comparison against the backup:</p>

<pre><code>rsync -a --delete --checksum --dry-run --itemize-changes \
    /home/foo/backups/documents/ /home/foo/filesync/master/documents/</code></pre>

	<p>No output and exit 0 mean the master matches the backup. Any line beginning
	<code>&gt;f</code> names a path that still differs, and <code>*deleting</code>
	names one the rollback should have removed. The index still describes the
	pre-rollback tree, so <code>filesync-admin verify</code> may report drift at
	this point; that is expected. Rebuild it and check it:</p>

<pre><code>filesync-admin --root ~/filesync reindex documents
filesync-admin --root ~/filesync verify documents --deep</code></pre>

	<p><code>reindex</code> hashes every file in the master and replaces the index
	atomically; it refuses to run while a sync session holds the repo lock, and it
	names any paths it could not index. <code>clean</code> and exit 0 from
	<code>verify</code> confirm that the master and its index agree. Re-enable the
	jobs once that check passes.</p>

	<p>To restore just one file or directory, copy that path back instead of
	mirroring the whole tree, with the jobs paused as above so nothing changes the
	tree while the copy runs:</p>

<pre><code>rsync -a --checksum /home/foo/backups/documents/notes/plan.txt \
    /home/foo/filesync/master/documents/notes/
rsync -a --checksum /home/foo/backups/documents/photos/ \
    /home/foo/filesync/master/documents/photos/</code></pre>

	<p>The trailing slash on the second source copies the directory's contents;
	without it rsync would put the directory itself inside the destination. Add
	<code>--delete</code> only when that directory should match the backup
	exactly, since it removes files created after the backup was taken. Refresh
	the index with <code>reindex</code> as above, or let the next session do it,
	and clients pull the restored versions.</p>
</main>

<footer class="site-footer">
	<div class="wrap">
		<p>App::FileSync 0.002.0 &middot; Copyright 2026 Nigel Horne &middot; GPL-2.0</p>
		<p><a href="https://metacpan.org/dist/App-FileSync">CPAN</a> &middot;
		<a href="https://github.com/nigelhorne/App-FileSync">GitHub</a> &middot;
		<a href="https://github.com/nigelhorne/App-FileSync/issues">Issues</a> &middot;



( run in 3.615 seconds using v1.01-cache-2.11-cpan-99fa8243a42 )