GitRefs class abstract interface Getting started

References of one repository: exact ref reads, symbolic refs and ref updates.

It implements GitRefReader, so it can be used wherever server code needs to read references. Every command runs inside the owning repository's context, so a derived view (an alternate index, extra environment variables) applies here too.

The operations behave the same in a bare repository and in a clone with a work tree. Every failure is a GitException, except where an operation documents a null result (an absent revision); the refusals a caller can treat are named on the operation.

Branch administration lives on GitBranches, tags on GitTags; this facade stays at the level of named references.

The names the write operations (setHead, updateRef, deleteRef) take are rejected before any command runs when they cannot name a reference: the rules documented on GitInvalidRefNameException. A full reference is a refs/... name under those rules, or one of the pseudo-references git maintains at the top level (HEAD, FETCH_HEAD, MERGE_HEAD, ORIG_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD); any other one-level name is refused. Revision expressions this facade resolves — exists, resetSoft — follow the grammar of GitRevisionResolver, including the rule that an expression starting with - names nothing.

final GitOid? main = await repo.refs.resolveRef('refs/heads/main');
final String? target = await repo.refs.symbolicTarget('HEAD');
final List<GitRef> branches =
    await repo.refs.listRefs(prefix: 'refs/heads/');
final bool known = await repo.refs.exists('main');
await repo.refs.updateRef('refs/heads/main', head, expectedOld: base);
await repo.refs.deleteRef('refs/heads/stale');
await repo.refs.resetSoft('main');
Implemented types

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

deleteRef(String name, {GitOid? expectedOld}) → Future<void>
Deletes name.
exists(String refName) → Future<bool>
Whether refName resolves to an object.
listRefs({String? prefix}) → Future<List<GitRef>>
Every reference whose full name starts with prefix; see GitRefReader.listRefs.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
resetSoft(String target) → Future<void>
Moves HEAD to target without touching the index or the work tree (git reset --soft).
resolveRef(String refName) → Future<GitOid?>
Resolves the exact reference refName; see GitRefReader.resolveRef.
override
setHead(String refName) → Future<void>
Makes HEAD a symbolic ref to refName.
symbolicTarget(String refName) → Future<String?>
Target of the symbolic reference refName; see GitRefReader.symbolicTarget.
override
toString() → String
A string representation of this object.
inherited
updateRef(String name, GitOid oid, {GitOid? expectedOld}) → Future<void>
Sets name to oid.

Operators

operator ==(Object other) → bool
The equality operator.
inherited