grepo

Pin npm, cargo, and git sources into read-only grepo alias trees.

1|Updated Aug 24, 2025
One-click install
npx skills add https://github.com/tomrford/config --skill grepo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: grepo
Source: https://github.com/tomrford/config/tree/main/.agents/skills/grepo
Command: npx skills add https://github.com/tomrford/config --skill grepo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

grepo pins recurring read-only reference sources into a project-local grepo/ directory. grepo/.lock is the tracked source of truth; each grepo/<alias> is a generated symlink into a shared cached snapshot (a read-only tree with .git stripped).

Core Features & Use Cases

  • Lockfile-driven snapshots: A single source of truth for all alias trees and their sources.
  • Multi-source provenance: Supports npm packages, cargo crates, and git URLs, with subdir and ref handling.
  • Deterministic upgrades: Use grepo update to advance movable entries; grepo sync materializes what is recorded in the lockfile.
  • Reference management in projects: Alias trees under grepo/<alias> are read-only and are meant to be shared across the workspace.
  • Use Case: In a project with a suite of dependencies, grepo ensures each developer uses identical snapshot trees by symlinking grepo/<alias> references from a central cache.

Quick Start

Initialize grepo in your project, add references with grepo add, then run grepo sync or grepo update to materialize and refresh snapshots.

Frequently Asked Questions about grepo

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I manage project-local reference snapshots for reproducible builds?

Project-local reference snapshots are managed by pinning external sources into read-only trees under a grepo directory. A lockfile acts as the source of truth, symlinking aliases to cached snapshots to ensure deterministic builds across the workspace.

What's the best way to pin npm packages and cargo crates for deterministic updates?

Pinning npm packages and cargo crates is handled by adding sources to a lockfile and materializing them as read-only alias trees. Using a sync command applies lockfile pins while an update command advances movable entries for deterministic version control.

How does a lockfile-driven snapshot reduce drift across multiple developers?

A lockfile-driven snapshot reduces drift by serving as a tracked single source of truth for all reference sources. Each developer runs a sync command to materialize identical read-only trees via symlinks from a shared central cache, ensuring reproducible environments.

Can I use git repos with subdir and ref handling as local reference sources?

Git URLs can be used as reference sources with subdir and ref handling. The system pins specific commits and materializes the repository contents into read-only alias trees, stripping the .git directory to create stable project-local snapshots.

Why do alias trees under a grepo directory need to be read-only?

Alias trees must be read-only to prevent accidental modifications to the materialized snapshots. This ensures the cached external sources remain stable and reproducible across the workspace, allowing reliable deterministic updates driven solely by the lockfile.

Do I need a specific lockfile to initialize reference management in my project?

You need a project with a grepo/.lock file to initialize reference management. This lockfile is the tracked source of truth that records all alias trees, package sources, and commit pins required to control exactly what is materialized.