Lockfile (stacy.lock)

Records installed package versions for reproducible environments. Auto-generated by stacy lock and stacy install.

Purpose

• Reproducibility: Ensures identical packages across machines and over time
• Verification: SHA256 checksums detect corruption or tampering
• Documentation: Records exact sources for each package
• Collaboration: Teammates get the same versions you tested with

Format Specification

The lockfile uses TOML format with a defined schema:

# Auto-generated by stacy. Do not edit manually.
version = "1"                    # Lockfile format version

[packages.<name>]                # One section per package
version = "<version>"            # Version string (date or semver)
checksum = "sha256:<hash>"       # SHA256 of package contents

[packages.<name>.source]         # Where the package came from
type = "SSC" | "GitHub"          # Source type
name = "<name>"                  # Package name (SSC only)
repo = "<owner>/<repo>"          # Repository (GitHub only)
tag = "<ref>"                    # Git ref (GitHub only)

Annotated Example

# Auto-generated by stacy. Do not edit manually.
# Lockfile format version - stacy checks compatibility
version = "1"

# ─────────────────────────────────────────────────────────────
# SSC Package
# ─────────────────────────────────────────────────────────────
[packages.estout]
# Version comes from SSC metadata (typically a date)
version = "2024.03.15"
# SHA256 hash of all .ado and .sthlp files concatenated
checksum = "sha256:14af94e03edd2e5f12021a8967afe1eee2dc7ebd..."

[packages.estout.source]
type = "SSC"
name = "estout"

# ─────────────────────────────────────────────────────────────
# GitHub Package
# ─────────────────────────────────────────────────────────────
[packages.reghdfe]
# Version from git tag or commit
version = "6.12.3"
checksum = "sha256:8f9234ab12cd56ef78901234567890abcdef..."

[packages.reghdfe.source]
type = "GitHub"
repo = "sergiocorreia/reghdfe"
# Tag, branch, or commit SHA
tag = "v6.12.3"

How Checksums Work

Checksums verify that the installed package matches exactly what was recorded:

1. On install: stacy downloads the package, computes SHA256 of the contents
2. On lock: Computed hash is stored in stacy.lock
3. On verify: Cached package is re-hashed and compared to lockfile

The checksum covers all .ado and .sthlp files in the package, sorted and concatenated. This catches:

• Corrupted downloads
• SSC updates that changed the package
• Manual modifications to cached files

If checksums don’t match, stacy install fails with an error explaining the mismatch.

Fields Reference

Workflow

Creating a lockfile

# Add packages (creates/updates lockfile automatically)
stacy add estout reghdfe

# Or generate lockfile from existing stacy.toml
stacy lock

Installing from a lockfile

# Clone a project
git clone https://github.com/user/project
cd project

# Install exact versions from lockfile
stacy install

Verifying in CI

# Fails if lockfile doesn't match stacy.toml
stacy lock --check

Updating packages

# Update one package to latest
stacy update reghdfe

# Update all packages
stacy update

Version Control

Always commit both stacy.toml and stacy.lock. The lockfile is what ensures everyone gets the same package versions.

Troubleshooting

“Lockfile out of sync”

The lockfile doesn’t match stacy.toml:

stacy lock  # Regenerate

“Checksum mismatch”

The cached package differs from what’s in the lockfile:

stacy cache packages clean  # Clear cache
stacy install               # Re-download

Merge conflicts in lockfile

After a git merge with conflicts:

# Resolve stacy.toml conflicts first, then:
stacy lock  # Regenerate lockfile

See Also

• stacy install - Install packages from lockfile
• stacy lock - Generate/verify lockfile
• stacy add - Add packages
• Project Config - The stacy.toml file