Xvc for Everyone

This guide is a gentle introduction to Xvc for anyone who needs to keep track of a growing collection of files — photos, documents, recordings — and share them with others. It assumes no prior experience with Git or the command line beyond being able to run a command in a terminal.

Xvc keeps large files versioned alongside your project without storing the files themselves in Git. Git tracks small text files well but becomes slow and bloated when it stores large binaries, because every clone copies the entire history. Xvc records the content of your files separately, so Git stays small while you still get versioning, backup, and sharing.

Set up a folder for Xvc

Xvc works best on top of Git. In the folder you want to track, initialize both:

$ git init
$ xvc init

You only run this once per folder. From now on, Xvc handles the Git operations for the metadata it creates, so you don't need to learn Git commands unless you want to share your files with other people.

Hide files you don't want tracked

If some files are private and you don't want Xvc to see them at all, list them in a .xvcignore file in the root of your folder. Xvc skips anything matching the patterns you put there, the same way Git uses .gitignore.

Track your files

Use xvc file track to register files and directories. To track a single directory:

$ xvc file track today/

Xvc calculates a content hash for every file, copies the content into its cache, and puts the files back in your folder. To track everything that isn't ignored, run the command without a target:

$ xvc file track

Xvc can store the content of your files in a separate location — for example an AWS S3 bucket — so you can back them up or share them. First, configure a storage:

$ xvc storage new s3 --name my-photos --region eu-central-1 --bucket-name my-bucket

Then send the tracked content to it:

$ xvc file send --to my-photos

Xvc never stores your cloud credentials. It reads them from your AWS configuration or environment variables when it needs them, and it makes no network requests without your knowledge. To let other people download the files, give them read access to the bucket.

The storage holds the file contents; Git holds the small metadata that points to them. To share the whole project, push the Git repository to a host such as GitHub:

$ git remote add origin https://github.com/your-username/my-photos
$ git push --set-upstream origin main

Get the files on another computer

Someone else (or you, on a different machine) can now clone the repository and fetch the file contents from the storage:

$ git clone https://github.com/your-username/my-photos
$ cd my-photos
$ xvc file bring .

There is no need to run xvc init again — the repository is already initialized. The person fetching the files does need valid credentials for the storage, because Xvc never stores them for you.

The everyday workflow

Once everything is set up, adding and sharing new files follows a simple order:

$ xvc file track      # register new or changed files with Xvc
$ git push            # publish the metadata

Xvc commits its metadata to Git automatically, so pushing sends both the new records and any storage changes. On another computer, receive the changes in the same order:

$ git pull            # get the latest metadata
$ xvc file bring      # download the file contents

Pull the metadata first, then bring the files, because Xvc needs the records before it can find the content in the storage.

The Xvc Book