0
# VCS Support
1
2
Version control system integration for handling Git repositories and dependency sources from VCS. Poetry Core provides Git support for accessing dependencies from version control systems.
3
4
## Core Import
5
6
```python
7
from poetry.core.vcs import get_vcs
8
from poetry.core.vcs.git import Git
9
``` { .api }
10
11
## Capabilities
12
13
### VCS Detection and Access
14
15
Detects and provides access to version control systems in a given directory.
16
17
```python { .api }
18
def get_vcs(directory: Path) -> Git | None:
19
"""
20
Detect and return VCS instance for a directory.
21
22
Args:
23
directory: Path to check for VCS repository
24
25
Returns:
26
Git instance if directory is in a Git repository, None otherwise
27
28
Note:
29
Currently only supports Git repositories. Checks if directory
30
is ignored by Git and returns None if so.
31
"""
32
```
33
34
### Git Repository Operations
35
36
The `Git` class provides comprehensive Git repository operations for dependency handling and metadata extraction.
37
38
```python { .api }
39
class Git:
40
"""
41
Git version control system support for Poetry Core.
42
43
Provides repository operations, URL parsing, and dependency handling
44
for Git-based dependencies.
45
"""
46
47
def __init__(self, work_dir: Path):
48
"""
49
Initialize Git instance for a working directory.
50
51
Args:
52
work_dir: Path to Git repository root
53
"""
54
55
@property
56
def work_dir(self) -> Path:
57
"""Get the working directory path"""
58
59
def clone(self, repository: str, dest: Path) -> str:
60
"""
61
Clone a Git repository.
62
63
Args:
64
repository: Git repository URL
65
dest: Destination path for clone
66
67
Returns:
68
Path to cloned repository
69
"""
70
71
def checkout(self, rev: str, folder: Path | None = None) -> str:
72
"""
73
Checkout specific revision.
74
75
Args:
76
rev: Git revision (branch, tag, commit hash)
77
folder: Optional working directory
78
79
Returns:
80
Checked out revision hash
81
"""
82
83
def rev_parse(self, rev: str, folder: Path | None = None) -> str:
84
"""
85
Parse revision to get commit hash.
86
87
Args:
88
rev: Git revision to parse
89
folder: Optional working directory
90
91
Returns:
92
Full commit hash
93
"""
94
95
def get_ignored_files(self, folder: Path | None = None) -> list[str]:
96
"""
97
Get list of files ignored by Git.
98
99
Args:
100
folder: Optional working directory
101
102
Returns:
103
List of ignored file paths
104
"""
105
106
@classmethod
107
def normalize_url(cls, url: str) -> str:
108
"""
109
Normalize Git URL to standard format.
110
111
Args:
112
url: Git URL to normalize
113
114
Returns:
115
Normalized Git URL
116
"""
117
118
@classmethod
119
def parse_url(cls, url: str) -> dict[str, str | None]:
120
"""
121
Parse Git URL into components.
122
123
Args:
124
url: Git URL to parse
125
126
Returns:
127
Dictionary with URL components (protocol, resource, pathname, etc.)
128
"""
129
```
130
131
## Usage Examples
132
133
### Detecting VCS in Directory
134
135
```python
136
from pathlib import Path
137
from poetry.core.vcs import get_vcs
138
139
# Check if current directory is in a Git repository
140
project_path = Path.cwd()
141
vcs = get_vcs(project_path)
142
143
if vcs:
144
print(f"Found Git repository at: {vcs.work_dir}")
145
else:
146
print("No VCS found or directory is ignored")
147
```
148
149
### Working with Git Repositories
150
151
```python
152
from pathlib import Path
153
from poetry.core.vcs.git import Git
154
155
# Initialize Git instance for repository
156
repo_path = Path("/path/to/repo")
157
git = Git(repo_path)
158
159
# Clone a repository
160
dest_path = Path("/tmp/cloned-repo")
161
git.clone("https://github.com/user/repo.git", dest_path)
162
163
# Checkout specific revision
164
commit_hash = git.checkout("v1.2.3")
165
print(f"Checked out: {commit_hash}")
166
167
# Parse revision to get full hash
168
full_hash = git.rev_parse("HEAD")
169
print(f"Current commit: {full_hash}")
170
171
# Get ignored files
172
ignored = git.get_ignored_files()
173
print(f"Ignored files: {ignored}")
174
```
175
176
### URL Parsing and Normalization
177
178
```python
179
from poetry.core.vcs.git import Git
180
181
# Parse Git URL
182
url = "git+https://github.com/user/repo.git@v1.2.3#egg=package"
183
parsed = Git.parse_url(url)
184
print(f"Protocol: {parsed['protocol']}")
185
print(f"Resource: {parsed['resource']}")
186
print(f"Revision: {parsed['rev']}")
187
188
# Normalize URL
189
normalized = Git.normalize_url("git@github.com:user/repo.git")
190
print(f"Normalized: {normalized}")
191
```
192
193
## Git URL Formats
194
195
Poetry Core supports various Git URL formats:
196
197
### Standard Git URLs
198
- `git://github.com/user/repo.git`
199
- `git+ssh://git@github.com/user/repo.git`
200
- `git+https://github.com/user/repo.git`
201
202
### SSH URLs
203
- `git@github.com:user/repo.git`
204
- `ssh://git@github.com/user/repo.git`
205
206
### HTTP/HTTPS URLs
207
- `https://github.com/user/repo.git`
208
- `http://example.com/repo.git`
209
210
### With Revisions and Subdirectories
211
- `git+https://github.com/user/repo.git@v1.2.3`
212
- `git+https://github.com/user/repo.git@main#subdirectory=packages/core`
213
- `git+https://github.com/user/repo.git@abc123#egg=package&subdirectory=src`
214
215
## Exceptions
216
217
```python { .api }
218
class GitError(RuntimeError):
219
"""
220
Raised when Git operations fail.
221
222
This includes clone failures, checkout errors, revision parsing
223
problems, and other Git command execution issues.
224
"""
225
```
226
227
## Integration with Dependencies
228
229
The VCS support integrates with Poetry's dependency system through `VCSDependency`:
230
231
```python
232
from poetry.core.packages.vcs_dependency import VCSDependency
233
from poetry.core.constraints.version import parse_constraint
234
235
# Create VCS dependency
236
vcs_dep = VCSDependency(
237
name="my-package",
238
vcs="git",
239
source="https://github.com/user/repo.git",
240
rev="v1.2.3",
241
constraint=parse_constraint("*")
242
)
243
244
print(f"VCS: {vcs_dep.vcs}")
245
print(f"Source: {vcs_dep.source}")
246
print(f"Revision: {vcs_dep.rev}")
247
```