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

> Learn how Archify uses Git for source evidence, cloning repos and verifying commit SHAs to ensure diagram traceability and reproducibility. Discover source-verified diagrams.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-31

---

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

```bash

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

```bash

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

```bash

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

```bash

# 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

```json
{
  "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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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.