0
# Repository Management
1
2
Repository initialization, configuration, and maintenance operations for managing BorgBackup repositories.
3
4
```python
5
import subprocess
6
import json
7
```
8
9
## Capabilities
10
11
### Repository Initialization
12
13
Initialize a new BorgBackup repository with specified encryption method.
14
15
```python { .api }
16
def init_repository(repo_path: str, encryption: str = 'repokey', **options) -> None:
17
"""
18
Initialize a new repository.
19
20
Args:
21
repo_path: Path to repository location
22
encryption: Encryption mode ('none', 'keyfile', 'repokey', 'keyfile-blake2', 'repokey-blake2', 'authenticated', 'authenticated-blake2')
23
**options: Additional options like append_only, storage_quota
24
"""
25
cmd = ['borg', 'init', f'--encryption={encryption}']
26
if options.get('append_only'):
27
cmd.append('--append-only')
28
if options.get('storage_quota'):
29
cmd.extend(['--storage-quota', str(options['storage_quota'])])
30
cmd.append(repo_path)
31
subprocess.run(cmd, check=True)
32
```
33
34
Usage example:
35
```python
36
import subprocess
37
38
# Initialize with repokey encryption
39
subprocess.run(['borg', 'init', '--encryption=repokey', '/backup/repo'], check=True)
40
41
# Initialize append-only repository
42
subprocess.run(['borg', 'init', '--encryption=repokey', '--append-only', '/backup/repo'], check=True)
43
44
# Initialize with storage quota (in bytes)
45
subprocess.run(['borg', 'init', '--encryption=repokey', '--storage-quota=10G', '/backup/repo'], check=True)
46
```
47
48
### Repository Information
49
50
Get comprehensive information about a repository including encryption, cache, and statistics.
51
52
```python { .api }
53
def get_repository_info(repo_path: str, json_output: bool = True) -> dict:
54
"""
55
Get repository information.
56
57
Args:
58
repo_path: Path to repository
59
json_output: Return structured JSON data
60
61
Returns:
62
Dictionary containing repository metadata, cache info, and encryption details
63
"""
64
cmd = ['borg', 'info', repo_path]
65
if json_output:
66
cmd.append('--json')
67
result = subprocess.run(cmd, capture_output=True, text=True, check=True)
68
return json.loads(result.stdout) if json_output else result.stdout
69
```
70
71
Usage example:
72
```python
73
import subprocess
74
import json
75
76
# Get repository info as JSON
77
result = subprocess.run(['borg', 'info', '--json', '/backup/repo'],
78
capture_output=True, text=True, check=True)
79
repo_info = json.loads(result.stdout)
80
81
print(f"Repository ID: {repo_info['repository']['id']}")
82
print(f"Encryption: {repo_info['encryption']['mode']}")
83
print(f"Location: {repo_info['repository']['location']}")
84
```
85
86
### Repository Verification
87
88
Check repository consistency and detect corruption.
89
90
```python { .api }
91
def check_repository(repo_path: str, verify_data: bool = False, repair: bool = False) -> None:
92
"""
93
Verify repository consistency.
94
95
Args:
96
repo_path: Path to repository
97
verify_data: Verify data integrity (slower)
98
repair: Attempt to repair inconsistencies
99
"""
100
cmd = ['borg', 'check']
101
if verify_data:
102
cmd.append('--verify-data')
103
if repair:
104
cmd.append('--repair')
105
cmd.append(repo_path)
106
subprocess.run(cmd, check=True)
107
```
108
109
Usage example:
110
```python
111
import subprocess
112
113
# Basic repository check
114
subprocess.run(['borg', 'check', '/backup/repo'], check=True)
115
116
# Check with data verification (slower but more thorough)
117
subprocess.run(['borg', 'check', '--verify-data', '/backup/repo'], check=True)
118
119
# Check and attempt repairs
120
subprocess.run(['borg', 'check', '--repair', '/backup/repo'], check=True)
121
```
122
123
### Repository Configuration
124
125
Manage repository configuration and settings.
126
127
```python { .api }
128
def configure_repository(repo_path: str, **config_options) -> None:
129
"""
130
Configure repository settings.
131
132
Args:
133
repo_path: Path to repository
134
**config_options: Configuration options to set
135
"""
136
for key, value in config_options.items():
137
cmd = ['borg', 'config', repo_path, key, str(value)]
138
subprocess.run(cmd, check=True)
139
140
def get_repository_config(repo_path: str, key: str = None) -> str:
141
"""
142
Get repository configuration value.
143
144
Args:
145
repo_path: Path to repository
146
key: Specific configuration key (optional)
147
148
Returns:
149
Configuration value or all configuration if key not specified
150
"""
151
cmd = ['borg', 'config', repo_path]
152
if key:
153
cmd.append(key)
154
result = subprocess.run(cmd, capture_output=True, text=True, check=True)
155
return result.stdout.strip()
156
```
157
158
Usage example:
159
```python
160
import subprocess
161
162
# Set repository configuration
163
subprocess.run(['borg', 'config', '/backup/repo', 'additional_free_space', '2G'], check=True)
164
165
# Get configuration value
166
result = subprocess.run(['borg', 'config', '/backup/repo', 'additional_free_space'],
167
capture_output=True, text=True, check=True)
168
free_space = result.stdout.strip()
169
```
170
171
### Repository Key Management
172
173
Manage repository encryption keys including export, import, and change operations.
174
175
```python { .api }
176
def export_key(repo_path: str, output_file: str, paper: bool = False) -> None:
177
"""
178
Export repository key.
179
180
Args:
181
repo_path: Path to repository
182
output_file: Path to output key file
183
paper: Export in paper format for printing
184
"""
185
cmd = ['borg', 'key', 'export']
186
if paper:
187
cmd.append('--paper')
188
cmd.extend([repo_path, output_file])
189
subprocess.run(cmd, check=True)
190
191
def import_key(repo_path: str, key_file: str, paper: bool = False) -> None:
192
"""
193
Import repository key.
194
195
Args:
196
repo_path: Path to repository
197
key_file: Path to key file
198
paper: Import from paper format
199
"""
200
cmd = ['borg', 'key', 'import']
201
if paper:
202
cmd.append('--paper')
203
cmd.extend([repo_path, key_file])
204
subprocess.run(cmd, check=True)
205
206
def change_passphrase(repo_path: str) -> None:
207
"""
208
Change repository passphrase.
209
210
Args:
211
repo_path: Path to repository
212
"""
213
cmd = ['borg', 'key', 'change-passphrase', repo_path]
214
subprocess.run(cmd, check=True)
215
216
def migrate_to_repokey(repo_path: str) -> None:
217
"""
218
Migrate passphrase-mode repository to repokey.
219
220
Args:
221
repo_path: Path to repository
222
"""
223
cmd = ['borg', 'key', 'migrate-to-repokey', repo_path]
224
subprocess.run(cmd, check=True)
225
```
226
227
Usage example:
228
```python
229
import subprocess
230
231
# Export key to file
232
subprocess.run(['borg', 'key', 'export', '/backup/repo', '/secure/backup-key.txt'], check=True)
233
234
# Export key in paper format
235
subprocess.run(['borg', 'key', 'export', '--paper', '/backup/repo', '/secure/backup-key-paper.txt'], check=True)
236
237
# Import key from file
238
subprocess.run(['borg', 'key', 'import', '/backup/repo', '/secure/backup-key.txt'], check=True)
239
240
# Change repository passphrase
241
subprocess.run(['borg', 'key', 'change-passphrase', '/backup/repo'], check=True)
242
243
# Migrate from keyfile to repokey mode
244
subprocess.run(['borg', 'key', 'migrate-to-repokey', '/backup/repo'], check=True)
245
```
246
247
## Types
248
249
```python { .api }
250
class RepositoryConfig:
251
"""Repository configuration structure"""
252
def __init__(self):
253
self.additional_free_space: str # Additional free space to maintain
254
self.append_only: bool # Append-only mode
255
self.storage_quota: str # Storage quota limit
256
257
class EncryptionInfo:
258
"""Repository encryption information"""
259
def __init__(self):
260
self.mode: str # Encryption mode
261
self.keyfile: str # Path to keyfile (if applicable)
262
263
class RepositoryStats:
264
"""Repository statistics"""
265
def __init__(self):
266
self.total_chunks: int
267
self.total_csize: int # Compressed size
268
self.total_size: int # Original size
269
self.total_unique_chunks: int
270
self.unique_csize: int # Unique compressed size
271
self.unique_size: int # Unique original size
272
```