Sources and distribution¶
Distribution is outside the directory format. An overlay MAY be copied, archived, served over HTTP, listed in a catalog, kept inside a larger repository, or stored in version control.
Source form¶
Optional Extension. A consumer's configuration names where an overlay comes from with a source string:
source = [ "git+" ] location [ "@" ref ] [ "#" path ]
locationis a local path, anhttporhttpsURL, or a Git repository: one ending in.git, startinggit@,ssh://orgit://, or prefixedgit+.refexists only for a Git location: a branch, tag or commit, with no/,:or\. It is the part after the last@, when that@is not part ofgit@host, a URL's user information, or a scheme. Absent, the remote's default branch. A URL's authority runs from after://to the first/or?, and an@in it is always user information:git+https://evil.example@github.comnames the hostgithub.comwith a user, and no ref.pathis the part after the first#: the overlay's root inside the location, with leading and trailing/removed; what remains is a relative path, or the source is refused. Absent, the location's root is the overlay.- A Git location is a local path, an scp-like
user@host:path, or a URL whose scheme ishttps,http,ssh,gitorfile. A location holding::(Git's remote-helper syntax, which runs a program) is refused, and so is a location, ref or host starting with-, since it would reachgitorsshas an option, and so is a user, port or scp-like path that starts with-once percent-decoded (ssh://%2doProxyCommand=x@host/a.git). A consumer passes the location after--, and limits Git's transports (protocol.allow) to the ones it accepts. - A source holds no control character (U+0000–U+001F, U+007F–U+009F), no U+2028 or U+2029 and no
character that reorders displayed text (U+200E, U+200F, U+202A–U+202E, U+2066–U+2069), and an
authority holds no
\, which URL parsers read differently: what a person is shown must be what is fetched.
| Source | Kind | Location | Ref | Path |
|---|---|---|---|---|
./overlays/rust |
directory | ./overlays/rust |
||
https://github.com/example/agents.git@v2#overlays/rust |
git | https://github.com/example/agents.git |
v2 |
overlays/rust |
git@github.com:example/agents.git |
git | git@github.com:example/agents.git |
||
git+https://example.org/agents@main#rust |
git | https://example.org/agents |
main |
rust |
/srv/overlays@v2 |
directory | /srv/overlays@v2 |
||
https://example.org/overlays/rust |
URL | https://example.org/overlays/rust |
A location is a Git location as above, else a URL when it contains ://, else a
directory. Surrounding whitespace is removed first; an empty source is an error.
A pinned source pairs a source with a pin. For a reproducible install the ref is a full commit id (40 or 64 hexadecimal digits) and the pin is the tree digest; a branch or a tag can move.
A consumer that logs or stores a source removes any user information and query string from it first
(https://user:secret@host/x.git?token=t is shown as https://host/x.git). Who writes a source limits
what it can be: a catalog from elsewhere names nothing on the
consumer's machine, and neither does a manifest, which holds no credential
either.
Status: dotagents parses exactly this form (
<location>[@<ref>][#<path>]) for repositories and overlays. It also reads registries (a JSON, TOML or YAML mapping from name or alias to source, relative entries resolved beside the registry: the minimal form of a catalog) and, with optional dependencies, URI schemes such aszip:,sftp:ands3:. It consults--repo, thenAGENTS_OVERLAYS_REPO_<KEY>, thenAGENTS_OVERLAYS_REPO, then the project's and the user'sdotagents.{json,toml,yaml,yml}; the first that offers a name wins. That order is dotagents policy.
Provenance¶
A manager records, for each installed overlay, the source with its user information removed, the resolved commit when there is one, the tree digest, and when it was fetched. It shows source and ref before it activates an overlay for the first time, and the difference before it updates one.
AOS does not require GitHub, Git, or any registry protocol.