GitRepository
The GitRepository type represents a Git repository.
remotes lists named remotes. remote(name) looks up one by name. These operations read configuration without contacting remote servers. Registered remotes override configured remotes with the same name.
defaultRemote selects the sole remote, otherwise origin, otherwise the selected branch's upstream remote. It returns null when none of these rules selects a remote. A workspace snapshot retains the upstream selection from capture, including when its HEAD is detached.
Credentials configured on the source repository remain available for the same remote after snapshotting. Other configured remotes use the caller's authentication. An ancestry comparison fails if complete history cannot be obtained.
Filter by branch ancestry
GitRef.contains checks whether another commit is reachable from the receiver's history. Comparing the workspace commit with the default remote's current HEAD determines whether the commit has reached the default branch.
Run CurrentCommit to obtain the workspace's GitRef ID, then pass it as $current to InDefaultBranch. noLock: true resolves the remote HEAD without a lock-file pin.
query CurrentCommit {
currentWorkspace {
git {
head {
id
}
}
}
}
query InDefaultBranch($current: ID!) {
currentWorkspace {
git {
head {
asRepository {
defaultRemote {
name
repository {
head(noLock: true) {
contains(other: $current)
}
}
}
}
}
}
}
}
API reference
A git repository.
Implements Node
branches- branches that match any of the given glob patterns.
id- A unique identifier for this GitRepository.
tags- tags that match any of the given glob patterns.
url- The URL of the git repository.
asWorkspace- Creates a synthetic workspace from this repository's HEAD and uncommitted file changes.
branch- Returns details of a branch.
bundle- Pack the given refs and the objects needed to reconstruct them into a Git bundle.
commit- Returns details of a commit.
defaultRemote- Return the sole remote, otherwise origin, otherwise the selected branch's upstream remote, otherwise null.
head- Returns details for HEAD.
latest- Return the latest stable release tag, falling back to HEAD when no release exists.
ref- Returns details of a ref.
remote- Look up a remote by name. Fails when the remote does not exist.
remotes- List this repository's named remotes, with registered remotes overriding configured ones. Does not contact remote servers.
tag- Returns details of a tag.
uncommitted- Returns the changeset of uncommitted changes in the git repository.
withBundle- Import a Git bundle after fetching and verifying all of its prerequisites.
withContents- Replace this repository's storage with the supplied self-contained Git repository, retaining its logical URL and push destinations.
withRemote- Register a named remote on this repository, replacing any registered remote of the same name.
branches(patterns: [String!]): [String!]!
branches that match any of the given glob patterns.
patterns: [String!]Glob patterns (e.g., "refs/tags/v*").
id: ID!
A unique identifier for this GitRepository.
tags(patterns: [String!]): [String!]!
tags that match any of the given glob patterns.
patterns: [String!]Glob patterns (e.g., "refs/tags/v*").
url: String
The URL of the git repository.
asWorkspace(cwd: String = "/"): Workspace!
Creates a synthetic workspace from this repository's HEAD and uncommitted file changes.
Pending changes are applied at the repository root. The staging split is not preserved. The source repository is not modified.
cwd: String = "/"Current working directory inside the workspace root. Defaults to the workspace root.
branch(name: String!, noLock: Boolean = false): GitRef!
Returns details of a branch.
name: String!Branch's name (e.g., "main").
noLock: Boolean = falseIgnore the workspace lockfile for this lookup.
bundle(refs: [String!]!, base: GitRef): GitBundle!
Pack the given refs and the objects needed to reconstruct them into a Git bundle.
refs: [String!]!Refs to advertise in the bundle. At least one named ref is required.
base: GitRefA Git ref whose reachable objects are omitted and recorded as a prerequisite.
commit(id: String!): GitCommit!
Returns details of a commit.
id: String!Identifier of the commit (e.g., "b6315d8f2810962c601af73f86831f6866ea798b").
May be abbreviated to an unambiguous hex prefix (4-40 characters), which is expanded against locally available objects. Remote repositories (resolved via ls-remote) can only expand prefixes of already-fetched commits; use the full SHA otherwise.
defaultRemote: GitRemote
Return the sole remote, otherwise origin, otherwise the selected branch's upstream remote, otherwise null.
Frozen workspaces retain their captured upstream selection. Does not contact remote servers.
head(noLock: Boolean = false): GitRef!
Returns details for HEAD.
noLock: Boolean = falseIgnore the workspace lockfile for this lookup.
latest(version: String = "", noLock: Boolean = false): GitRef!
Return the latest stable release tag, falling back to HEAD when no release exists.
Release selection accepts an optional "v" prefix, incomplete versions, and zero-padded numeric components. This operation is pinned unless noLock is enabled.
version: String = ""Version query used to select the greatest matching release ref.
noLock: Boolean = falseIgnore the workspace lockfile for this lookup.
ref(name: String!, noLock: Boolean = false): GitRef!
Returns details of a ref.
name: String!Ref's name (can be a commit identifier, a tag name, a branch name, or a fully-qualified ref).
Commit identifiers may be abbreviated: an unambiguous hex prefix (4-40 characters) of a commit SHA resolves like git rev-parse, with named refs taking precedence. Abbreviated SHAs resolve against locally available objects, so remote repositories (resolved via ls-remote) can only expand prefixes of already-fetched commits; use the full SHA or a named ref otherwise.
The name may be followed by git revision suffixes, applied left to right:
~Nfollows first parents N times and^Nselects the Nth parent (~and^mean 1,^0is the commit itself), e.g.HEAD~3,main^2orabc1234~2. The result is a detached ref of the resulting commit; remote repositories fetch the history the walk needs. Other git revision syntax (^{...},@{...},:path, ranges) is not supported.A repository derived from a remote one (e.g. a workspace's history after a snapshot or commit) resolves names and commits it does not contain itself through that remote, with its authentication. Its branches and tags listings include the remote's.
noLock: Boolean = falseIgnore the workspace lockfile for this lookup.
remote(name: String!): GitRemote!
Look up a remote by name. Fails when the remote does not exist.
name: String!The remote's name.
remotes: [GitRemote!]!
List this repository's named remotes, with registered remotes overriding configured ones. Does not contact remote servers.
tag(name: String!, noLock: Boolean = false): GitRef!
Returns details of a tag.
name: String!Tag's name (e.g., "v0.3.9").
noLock: Boolean = falseIgnore the workspace lockfile for this lookup.
uncommitted: Changeset!
Returns the changeset of uncommitted changes in the git repository.
withBundle(bundle: GitBundle!, prerequisiteRef: String = ""): GitRepository!
Import a Git bundle after fetching and verifying all of its prerequisites.
bundle: GitBundle!The Git bundle to import.
prerequisiteRef: String = ""An optional remote ref hint for fetching a prerequisite when the remote does not allow fetches by object ID.
withContents(directory: Directory!): GitRepository!
Replace this repository's storage with the supplied self-contained Git repository, retaining its logical URL and push destinations.
Accepts a whole checkout (including .git and pending file edits), .git contents, or a bare repository. Does not initialize a repository, merge histories, or modify either input.
The receiver's logical routing wins over the supplied Git configuration; that configuration is not rewritten. Use Directory.asGit to open the supplied repository without retaining the receiver's routing.
When the receiver is a remote repository (or was derived from one), that remote is retained with its authentication: refs the supplied storage does not contain resolve through it.
directory: Directory!Existing Git storage to open. Git metadata and object dependencies must be contained in this directory.
withRemote(name: String!,url: String!,pushUrl: String = ""): GitRepository!
Register a named remote on this repository, replacing any registered remote of the same name.
Registered remotes are recorded in checkouts materialized from this repository (GitRef.tree, Workspace.git.directory), so remote-aware tooling like gh can resolve and fetch from them. The origin remote also routes push when no explicit destination is passed: its push URL, or its URL, becomes the default destination.
Routing metadata only, never a credential grant: pushes still authenticate with the caller's own credentials and require approval as usual.
name: String!The remote's name, e.g. "origin" or "upstream".
url: String!The remote's fetch URL.
pushUrl: String = ""Push destination, when pushes go somewhere other than url. Empty uses url.