class Agate::Repository

• Agate::Repository
• Reference
• Object

Defined in:

Constant Summary

INIT_OPTIONS_VERSION = 1

Constructors

• .clone_at(url : String, path : String | Path, credentials : Credentials::Provider | Nil = nil, bare : Bool = false) : Repository

  Clones a repository from a URL to a local path.

• .clone_at(url : String, path : String | Path, bare : Bool = false, &block : String, String | Nil, UInt32 -> Credentials::Credential | Nil) : Repository

  Clones with a block-based credential provider.

• .init(path : String | Path, bare = false) : Repository

  Initializes a new repository at path.

• .init(path : String | Path, &) : Repository

  Initializes a new repository, yielding an InitOptions builder for configuration.

Class Method Summary

• .discover(path : String | Path = ".") : Path

  Discovers a repository from a path, walking up the directory tree.

• .discover?(path : String | Path = ".") : Path | Nil

  Discovers a repository, returning nil if none is found.

• .open(path : String | Path = ".")

  Opens an existing repository at the given path.

• .open?(path : String | Path = ".") : Repository | Nil

  Returns the repository opened at path, or nil if not found.

Instance Method Summary

• #==(other : self)

  Compares this repository's underlying pointer to another's.

• #ahead_behind(local : OID, upstream : OID) : Tuple(Int32, Int32)

  Returns how far ahead and behind the local OID is from upstream.

• #apply(diff : Diff, location : ApplyLocation = ApplyLocation::Workdir) : Nil

  Applies a diff to the repository.

• #attr_add_macro(name : String, values : String) : Nil

  Adds a macro definition (e.g., "binary" expands to "-diff -merge -text").

• #attr_cache_flush : Nil

  Flushes the gitattributes cache, forcing a reload on next access.

• #attributes(path : String | Path, check : AttrCheck = AttrCheck::None) : Attributes

  Returns an attribute lookup proxy for the given path.

• #bare?

  Returns whether this repository is bare

• #blob_at(rev : String, path : String) : Blob | Nil

  Returns the blob at the given path in the given revision.

• #branches : BranchCollection

  Returns the collection of branches in this repository.

• #checkout_head(strategy : CheckoutStrategy = CheckoutStrategy::Safe) : Nil

  Updates the working directory to match HEAD.

• #checkout_index(index : Index | Nil = nil, strategy : CheckoutStrategy = CheckoutStrategy::Safe) : Nil

  Updates the working directory to match the index.

• #checkout_tree(target : Object, strategy : CheckoutStrategy = CheckoutStrategy::Force) : Nil

  Updates the working directory to match the given tree/commit.

• #cherrypick_commit(commit : Commit, our_commit : Commit, mainline : UInt32 = 0) : Index

  Cherry-picks a commit into the given base commit, returning the resulting index.

• #close : Nil

  Explicitly frees the underlying repository handle.

• #commondir : Path

  Gets this repository's commondir

• #config : Config

  Gets this repository's config.

• #config_snapshot : Config

  Gets a snapshot of this repository's config

• #default_signature : Signature | Nil

  Returns the default signature from user.name/email config, or nil.

• #descendant_of?(commit : OID, ancestor : OID) : Bool

  Returns true if commit is a descendant of ancestor.

• #each_id(&block : OID -> ) : Nil

  Iterates over all object IDs in the repository.

• #empty? : Bool

  Returns whether this repository is empty

• #exists?(oid : OID) : Bool

  Returns true if an object with the given OID exists in the repo.

• #fetch(remote_name : String = "origin", refspecs : Array(String) | Nil = nil, credentials : Credentials::Provider | Nil = nil) : Nil

  Fetches from a named remote.

• #head

  Gets the head of the repository

• #head=(refname : String) : Nil

  Sets HEAD to point at the given reference name.

• #head_detached? : Bool

  Returns true if HEAD is detached (pointing at a commit, not a branch).

• #head_unborn? : Bool

  Returns true if HEAD points to a branch with no commits.

• #ident : Ident

  Gets this repository's ident

• #index : Index

  Gets this repository's index.

• #last_commit : Commit

  Returns the HEAD commit.

• #lookup(oid : OID) : Object

  Looks up any object by OID.

• #merge_analysis(their_heads : Array(AnnotatedCommit)) : Tuple(MergeAnalysis, MergePreference)

  Performs merge analysis on the given annotated commits.

• #merge_base(oid1 : OID, oid2 : OID) : OID

  Finds the merge base between two commits.

• #merge_base?(oid1 : OID, oid2 : OID) : OID | Nil

  Finds the merge base, returning nil if there is none.

• #merge_commits(ours : Commit, theirs : Commit) : Index

  Merges two commits, returning the resulting index.

• #message : String | Nil

  Gets this repository's prepared message, or nil if there isn't any.

• #message=(x : Nil = nil)

  Clears this repository's prepared message

• #namespace : String | Nil

  Returns the namespace, or nil if none is set.

• #namespace=(ns : String | Nil) : Nil

  Sets the namespace.

• #odb : ODB

  Gets this repository object database.

• #path : Path

  Gets the path to this repository (usually the '.git/' folder)

• #path_ignored?(path : String | Path) : Bool

  Returns true if the given path is ignored by .gitignore.

• #push(remote_name : String = "origin", refspecs : Array(String) | Nil = nil, credentials : Credentials::Provider | Nil = nil) : Nil

  Pushes to a named remote.

• #read(oid : OID) : OdbObject

  Reads a raw object from the ODB.

• #read_header(oid : OID) : Tuple(Object::Type, UInt64)

  Reads just the header (type + size) of an object.

• #refdb : RefDB

  Gets this repository ref database.

• #references : ReferenceCollection

  Returns the collection of references in this repository.

• #remotes : RemoteCollection

  Returns the collection of remotes in this repository.

• #reset(target : Object, type : ResetType = ResetType::Mixed) : Nil

  Resets the repository to the given target.

• #reset_path(target : Object, pathspecs : Array(String)) : Nil

  Resets the index (and optionally working directory) for specific paths.

• #rev_parse(spec : String) : Object

  Parses a revision spec (e.g., "HEAD", "HEAD~2", tag name, SHA).

• #rev_parse_oid(spec : String) : OID

  Parses a revision spec and returns just the OID.

• #revert(commit : Commit) : Nil

  Reverts a commit in the working directory and index, like git revert.

• #revert_commit(commit : Commit, our_commit : Commit, mainline : UInt32 = 0) : Index

  Reverts a commit against the given base commit, returning the resulting index.

• #shallow? : Bool

  Returns true if the repository is a shallow clone.

• #status(path : String | Path) : StatusEntry::Flags

  Returns the status flags for a single file.

• #status : StatusList

  Returns the status list for this repository.

• #submodules : SubmoduleCollection

  Returns the collection of submodules.

• #tags : TagCollection

  Returns the collection of tags in this repository.

• #walk : Walker

  Creates a new commit walker for this repository.

• #workdir : Path | Nil

  Gets the path to this repository's working directory, or nil for bare repos.

• #workdir=(path : String | Path)

  Sets the path to this repository's working directory

• #worktree?

  Returns whether this repository is a worktree

• #worktrees : Array(String)

  Lists the names of all linked worktrees.

• #write(data : Bytes | String, type : Object::Type) : OID

  Writes raw data to the ODB, returning the OID.

Constructor Detail

repo = Repository.clone_at("https://github.com/user/repo.git", "/tmp/repo")
repo = Repository.clone_at(url, path, credentials: Credentials::UserPassword.new("user", "token"))
repo = Repository.clone_at(url, path, bare: true)

repo = Repository.init("/path/to/repo")
repo = Repository.init("/path/to/bare.git", bare: true)

repo = Repository.init("/path/to/repo") do |opts|
  opts.initial_head = "main"
  opts.mkpath = true
end

Class Method Detail

repo = Repository.open("/path/to/repo")
repo.head.name # => "refs/heads/main"
repo.bare?     # => false

Instance Method Detail

ahead, behind = repo.ahead_behind(local_oid, upstream_oid)

attrs = repo.attributes("lib/main.cr")
attrs["diff"]   # => "crystal"
attrs["text"]   # => true
attrs["binary"] # => nil

repo.descendant_of?(child_oid, parent_oid) # => true

repo.fetch("origin")
repo.fetch("origin", credentials: Credentials::UserPassword.new("user", "token"))

repo.path_ignored?("build/output.o") # => true
repo.path_ignored?("src/main.cr")    # => false

repo.push("origin", refspecs: ["refs/heads/main"])

repo.revert(bad_commit)

index = repo.revert_commit(bad_commit, head_commit)