Guide Git

Git

ARO has a native Git integration built on libgit2. Operations against <git> are typed actions, not shell-outs to the git binary, except for Push, Pull, and Clone which require credential handling and shell out to the system git CLI.

Git actions and the <git> system object are introduced in ARO-0080. They are available on macOS and Linux today; Windows builds skip the module.

The <git> System Object

<git> represents a Git repository.

Form	Repository
<git>	Current working directory
<git: "/srv/repo">	Repository at the given path

The same object is used for both reads (Retrieve, Pull, Clone) and writes (Stage, Commit, Push, Tag, Checkout).

Reading State

Retrieve is the REQUEST action for Git. The result name picks what to read:

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

Status

Retrieve the <status> from the <git>.
Extract the <branch> from the <status: branch>.
Extract the <clean>  from the <status: clean>.
Extract the <files>  from the <status: files>.

Log "On branch ${branch}" to the <console>.

status exposes branch, clean (boolean), and files (per-file change list).

Log

Retrieve the <log> from the <git>.
For each <entry> in <log> {
    Extract the <hash>    from the <entry: short>.
    Extract the <message> from the <entry: message>.
    Extract the <author>  from the <entry: author>.
    Log "${hash} ${message} (${author})" to the <console>.
}

Each log entry has short, hash, message, author, email, timestamp.

Branch

Retrieve the <branch> from the <git>.
Log "Current branch: ${branch}" to the <console>.

Staging and Committing

Stage  the <files>  to the <git> with ".".
Commit the <result> to the <git> with "feat: add login flow".

Stage's with clause accepts:

• "." (everything)
• A single path string
• A list of paths

Commit returns a commit object (hash, short, message, author) and emits git.commit.

Push, Pull, Clone

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

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

These three shell out to the git CLI. Make sure git is on $PATH and that the user running ARO has any credentials it needs (SSH key, credential helper, or token).

Clone accepts an optional branch field:

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

Branches and Tags

Checkout the <branch> from the <git> with "feature/x".

Tag the <release> for the <git> with "v1.0.0".

Tag the <release> for the <git> with {
    name: "v1.0.0",
    message: "First stable release"
}.

Action Summary

Verb	Role	Prepositions	Notes
Retrieve	REQUEST	from	<status>, <log>, <branch>
Stage	OWN	to, for	with accepts ".", path, list
Commit	EXPORT	to, with	Emits git.commit
Pull	REQUEST	from	Shell-out, emits git.pull
Push	EXPORT	to, with	Shell-out, emits git.push
Clone	REQUEST	from, with	Shell-out, emits git.clone
Checkout	OWN	from, to, with	Emits git.checkout
Tag	EXPORT	for, with	Emits git.tag

Git Events

Every mutating Git action emits a runtime event. Handler feature sets are written exactly like other event handlers:

Event	Trigger	Payload
GitCommit	Commit	hash, message, author
GitPush	Push	branch
GitPull	Pull	branch
GitCheckout	Checkout	ref
GitTag	Tag	name
GitClone	Clone	url, path

(Notify Release: GitTag Handler) {
    Extract the <name> from the <event: name>.
    Send the <release-note> to the <slack-channel> with "Released ${name}".
    Return an <OK: status> for the <notification>.
}

Common Patterns

CI Auto-Commit

(Auto Commit: CI) {
    Retrieve the <status> from the <git>.
    Extract  the <clean>  from the <status: clean>.

    Return an <OK: status> for "nothing to commit" when <clean> = true.

    Stage  the <files>  to the <git> with ".".
    Commit the <commit> to the <git> with "chore: auto-commit ${run-id}".
    Push   the <result> to the <git>.

    Return an <OK: status> with <commit>.
}

Audit Walk

(Audit Recent Commits: Audit) {
    Retrieve the <log> from the <git>.
    For each <entry> in <log> {
        Extract the <author> from the <entry: author>.
        Emit a <CommitSeen: event> with <entry> when <author> != "ci-bot".
    }
    Return an <OK: status> for the <walk>.
}

Release Tagger

(Tag Release: Releases) {
    Extract the <version> from the <event: version>.
    Tag      the <release> for the <git> with {
        name: <version>,
        message: "Release ${version}"
    }.
    Push the <result> to the <git> with "tags".
    Return an <OK: status> with <release>.
}

When to Use Exec Instead

The native action set covers the most common operations. For things it doesn't expose — git bisect, git rebase, custom plumbing — drop down to Exec:

Exec the <result> for the <command: "git"> with ["bisect", "start"].

Prefer the native actions where they fit: they're typed, emit events, and don't depend on the git binary for read-only work.

Next Steps

• Reference: Actions — full action reference
• Reference: System Objects — <git> and other system objects
• Guide: Events — handling Git events