Get Vault File/Path Lineage
vault_get_file_historyTrace commit history for any file or directory in the vault, listing each commit that changed it, most recent first.
Instructions
Get the commit lineage (history) affecting a file or directory in canonical-vault — i.e. every commit that touched that path, most recent first.
Args:
path (string): File or directory path to trace (default: "" for whole-repo history)
ref (string): Branch, tag, or commit SHA to start from (default: 'main')
limit (number): Max commits to return, 1-100 (default: 20)
offset (number): Commits to skip for pagination (default: 0)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: For JSON format: { "path": string, "count": number, "commits": [{ "sha": string, "message": string, "author": string, "date": string, "url": string }], "has_more": boolean }
Examples:
Use when: "How has VARA_SPEC_1.0 evolved?" -> path="system-specs/VARA_SPEC_1.0.md"
Use when: "What's the recent commit lineage for the whole vault?" -> path=""
Don't use when: You need the full diff of one specific commit (use vault_get_commit instead)
Error Handling:
Returns "Error: ... not found" if the path or ref doesn't exist
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Branch, tag, or commit SHA to read from (default: 'main') | main |
| path | No | File or directory path to trace lineage for. Empty string means whole-repo history. | |
| limit | No | Maximum commits to return | |
| offset | No | Number of most-recent commits to skip, for pagination | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable | markdown |