0
# VCS Integration
1
2
Extract version information from version control systems with support for Git, Mercurial, Darcs, Subversion, Bazaar, Fossil, and Pijul.
3
4
## Capabilities
5
6
### Auto-Detection
7
8
Automatically detect the version control system and extract version information from the current repository.
9
10
```python { .api }
11
@classmethod
12
def from_any_vcs(
13
cls,
14
pattern: Union[str, Pattern] = Pattern.Default,
15
latest_tag: bool = False,
16
tag_dir: str = "tags",
17
tag_branch: Optional[str] = None,
18
full_commit: bool = False,
19
strict: bool = False,
20
path: Optional[Path] = None,
21
pattern_prefix: Optional[str] = None,
22
ignore_untracked: bool = False,
23
commit_length: Optional[int] = None,
24
) -> "Version"
25
```
26
27
**Parameters**:
28
- `pattern`: Regular expression or Pattern enum for parsing tags
29
- `latest_tag`: Use the latest tag by date instead of the latest by version
30
- `tag_dir`: Directory containing tags (for Subversion)
31
- `tag_branch`: Limit search to specific branch (for Git)
32
- `full_commit`: Include full commit hash instead of abbreviated
33
- `strict`: Raise exception if no tags found
34
- `path`: Repository path (defaults to current directory)
35
- `pattern_prefix`: Additional prefix for pattern matching
36
- `ignore_untracked`: Ignore untracked files when determining dirty state
37
- `commit_length`: Length of commit hash to use
38
39
**Usage Examples**:
40
41
```python
42
from dunamai import Version, Pattern
43
from pathlib import Path
44
45
# Auto-detect VCS in current directory
46
version = Version.from_any_vcs()
47
print(version.serialize()) # e.g., "1.2.3.post7.dev0+g29045e8"
48
49
# Auto-detect with custom options
50
version = Version.from_any_vcs(
51
pattern=Pattern.DefaultUnprefixed,
52
full_commit=True,
53
strict=True
54
)
55
56
# Auto-detect in specific directory
57
version = Version.from_any_vcs(path=Path("/path/to/repo"))
58
59
# Use latest tag by date instead of version
60
version = Version.from_any_vcs(latest_tag=True)
61
```
62
63
### Git Integration
64
65
Extract version information specifically from Git repositories with Git-specific options.
66
67
```python { .api }
68
@classmethod
69
def from_git(
70
cls,
71
pattern: Union[str, Pattern] = Pattern.Default,
72
latest_tag: bool = False,
73
tag_branch: Optional[str] = None,
74
full_commit: bool = False,
75
strict: bool = False,
76
path: Optional[Path] = None,
77
pattern_prefix: Optional[str] = None,
78
ignore_untracked: bool = False,
79
commit_length: Optional[int] = None,
80
) -> "Version"
81
```
82
83
**Git-Specific Parameters**:
84
- `tag_branch`: Only consider tags reachable from this branch
85
- `ignore_untracked`: Don't consider untracked files when determining dirty state
86
87
**Usage Examples**:
88
89
```python
90
from dunamai import Version
91
92
# Basic Git version extraction
93
version = Version.from_git()
94
95
# Git with branch filtering
96
version = Version.from_git(tag_branch="main")
97
98
# Git ignoring untracked files
99
version = Version.from_git(ignore_untracked=True)
100
101
# Git with full commit hash
102
version = Version.from_git(full_commit=True, commit_length=40)
103
104
# Git with custom tag pattern
105
version = Version.from_git(
106
pattern=r"^release-(?P<base>\d+\.\d+\.\d+)$",
107
pattern_prefix="release-"
108
)
109
```
110
111
### Mercurial Integration
112
113
Extract version information from Mercurial repositories.
114
115
```python { .api }
116
@classmethod
117
def from_mercurial(
118
cls,
119
pattern: Union[str, Pattern] = Pattern.Default,
120
latest_tag: bool = False,
121
full_commit: bool = False,
122
strict: bool = False,
123
path: Optional[Path] = None,
124
pattern_prefix: Optional[str] = None,
125
commit_length: Optional[int] = None,
126
) -> "Version"
127
```
128
129
**Usage Examples**:
130
131
```python
132
from dunamai import Version
133
134
# Basic Mercurial version extraction
135
version = Version.from_mercurial()
136
137
# Mercurial with custom commit length
138
version = Version.from_mercurial(commit_length=12)
139
```
140
141
### Darcs Integration
142
143
Extract version information from Darcs repositories.
144
145
```python { .api }
146
@classmethod
147
def from_darcs(
148
cls,
149
pattern: Union[str, Pattern] = Pattern.Default,
150
latest_tag: bool = False,
151
strict: bool = False,
152
path: Optional[Path] = None,
153
pattern_prefix: Optional[str] = None,
154
commit_length: Optional[int] = None,
155
) -> "Version"
156
```
157
158
**Usage Examples**:
159
160
```python
161
from dunamai import Version
162
163
# Basic Darcs version extraction
164
version = Version.from_darcs()
165
166
# Darcs with strict mode
167
version = Version.from_darcs(strict=True)
168
```
169
170
### Subversion Integration
171
172
Extract version information from Subversion repositories with tag directory support.
173
174
```python { .api }
175
@classmethod
176
def from_subversion(
177
cls,
178
pattern: Union[str, Pattern] = Pattern.Default,
179
latest_tag: bool = False,
180
tag_dir: str = "tags",
181
strict: bool = False,
182
path: Optional[Path] = None,
183
pattern_prefix: Optional[str] = None,
184
commit_length: Optional[int] = None,
185
) -> "Version"
186
```
187
188
**Subversion-Specific Parameters**:
189
- `tag_dir`: Directory containing tags (default: "tags")
190
191
**Usage Examples**:
192
193
```python
194
from dunamai import Version
195
196
# Basic Subversion version extraction
197
version = Version.from_subversion()
198
199
# Subversion with custom tag directory
200
version = Version.from_subversion(tag_dir="releases")
201
```
202
203
### Bazaar Integration
204
205
Extract version information from Bazaar repositories.
206
207
```python { .api }
208
@classmethod
209
def from_bazaar(
210
cls,
211
pattern: Union[str, Pattern] = Pattern.Default,
212
latest_tag: bool = False,
213
strict: bool = False,
214
path: Optional[Path] = None,
215
pattern_prefix: Optional[str] = None,
216
commit_length: Optional[int] = None,
217
) -> "Version"
218
```
219
220
**Usage Examples**:
221
222
```python
223
from dunamai import Version
224
225
# Basic Bazaar version extraction
226
version = Version.from_bazaar()
227
```
228
229
### Fossil Integration
230
231
Extract version information from Fossil repositories.
232
233
```python { .api }
234
@classmethod
235
def from_fossil(
236
cls,
237
pattern: Union[str, Pattern] = Pattern.Default,
238
latest_tag: bool = False,
239
strict: bool = False,
240
path: Optional[Path] = None,
241
pattern_prefix: Optional[str] = None,
242
commit_length: Optional[int] = None,
243
) -> "Version"
244
```
245
246
**Usage Examples**:
247
248
```python
249
from dunamai import Version
250
251
# Basic Fossil version extraction
252
version = Version.from_fossil()
253
```
254
255
### Pijul Integration
256
257
Extract version information from Pijul repositories.
258
259
```python { .api }
260
@classmethod
261
def from_pijul(
262
cls,
263
pattern: Union[str, Pattern] = Pattern.Default,
264
latest_tag: bool = False,
265
strict: bool = False,
266
path: Optional[Path] = None,
267
pattern_prefix: Optional[str] = None,
268
commit_length: Optional[int] = None,
269
) -> "Version"
270
```
271
272
**Usage Examples**:
273
274
```python
275
from dunamai import Version
276
277
# Basic Pijul version extraction
278
version = Version.from_pijul()
279
```
280
281
### Explicit VCS Selection
282
283
Use a specific VCS type instead of auto-detection.
284
285
```python { .api }
286
@classmethod
287
def from_vcs(
288
cls,
289
vcs: Vcs,
290
pattern: Union[str, Pattern] = Pattern.Default,
291
latest_tag: bool = False,
292
tag_dir: str = "tags",
293
tag_branch: Optional[str] = None,
294
full_commit: bool = False,
295
strict: bool = False,
296
path: Optional[Path] = None,
297
pattern_prefix: Optional[str] = None,
298
ignore_untracked: bool = False,
299
commit_length: Optional[int] = None,
300
) -> "Version"
301
```
302
303
**Usage Examples**:
304
305
```python
306
from dunamai import Version, Vcs
307
308
# Explicitly use Git
309
version = Version.from_vcs(Vcs.Git)
310
311
# Explicitly use Mercurial with options
312
version = Version.from_vcs(
313
Vcs.Mercurial,
314
full_commit=True,
315
strict=True
316
)
317
```
318
319
## Common Patterns
320
321
### Repository Detection
322
323
```python
324
from dunamai import Version
325
from pathlib import Path
326
327
# Try multiple paths
328
paths = [Path("."), Path("../"), Path("/some/repo")]
329
for path in paths:
330
try:
331
version = Version.from_any_vcs(path=path, strict=True)
332
print(f"Found version {version} in {path}")
333
break
334
except Exception as e:
335
print(f"No version found in {path}: {e}")
336
```
337
338
### Fallback Strategy
339
340
```python
341
from dunamai import Version, Vcs
342
343
# Try specific VCS first, fall back to auto-detection
344
try:
345
version = Version.from_git(strict=True)
346
except:
347
try:
348
version = Version.from_any_vcs(strict=True)
349
except:
350
version = Version("0.0.0") # Ultimate fallback
351
```
352
353
### Custom Tag Patterns
354
355
```python
356
from dunamai import Version
357
358
# Custom pattern for release tags like "release-1.2.3"
359
version = Version.from_any_vcs(
360
pattern=r"^release-(?P<base>\d+\.\d+\.\d+)(-(?P<stage>\w+)\.(?P<revision>\d+))?$"
361
)
362
363
# Pattern for tags with metadata like "v1.2.3+linux"
364
version = Version.from_any_vcs(
365
pattern=r"^v(?P<base>\d+\.\d+\.\d+)(\+(?P<tagged_metadata>.+))?$"
366
)
367
```