0
# References and Branches
1

2
Management of Git references including branches, tags, HEAD, and remote references. Supports creation, deletion, and manipulation of all reference types with symbolic reference handling.
3

4
## Capabilities
5

6
### Reference Base Classes
7

8
```python { .api }
9
class Reference:
10
    def __init__(self, repo: "Repo", path: str, check_path: bool = True):
11
        """Initialize reference."""
12
    
13
    @property
14
    def name(self) -> str:
15
        """Reference name."""
16
    
17
    @property  
18
    def commit(self) -> "Commit":
19
        """Referenced commit."""
20
    
21
    def set_commit(self, commit: "Commit", logmsg: str = None) -> "Reference":
22
        """Set reference to commit."""
23
    
24
    def delete(self, repo: "Repo", *refs: "Reference") -> None:
25
        """Delete references."""
26

27
class SymbolicReference(Reference):
28
    def __init__(self, repo: "Repo", path: str):
29
        """Initialize symbolic reference."""
30
```
31

32
### Branch Management
33

34
```python { .api }
35
class Head(Reference):
36
    def checkout(self, force: bool = False, **kwargs) -> "HEAD":
37
        """Checkout this branch."""
38
    
39
    def reset(self, commit: "Commit" = None, index: bool = True, working_tree: bool = False, paths: list = None, **kwargs) -> "Head":
40
        """Reset branch to commit."""
41

42
class HEAD(SymbolicReference):
43
    def reset(self, commit: "Commit" = None, index: bool = True, working_tree: bool = False, paths: list = None, **kwargs) -> "HEAD":
44
        """Reset HEAD."""
45
```
46

47
### Tag Management
48

49
```python { .api }
50
class TagReference(Reference):
51
    @property
52
    def tag(self) -> "TagObject":
53
        """Tag object (for annotated tags)."""
54

55
class Tag(TagReference):
56
    def delete(self, repo: "Repo", *tags: "Tag") -> None:
57
        """Delete tags."""
58
```
59

60
### Remote References
61

62
```python { .api }
63
class RemoteReference(Reference):
64
    @property
65
    def remote_name(self) -> str:
66
        """Remote name."""
67
    
68
    @property
69
    def remote_head(self) -> str:
70
        """Remote branch name."""
71
```
72

73
### Reference Logs
74

75
```python { .api }
76
class RefLog:
77
    def __init__(self, filepath: str):
78
        """Initialize reflog."""
79
    
80
    def __iter__(self) -> Iterator["RefLogEntry"]:
81
        """Iterate reflog entries."""
82

83
class RefLogEntry:
84
    def __init__(self, from_sha: str, to_sha: str, actor: "Actor", time: int, tz_offset: int, message: str):
85
        """Initialize reflog entry."""
86
    
87
    @property
88
    def oldhexsha(self) -> str:
89
        """Previous SHA."""
90
    
91
    @property
92
    def newhexsha(self) -> str:
93
        """New SHA."""
94
```
95

96
## Usage Examples
97

98
```python
99
from git import Repo
100

101
repo = Repo('/path/to/repo')
102

103
# Work with branches
104
main_branch = repo.heads.main
105
feature_branch = repo.create_head('feature/new-feature')
106

107
# Checkout branch
108
feature_branch.checkout()
109

110
# Create and switch to new branch
111
new_branch = repo.create_head('hotfix', commit='HEAD~3')
112
new_branch.checkout()
113

114
# Work with tags
115
tag = repo.create_tag('v1.0.0', message='Release v1.0.0')
116
for tag in repo.tags:
117
    print(f"Tag: {tag.name}")
118

119
# Access remote references
120
for remote_ref in repo.remotes.origin.refs:
121
    print(f"Remote ref: {remote_ref.name}")
122
```