0
# BorgBackup
1

2
BorgBackup is a deduplicating backup program that provides efficient and secure data backup through content-defined chunking deduplication, authenticated encryption (AES-256 with HMAC-SHA256), and multiple compression algorithms. It supports both local and remote backups over SSH with mountable backup archives as filesystems for easy restore operations.
3

4
## Package Information
5

6
- **Package Name**: borgbackup
7
- **Package Type**: pypi
8
- **Language**: Python (with C/Cython extensions)
9
- **Installation**: `pip install borgbackup`
10

11
## Core Imports
12

13
For JSON API programming:
14
```python
15
import subprocess
16
import json
17
```
18

19
For internal API access (not recommended, unstable):
20
```python
21
import borg
22
from borg.archiver import main
23
from borg.repository import Repository
24
from borg.archive import Archive
25
```
26

27
## Basic Usage
28

29
### Command-Line Interface with JSON Output (Recommended)
30

31
```python
32
import subprocess
33
import json
34

35
# List archives with JSON output
36
result = subprocess.run(['borg', 'list', '--json', '/path/to/repo'], 
37
                       capture_output=True, text=True, check=True)
38
archives = json.loads(result.stdout)
39

40
# Get archive info
41
result = subprocess.run(['borg', 'info', '--json', '/path/to/repo::archive-name'], 
42
                       capture_output=True, text=True, check=True)
43
archive_info = json.loads(result.stdout)
44

45
# Create archive with JSON stats (--json implies --stats)
46
result = subprocess.run(['borg', 'create', '--json', 
47
                        '/path/to/repo::archive-{now}', '/home/user/documents'], 
48
                       capture_output=True, text=True, check=True)
49
create_stats = json.loads(result.stdout)
50

51
# List archive contents with JSON Lines output
52
result = subprocess.run(['borg', 'list', '--json-lines', '/path/to/repo::archive-name'], 
53
                       capture_output=True, text=True, check=True)
54
files = [json.loads(line) for line in result.stdout.strip().split('\n') if line]
55
```
56

57
**Note**: JSON support is selective in BorgBackup. Commands with `--json` support: create, info, list (repositories), recreate, import-tar. Commands with `--json-lines` support: diff, list (archive contents).
58

59
### Repository Initialization
60

61
```bash
62
# Initialize encrypted repository
63
borg init --encryption=repokey /path/to/repo
64

65
# Initialize with passphrase encryption
66
borg init --encryption=keyfile /path/to/repo
67
```
68

69
## Architecture
70

71
BorgBackup's architecture consists of several key components:
72

73
- **Repository**: Storage backend managing segments, manifest, and metadata
74
- **Archives**: Individual backup snapshots with deduplication across time
75
- **Chunks**: Content-defined variable-size data blocks for deduplication
76
- **Cache**: Local metadata cache for performance optimization
77
- **Encryption**: AES-256 encryption with HMAC-SHA256 authentication
78

79
The tool uses content-defined chunking for cross-file and cross-archive deduplication, making it highly space-efficient for incremental backups.
80

81
## Capabilities
82

83
### Repository Operations
84

85
Repository initialization, configuration, and maintenance operations including creation, checking, and upgrades.
86

87
```python { .api }
88
# Repository initialization
89
subprocess.run(['borg', 'init', '--encryption=repokey', repository_path])
90

91
# Repository info
92
result = subprocess.run(['borg', 'info', '--json', repository_path], 
93
                       capture_output=True, text=True, check=True)
94

95
# Repository check
96
subprocess.run(['borg', 'check', repository_path])
97
```
98

99
[Repository Management](./repository.md)
100

101
### Archive Operations
102

103
Archive creation, extraction, listing, and deletion operations for managing backup snapshots.
104

105
```python { .api }
106
# Create archive
107
subprocess.run(['borg', 'create', '--json',
108
               f'{repository_path}::{archive_name}', *source_paths])
109

110
# List archives
111
result = subprocess.run(['borg', 'list', '--json', repository_path],
112
                       capture_output=True, text=True, check=True)
113

114
# Extract archive
115
subprocess.run(['borg', 'extract', f'{repository_path}::{archive_name}'])
116
```
117

118
[Archive Operations](./archives.md)
119

120
### Pruning and Maintenance
121

122
Archive pruning, repository maintenance, and cleanup operations for managing backup retention policies.
123

124
```python { .api }
125
# Prune archives by retention policy
126
subprocess.run(['borg', 'prune', '--keep-daily=7', '--keep-weekly=4', 
127
               '--keep-monthly=6', repository_path])
128

129
# Compact repository
130
subprocess.run(['borg', 'compact', repository_path])
131
```
132

133
[Pruning and Maintenance](./maintenance.md)
134

135
### Mount and Access
136

137
Mounting archives as filesystems for browsing and selective file restoration.
138

139
```python { .api }
140
# Mount archive as filesystem
141
subprocess.run(['borg', 'mount', f'{repository_path}::{archive_name}', mount_point])
142

143
# Unmount
144
subprocess.run(['borgfs', 'umount', mount_point])
145
```
146

147
[Mount and Access](./mount.md)
148

149
### Utility Operations
150

151
Version information, help system, benchmarking, and advanced lock management for BorgBackup operations.
152

153
```python { .api }
154
# Get version information
155
result = subprocess.run(['borg', 'version'], capture_output=True, text=True, check=True)
156

157
# Benchmark performance
158
subprocess.run(['borg', 'benchmark', 'crud', repository_path, '/tmp/benchmark'])
159

160
# Run command with repository lock
161
subprocess.run(['borg', 'with-lock', repository_path, 'custom-command'])
162
```
163

164
[Utility Operations](./utilities.md)
165

166
## Types
167

168
```python { .api }
169
class RepositoryInfo:
170
    """Repository information structure"""
171
    def __init__(self):
172
        self.cache: dict
173
        self.security_dir: str
174
        self.repository: dict  # Contains id, last_modified, location
175
        self.encryption: dict  # Contains mode, keyfile
176
        
177
class ArchiveInfo:
178
    """Archive information structure"""
179
    def __init__(self):
180
        self.name: str
181
        self.id: str
182
        self.start: str  # ISO timestamp
183
        self.end: str    # ISO timestamp
184
        self.duration: float
185
        self.stats: dict  # Contains original_size, compressed_size, deduplicated_size
186
        
187
class CreateResult:
188
    """Result of archive creation"""
189
    def __init__(self):
190
        self.archive: dict      # Archive metadata
191
        self.repository: dict   # Repository state
192
        self.cache: dict       # Cache statistics
193
```
194

195
## Error Handling
196

197
BorgBackup uses exit codes for error signaling:
198

199
- **0**: Success
200
- **1**: Warning (operation succeeded, but there were warnings)
201
- **2**: Error (operation failed)
202
- **128+N**: Killed by signal N
203

204
Common exceptions when using subprocess:
205
- `subprocess.CalledProcessError`: Command execution failed
206
- `json.JSONDecodeError`: Invalid JSON response
207
- `FileNotFoundError`: Borg executable not found