madomeda/VERSION_FIELD.md

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:

---
version: v1.0.0
---

Without Git Tag

Git history:

0463d73 Add file without tag

Resulting frontmatter:

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

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

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:

git tag -a v2.1.0 -m "Release 2.1.0"

Files modified in this commit will have:

version: v2.1.0

Development Builds

Commits without tags automatically get short hash:

version: a3f9c21

Best Practices

1. Tag releases: Use semantic versioning for releases

   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:

# 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