Source declarations¶

okr supports CRAN snapshot entries and the milestone 0.1 subset of the R Remotes syntax. Package dependencies are not discovered transitively: every package or reference repository you want in the source tree must be declared.

CRAN packages¶

Under [packages], "*" selects the package version present in the configured dated snapshot. An explicit version pins that version; if it is no longer in the snapshot index, okr uses the corresponding CRAN archive URL.

[project]
snapshot = "2026-06-30"

[packages]
rpact = "*"
gsDesign = "3.6.4"

okr add rpact writes the wildcard form. Resolution is a lookup in PACKAGES.gz, not a dependency or version-constraint solver.

Remote grammar¶

[type::]body[@ref]

A ref may be a branch, tag, abbreviated commit, or full 40-character commit. Named refs are resolved and frozen to the exact commit in okr.lock. Branches and omitted refs produce a warning because their future target can move, but the completed lock remains reproducible. A full commit skips remote ref resolution.

GitHub alone also supports @*release:

okr add r-lib/testthat@\*release

The latest release tag is resolved through authenticated gh, GITHUB_TOKEN, or anonymous GitHub API access, then frozen to its commit.

Note that this selects the latest GitHub release, not the newest standalone Git tag. For a repository that publishes tags without releases, name the tag explicitly, for example owner/repo@v1.2.3.

Arbitrary Git hosts¶

Use git:: for GitHub Enterprise, self-hosted GitLab, Codeberg, SSH remotes, or any other transport supported by the host git executable:

[packages]
simlib = { git = "git@ghe.example:stats/simlib.git", ref = "v2.1" }

[references]
protocols = "git::https://codeberg.org/org/protocols.git@main"

okr invokes Git with explicit arguments and inherits your SSH configuration and credential helpers. It neither prompts for nor stores credentials.

Direct archives¶

A direct URL must point to a .tar.gz, .tgz, or .zip archive and use table form with the expected SHA-256 of the downloaded file:

[packages]
internalpkg = {
  url = "https://example.com/internalpkg_0.2.1.tar.gz",
  sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
}

[references]
tamethebeast = {
  url = "https://mirrors.mit.edu/CTAN/info/bibtex/tamethebeast.zip",
  sha256 = "4bbdb2d35190426f15d508723600c07e883c67e40fd9f857783c93f3b5130428",
}

Compute the pin from a downloaded copy with shasum -a 256 or sha256sum. This digest is checked before the artifact is committed to the cache.

okr identifies the archive format from the downloaded bytes rather than from the URL, and gzip tarballs and zip archives follow the same rules. The archive must contain one top-level directory, which is removed, and safe entries. Symbolic links are materialized as regular files containing their exact link-target bytes. Hard links, special files, absolute paths, and path traversal are rejected. Zip entries must be stored or deflate-compressed, which covers archives produced by common tools, forges, and mirrors.

The lock records a direct download as fetch-method = "tarball" for either archive format; the declared URL and sha256 pin identify the source.

Packages and references¶

The two sections intentionally behave differently.

References cannot use a CRAN-shaped value such as "*" or "1.2.3". Add a Git reference from the CLI with okr add --reference <spec>.

Pruning¶

Package vendoring excludes these paths by default, with case-insensitive glob matching:

• data/**, pkgdown/**, docs/**, .github/**, revdep/**;
• Git metadata matched by .git*;
• serialized data files such as *.rda, *.rds, and *.RData; and
• tests/** when include-tests = false.

Source and documentation useful to agents remain, including R/, src/, man/, vignettes/, inst/, NEWS*, DESCRIPTION, NAMESPACE, and licenses. Reference repositories use only the version-control exclusions by default because R-specific pruning would discard potentially important context.

Global vendor.exclude patterns and per-entry exclude patterns are merged on top of these defaults. Pruning affects the tree digest, so changing a pattern requires a new okr sync.

Not yet supported¶

Profiles, bundles, and transitive resolution are also roadmap features, not part of the current CLI.