0
# CLI Interface
1

2
Complete command-line interface for creating and applying patches to npm dependencies. The CLI supports both interactive development workflows and automated CI/CD environments with comprehensive error handling and flexible configuration options.
3

4
## Capabilities
5

6
### Main Command
7

8
The primary patch-package command with multiple operation modes.
9

10
```bash { .api }
11
# Patch application mode (default)
12
patch-package [options]
13

14
# Patch creation mode
15
patch-package <package-name> [package-name...] [options]
16

17
# Rebase mode
18
patch-package --rebase <target> <package-name>
19

20
# Help and version
21
patch-package --help
22
patch-package --version
23
```
24

25
### Patch Application Options
26

27
Options for applying existing patches during package installation.
28

29
```bash { .api }
30
--patch-dir <dirname>        # Specify patch directory (default: "patches")
31
--error-on-fail              # Exit with code 1 on failure (auto-enabled in CI)
32
--error-on-warn              # Exit with code 1 on warnings
33
--reverse                    # Un-apply all patches
34
--partial                    # Best-effort patch application, continue on failures
35
```
36

37
**Usage Examples:**
38

39
```bash
40
# Apply patches from custom directory
41
patch-package --patch-dir=custom-patches
42

43
# Apply patches with strict error handling
44
patch-package --error-on-fail --error-on-warn
45

46
# Reverse all applied patches
47
patch-package --reverse
48

49
# Apply patches with best-effort mode (continue on failures)
50
patch-package --partial
51
```
52

53
### Patch Creation Options
54

55
Options for creating new patch files from modified node_modules.
56

57
```bash { .api }
58
--create-issue               # Open GitHub issue creation link
59
--use-yarn                   # Force use of yarn package manager
60
--include <regexp>           # Include paths matching regexp (default: .*)
61
--exclude <regexp>           # Exclude paths matching regexp (default: ^package\.json$)
62
--case-sensitive-path-filtering  # Make path filters case-sensitive
63
--append [name]              # Append new patch to sequence (name is optional)
64
```
65

66
**Usage Examples:**
67

68
```bash
69
# Create patch for single package
70
patch-package react
71

72
# Create patches for multiple packages
73
patch-package react react-dom lodash
74

75
# Create patch with custom include/exclude patterns
76
patch-package lodash --include="src/.*" --exclude="test/.*"
77

78
# Create patch and open GitHub issue
79
patch-package broken-package --create-issue
80

81
# Append to existing patch sequence
82
patch-package some-package --append="fix-critical-bug"
83

84
# Force yarn usage even in npm project
85
patch-package some-package --use-yarn
86
```
87

88
### Rebase Operations
89

90
Advanced functionality for rebasing patch sequences to different targets.
91

92
```bash { .api }
93
--rebase <target> <package-name>    # Rebase patches to target patch file/number
94
```
95

96
**Usage Examples:**
97

98
```bash
99
# Rebase to specific patch file
100
patch-package --rebase patches/lodash+4.17.20.patch lodash
101

102
# Rebase to patch sequence number
103
patch-package --rebase 3 lodash
104

105
# Rebase to sequence name
106
patch-package --rebase security-fix lodash
107

108
# Rebase to beginning (un-apply all patches)
109
patch-package --rebase 0 lodash
110
```
111

112
**Rebase Workflow:**
113

114
When rebasing, patch-package will:
115
1. Un-apply all patches after the target
116
2. Put the package in "rebasing" state
117
3. Allow you to make changes
118
4. Use normal patch creation commands to continue
119

120
**During Rebase:**
121

122
```bash
123
# Update the current target patch
124
patch-package my-package
125

126
# Add new patch after target
127
patch-package my-package --append="new-feature"
128
```
129

130
### Help and Version
131

132
```bash { .api }
133
--help, -h                   # Show help information
134
--version, -v                # Show version number
135
```
136

137
## Command Behavior
138

139
### Automatic Mode Detection
140

141
patch-package automatically detects the intended operation mode:
142

143
- **Application Mode**: When no package names are provided, applies existing patches
144
- **Creation Mode**: When package names are provided, creates new patches
145
- **Rebase Mode**: When `--rebase` flag is used with target and package name
146

147
### CI Environment Detection
148

149
The CLI automatically detects CI environments and adjusts behavior:
150

151
- Enables `--error-on-fail` by default in CI environments
152
- Provides appropriate exit codes for build system integration
153
- Reduces interactive prompts in favor of explicit configuration
154

155
### Package Manager Integration
156

157
Automatically detects and works with:
158

159
- **npm**: Uses package-lock.json for resolution
160
- **yarn v1**: Uses yarn.lock for resolution  
161
- **npm-shrinkwrap**: Uses npm-shrinkwrap.json for resolution
162

163
Can be overridden with `--use-yarn` flag when needed.
164

165
### Error Handling
166

167
Comprehensive error handling with configurable exit behavior:
168

169
- **Default**: Logs errors but continues execution
170
- **Strict Mode**: `--error-on-fail` exits on any patch failure
171
- **Warning Mode**: `--error-on-warn` exits on warnings
172
- **Best Effort**: `--partial` continues even when individual patches fail
173

174
### File Filtering
175

176
Advanced file filtering capabilities for patch creation:
177

178
- **Include Patterns**: `--include` regexp to specify which files to patch
179
- **Exclude Patterns**: `--exclude` regexp to specify which files to ignore
180
- **Case Sensitivity**: `--case-sensitive-path-filtering` for precise control
181
- **Default Behavior**: Includes all files except package.json
182

183
**Filtering Examples:**
184

185
```bash
186
# Only patch TypeScript files
187
patch-package my-lib --include=".*\.ts$"
188

189
# Exclude test and documentation files
190
patch-package my-lib --exclude="(test|docs|spec)/.*"
191

192
# Case-sensitive filtering
193
patch-package my-lib --include="src/.*" --case-sensitive-path-filtering
194
```
195

196
### Patch Sequences
197

198
Support for sequential patches on the same package:
199

200
- **Overwrite Mode**: Default behavior replaces existing patches
201
- **Append Mode**: `--append` adds to existing patch sequence
202
- **Named Sequences**: Optional names for patch sequences
203
- **Automatic Numbering**: Sequential numbering for patch order
204

205
**Sequence Examples:**
206

207
```bash
208
# Create first patch
209
patch-package my-package
210

211
# Append additional patch with name
212
patch-package my-package --append="security-fix"
213

214
# Append patch without name (auto-numbered)
215
patch-package my-package --append
216

217
# Append another patch to sequence
218
patch-package my-package --append="performance-improvement"
219
```
220

221
This creates a sequence like:
222
- `patches/my-package+1.0.0.patch`
223
- `patches/my-package+1.0.0++001_security-fix.patch`  
224
- `patches/my-package+1.0.0++002_performance-improvement.patch`