0
# lint-staged
1

2
lint-staged runs linters and formatters against staged git files and prevents broken code from entering your repository. It optimizes performance by processing only changed files and provides both CLI and programmatic Node.js APIs.
3

4
## Package Information
5

6
- **Package Name**: lint-staged
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Modules) with TypeScript definitions
9
- **Installation**: `npm install --save-dev lint-staged`
10
- **Node.js Requirements**: >= 20.17
11

12
## Core Imports
13

14
```javascript
15
import lintStaged from "lint-staged";
16
```
17

18
For TypeScript with type imports:
19

20
```typescript
21
import lintStaged, { type Options, type Configuration } from "lint-staged";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const lintStaged = require("lint-staged");
28
```
29

30
## Basic Usage
31

32
### CLI Usage
33

34
```bash
35
# Run lint-staged against all staged files
36
npx lint-staged
37

38
# Run with configuration file
39
npx lint-staged --config .lintstagedrc.json
40

41
# Run with debug output
42
npx lint-staged --debug
43
```
44

45
### Programmatic Usage
46

47
```javascript
48
import lintStaged from "lint-staged";
49

50
// Basic usage with default options
51
const success = await lintStaged();
52

53
// With custom options
54
const success = await lintStaged({
55
  config: {
56
    "*.js": "eslint --fix",
57
    "*.{json,md}": "prettier --write"
58
  },
59
  concurrent: true,
60
  verbose: true
61
});
62

63
console.log(success ? "All tasks passed" : "Some tasks failed");
64
```
65

66
## Architecture
67

68
lint-staged is built around several key components:
69

70
- **Main API Function**: Single default export function with comprehensive options
71
- **CLI Interface**: Feature-rich command-line tool with extensive flag support
72
- **Configuration System**: Flexible configuration loading from multiple file formats
73
- **Git Workflow Management**: Safe stashing and restoration with error recovery
74
- **Task Execution Engine**: Concurrent task execution with file chunking for performance
75
- **Error Handling**: Comprehensive error symbols and recovery mechanisms
76

77
## Capabilities
78

79
### Programmatic API
80

81
Core programmatic interface for running lint-staged from Node.js applications. Provides full control over execution with comprehensive options.
82

83
```javascript { .api }
84
/**
85
 * Main lint-staged function for programmatic usage
86
 * @param options - Configuration options
87
 * @param logger - Custom logger instance
88
 * @returns Promise resolving to true if all tasks passed, false if some failed
89
 */
90
function lintStaged(options?: Options, logger?: Logger): Promise<boolean>;
91

92
interface Options {
93
  allowEmpty?: boolean;
94
  concurrent?: boolean | number;
95
  config?: Configuration;
96
  configPath?: string;
97
  cwd?: string;
98
  debug?: boolean;
99
  diff?: string;
100
  diffFilter?: string;
101
  maxArgLength?: number;
102
  quiet?: boolean;
103
  relative?: boolean;
104
  revert?: boolean;
105
  stash?: boolean;
106
  hidePartiallyStaged?: boolean;
107
  verbose?: boolean;
108
}
109

110
interface Logger {
111
  log: (...params: any) => void;
112
  warn: (...params: any) => void;
113
  error: (...params: any) => void;
114
}
115
```
116

117
[Programmatic API](./programmatic-api.md)
118

119
### Command Line Interface
120

121
Full-featured CLI with extensive options for customizing behavior, git operations, and output formatting.
122

123
```bash { .api }
124
lint-staged [options]
125

126
Options:
127
  --allow-empty                    allow empty commits when tasks revert all staged changes
128
  -p, --concurrent <number|boolean> the number of tasks to run concurrently, or false for serial
129
  -c, --config [path]              path to configuration file, or - to read from stdin
130
  --cwd [path]                     run all tasks in specific directory, instead of the current
131
  -d, --debug                      print additional debug information
132
  --diff [string]                  override the default "--staged" flag of "git diff" to get list of files
133
  --diff-filter [string]           override the default "--diff-filter=ACMR" flag of "git diff"
134
  --max-arg-length [number]        maximum length of the command-line argument string
135
  --no-revert                      do not revert to original state in case of errors
136
  --no-stash                       disable the backup stash
137
  --no-hide-partially-staged       disable hiding unstaged changes from partially staged files
138
  -q, --quiet                      disable lint-staged's own console output
139
  -r, --relative                   pass relative filepaths to tasks
140
  -v, --verbose                    show task output even when tasks succeed
141
```
142

143
[CLI Interface](./cli-interface.md)
144

145
### Configuration System
146

147
Flexible configuration system supporting multiple file formats and programmatic configuration with glob patterns and task definitions.
148

149
```javascript { .api }
150
type Configuration = 
151
  | Record<string, string | TaskFunction | GenerateTask | (string | GenerateTask)[]>
152
  | GenerateTask;
153

154
type GenerateTask = (stagedFileNames: string[]) => string | string[] | Promise<string | string[]>;
155

156
interface TaskFunction {
157
  title: string;
158
  task: (stagedFileNames: string[]) => void | Promise<void>;
159
}
160
```
161

162
[Configuration](./configuration.md)
163

164
## Core Types
165

166
These types are exported for TypeScript usage and can be imported as shown in the Core Imports section.
167

168
```typescript { .api }
169
interface Options {
170
  /** Allow empty commits when tasks revert all staged changes */
171
  allowEmpty?: boolean;
172
  
173
  /** The number of tasks to run concurrently, or false to run tasks serially */
174
  concurrent?: boolean | number;
175
  
176
  /** Manual task configuration; disables automatic config file discovery */
177
  config?: Configuration;
178
  
179
  /** Path to single configuration file; disables automatic config file discovery */
180
  configPath?: string;
181
  
182
  /** Working directory to run all tasks in, defaults to current working directory */
183
  cwd?: string;
184
  
185
  /** Whether or not to enable debug output */
186
  debug?: boolean;
187
  
188
  /** Override the default --staged flag of git diff to get list of files */
189
  diff?: string;
190
  
191
  /** Override the default --diff-filter=ACMR flag of git diff to get list of files */
192
  diffFilter?: string;
193
  
194
  /** Maximum argument string length, by default automatically detected */
195
  maxArgLength?: number;
196
  
197
  /** Disable lint-staged's own console output */
198
  quiet?: boolean;
199
  
200
  /** Pass filepaths relative to CWD to tasks, instead of absolute */
201
  relative?: boolean;
202
  
203
  /** Revert to original state in case of errors */
204
  revert?: boolean;
205
  
206
  /** Enable the backup stash, and revert in case of errors */
207
  stash?: boolean;
208
  
209
  /** Whether to hide unstaged changes from partially staged files before running tasks */
210
  hidePartiallyStaged?: boolean;
211
  
212
  /** Show task output even when tasks succeed; by default only failed output is shown */
213
  verbose?: boolean;
214
}
215

216
type LogFunction = (...params: any) => void;
217

218
interface Logger {
219
  log: LogFunction;
220
  warn: LogFunction;
221
  error: LogFunction;
222
}
223
```