Installing Synck

Synck is a single program, synck, written in Rust. For the 0.1 release you install it by building it from source, which takes a few minutes the first time. Building is the same on macOS, Linux and Windows.

Before you start

You need three things:

  1. Git, to download the source.
  2. Rust, installed through rustup. The source tree names the exact compiler version it was tested with in rust-toolchain.toml, and rustup downloads that version automatically the first time you build.
  3. A C compiler and linker. Some of Synck’s dependencies, including the SQLite database it bundles, contain C code:
    • macOS: the Xcode Command Line Tools (xcode-select --install).
    • Linux: your distribution’s C build tools, for example build-essential on Debian and Ubuntu or gcc on Fedora.
    • Windows: the Microsoft C++ Build Tools, which the rustup installer offers to set up for you.

Build and install

Download the source and install the command:

git clone https://github.com/synergyos/synck.git
cd synck
cargo install --locked --path crates/synck-local

--locked makes Cargo use exactly the dependency versions recorded in Cargo.lock, which are the versions the release was tested with. Cargo places the finished synck program in its binary directory: ~/.cargo/bin on macOS and Linux, %USERPROFILE%\.cargo\bin on Windows. rustup normally adds that directory to your PATH. If your shell cannot find synck afterwards, open a new terminal, or add the directory to PATH yourself.

Check that it works:

$ synck --version
synck 0.1.0

Synck keeps no global settings and has nothing to configure after installation. Every repository carries its own configuration inside its .synck directory.

Getting help

The tool documents itself. synck --help lists every command, and every command and subcommand accepts --help:

$ synck mv --help
Move a tracked item and preserve its identity

Usage: synck mv [OPTIONS] --message <MESSAGE> <SOURCE> <DESTINATION>
...

synck instructions prints a compact operating guide that covers the safe way to work with repositories and their copies. It is written for people and for AI agents that drive the CLI on someone’s behalf, and it is worth reading once.

A note on the examples

The examples in this documentation use a POSIX shell such as zsh or bash, as on macOS and Linux. Synck commands are the same on Windows. Only the surrounding shell commands, such as printf, cat and mkdir, differ, and PowerShell has equivalents for all of them.

Example output is real. IDs, hashes and timestamps will be different on your machine, because Synck generates fresh IDs and records the actual time.

Updating and removing

To update, fetch the new source and install again. --force replaces the installed program even when the version number has not changed:

cd synck
git pull
cargo install --locked --path crates/synck-local --force

Updating the tool never rewrites your repositories. To remove Synck, run cargo uninstall synck-local. Your repositories are ordinary folders and are not affected.

A background helper you might notice

When you work in a tracked folder, Synck starts a small background process, synck monitor, that watches the folder for changes so that synck status and synck commit stay fast in large folders. It holds no data of its own and is safe to stop at any time:

$ synck monitor status
monitor running
$ synck monitor stop
monitor stopped

Synck starts it again the next time a command needs to scan the folder.

Now create your first repository.

Previous
Getting started
Next
Your first repository