0
# Revision Management
1

2
Version control functionality for managing different revisions of deployed projects, enabling rollbacks, staged deployments, and revision history management.
3

4
## Capabilities
5

6
### Rollback
7

8
Revert a project to the previous revision.
9

10
```javascript { .api }
11
/**
12
 * Revert project to previous revision
13
 * @param hooks - Optional lifecycle hooks
14
 * @returns Command function
15
 */
16
function rollback(hooks?: HookConfig): CommandFunction;
17
```
18

19
**CLI Usage:**
20
```bash
21
# Rollback interactive domain selection
22
surge rollback
23

24
# Rollback specific domain
25
surge rollback example.surge.sh
26
```
27

28
Reverts the live project to the previously deployed revision. Useful for quickly undoing problematic deployments.
29

30
**Library Usage:**
31
```javascript
32
surge.rollback({})(process.argv.slice(2));
33
```
34

35
### Roll Forward
36

37
Advance a project to the next revision (opposite of rollback).
38

39
```javascript { .api }
40
/**
41
 * Advance project to next revision
42
 * @param hooks - Optional lifecycle hooks
43
 * @returns Command function
44
 */
45
function rollfore(hooks?: HookConfig): CommandFunction;
46
```
47

48
**CLI Usage:**
49
```bash
50
# Roll forward interactive domain selection
51
surge rollfore
52

53
# Roll forward specific domain
54
surge rollfore example.surge.sh
55
```
56

57
Moves the live project forward to the next available revision in history.
58

59
**Library Usage:**
60
```javascript
61
surge.rollfore({})(process.argv.slice(2));
62
```
63

64
### Cutover
65

66
Switch to the latest revision of a project.
67

68
```javascript { .api }
69
/**
70
 * Switch project to latest revision
71
 * @param hooks - Optional lifecycle hooks
72
 * @returns Command function
73
 */
74
function cutover(hooks?: HookConfig): CommandFunction;
75
```
76

77
**CLI Usage:**
78
```bash
79
# Cutover interactive domain selection
80
surge cutover
81

82
# Cutover specific domain
83
surge cutover example.surge.sh
84
```
85

86
Switches the live project to the most recent revision, effectively "catching up" if the project is behind.
87

88
**Library Usage:**
89
```javascript
90
surge.cutover({})(process.argv.slice(2));
91
```
92

93
### Discard Revision
94

95
Remove a specific revision from the system permanently.
96

97
```javascript { .api }
98
/**
99
 * Remove revision from system permanently
100
 * @param hooks - Optional lifecycle hooks
101
 * @returns Command function
102
 */
103
function discard(hooks?: HookConfig): CommandFunction;
104
```
105

106
**CLI Usage:**
107
```bash
108
# Discard with interactive selection
109
surge discard
110

111
# Discard from specific domain
112
surge discard example.surge.sh
113
```
114

115
Permanently removes a revision from the system. This action cannot be undone.
116

117
**Library Usage:**
118
```javascript
119
surge.discard({})(process.argv.slice(2));
120
```
121

122
### Select Revision
123

124
Select a specific revision to make it the active deployment.
125

126
```javascript { .api }
127
/**
128
 * Select specific revision as active deployment
129
 * @param hooks - Optional lifecycle hooks
130
 * @returns Command function
131
 */
132
function select(hooks?: HookConfig): CommandFunction;
133
```
134

135
**CLI Usage:**
136
```bash
137
# Select with interactive menu
138
surge select
139

140
# Select from specific domain
141
surge select example.surge.sh
142
```
143

144
Presents an interactive menu of available revisions and allows selection of which one should be live.
145

146
**Library Usage:**
147
```javascript
148
surge.select({})(process.argv.slice(2));
149
```
150

151
## Revision System
152

153
### How Revisions Work
154

155
- Each `surge publish` creates a new revision
156
- Revisions are immutable once created
157
- Live traffic always serves from the "active" revision
158
- Multiple revisions can exist simultaneously
159
- Revisions include full file snapshots
160

161
### Revision Metadata
162

163
Each revision contains:
164
- **Timestamp**: When the revision was created
165
- **File Count**: Number of files in the revision
166
- **Total Size**: Combined size of all files
167
- **Commit Message**: Optional message for the revision
168
- **User**: Who created the revision
169

170
### Revision Limits
171

172
- Number of stored revisions varies by plan
173
- Older revisions are automatically pruned
174
- Critical revisions can be marked for retention
175

176
## Deployment Strategies
177

178
### Blue-Green Deployments
179

180
Use revisions to implement blue-green deployment patterns:
181

182
1. Deploy new version (creates new revision)
183
2. Test new revision on staging domain
184
3. Use `cutover` to switch live traffic
185
4. Keep previous revision as rollback option
186

187
### Staged Rollouts
188

189
Deploy with preview mode, then promote:
190

191
```bash
192
# Deploy to preview
193
surge --preview ./build preview.example.surge.sh
194

195
# After testing, deploy to production
196
surge ./build example.surge.sh
197

198
# If issues arise, rollback
199
surge rollback example.surge.sh
200
```
201

202
### Canary Releases
203

204
Combine revision management with traffic splitting:
205

206
1. Deploy new revision
207
2. Route small percentage of traffic to new revision
208
3. Monitor metrics and errors
209
4. Gradually increase traffic or rollback if issues
210

211
## Revision CLI Options
212

213
### Message Annotation
214

215
Add descriptive messages to revisions:
216

217
```bash
218
surge --message "Fix navigation bug" ./build example.surge.sh
219
```
220

221
The message helps identify revisions in the revision history.
222

223
### Staging Environments
224

225
Use preview mode for testing revisions:
226

227
```bash
228
# Deploy to staging first
229
surge --stage ./build staging.example.surge.sh
230

231
# After verification, deploy to production
232
surge ./build example.surge.sh
233
```
234

235
## Integration with Version Control
236

237
### Git Integration
238

239
Sync revisions with git commits:
240

241
```bash
242
# Use git commit message for revision
243
COMMIT_MSG=$(git log -1 --pretty=%B)
244
surge --message "$COMMIT_MSG" ./build example.surge.sh
245
```
246

247
### Automated Deployment
248

249
Integrate revision management in CI/CD:
250

251
```yaml
252
# GitHub Actions example
253
- name: Deploy to staging
254
  run: surge --stage ./build staging.example.surge.sh
255
  
256
- name: Run tests against staging
257
  run: npm run test:e2e
258
  
259
- name: Deploy to production
260
  run: surge ./build example.surge.sh
261
  if: success()
262
  
263
- name: Rollback on failure
264
  run: surge rollback example.surge.sh
265
  if: failure()
266
```
267

268
## Monitoring Revisions
269

270
### Revision History
271

272
Use `surge list` to view revision history:
273

274
```bash
275
surge list example.surge.sh
276
```
277

278
Shows table with:
279
- Revision timestamps
280
- File counts and sizes
281
- Active revision indicator
282
- Revision messages
283

284
### Tracking Changes
285

286
Monitor revision changes:
287
- File additions/deletions
288
- Size changes
289
- Deployment frequency
290
- Rollback frequency
291

292
## Error Handling
293

294
### Revision Management Errors
295

296
- **No Revisions Available**: Project has no deployment history
297
- **Revision Not Found**: Specified revision doesn't exist
298
- **Active Revision**: Cannot discard currently active revision
299
- **Permission Denied**: User lacks revision management permissions
300

301
All revision commands provide clear error messages and suggested actions.