madomeda/VERSION_FIELD.md

---
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