0
# Git Integration
1

2
Git repository utilities and integration functions for working with staged files, repository state, and Git workflow integration. Pre-commit provides deep integration with Git operations to enable seamless hook execution within development workflows.
3

4
## Capabilities
5

6
### Repository Information
7

8
Functions for retrieving basic repository information and paths.
9

10
```python { .api }
11
def get_root() -> str:
12
    """
13
    Get the root directory of the current Git repository.
14
    
15
    Returns:
16
    - str: Absolute path to repository root
17
    
18
    Raises:
19
    - CalledProcessError: If not in a Git repository
20
    """
21

22
def get_git_dir() -> str:
23
    """
24
    Get the .git directory path for the current repository.
25
    
26
    Returns:
27
    - str: Path to .git directory
28
    """
29

30
def get_git_common_dir() -> str:
31
    """
32
    Get the common Git directory (for worktrees).
33
    
34
    Returns:
35
    - str: Path to common Git directory
36
    """
37
```
38

39
### File Status and Listing
40

41
Functions for retrieving file lists based on Git status and staging state.
42

43
```python { .api }
44
def get_staged_files(cwd: str | None = None) -> list[str]:
45
    """
46
    Get list of files currently staged for commit.
47
    
48
    Parameters:
49
    - cwd: Working directory (defaults to repository root)
50
    
51
    Returns:
52
    - list: Staged file paths relative to repository root
53
    """
54

55
def get_all_files() -> list[str]:
56
    """
57
    Get all tracked files in the repository.
58
    
59
    Returns:
60
    - list: All tracked file paths relative to repository root
61
    """
62

63
def get_changed_files(old: str, new: str) -> list[str]:
64
    """
65
    Get files changed between two Git references.
66
    
67
    Parameters:
68
    - old: Old Git reference (commit, branch, tag)
69
    - new: New Git reference (commit, branch, tag)
70
    
71
    Returns:
72
    - list: Changed file paths between references
73
    """
74

75
def get_conflicted_files() -> set[str]:
76
    """
77
    Get files currently in merge conflict state.
78
    
79
    Returns:
80
    - set: File paths with unresolved conflicts
81
    """
82
```
83

84
### Repository State
85

86
Functions for checking repository state and conditions.
87

88
```python { .api }
89
def is_in_merge_conflict() -> bool:
90
    """
91
    Check if repository is currently in a merge conflict state.
92
    
93
    Returns:
94
    - bool: True if there are unresolved merge conflicts
95
    """
96

97
def is_in_rebase() -> bool:
98
    """
99
    Check if repository is currently in a rebase operation.
100
    
101
    Returns:
102
    - bool: True if rebase is in progress
103
    """
104

105
def is_in_cherry_pick() -> bool:
106
    """
107
    Check if repository is currently in a cherry-pick operation.
108
    
109
    Returns:
110
    - bool: True if cherry-pick is in progress
111
    """
112

113
def has_unmerged_paths() -> bool:
114
    """
115
    Check if repository has unmerged paths.
116
    
117
    Returns:
118
    - bool: True if there are unmerged paths
119
    """
120
```
121

122
### Git Configuration
123

124
Functions for reading and checking Git configuration settings.
125

126
```python { .api }
127
def has_core_hookpaths_set() -> bool:
128
    """
129
    Check if Git core.hooksPath configuration is set.
130
    
131
    Pre-commit needs to know if custom hook paths are configured
132
    to handle installation correctly.
133
    
134
    Returns:
135
    - bool: True if core.hooksPath is configured
136
    """
137

138
def get_hook_paths() -> list[str]:
139
    """
140
    Get configured Git hook paths.
141
    
142
    Returns:
143
    - list: Hook directory paths
144
    """
145
```
146

147
### Commit and Reference Operations
148

149
Functions for working with commits, branches, and references.
150

151
```python { .api }
152
def get_commit_msg(commit_msg_filename: str) -> str:
153
    """
154
    Read commit message from file.
155
    
156
    Parameters:
157
    - commit_msg_filename: Path to commit message file
158
    
159
    Returns:
160
    - str: Commit message content
161
    """
162

163
def set_commit_msg(commit_msg_filename: str, new_msg: str) -> None:
164
    """
165
    Write commit message to file.
166
    
167
    Parameters:
168
    - commit_msg_filename: Path to commit message file
169
    - new_msg: New commit message content
170
    """
171

172
def get_staged_files_intent_to_add() -> list[str]:
173
    """
174
    Get files staged with intent-to-add flag.
175
    
176
    Returns:
177
    - list: File paths staged with git add --intent-to-add
178
    """
179
```
180

181
### Git Command Utilities
182

183
Low-level utilities for executing Git commands and processing output.
184

185
```python { .api }
186
def zsplit(s: str) -> list[str]:
187
    """
188
    Split null-separated string into list.
189
    
190
    Used for processing Git output with null separators.
191
    
192
    Parameters:
193
    - s: Null-separated string
194
    
195
    Returns:
196
    - list: Split string components
197
    """
198

199
def no_git_env(**kwargs) -> dict[str, str]:
200
    """
201
    Create environment dictionary with Git variables removed.
202
    
203
    Useful for running commands without Git environment influence.
204
    
205
    Parameters:
206
    - kwargs: Additional environment variables
207
    
208
    Returns:
209
    - dict: Environment without Git variables
210
    """
211
```
212

213
### File Modification Detection
214

215
Functions for detecting file changes and modifications.
216

217
```python { .api }
218
def get_diff_files(ref1: str, ref2: str) -> list[str]:
219
    """
220
    Get files different between two references.
221
    
222
    Parameters:
223
    - ref1: First Git reference
224
    - ref2: Second Git reference
225
    
226
    Returns:
227
    - list: Files with differences
228
    """
229

230
def intent_to_add_cleared() -> bool:
231
    """
232
    Check if intent-to-add files have been cleared from index.
233
    
234
    Returns:
235
    - bool: True if intent-to-add state is clear
236
    """
237
```
238

239
## Git Hook Integration
240

241
### Hook Installation Paths
242

243
Functions for determining where Git hooks should be installed.
244

245
```python { .api }
246
def get_hook_script_path(hook_type: str) -> str:
247
    """
248
    Get the file path where a Git hook script should be installed.
249
    
250
    Parameters:
251
    - hook_type: Type of Git hook (pre-commit, pre-push, etc.)
252
    
253
    Returns:
254
    - str: Path to hook script file
255
    """
256

257
def hook_exists(hook_type: str) -> bool:
258
    """
259
    Check if a Git hook script already exists.
260
    
261
    Parameters:
262
    - hook_type: Type of Git hook to check
263
    
264
    Returns:
265
    - bool: True if hook script exists
266
    """
267
```
268

269
### Git Object Utilities
270

271
Functions for working with Git objects and SHA values.
272

273
```python { .api }
274
def get_object_name(ref: str) -> str:
275
    """
276
    Get the SHA hash for a Git reference.
277
    
278
    Parameters:
279
    - ref: Git reference (branch, tag, commit)
280
    
281
    Returns:
282
    - str: SHA hash of the object
283
    """
284

285
def is_valid_sha(sha: str) -> bool:
286
    """
287
    Check if string is a valid Git SHA hash.
288
    
289
    Parameters:
290
    - sha: String to validate
291
    
292
    Returns:
293
    - bool: True if valid SHA format
294
    """
295
```
296

297
## Usage Examples
298

299
### Working with Staged Files
300

301
```python
302
from pre_commit import git
303

304
# Get all staged files for processing
305
staged_files = git.get_staged_files()
306
print(f"Processing {len(staged_files)} staged files:")
307
for file_path in staged_files:
308
    print(f"  {file_path}")
309

310
# Check if we're in a merge conflict
311
if git.is_in_merge_conflict():
312
    print("Repository is in merge conflict state")
313
    conflicted = git.get_conflicted_files()
314
    print(f"Conflicted files: {conflicted}")
315
else:
316
    print("Repository is in clean state")
317
```
318

319
### Repository Information
320

321
```python
322
from pre_commit import git
323

324
# Get repository root
325
repo_root = git.get_root()
326
print(f"Repository root: {repo_root}")
327

328
# Check Git configuration
329
if git.has_core_hookpaths_set():
330
    print("Custom hook paths are configured")
331
    paths = git.get_hook_paths()
332
    print(f"Hook paths: {paths}")
333
else:
334
    print("Using default Git hook paths")
335
```
336

337
### File Change Detection
338

339
```python
340
from pre_commit import git
341

342
# Get all tracked files
343
all_files = git.get_all_files()
344
print(f"Repository contains {len(all_files)} tracked files")
345

346
# Get changes between commits
347
changed_files = git.get_changed_files('HEAD~1', 'HEAD')
348
print(f"Files changed in last commit: {len(changed_files)}")
349
for file_path in changed_files:
350
    print(f"  {file_path}")
351

352
# Get files staged with intent-to-add
353
intent_files = git.get_staged_files_intent_to_add()
354
if intent_files:
355
    print(f"Files staged with intent-to-add: {intent_files}")
356
```
357

358
### Environment Management
359

360
```python
361
from pre_commit import git
362
import subprocess
363

364
# Run command without Git environment variables
365
env = git.no_git_env(CUSTOM_VAR='value')
366
result = subprocess.run(
367
    ['some-command'],
368
    env=env,
369
    capture_output=True,
370
    text=True
371
)
372
```
373

374
### Repository State Checking
375

376
```python
377
from pre_commit import git
378

379
# Check various repository states
380
states = {
381
    'merge_conflict': git.is_in_merge_conflict(),
382
    'rebase': git.is_in_rebase(),
383
    'cherry_pick': git.is_in_cherry_pick(),
384
    'unmerged_paths': git.has_unmerged_paths()
385
}
386

387
active_states = [name for name, active in states.items() if active]
388
if active_states:
389
    print(f"Repository states: {', '.join(active_states)}")
390
else:
391
    print("Repository is in normal state")
392
```