The Repository struct is the central type in rustic_core for interacting with backup repositories. It manages the backend storage, encryption keys, and repository state.
Overview
A repository can be in different states, each allowing specific operations:
- Uninitialized (
Repository<()>) - Newly created, not yet opened
- Open (
Repository<OpenStatus>) - Password verified, ready for basic operations
- IndexedIds (
Repository<IndexedIdsStatus>) - Indexed for backup operations
- IndexedFull (
Repository<IndexedFullStatus>) - Fully indexed for all operations
- IndexedTree (
Repository<IndexedTreeStatus>) - Tree-only index for memory efficiency
Type Definition
pub struct Repository<S> {
pub name: String,
// Internal fields
}
The name/location identifier of the repository
Generic type parameter representing the repository’s current state
Creating a Repository
new
Create a new repository instance without progress bars.
pub fn new(
opts: &RepositoryOptions,
backends: &RepositoryBackends
) -> RusticResult<Repository<()>>
opts
&RepositoryOptions
required
Configuration options for the repository
backends
&RepositoryBackends
required
Backend storage configuration (local, REST, S3, etc.)
use rustic_core::{Repository, RepositoryOptions};
use rustic_backend::BackendOptions;
let backends = BackendOptions::default()
.repository("/tmp/repo")
.to_backends()?;
let repo = Repository::new(&RepositoryOptions::default(), &backends)?;
new_with_progress
Create a new repository with custom progress bars.
pub fn new_with_progress<P: ProgressBars>(
opts: &RepositoryOptions,
backends: &RepositoryBackends,
pb: P
) -> RusticResult<Repository<()>>
Progress bar implementation for operation feedback
Initializing a Repository
init
Initialize a new repository with credentials and configuration.
pub fn init(
self,
credentials: &Credentials,
key_opts: &KeyOptions,
config_opts: &ConfigOptions
) -> RusticResult<Repository<OpenStatus>>
Password or master key for repository encryption
Key generation options (encryption parameters)
Repository configuration (version, compression, chunking)
use rustic_core::{
Repository, RepositoryOptions, Credentials,
KeyOptions, ConfigOptions, repofile::MasterKey
};
let repo = Repository::new(&RepositoryOptions::default(), &backends)?;
let repo = repo.init(
&Credentials::Masterkey(MasterKey::new()),
&KeyOptions::default(),
&ConfigOptions::default()
)?;
init_with_config
Initialize with a pre-configured ConfigFile.
pub fn init_with_config(
self,
credentials: &Credentials,
key_opts: &KeyOptions,
config: ConfigFile
) -> RusticResult<Repository<OpenStatus>>
Opening a Repository
open
Open an existing repository with credentials.
pub fn open(
self,
credentials: &Credentials
) -> RusticResult<Repository<OpenStatus>>
let credentials = Credentials::password("my-password");
let repo = Repository::new(&repo_opts, &backends)?
.open(&credentials)?;
open_only_cold
Open using only the cold (main) repository, ignoring hot storage.
pub fn open_only_cold(
self,
credentials: &Credentials
) -> RusticResult<Repository<OpenStatus>>
State Transitions
to_indexed
Transition to fully indexed state for all operations.
pub fn to_indexed(self) -> RusticResult<Repository<IndexedFullStatus>>
to_indexed_ids
Transition to ID-only indexed state for backup operations.
pub fn to_indexed_ids(self) -> RusticResult<Repository<IndexedIdsStatus>>
let repo = Repository::new(&repo_opts, &backends)?
.open(&credentials)?
.to_indexed_ids()?;
// Now ready for backup operations
let snap = repo.backup(&backup_opts, &source, snap)?;
to_indexed_checked
Transition to indexed state with pack file verification.
pub fn to_indexed_checked(self) -> RusticResult<Repository<IndexedFullStatus>>
drop_index
Drop the index and return to Open state.
pub fn drop_index(self) -> Repository<OpenStatus>
Repository Operations
Snapshots
get_all_snapshots
pub fn get_all_snapshots(&self) -> RusticResult<Vec<SnapshotFile>>
get_snapshot_from_str
pub fn get_snapshot_from_str(
&self,
id: &str,
filter: impl FnMut(&SnapshotFile) -> bool + Send + Sync
) -> RusticResult<SnapshotFile>
Snapshot ID, “latest”, or “latest~N” for Nth latest snapshot
Function to filter snapshots (e.g., by host, tags, paths)
delete_snapshots
pub fn delete_snapshots(&self, ids: &[SnapshotId]) -> RusticResult<()>
Maintenance
check
Verify repository integrity.
pub fn check(&self, opts: CheckOptions) -> RusticResult<CheckResults>
prune_plan
Generate a pruning plan.
pub fn prune_plan(&self, opts: &PruneOptions) -> RusticResult<PrunePlan>
prune
Execute repository pruning.
pub fn prune(
&self,
opts: &PruneOptions,
prune_plan: PrunePlan
) -> RusticResult<()>
Configuration
config
Get the repository configuration.
pub fn config(&self) -> &ConfigFile
apply_config
Update repository configuration.
pub fn apply_config(&mut self, opts: &ConfigOptions) -> RusticResult<bool>
Keys
add_key
Add a new access key to the repository.
pub fn add_key(&self, pass: &str, opts: &KeyOptions) -> RusticResult<KeyId>
delete_key
Remove an access key (cannot remove the currently used key).
pub fn delete_key(&self, id: &KeyId) -> RusticResult<()>
key_id
Get the ID of the currently used key.
pub fn key_id(&self) -> &Option<KeyId>
Trees and Files
get_tree
Retrieve a tree by ID.
pub fn get_tree(&self, id: &TreeId) -> RusticResult<Tree>
IndexedTree state and above.
node_from_path
Get a node from a tree and path.
pub fn node_from_path(
&self,
root_tree: TreeId,
path: &Path
) -> RusticResult<Node>
node_from_snapshot_path
Get a node using “SNAP[:PATH]” syntax.
pub fn node_from_snapshot_path(
&self,
snap_path: &str,
filter: impl FnMut(&SnapshotFile) -> bool + Send + Sync
) -> RusticResult<Node>
// Get a specific file from a snapshot
let node = repo.node_from_snapshot_path(
"latest:/path/to/file.txt",
|_| true
)?;
open_file
Open a file for reading (requires IndexedFull state).
pub fn open_file(&self, node: &Node) -> RusticResult<OpenFile>
read_file_at
Read file contents at a specific offset.
pub fn read_file_at(
&self,
open_file: &OpenFile,
offset: usize,
length: usize
) -> RusticResult<Bytes>
Progress Tracking
pub fn progress_counter(&self, prefix: &str) -> Progress
pub fn progress_bytes(&self, prefix: &str) -> Progress
pub fn progress_spinner(&self, prefix: &str) -> Progress
pub fn progress_hidden(&self) -> Progress
Repair Operations
repair_index
pub fn repair_index(
&self,
opts: &RepairIndexOptions,
dry_run: bool
) -> RusticResult<()>
repair_hotcold_packs
pub fn repair_hotcold_packs(&self, dry_run: bool) -> RusticResult<()>
Complete Example
use rustic_backend::BackendOptions;
use rustic_core::{
Repository, RepositoryOptions, Credentials,
BackupOptions, PathList, SnapshotOptions
};
// Set up backend
let backends = BackendOptions::default()
.repository("/tmp/repo")
.to_backends()?;
// Open repository
let repo = Repository::new(&RepositoryOptions::default(), &backends)?
.open(&Credentials::password("my-password"))?
.to_indexed_ids()?;
// Perform backup
let source = PathList::from_string(".")?.sanitize()?;
let snap = SnapshotOptions::default()
.add_tags("daily,important")?
.to_snapshot()?;
let snapshot = repo.backup(&BackupOptions::default(), &source, snap)?;
println!("Created snapshot: {}", snapshot.id);
// Check repository
let results = repo.drop_index()
.to_indexed()?
.check(CheckOptions::default())?;
println!("Check complete: {:?}", results);
See Also
