Xgit v0.3.0 Xgit.Repository behaviour View Source

Represents an abstract git repository.

Looking for Typical Git Commands?

The operations to inspect or mutate a git repository are not located in this module. (See Design Goals, below, and the README.md file in the lib/xgit folder for an explanation.)

You'll find these operations in the modules named Xgit.Api.* (none yet as of this writing) and Xgit.Plumbing.*

Design Goals

Xgit intends to allow repositories to be stored in multiple different mechanisms. While it includes built-in support for local on-disk repositories (see Xgit.Repository.OnDisk), and in-lib repositories (see Xgit.Repository.InMemory), you could envision repositories stored entirely on a remote file system or database.

Implementing a Storage Architecture

To define a new mechanism for storing a git repo, start by creating a new module that uses this module and implements the required callbacks. Consider the information stored in a typical .git directory in a local repository. You will be building an alternative to that storage mechanism.

Link to this section Summary

Types

Error codes that can be returned by get_object/2.

Error codes that can be returned by put_loose_object/2.

t()

The process ID for a Repository process.

Functions

Returns a specification to start this module under a supervisor.

Get the default working tree if one has been attached.

Retrieves an object from the repository.

Returns true if all objects in the list are present in the object dictionary.

Writes a loose object to the repository.

Attach a working tree to this repository as the default working tree.

Starts a Repository process linked to the current process.

Returns true if the argument is a PID representing a valid Repository process.

Callbacks

Retrieves an object from the repository.

Checks for presence of multiple object Ids.

Writes a loose object to the repository.

Link to this section Types

Link to this type

get_object_reason()

View Source
get_object_reason() :: :not_found | :invalid_object

Error codes that can be returned by get_object/2.

Link to this type

put_loose_object_reason()

View Source
put_loose_object_reason() :: :cant_create_file | :object_exists

Error codes that can be returned by put_loose_object/2.

The process ID for a Repository process.

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

default_working_tree(repository)

View Source
default_working_tree(repository :: t()) ::
  Xgit.Repository.WorkingTree.t() | nil

Get the default working tree if one has been attached.

Other working trees may also be attached to this repository, but do not have special status with regard to the repository.

Link to this function

get_object(repository, object_id)

View Source
get_object(repository :: t(), object_id :: Xgit.Core.ObjectId.t()) ::
  {:ok, object :: Xgit.Core.Object.t()}
  | {:error, reason :: get_object_reason()}

Retrieves an object from the repository.

Return Value

{:ok, object} if the object exists in the database.

{:error, :not_found} if the object does not exist in the database.

{:error, :invalid_object} if object was found, but invalid.

Link to this function

has_all_object_ids?(repository, object_ids)

View Source
has_all_object_ids?(
  repository :: t(),
  object_ids :: [Xgit.Core.ObjectId.t()]
) :: boolean()

Returns true if all objects in the list are present in the object dictionary.

This limit is not enforced, but it's recommended to query for no more than ~100 object IDs at a time.

Link to this function

put_loose_object(repository, object)

View Source
put_loose_object(repository :: t(), object :: Xgit.Core.Object.t()) ::
  :ok | {:error, reason :: put_loose_object_reason()}

Writes a loose object to the repository.

Return Value

:ok if written successfully.

{:error, :cant_create_file} if unable to create the storage for the loose object.

{:error, :object_exists} if the object already exists in the database.

Link to this function

set_default_working_tree(repository, working_tree)

View Source
set_default_working_tree(
  repository :: t(),
  working_tree :: Xgit.Repository.WorkingTree.t()
) :: :ok | :error

Attach a working tree to this repository as the default working tree.

Future plumbing and API commands that target this repository will use this working tree unless otherwise dictated.

Return Value

:ok if the working tree was successfully attached.

:error if a working tree was already attached or the proposed working tree was not valid.

Link to this function

start_link(module, init_arg, options)

View Source
start_link(module :: module(), init_arg :: term(), GenServer.options()) ::
  GenServer.on_start()

Starts a Repository process linked to the current process.

IMPORTANT: You should not invoke this function directly unless you are implementing a new storage implementation module that implements this behaviour.

Parameters

module is the name of a module that implements the callbacks defined in this module.

init_arg is passed to the init/1 function of module.

options are passed to GenServer.start_link/3.

Return Value

See GenServer.start_link/3.

Link to this function

valid?(repository)

View Source
valid?(repository :: term()) :: boolean()

Returns true if the argument is a PID representing a valid Repository process.

Link to this section Callbacks

Link to this callback

handle_get_object(state, object_id)

View Source
handle_get_object(state :: any(), object_id :: Xgit.Core.ObjectId.t()) ::
  {:ok, object :: Xgit.Core.Object.t(), state :: any()}
  | {:error, reason :: get_object_reason(), state :: any()}

Retrieves an object from the repository.

Called when get_object/2 is called.

Return Value

Should return {:ok, object, state} if read successfully.

Should return {:error, :not_found, state} if unable to find the object.

Should return {:error, :invalid_object, state} if object was found, but invalid.

Link to this callback

handle_has_all_object_ids?(state, object_ids)

View Source
handle_has_all_object_ids?(
  state :: any(),
  object_ids :: [Xgit.Core.ObjectId.t()]
) :: {:ok, has_all_object_ids? :: boolean(), state :: any()}

Checks for presence of multiple object Ids.

Called when has_all_object_ids?/2 is called.

Return Value

Should return {:ok, has_all_object_ids?, state} where has_all_object_ids? is true if all object IDs can be found in the object dictionary; false otherwise.

Link to this callback

handle_put_loose_object(state, object)

View Source
handle_put_loose_object(state :: any(), object :: Xgit.Core.Object.t()) ::
  {:ok, state :: any()}
  | {:error, reason :: put_loose_object_reason(), state :: any()}

Writes a loose object to the repository.

Called when put_loose_object/2 is called.

Return Value

Should return {:ok, state} if written successfully.

Should return {:error, :cant_create_file} if unable to create the storage for the loose object.

Should return {:error, :object_exists} if the object already exists in the database.