0
# CLI Commands
1

2
Complete command-line interface for pre-commit hook management. All commands are executed through the `pre-commit` console script entry point, which routes to the appropriate command implementations.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
Primary entry point for all CLI commands that parses arguments and routes to appropriate command handlers.
9

10
```python { .api }
11
def main(argv: Sequence[str] | None = None) -> int:
12
    """
13
    Main CLI entry point for pre-commit commands.
14
    
15
    Parameters:
16
    - argv: Optional command-line arguments array
17
    
18
    Returns:
19
    - int: Exit code (0 for success, non-zero for failure)
20
    """
21
```
22

23
### Installation Commands
24

25
Commands for installing and managing pre-commit hook scripts in Git repositories.
26

27
```python { .api }
28
def install(
29
    config_file: str,
30
    store: Store,
31
    hook_types: list[str] | None,
32
    overwrite: bool = False,
33
    hooks: bool = False,
34
    skip_on_missing_config: bool = False,
35
    git_dir: str | None = None,
36
) -> int:
37
    """
38
    Install git hook scripts.
39
    
40
    Parameters:
41
    - config_file: Path to configuration file
42
    - store: Store instance for hook management
43
    - hook_types: List of git hook types to install
44
    - overwrite: Whether to overwrite existing hooks
45
    - hooks: Whether to install hook environments too
46
    - skip_on_missing_config: Skip installation if config missing
47
    - git_dir: Git directory path (optional)
48
    
49
    Returns:
50
    - int: Exit code
51
    """
52

53
def uninstall(config_file: str, hook_types: list[str] | None) -> int:
54
    """
55
    Remove git hook scripts.
56
    
57
    Parameters:
58
    - config_file: Path to configuration file
59
    - hook_types: List of git hook types to uninstall
60
    
61
    Returns:
62
    - int: Exit code
63
    """
64

65
def install_hooks(config_file: str, store: Store) -> int:
66
    """
67
    Install hook environments for all configured hooks.
68
    
69
    Parameters:
70
    - config_file: Path to configuration file
71
    - store: Store instance for hook management
72
    
73
    Returns:
74
    - int: Exit code
75
    """
76

77
def init_templatedir(
78
    config_file: str,
79
    store: Store,
80
    directory: str,
81
    hook_types: list[str] | None,
82
    skip_on_missing_config: bool = True,
83
) -> int:
84
    """
85
    Setup hooks in git template directory.
86
    
87
    Parameters:
88
    - config_file: Path to configuration file
89
    - store: Store instance for hook management
90
    - directory: Template directory path
91
    - hook_types: List of git hook types to install
92
    - skip_on_missing_config: Skip installation if config missing
93
    
94
    Returns:
95
    - int: Exit code
96
    """
97
```
98

99
### Hook Execution Commands
100

101
Commands for running pre-commit hooks on files with various filtering and execution options.
102

103
```python { .api }
104
def run(
105
    config_file: str,
106
    store: Store,
107
    args: argparse.Namespace,
108
    environ: MutableMapping[str, str] = os.environ,
109
) -> int:
110
    """
111
    Execute hooks with file filtering and staging options.
112
    
113
    Parameters:
114
    - config_file: Path to configuration file
115
    - store: Store instance for hook management
116
    - all_files: Run on all files instead of just staged
117
    - files: Specific files to run on
118
    - hook_stage: Git hook stage to run
119
    - hook: Run only specific hook by id
120
    - from_ref: Git ref to compare from
121
    - to_ref: Git ref to compare to
122
    - show_diff_on_failure: Show diff when hooks fail
123
    - color: Color output mode ('auto', 'always', 'never')
124
    - verbose: Verbose output
125
    
126
    Returns:
127
    - int: Exit code (0 if all hooks pass)
128
    """
129

130
def hook_impl(config_file: str, hook_type: str, hook_dir: str | None = None,
131
             skip_on_missing_config: bool = False, **kwargs) -> int:
132
    """
133
    Internal hook implementation (not for direct user use).
134
    
135
    Parameters:
136
    - config_file: Path to configuration file
137
    - hook_type: Type of git hook being executed
138
    - hook_dir: Hook directory path
139
    - skip_on_missing_config: Skip if config missing
140
    
141
    Returns:
142
    - int: Exit code
143
    """
144
```
145

146
### Configuration Management Commands
147

148
Commands for managing, validating, and updating pre-commit configuration files.
149

150
```python { .api }
151
def autoupdate(config_file: str = '.pre-commit-config.yaml', store: Store | None = None,
152
              tags_only: bool = False, bleeding_edge: bool = False,
153
              freeze: bool = False, repo: Sequence[str] = (),
154
              jobs: int = 1) -> int:
155
    """
156
    Auto-update repository versions in configuration.
157
    
158
    Parameters:
159
    - config_file: Path to configuration file
160
    - store: Store instance for repository management
161
    - tags_only: Only use tagged versions
162
    - bleeding_edge: Use latest commit instead of latest tag
163
    - freeze: Store exact commit hash instead of tag
164
    - repo: Update only specific repositories
165
    - jobs: Number of concurrent jobs
166
    
167
    Returns:
168
    - int: Exit code
169
    """
170

171
def migrate_config(config_file: str = '.pre-commit-config.yaml') -> int:
172
    """
173
    Migrate configuration file to latest format.
174
    
175
    Parameters:
176
    - config_file: Path to configuration file
177
    
178
    Returns:
179
    - int: Exit code
180
    """
181

182
def validate_config(filenames: Sequence[str]) -> int:
183
    """
184
    Validate .pre-commit-config.yaml files.
185
    
186
    Parameters:
187
    - filenames: List of config files to validate
188
    
189
    Returns:
190
    - int: Exit code (0 if all valid)
191
    """
192

193
def validate_manifest(filenames: Sequence[str]) -> int:
194
    """
195
    Validate .pre-commit-hooks.yaml manifest files.
196
    
197
    Parameters:
198
    - filenames: List of manifest files to validate
199
    
200
    Returns:
201
    - int: Exit code (0 if all valid)
202
    """
203
```
204

205
### Utility Commands
206

207
Utility commands for testing, configuration generation, and maintenance operations.
208

209
```python { .api }
210
def sample_config() -> int:
211
    """
212
    Generate sample .pre-commit-config.yaml configuration.
213
    
214
    Returns:
215
    - int: Exit code
216
    """
217

218
def try_repo(repo: str, ref: str = 'HEAD', **kwargs) -> int:
219
    """
220
    Test hooks from a repository without modifying configuration.
221
    
222
    Parameters:
223
    - repo: Repository URL or path
224
    - ref: Git reference to use
225
    
226
    Returns:
227
    - int: Exit code
228
    """
229

230
def clean(store: Store | None = None) -> int:
231
    """
232
    Clean pre-commit cache and temporary files.
233
    
234
    Parameters:
235
    - store: Store instance for cleanup operations
236
    
237
    Returns:
238
    - int: Exit code
239
    """
240

241
def gc(store: Store | None = None) -> int:
242
    """
243
    Garbage collect unused repositories and environments.
244
    
245
    Parameters:
246
    - store: Store instance for garbage collection
247
    
248
    Returns:
249
    - int: Exit code
250
    """
251
```
252

253
## Hook Types and Stages
254

255
### Supported Git Hook Types
256

257
```python { .api }
258
HOOK_TYPES = (
259
    'commit-msg', 'post-checkout', 'post-commit', 'post-merge',
260
    'post-rewrite', 'pre-commit', 'pre-merge-commit', 'pre-push',
261
    'pre-rebase', 'prepare-commit-msg'
262
)
263

264
STAGES = (*HOOK_TYPES, 'manual')
265
```
266

267
### Commands Without Git Repository Requirement
268

269
```python { .api }
270
COMMANDS_NO_GIT = {
271
    'clean', 'gc', 'init-templatedir', 'sample-config',
272
    'validate-config', 'validate-manifest',
273
}
274
```
275

276
## Usage Examples
277

278
### Basic Command Usage
279

280
```python
281
from pre_commit.main import main
282

283
# Install hooks
284
exit_code = main(['install'])
285

286
# Run all hooks
287
exit_code = main(['run', '--all-files'])
288

289
# Auto-update configuration
290
exit_code = main(['autoupdate'])
291

292
# Validate configuration
293
exit_code = main(['validate-config', '.pre-commit-config.yaml'])
294
```
295

296
### Advanced Command Usage
297

298
```python
299
# Run specific hook with verbose output
300
exit_code = main(['run', '--hook', 'flake8', '--verbose'])
301

302
# Run on specific files
303
exit_code = main(['run', '--files', 'file1.py', 'file2.py'])
304

305
# Show diff on failure
306
exit_code = main(['run', '--show-diff-on-failure'])
307

308
# Try hooks from external repository
309
exit_code = main(['try-repo', 'https://github.com/psf/black'])
310
```