App-FileSync

 view release on metacpan or  search on metacpan

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

		<thead>
			<tr><th>Option</th><th>Meaning</th></tr>
		</thead>
		<tbody>
			<tr><td><code>--to DIR</code></td><td>Copy the version into DIR instead of back into the sync root.</td></tr>
			<tr><td><code>--list</code></td><td>List the stored versions; restore nothing.</td></tr>
		</tbody>
	</table>
	</div>

	<p>The trash entry is kept, so a restore is repeatable. The destination must not
	already exist.</p>

	<h3>filesync snapshot</h3>

	<p>Takes today's snapshot of a replica, pruning old ones. Snapshots are for the
	<code>replica</code> role only. <code>--keep N</code> sets how many to keep,
	defaulting to the repo's <code>snapshot_keep</code> and then to 14; 0 keeps
	all.</p>

<pre><code>filesync snapshot --repo offsite --keep 7
filesync snapshot list --repo offsite
filesync snapshot restore 2026-10-20 --repo offsite --to /tmp/export
filesync snapshot restore 2026-10-20 notes --repo offsite</code></pre>

	<p><code>snapshot restore</code> copies a whole snapshot, or one relative path
	of it, back. Without <code>--to</code> it restores into the sync root, which
	rolls the replica back to that date. It holds the repo lock while it works.</p>

	<h2 id="admin">filesync-admin</h2>

<pre><code>filesync-admin --root DIR &lt;command&gt;

  repo create NAME [--trash-days N] [--max-deletes N] [--max-delete-percent N]
                   [--ignore PATTERN]...
  repo list
  repo show NAME
  client allow ID --repo NAME [--role client|replica]
  client list --repo NAME
  client forget ID --repo NAME
  reindex NAME [--dry-run] [--json]
  verify NAME [--deep] [--sample N] [--json]
  restore NAME PATH [--to DIR] [--list] [--date YYYY-MM-DD]
  log NAME... [-n N] [--client ID] [--since YYYY-MM-DD|EPOCH]
              [--until YYYY-MM-DD|EPOCH] [--exit N]... [--warnings] [--json]</code></pre>

	<p><code>--root</code> is read only before the command name.</p>

	<div class="table-wrap">
	<table>
		<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
	is unwritable, so a full disk or a root that is a file keeps its own error.</p>

	<h2 id="server">filesync-server</h2>

<pre><code>command="filesync-server --repo docs --client laptop --role client" ssh-ed25519 AAAA...</code></pre>

	<p>It is not run by hand: sshd starts it with the arguments pinned in
	<code>authorized_keys</code>. The session carries only the repo, the client id
	and the role, which is why the client cannot choose the server root and why
	the <a href="quickstart.html#wrapper">wrapper</a> exists. It refuses to speak
	the protocol on a terminal unless <code>FILESYNC_ALLOW_TTY</code> is set.</p>

	<h2 id="exit">Exit codes</h2>

	<div class="table-wrap">
	<table>
		<thead>
			<tr><th>Code</th><th>Meaning</th><th>Applies to</th></tr>
		</thead>
		<tbody>
			<tr><td>0</td><td>Success.</td><td>both</td></tr>
			<tr><td>1</td><td>Fatal error.</td><td>both</td></tr>
			<tr><td>2</td><td>Another run holds the lock.</td><td>client</td></tr>
			<tr><td>3</td><td>Completed with warnings.</td><td>client</td></tr>
			<tr><td>4</td><td>Verification found drift.</td><td>both</td></tr>
		</tbody>
	</table>
	</div>

	<p>Library errors are raised with <code>croak</code>, but the commands strip the
	<code>at FILE line N</code> suffix before printing. Set
	<code>FILESYNC_TRACE=1</code> to keep the full stack trace.</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;
		<a href="changelog.html">Changes</a></p>
	</div>
</footer>
</body>
</html>



( run in 1.451 second using v1.01-cache-2.11-cpan-99fa8243a42 )