Git

The <git> object

ARO talks to Git through libgit2, linked into the runtime — there is no git subprocess for the local operations. The bare <git> object discovers the enclosing repository by walking upward from the current working directory, exactly the way the git command does. Give it a path when you mean a specific repository, and it is opened as given, with no discovery:

Retrieve the <status> from the <git>.
Retrieve the <other-status> from the <git: "/srv/checkouts/api">.

Reading the repository

Status, log and branch are all Retrieve. Which one you get is decided by the name you bind, so the statement reads as the question it asks:

Retrieve the <status> from the <git>.
Retrieve the <log> from the <git>.
Retrieve the <branch> from the <git>.

Log <branch> to the <console>.

Staging and committing

Stage the <staged> to the <git> with ".".
Stage the <staged-one> to the <git> with "src/main.aro".
Stage the <staged-many> to the <git> with ["a.txt", "b.txt"].

Commit the <commit> to the <git> with "feat: add the ordering endpoint".

Remotes

Push and Pull shell out to the git CLI, because they need the credential helpers and transport configuration the user already has set up.

Pull the <updates> from the <git>.
Push the <pushed> to the <git>.

Branches, tags and clones

Checkout the <switched> from the <git> with "feature/new".
Tag the <release> for the <git> with "v1.0.0".

Clone the <repo> from the <git> with {
    url: "https://github.com/user/repo.git",
    path: "./cloned"
}.

(* `branch:` checks that ref out at clone time *)
Clone the <pinned> from the <git> with {
    url: "https://github.com/user/repo.git",
    path: "./cloned",
    branch: "develop"
}.

The action table

Git events

Every mutating Git action emits an event a feature set can subscribe to. The business activity is the event name plus Handler, the same shape every other handler uses:

(Notify Commit: GitCommit Handler) {
    Extract the <hash> from the <event: hash>.
    Extract the <message> from the <event: message>.
    Extract the <author> from the <event: author>.
    Log "${hash} by ${author}: ${message}" to the <console>.
    Return an <OK: status> for the <hash>.
}