0
# Exception Handling
1

2
Comprehensive exception hierarchy for robust error handling across all Git operations. Includes specific exceptions for common Git scenarios and command failures.
3

4
## Capabilities
5

6
### Base Exceptions
7

8
```python { .api }
9
class GitError(Exception):
10
    """Base exception for all git operations."""
11

12
class InvalidGitRepositoryError(GitError):
13
    """Repository is not a valid git repository."""
14

15
class WorkTreeRepositoryUnsupported(GitError):
16
    """Operation not supported on worktree repositories."""
17

18
class NoSuchPathError(GitError):
19
    """Path does not exist in repository."""
20
```
21

22
### Command Exceptions
23

24
```python { .api }
25
class CommandError(GitError):
26
    """Git command execution failed."""
27

28
class GitCommandError(CommandError):
29
    """Git command returned non-zero exit code."""
30
    
31
    @property
32
    def status(self) -> int:
33
        """Command exit status."""
34
    
35
    @property
36
    def command(self) -> list[str]:
37
        """Failed command."""
38
    
39
    @property
40
    def stdout(self) -> str:
41
        """Command stdout."""
42
    
43
    @property
44
    def stderr(self) -> str:
45
        """Command stderr."""
46

47
class GitCommandNotFound(CommandError):
48
    """Git executable not found."""
49
```
50

51
### Security Exceptions
52

53
```python { .api }
54
class UnsafeProtocolError(GitError):
55
    """Unsafe protocol usage detected."""
56

57
class UnsafeOptionError(GitError):
58
    """Unsafe option usage detected."""
59
```
60

61
### Repository State Exceptions
62

63
```python { .api }
64
class CheckoutError(GitError):
65
    """Checkout operation failed."""
66

67
class RepositoryDirtyError(GitError):
68
    """Repository has uncommitted changes."""
69

70
class UnmergedEntriesError(GitError):
71
    """Index contains unmerged entries."""
72

73
class CacheError(GitError):
74
    """Object cache operation failed."""
75

76
class HookExecutionError(GitError):
77
    """Git hook execution failed."""
78
```
79

80
### Object Database Exceptions
81

82
```python { .api }
83
# Inherited from gitdb
84
class AmbiguousObjectName(GitError):
85
    """Object name matches multiple objects."""
86

87
class BadName(GitError):
88
    """Invalid object name."""
89

90
class BadObject(GitError):
91
    """Invalid or corrupted object."""
92

93
class BadObjectType(GitError):
94
    """Invalid object type."""
95

96
class InvalidDBRoot(GitError):
97
    """Invalid database root directory."""
98

99
class ODBError(GitError):
100
    """Object database error."""
101

102
class ParseError(GitError):
103
    """Object parsing failed."""
104

105
class UnsupportedOperation(GitError):
106
    """Operation not supported."""
107
```
108

109
## Usage Examples
110

111
```python
112
from git import Repo, GitCommandError, InvalidGitRepositoryError
113

114
try:
115
    repo = Repo('/invalid/path')
116
except InvalidGitRepositoryError as e:
117
    print(f"Not a git repository: {e}")
118

119
try:
120
    repo = Repo('/valid/repo')
121
    repo.git.execute(['invalid-command'])
122
except GitCommandError as e:
123
    print(f"Command failed: {e.command}")
124
    print(f"Exit code: {e.status}")
125
    print(f"Error: {e.stderr}")
126

127
# Handle specific scenarios
128
try:
129
    repo.heads.main.checkout()
130
except CheckoutError as e:
131
    print(f"Checkout failed: {e}")
132
    # Handle conflicts or dirty working tree
133

134
try:
135
    repo.index.commit("Test commit")
136
except RepositoryDirtyError:
137
    print("Cannot commit: repository has uncommitted changes")
138
```