Xgit v0.1.1 Xgit.Repository behaviour

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), you could envision repositories stored entirely in memory, or 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.

Retrieves an object from the repository.

Writes a loose object to the repository.

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.

Writes a loose object to the repository.

Link to this section Types

Link to this type

get_object_reason()
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()
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

Link to this function

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

get_object(repository, object_id)
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

put_loose_object(repository, object)
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

start_link(module, init_arg, options)
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)
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)
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_put_loose_object(state, object)
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.