git – Keystone Core

git

Manages a git working tree on the agent: clones a repository to a path and optionally tracks a revision on the remote. Idempotent: re-applying an unchanged declaration reports no change.

Category: Files & VCS

States

State	Meaning
`present`	A working tree exists at the declaration name, cloned from `url`, with the named remote pointing at `url`. The checked-out revision is set from `rev` on the initial clone but not enforced afterward.
`latest`	Like `present`, and HEAD matches `rev` on the remote (default: the remote’s default branch). Apply fetches and, with `force`, hard-resets the current ref to the fetched commit.
`absent`	The path does not exist. A non-repo directory at the path is left in place with an error.

Parameters

Parameter	Type	Description
`url`	string	Repository URL. Required for `present` and `latest`; rejected for `absent`.
`rev`	string	Branch, tag, or SHA to track. `HEAD` means the remote’s default branch. Default: `HEAD`.
`depth`	int	Shallow-clone depth; `0` means a full clone. Default: `0`.
`remote`	string	Name of the git remote. Default: `origin`.
`force`	bool	Let `latest` discard local changes during a hard reset. Defaults to `true` for `latest`; opt out with `force: false`.

Examples

Clone a repository once

present clones if the tree is missing and does not enforce the revision thereafter.

git:
  /opt/myapp/src:
    state: present
    url: https://example.com/myorg/myapp.git
    rev: v1.2.0

Track a branch on the remote

latest fetches and hard-resets the current ref to match the remote.

git:
  /opt/myapp/src:
    state: latest
    url: https://example.com/myorg/myapp.git
    rev: main
    remote: upstream
    depth: 1

Remove a working tree

git:
  /opt/myapp/src:
    state: absent

Notes

Distro-agnostic: shells out to the git binary via a provider. Mutating operations fail when git is not installed.
url is required for present/latest and rejected (along with rev, depth, remote) for absent.
On latest, rev updates the current ref, not a named local branch; it does not switch branches.
Out of scope in v0.1: authentication (deploy keys, credential helpers, token rotation, SSH host keys), submodules, sparse/partial/bare checkouts, and server-side rev resolution for the present up-to-date check (which deliberately does not contact the remote).

config langpkg