0
# Database and Utilities
1

2
Infrastructure components for object database access and file locking mechanisms. These classes provide low-level access to Git's object storage and concurrent access control.
3

4
## Capabilities
5

6
### Object Database
7

8
Direct access to Git's object database with both high-level and command-line interfaces for reading and writing Git objects.
9

10
```python { .api }
11
from git.types import PathLike
12

13
class GitDB:
14
    """Git object database interface providing access to Git objects."""
15
    
16
    def __init__(self, root_path: PathLike): ...
17
    
18
    def stream(self, binsha: bytes): ...
19
    def info(self, binsha: bytes): ...
20
    def store(self, istream): ...
21

22
class GitCmdObjectDB:
23
    """Git object database using command-line interface for object operations."""
24
    
25
    def __init__(self, root_path: PathLike, git: "Git") -> None:
26
        """
27
        Initialize database with root path and Git command interface.
28
        
29
        Args:
30
            root_path: Path to Git object database
31
            git: Git command interface instance
32
        """
33
    
34
    def info(self, binsha: bytes):
35
        """Get object header information using git command."""
36
    
37
    def stream(self, binsha: bytes):
38
        """Get object data as stream using git command."""
39
```
40

41
### File Locking
42

43
File-based locking mechanisms for concurrent access control, essential for safe multi-process Git operations.
44

45
```python { .api }
46
class LockFile:
47
    """File-based locking mechanism for concurrent access control."""
48
    
49
    def __init__(self, file_path: PathLike): ...
50
    
51
    def acquire(self, fail_on_lock: bool = True) -> bool:
52
        """Acquire file lock."""
53
    
54
    def release(self) -> None:
55
        """Release file lock."""
56
    
57
    def __enter__(self): ...
58
    def __exit__(self, exc_type, exc_val, exc_tb): ...
59

60
class BlockingLockFile(LockFile):
61
    """Blocking file lock that waits until lock can be obtained or timeout."""
62
    
63
    def __init__(self, file_path: PathLike, check_interval: float = 0.3, max_time: float = float('inf')): ...
64
    
65
    def acquire(self, fail_on_lock: bool = True) -> bool:
66
        """Acquire lock, blocking until available or timeout."""
67
```
68

69
## Usage Examples
70

71
### Working with Object Database
72

73
```python
74
from git import Repo
75
from git.db import GitCmdObjectDB
76

77
repo = Repo('/path/to/repo')
78

79
# Access object database
80
odb = repo.odb
81

82
# Get object info
83
commit_sha = repo.head.commit.binsha
84
info = odb.info(commit_sha)
85
print(f"Object type: {info.type}")
86
print(f"Object size: {info.size}")
87

88
# Stream object data  
89
stream = odb.stream(commit_sha)
90
data = stream.read()
91
```
92

93
### Using File Locks
94

95
```python
96
from git.util import LockFile, BlockingLockFile
97
import time
98

99
# Basic file lock
100
lock_file = LockFile('/path/to/file.lock')
101
try:
102
    if lock_file.acquire():
103
        print("Lock acquired")
104
        # Perform operations requiring exclusive access
105
        time.sleep(1)
106
    else:
107
        print("Could not acquire lock")
108
finally:
109
    lock_file.release()
110

111
# Using context manager
112
with LockFile('/path/to/file.lock') as lock:
113
    # Operations here are protected by lock
114
    pass
115

116
# Blocking lock with timeout
117
blocking_lock = BlockingLockFile('/path/to/file.lock', max_time=30.0)
118
try:
119
    blocking_lock.acquire()  # Will wait up to 30 seconds
120
    # Protected operations
121
finally:
122
    blocking_lock.release()
123
```