Introduction

Rustic is a fast and secure backup program. In the following sections, we will present typical workflows, starting with installing, preparing a new repository, and making the first backup.

Note: Parts of this documentation are shamelessly copied from the restic documentation and then adapted to rustic as most workflows work in rustic exactly like restic. See also the restic documentation for more information about restic.

Contact

You can ask questions in the Discussions or have a look at the FAQ.

Contact	Where?
Issue Tracker	GitHub Issues
Discord
Discussions	GitHub Discussions

Contributing

Thank you for your interest in contributing to the rustic ecosystem!

We appreciate your help in making this project better.

Table of Contents

• Code of Conduct
• How to Contribute
  • Reporting Bugs
  • Issue and Pull Request Labels
  • Suggesting Enhancements
  • Code Style and Formatting
  • Testing
  • Submitting Pull Requests
    • Rebasing and other workflows
• Development Setup
• License

Code of Conduct

Please review and abide by the general Rust Community Code of Conduct when contributing to this project. In the future, we might create our own Code of Conduct and supplement it at this location.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue on GitHub and provide as much detail as possible. Include steps to reproduce the bug and the expected behavior.

Issue and Pull Request labels

Our Issues and Pull Request labels follow the official Rust style:

A - Area
C - Category
D - Diagnostic
E - Call for participation
F - Feature
I - Issue e.g. I-crash
M - Meta
O - Operating systems
P - priorities e.g. P-{low, medium, high, critical}
PG - Project Group
perf - Performance
S - Status e.g. S-{blocked, experimental, inactive}
T - Team relevancy
WG - Working group

Suggesting Enhancements

If you have an idea for an enhancement or a new feature, we’d love to hear it! Open an issue on GitHub and describe your suggestion in detail.

Code Style and Formatting

We follow the Rust community’s best practices for code style and formatting. Before submitting code changes, please ensure your code adheres to these guidelines:

• Use rustfmt to format your code. You can run it with the following command:

  cargo fmt --all
  

• Use dprint to format text in markdown, toml, and json. You can install it with cargo install dprint/scoop install dprint and run it with the following command in the repository root:

  dprint fmt
  

• Use Clippy — a collection of lints to catch common mistakes. If you haven’t installed your Rust toolchain with rustup, please install Clippy first. Then run Clippy with the following command in the crate root:

  cargo clippy --all -- -D warnings
  

• Write clear and concise code with meaningful, self-describing variable and function names. This tells the reader what the code does.

• Write clear and consise comments to tell the reader why you chose to implement it that way and which problem it solves.

Testing

We value code quality and maintainability. If you are adding new features or making changes, please include relevant unit tests. Run the test suite with:

cargo test --workspace

or check the testing guide for more information which tools we provide for making developing rustic easier.

Make sure all tests pass before submitting your changes. PRs containing tests have a much higher probability of getting merged (fast).

We expect PRs especially ones that introduce new features to contain tests for the new code.

Besides that, we welcome PRs which increase the general test coverage of the project. You can check the testing guide for more information.

We appreciate tests in every form: be it unit, doc or integration tests (chose depending on your use case).

If you want to implement some fuzzing or benchmarking, that is also highly appreciated.

Submitting Pull Requests

To contribute code changes, follow these steps:

1. Fork the repository.

2. Create a new branch with a descriptive name:

   git checkout -b feature/your-feature-name
   

3. Check and Commit your changes:

   just pre-commit
   git commit -m "Add your meaningful commit message here"
   

4. Push your branch to your forked repository:

   git push origin feature/your-feature-name
   

5. Open a Pull Request (PR) to our repository. Please include a detailed description of the changes and reference any related issues.

Release early and often! also applies to pull requests

Consider drafting a Pull request early in the development process, so we can follow your progress and can give early feedback.

Once your PR is submitted, it will be reviewed by the maintainers. We may suggest changes or ask for clarifications before merging.

IMPORTANT NOTE

Please don’t force push commits in your branch, in order to keep commit history and make it easier for us to see changes between reviews.

Make sure to Allow edits of maintainers (under the text box) in the PR so people can actually collaborate on things or fix smaller issues themselves.

Rebasing and other workflows

(taken from: openage on rebasing)

Rebasing is ‘moving’ your commits to a different parent commit.

In other words: Cut off your branch from its tree, and attach it somewhere else.

There’s two main applications:

• If you based your work on a older main (so old that stuff can’t be automatically merged), you can rebase to move your commits to the current upstream main:

# update the upstream remote to receive new commits
git fetch upstream

# be on your feature branch (you probably are)
git checkout my-awesome-feature

# make backup (you never know, you know?)
git branch my-awesome-feature-backup

# rebase: put your commits on top of upstream's main
git rebase -m upstream/main

• If you want to fix an older commit of yours, or merge several commits into a single one (squash them), rebase interactively. We don’t want to have a commit history like this:

  • add stuff
  • fix typo in stuff
  • fix compilation
  • change stuff a bit
  • and so on…

rebase in practice

git log --graph --oneline shows your commit history as graph. To make some changes in that graph, you do an interactive rebase:

git rebase -i -m upstream/main

With this command, your new “base” is upstream/main and you can then change any of your branch’s commits.

-i will open an interactive editor where you can choose actions for each individual commit:

• re-order commits
• drop commits by deleting their line
• squash/fixup (“meld”) your commits
• reword a commit message
• stop rebasing at a commit to edit (--amend) it manually

Just follow the messages on screen.

Changing commits with amend and fixup

There’s also git commit --amend which is a “mini-rebase” that modifies just the last commit with your current changes by git add. It just skips the creation of a new commit and instead melds the changes into the last one you made.

If you want to update a single commit in the range [upstream/main, current HEAD] which is not the last commit:

• edit stuff you wanna change in some previous commit
• git add changed_stuff
• git commit --fixup $hash_of_commit_to_be_fixed
• git rebase --autosquash -i -m upstream/main

Pushing changes

After you have rebased stuff (“rewritten history”) that had already been pushed, git will not accept your pushes because they’re not simple fast-forwards:

• The commit contents and the parent commit have changed as you updated the commit, therefore the commit hash changed, too.

  • If somebody used those commits, they will keep a copy and have a hard time updating to your updated version (because they “use” the old hashes).
  • Update your pull request branch with your re-written history!

• force push is the standard way of overwriting your development work with the fixed and mergeable version of your contribution!

  • Why? You changed the commits, so you want the old ones to be deleted!

  You can use any of:

  • git push origin +my-awesome-feature
  • git push origin -f my-awesome-feature
  • git push origin --force my-awesome-feature

Some extra tutorials on git rebase:

• Atlassian’s Git Tutorial
• Pro Git book
• man git-rebase

Development Setup

If you want to set up a local development environment, follow the steps in the development guide file - which is currently being worked on.

License

By contributing to rustic or any crates contained in this repository, you agree that your contributions will be licensed under:

• Apache License, Version 2.0
• MIT license.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Frequently asked technical questions

Memory Requirements

Question: You mention a “huge decrease in memory requirement”; are you streaming blobs to the data store without keeping them in memory and just keeping the hashes in memory? How does the memory footprint look like?

The largest memory consuming part is the index which is kept in-memory by restic and rustic. For restic, however, the index took about 3-4 times the theoretical size - maybe due to Golangs garbage collector additions or other Golang-specific stuff.

In rustic, there are two basic improvements:

• the memory consumption is exactly as expected as Rust allows to directly define the in-memory structures

• For some operations, not all index information is needed. Rustic allows several kinds of index types to be loaded into memory (only trees, only ids, full index) and uses only the type needed for a given command. For instance with backup you need the list of all present blob IDs, but not the position within the repository - rustic thus only saves the IDs in memory for the backup command and therefore uses less memory.

Installation

• Official Binaries
  • Stable Releases
  • Unstable Builds
• From Source

Official Binaries

Stable Releases

cargo-binstall

cargo binstall rustic-rs

Windows

Scoop

scoop install rustic

You can download the latest stable release versions of rustic from the rustic release page. These builds are considered stable and releases are made regularly in a controlled manner.

There’s both pre-compiled binaries for different platforms as well as the source code available for download. Just download and run the one matching your system.

Once downloaded, the official binaries can be updated in place using the rustic self-update command (needs rustic 0.3.1 or later):

$ rustic  self-update
Checking target-arch... x86_64-unknown-linux-musl
Checking current version... v0.3.0-dev
Checking latest released version... v0.3.1
New release found! v0.3.0-dev --> v0.3.1
New release is *NOT* compatible

rustic release status:
    * Current exe: "/usr/local/bin/rustic"
    * New exe release: "rustic-v0.3.1-x86_64-unknown-linux-musl.tar.gz"
    * New exe download url: "https://api.github.com/repos/rustic/rustic/releases/assets/75146490"

The new release will be downloaded/extracted and the existing binary will be replaced.
Do you want to continue? [Y/n] Y
Downloading...
[00:00:00] [========================================] 4.29MiB/4.29MiB (0s) Done
Extracting archive... Done
Replacing binary file... Done
Update status: `0.3.1`!

Note: Please be aware that the user executing the rustic self-update command must have the permission to replace the rustic binary.

Unstable Builds

Another option is to use the nightly builds for the main branch, available on the nightly download page. These too are pre-compiled and ready to run, and a new version is built every night from the main branch of various repositories.

From Source

Beware: This installs the latest development version, which might be unstable.

rustic is written in Rust and you need a current Rust version.

In order to build rustic from source, execute the following steps:

Github

cargo install --git https://github.com/rustic-rs/rustic.git rustic-rs

crates.io

You can also directly install the latest crate from crates.io.

cargo install rustic-rs

Cross-compile

You can easily cross-compile rustic for all supported platforms, make sure that the cross-compile toolchain is installed for your target. Then run the build for your chosen target like this

cargo build --target aarch64-unknown-linux-gnu --release

Nightly builds

Nightly builds of rustic’s, rustic_server’s, and rustic_scheduler’s main branch are available here for download.

WARNING: These builds are not guaranteed to be stable, and may contain bugs. Use at your own risk.

Verification

Minisign/Rsign2

Install

• rsign2 with cargo install rsign2 or
• minisign with scoop install minisign (on Windows, check other installation instructions here).

Run

rsign verify <filename>.tar.gz \
  -x <filename>.tar.gz.sig \
  -P RWSWSCEJEEacVeCy0va71hlrVtiW8YzMzOyJeso0Bfy/ZXq5OryWi/8T

PGP

Download our public key or copy and paste it from below:

wget https://github.com/rustic-rs/nightly/raw/main/pub/pgp.pub

Check the fingerprint:

12B7166D9FD59124416952E34018C5DE3BF8C081

against the output of: gpg --show-keys <PUBLIC_KEY_FILE>

Import the key with gpg --import <PUBLIC_KEY_FILE>

Verify the signature with gpg --verify <filename>.tar.gz.asc <filename>.tar.gz

The output should say “Good Signature”.

Note: We use the .asc extension for the files because .sig was already taken for supporting minisign used by cargo-binstall.

Status

Download matrix