btrsync

Replicate btrfs subvolumes, handling Copy-on-Write (COW) relationships and incremental transfers automatically.

Documentation is on Read the Docs. Code repository and issue tracker are on GitHub. Changelog here.

Background

btrfs is a modern Linux Copy-on-Write (COW) filesystem supporting powerful features such as snapshotting and incremental serialization. This makes it easy to efficiently replicate related snapshots from one filesystem to another by transferring only the differences between them.

What is not easy, however, is manually identifying and tracking these relationships in order to fully leverage the features of btrfs. Built-in tools provide the necessary mechanisms, but the heavy lifting is left to the user.

This is where btrsync comes in.

True to its name, btrsync is "rsync, but for btrfs", reducing the complex task of comparing and replicating snapshots down to a one-liner:

btrsync SOURCE DESTINATION

Features

• Handles subvolume discovery and incremental transfers automatically
• Supports local and remote machines (through SSH)
• Intuitive CLI inspired by familiar tools like rsync and scp

Install

btrsync requires Python 3.9 or later.

The easiest way to install is from PyPI via pip:

pip install btrsync

(replace pip with pip3 if your system's pip defaults to Python 2)

Alternatively you can install from a locally built wheel (requires build and pip):

make && make install

This will run the unit tests, build the documentation and a local wheel, then install it with pip.

Usage

Command-line

See the CLI Usage section of the documentation for general guidance and examples.

The help option provides information about command-line options:

btrsync --help

Library

You can also import btrsync directly in your Python programs, see the API Reference. The implementation of the btrsync CLI provides an extensive example on how to use the API.

API

See the API Reference section of the documentation.

Development

Branches

• main: tracks the latest tagged release
• dev: pre-release features and fixes
• post-VERSION: maintenance branch for VERSION with backported fixes

Make reference

Running make with no arguments will:

1. Run the unit tests and (if passing) produce coverage information under htmlcov/
2. Build the HTML documentation under doc/build/html/
3. Build a Python source distribution (sdist) and wheel under dist/

Running Tests

Unit tests use the Python standard library unittest module. Coverage measurements require Coverage.py.

• make test runs all unit tests
• make cov runs all unit tests while collecting coverage information
• make htmlcov creates a HTML coverage report under htmlcov/, running the coverage measurements as needed

Building Documentation

Building the documentation requires Sphinx.

• make doc builds the default HTML documentation
• make -C doc/ lists more formats to build the documentation in (e.g., plain text, epub)

Build & Install Distributables

Building the source distribution (sdist) and wheel requires build. Installation requires pip.

• make dist builds both source distribution and wheel under dist/
• make install installs the built wheel with pip (forcefully replacing any previously installed version)

Cleanup

• make cleanpy removes Python compiled bytecode files (__pycache__)
• make cleancov removes collected coverage information and generated coverage report under htmlcov/
• make cleandist removes the distribution packages under dist/
• make cleandoc removes built documentation from doc/build/
• make cleandocgen removes auto-generated API reference pages from the documentation source
• make clean runs all of the above

Contributing

For bug reports and feature proposals use the GitHub Issues page.

You can also support this project by buying me a coffee.

License

Copyright © 2023 Andrei Tatar.

Code and tests licensed GPL-3.0-or-later.

Documentation (including this document) licensed CC-BY-SA-4.0.

Trivial miscellanea (Makefiles, .gitignores) licensed CC0-1.0.

This project is compliant with the REUSE specifications.