0
# Rebase Operations
1

2
Advanced patch sequence management for reordering, editing, and managing complex patch workflows. The rebase functionality enables developers to modify patch history, insert changes at specific points, and manage complex patch sequences with confidence.
3

4
## Capabilities
5

6
### Main Rebase Function
7

8
Core function for rebasing patch sequences to different targets.
9

10
```typescript { .api }
11
/**
12
 * Rebase patches to a specific target in the sequence
13
 * @param options - Rebase configuration options
14
 */
15
function rebase(options: RebaseOptions): void;
16

17
interface RebaseOptions {
18
  /** Application root path */
19
  appPath: string;
20
  /** Directory containing patch files */
21
  patchDir: string;
22
  /** Package path specifier to rebase */
23
  packagePathSpecifier: string;
24
  /** Target patch identifier (file name, number, name, or "0") */
25
  targetPatch: string;
26
}
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import { rebase } from "patch-package/dist/rebase";
33
import { getAppRootPath } from "patch-package/dist/getAppRootPath";
34

35
// Rebase to specific patch file
36
rebase({
37
  appPath: getAppRootPath(),
38
  patchDir: "patches",
39
  packagePathSpecifier: "lodash",
40
  targetPatch: "lodash+4.17.21.patch"
41
});
42

43
// Rebase to sequence number
44
rebase({
45
  appPath: process.cwd(),
46
  patchDir: "patches", 
47
  packagePathSpecifier: "react",
48
  targetPatch: "3"
49
});
50

51
// Reset to beginning (un-apply all patches)
52
rebase({
53
  appPath: process.cwd(),
54
  patchDir: "patches",
55
  packagePathSpecifier: "lodash", 
56
  targetPatch: "0"
57
});
58
```
59

60
## Rebase Target Types
61

62
### Patch File Names
63

64
Target a specific patch file by its exact filename.
65

66
```bash
67
patch-package --rebase "lodash+4.17.21.patch" lodash
68
```
69

70
### Sequence Numbers
71

72
Target patches by their position in the sequence (1-based indexing).
73

74
```bash
75
patch-package --rebase "3" lodash
76
```
77

78
### Sequence Names
79

80
Target patches by their descriptive names (if using named sequences).
81

82
```bash
83
patch-package --rebase "security-fix" lodash
84
```
85

86
### Reset to Beginning
87

88
Use "0" to un-apply all patches and start fresh.
89

90
```bash
91
patch-package --rebase "0" lodash
92
```
93

94
## Rebase Workflow
95

96
### 1. State Validation
97

98
Before rebasing, patch-package validates:
99
- All current patches are properly applied
100
- State file integrity matches actual patches
101
- No existing rebase operation is in progress
102

103
### 2. Un-apply Patches
104

105
Patches after the target are reversed in order:
106
1. Last patch applied is removed first
107
2. Each patch is verified before reversal
108
3. State is updated after each successful removal
109

110
### 3. Rebasing State
111

112
The package enters "rebasing" state where:
113
- Normal patch application is blocked
114
- Only patch creation/modification is allowed
115
- State file tracks the rebase progress
116

117
### 4. Making Changes
118

119
During rebase, you can:
120
- Modify files in the package directory
121
- Use standard patch creation commands
122
- Create new patches or update existing ones
123

124
### 5. Completing Rebase
125

126
```bash
127
# Update the target patch
128
patch-package my-package
129

130
# Add new patch after target
131
patch-package my-package --append="description"
132
```
133

134
## Advanced Rebase Features
135

136
### State Management Integration
137

138
Rebase operations integrate with patch application state for safe operation.
139

140
```typescript { .api }
141
/**
142
 * Internal function for un-applying patches during rebase
143
 * @param options - Un-apply configuration
144
 */
145
function unApplyPatches(options: UnApplyPatchesOptions): void;
146

147
interface UnApplyPatchesOptions {
148
  /** Array of patches to un-apply */
149
  patches: PatchedPackageDetails[];
150
  /** Application path */
151
  appPath: string;
152
  /** Patch directory */
153
  patchDir: string;
154
}
155
```
156

157
### Error Handling
158

159
Comprehensive error handling for rebase operations:
160

161
- **No Patches Found**: Clear message when no patches exist
162
- **Invalid Target**: Helpful listing of available patches
163
- **State Mismatch**: Guidance for resolving inconsistent state
164
- **Un-apply Failures**: Recovery instructions for failed reversals
165

166
**Error Recovery:**
167

168
```bash
169
# If rebase fails, you can:
170
# 1. Reinstall node_modules to reset state
171
npm install
172

173
# 2. Delete problematic patch files
174
rm patches/broken-package+1.0.0.patch
175

176
# 3. Restart the rebase process
177
patch-package --rebase 0 my-package
178
```
179

180
### Interactive Rebase Guidance
181

182
When rebase enters interactive mode, patch-package provides clear instructions:
183

184
```bash
185
# Output example during rebase
186
Make any changes you need inside /path/to/package
187

188
When you are done, do one of the following:
189

190
  To update lodash+4.17.21.patch run
191
    patch-package lodash
192
    
193
  To create a new patch file after lodash+4.17.21.patch run
194
    patch-package lodash --append 'MyChangeDescription'
195
```
196

197
## Rebase Use Cases
198

199
### 1. Insert Patch in Middle of Sequence
200

201
```bash
202
# Rebase to position 2
203
patch-package --rebase 2 my-package
204

205
# Make changes and insert new patch
206
patch-package my-package --append="hotfix"
207
```
208

209
### 2. Modify Early Patch
210

211
```bash
212
# Rebase to first patch
213
patch-package --rebase 1 my-package
214

215
# Modify files and update the patch
216
patch-package my-package
217
```
218

219
### 3. Remove Patches from End
220

221
```bash
222
# Rebase to earlier position
223
patch-package --rebase 3 my-package
224

225
# Don't add new patches - effectively truncates sequence
226
```
227

228
### 4. Completely Restart Patch Sequence
229

230
```bash
231
# Reset to beginning
232
patch-package --rebase 0 my-package
233

234
# Create entirely new patch sequence
235
patch-package my-package --append="complete-rewrite"
236
```
237

238
## Best Practices
239

240
### Before Rebasing
241

242
1. **Commit Current Work**: Ensure your changes are saved
243
2. **Backup Patches**: Copy patch files before major rebase operations
244
3. **Clean Working Directory**: Commit or stash uncommitted changes
245

246
### During Rebase
247

248
1. **Follow Instructions**: patch-package provides clear guidance
249
2. **Test Changes**: Verify your modifications work as expected
250
3. **Use Descriptive Names**: Name new patches clearly
251

252
### After Rebase
253

254
1. **Test Patch Application**: Run `patch-package` to verify patches apply
255
2. **Update Documentation**: Document significant patch sequence changes  
256
3. **Commit New Patches**: Add updated patch files to version control
257

258
**Complete Rebase Example:**
259

260
```typescript
261
import { rebase } from "patch-package/dist/rebase";
262
import { getAppRootPath } from "patch-package/dist/getAppRootPath";
263
import { getPatchApplicationState } from "patch-package/dist/stateFile"; 
264

265
// Check current state before rebasing
266
const appPath = getAppRootPath();
267
const packageDetails = { name: "lodash", path: "/path/to/lodash" };
268
const currentState = getPatchApplicationState(packageDetails);
269

270
if (currentState && !currentState.isRebasing) {
271
  // Safe to begin rebase
272
  rebase({
273
    appPath,
274
    patchDir: "patches",
275
    packagePathSpecifier: "lodash",
276
    targetPatch: "2" // Rebase to second patch
277
  });
278
  
279
  console.log("Rebase initiated - make your changes and run patch-package");
280
} else {
281
  console.log("Cannot rebase: operation already in progress or no state");
282
}
283
```
284

285
This comprehensive rebase system enables sophisticated patch management workflows while maintaining safety and providing clear guidance throughout the process.