Test User
140 lines
2.8 KiB
Markdown
140 lines
2.8 KiB
Markdown
---
|
|
title: Version Field Behavior
|
|
created: '2025-10-23T18:33:48+02:00'
|
|
status: draft
|
|
priority: 5
|
|
published: false
|
|
tags: []
|
|
reviewers: []
|
|
---
|
|
# Version Field Behavior
|
|
|
|
## Overview
|
|
|
|
The `version` field in frontmatter is derived from git metadata with tag preference.
|
|
|
|
## Priority
|
|
|
|
1. **Latest commit tag** (if exists)
|
|
2. **Short commit hash** (7 characters) as fallback
|
|
|
|
## Examples
|
|
|
|
### With Git Tag
|
|
|
|
**Git history:**
|
|
```
|
|
853ace5 (tag: v1.0.0) Add comparison test file
|
|
```
|
|
|
|
**Resulting frontmatter:**
|
|
```yaml
|
|
---
|
|
version: v1.0.0
|
|
---
|
|
```
|
|
|
|
### Without Git Tag
|
|
|
|
**Git history:**
|
|
```
|
|
0463d73 Add file without tag
|
|
```
|
|
|
|
**Resulting frontmatter:**
|
|
```yaml
|
|
---
|
|
version: 0463d73
|
|
---
|
|
```
|
|
|
|
## Implementation Details
|
|
|
|
### Repository Module
|
|
The `get_file_history()` method in `core/repository.py` extracts:
|
|
- `latest_hash`: The most recent commit hash for the file
|
|
- `latest_tag`: The tag associated with the latest commit (if any)
|
|
|
|
```python
|
|
# Get tag for latest commit if any
|
|
latest_tag = ''
|
|
if latest_hash:
|
|
result = subprocess.run(
|
|
['git', 'describe', '--tags', '--exact-match', latest_hash],
|
|
...
|
|
)
|
|
latest_tag = result.stdout.strip() if result.returncode == 0 else ''
|
|
```
|
|
|
|
### Processor Module
|
|
The `_get_heuristic_value()` method in `core/processor.py` prefers the tag:
|
|
|
|
```python
|
|
elif field == 'version':
|
|
# Prefer latest tag, fallback to short hash
|
|
latest_tag = git_info.get('latest_tag', '')
|
|
if latest_tag:
|
|
return latest_tag
|
|
latest_hash = git_info.get('latest_hash', '')
|
|
return latest_hash[:7] if latest_hash else ''
|
|
```
|
|
|
|
## Use Cases
|
|
|
|
### Semantic Versioning
|
|
Tag commits with semantic versions:
|
|
```bash
|
|
git tag -a v2.1.0 -m "Release 2.1.0"
|
|
```
|
|
|
|
Files modified in this commit will have:
|
|
```yaml
|
|
version: v2.1.0
|
|
```
|
|
|
|
### Development Builds
|
|
Commits without tags automatically get short hash:
|
|
```yaml
|
|
version: a3f9c21
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Tag releases:** Use semantic versioning for releases
|
|
```bash
|
|
git tag -a v1.0.0 -m "Release 1.0.0"
|
|
git tag -a v1.1.0 -m "Release 1.1.0"
|
|
```
|
|
|
|
2. **Let development builds use hashes:** Don't tag every commit
|
|
|
|
3. **Consistency:** Use a consistent tagging scheme
|
|
- `v1.0.0` (recommended)
|
|
- `1.0.0`
|
|
- `release-1.0.0`
|
|
|
|
## Verification
|
|
|
|
Check what version will be used:
|
|
```bash
|
|
# For a specific file
|
|
git log -1 --oneline path/to/file.md
|
|
|
|
# Check if commit has a tag
|
|
git describe --tags --exact-match <commit-hash>
|
|
```
|
|
|
|
## Limitations
|
|
|
|
- Only exact tag matches are used (`--exact-match`)
|
|
- Annotated tags and lightweight tags both work
|
|
- If multiple tags point to same commit, git chooses one
|
|
- Tags must exist locally (not just on remote)
|
|
|
|
## Migration Notes
|
|
|
|
If upgrading from previous version where only short hash was used:
|
|
- Re-run madomeda to update version fields
|
|
- Files on tagged commits will switch from hash to tag
|
|
- Use `--whatif` to preview changes
|