How Archify Uses Git for Source Evidence: A Deep Dive into Source-Verified Diagrams

Archify treats every diagram as an immutable source-evidence artifact by cloning Git repositories, validating remote URLs, verifying exact commit SHAs, and retrieving file blobs via git show to guarantee traceability and reproducibility.

Understanding the provenance of visual documentation is critical for teams maintaining complex systems. Archify solves this by anchoring every diagram node to specific, verifiable Git commits. This article explores how the tt-a1i/archify repository implements Git-based source evidence, with specific implementation details from the source code.

Core Git Operations for Source Verification

Archify's evidence pipeline runs six distinct Git operations to establish trust. Each step is implemented in archify/renderers/shared/repository-evidence.mjs and orchestrated through the CLI in archify/bin/archify.mjs.

Repository Access and Cloning

The --repo-root flag initiates the evidence chain. Archify accepts either a local path or a remote HTTPS URL.

# Example: Pointing Archify at a specific repository and commit

archify render diagram.json \
    --repo-root https://github.com/tt-a1i/archify \
    --revision 9f1a1cf1afdc04d7b5406782b40dfec76d9bc798

When provided a remote URL, Archify clones the repository to a temporary or cached location before proceeding with verification.

Remote URL Validation

Archify confirms repository identity using git remote get-url. This prevents diagram metadata from pointing to forks or unrelated repositories that might contain different code.

# Internal validation command

git remote get-url origin

If the retrieved URL does not match the repository.url field in the diagram JSON, Archify aborts with an error referencing scripts/stage-clean-skill.mjs — specifically the "Unable to enumerate tracked Archify files" message.

Commit SHA Verification

Exact revision verification uses git rev-parse and git cat-file -t to confirm the SHA exists and is a valid commit object.

# Verify the SHA is a valid, reachable commit

git rev-parse 9f1a1cf1afdc04d7b5406782b40dfec76d9bc798^{commit}

# Alternative type check

git cat-file -t 9f1a1cf1afdc04d7b5406782b40dfec76d9bc798

This step guarantees immutability: the diagram references a specific point in Git history that cannot be altered.

File Blob Retrieval

For each node displaying source code, Archify extracts the exact file content at the verified revision.

# Retrieve a specific file at a specific commit

git show 9f1a1cf1afdc04d7b5406782b40dfec76d9bc798:bin/mco.js

The output becomes the canonical source displayed in the diagram. No local working directory files are used — only committed, verifiable blobs.

Source Evidence Metadata Structure

Archify embeds comprehensive provenance data in every generated diagram. The JSON schema includes repository-level and node-level evidence fields.

Repository Provenance Object

{
  "schemaVersion": 1,
  "verified": true,
  "repository": {
    "url": "https://github.com/mco-org/mco",
    "revision": "9f1a1cf1afdc04d7b5406782b40dfec76d9bc798",
    "shortRevision": "9f1a1cf"
  }
}

The verified boolean indicates whether Git validation succeeded. The shortRevision provides human-readable reference while maintaining exact traceability via the full revision SHA.

Per-Node Source References

Each diagram node includes an href linking directly to GitHub's blame view:

{
  "nodes": {
    "entry": [
      {
        "path": "bin/mco.js",
        "line": 1,
        "label": "npm entry",
        "href": "https://github.com/mco-org/mco/blob/9f1a1cf1afdc04d7b5406782b40dfec76d9bc798/bin/mco.js#L1"
      }
    ]
  }
}

These links enable one-click navigation from any diagram element to the exact source line in the original repository.

Caching and Deterministic Rendering

Once a revision passes verification, Archify caches retrieved blobs — typically in archify.zip. This optimization ensures:

• Deterministic renders: Subsequent runs produce identical output without re-cloning
• Offline capability: Verified evidence persists without network access
• Performance: Large repositories need only be fetched once per unique SHA

The cache key combines repository URL and full revision SHA, preventing collision between different sources or versions.

Error Handling and Verification Failures

Archify fails explicitly when Git checks cannot complete. Two primary error paths exist in the codebase:

Error Condition	Source Location	Error Message
Repository access failure	scripts/stage-clean-skill.mjs	"Unable to enumerate tracked Archify files"
Incomplete evidence receipt	archify/bin/archify.mjs	"Rendered source evidence receipt is incomplete"

These messages surface when:

• The repository URL is unreachable or malformed
• The specified commit SHA does not exist in the repository
• The remote URL does not match diagram metadata
• Network timeouts prevent blob retrieval

Implementation Files and Architecture

Three core files implement Git-based source evidence in Archify:

• archify/renderers/shared/repository-evidence.mjs — Core verification logic: remote validation, SHA parsing, blob retrieval, and metadata assembly
• archify/bin/archify.mjs — CLI argument parsing for --repo-root and --revision, error handling coordination
• docs/authoring-cookbook.md — User guidance on embedding proper repository references in diagram definitions

The evidence system is designed as a separation of concerns: the renderer module contains pure Git operations, while the CLI handles user interface and error presentation.

Summary

• Archify uses Git for source evidence by treating every diagram as a verified artifact anchored to immutable commits
• Six verification steps ensure integrity: clone/access, remote validation, SHA verification, blob retrieval, metadata embedding, and caching
• Failure modes are explicit with clear error messages from established source locations
• Generated diagrams contain full provenance including repository URL, exact revision, and direct links to source lines
• Caching via archify.zip enables deterministic, performant re-rendering without re-verification

Frequently Asked Questions

What Git commands does Archify run internally?

Archify executes git remote get-url for repository validation, git rev-parse and git cat-file -t for SHA verification, and git show <revision>:<path> for file content retrieval. These commands are issued through Node.js child processes in repository-evidence.mjs.

Can Archify work with private Git repositories?

Yes, provided the runtime environment has appropriate credentials. Archify uses standard Git authentication mechanisms; configure SSH keys or HTTPS credentials in the environment before running with --repo-root.

What happens if the commit SHA in my diagram is wrong?

Archify aborts rendering with an error from archify/bin/archify.mjs: "Rendered source evidence receipt is incomplete". The verification fails at the git rev-parse step, preventing generation of diagrams with unverifiable source claims.

Does Archify modify the target repository?

No. Archify performs read-only operations: remote URL inspection, commit existence checks, and blob retrieval. No commits, tags, or refs are created or modified in the source repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}