Environment package sources

An environment package's source: is an external-source from (sigil build external). Its sha256: is the SHA-256 of the exact source archive bytes admitted to the store. An ordinary location downloads an archive:

(external-source location: "https://example.org/project-1.tar.gz"
                 sha256: "<64 lowercase hexadecimal digits>")

For a Git repository, import (sigil build git-source) and use git-source-location:

(external-source
  location: (git-source-location
              "https://git.usesigil.org/sigil/sigil-json.git"
              "1523ffc504043d9a46031708acc11697916b7434"
              "d9648c0cd3a455bde0c16dc00eb9e8a9f16a4c98")
  sha256: "8a235c456dba20ef52a9e3218c1ef0e6cce6e3bee738b8af411ad244017aaeb7")

The stored location is git+https://HOST/REPO.git#COMMIT:TREE. Both object IDs must be full, 40-character lowercase hexadecimal strings. Branches, tags, abbreviated IDs, embedded credentials, local file:/// locations, and unsupported transports are refused. A legacy recipe retains its existing (url LOCATION sha256: HASH) source form with this location string.

What the hashes cover

TREE is Git's tree object ID: it binds names, file contents, executable modes, and symlink targets. Submodules are refused. .git metadata is absent. Git fetches advertised refs in full, checks the commit and detached HEAD, and confirms the selected tree ID. This works with static HTTPS clones.

sha256: covers an uncompressed Git tar archive, not a compressed tarball or hash-directory result. The archive has these fixed settings:

  • Format tar, prefix source/, and mtime 2000-01-01T00:00:00Z.
  • tar.umask=0022, fixing regular-file modes to 0644 or 0755.
  • Git's deterministic tree ordering and archive headers, including the commit ID.
  • export-ignore and export-subst disabled through repository-local info/attributes, so files and substitution markers remain present.

Other committed Git attributes retain Git's archive behavior, including explicit line-ending conversion. The extracted archive is added to a fresh Git index and its tree must match TREE, including modes and symlinks. Global and system configuration and attributes are isolated. File mtimes, ownership, checkout location, and the caller's umask do not affect the archive bytes. Git must support archive --mtime.

Authoring and caching

materialize-git-source accepts a repository URL, commit, expected tree ID (or #f to discover it), destination archive, and private scratch directory. It returns the verified tree ID. Compute hash-file on the resulting archive to obtain sha256:. parse-git-source-location returns (repository commit tree).

The builder performs archive SHA-256 verification before file-store admission. An existing verified hash-cache entry needs no Git process or network access. Package canonical data, published channels, locks, and build receipts retain the existing location/checksum or content-addressed source-item representation.

Fetches disable credential helpers, prompts, hooks, templates, submodule recursion, replacement objects, and redirects. Only HTTPS transport is allowed. Clones and extraction checks run in private scratch inside the selected store. SHA-256 verification remains mandatory even after Git's commit and tree checks.

Offline tests can explicitly call (call-with-git-source-test-repository HTTPS-ORIGIN LOCAL-DIRECTORY THUNK). Within THUNK, materialization of that exact HTTPS origin reads the local Git repository with file transport. The mapping unwinds on return or error, and other HTTPS origins retain their normal transport restrictions. Public location validation stays HTTPS-only even within this test scope; package, channel, and recipe data cannot enable the mapping.