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 use
s 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
.
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.
Link to this section Types
get_object_reason()
get_object_reason() :: :not_found | :invalid_object
get_object_reason() :: :not_found | :invalid_object
Error codes that can be returned by get_object/2
.
put_loose_object_reason()
put_loose_object_reason() :: :cant_create_file | :object_exists
put_loose_object_reason() :: :cant_create_file | :object_exists
Error codes that can be returned by put_loose_object/2
.
t()
t() :: pid()
t() :: pid()
The process ID for a Repository
process.
Link to this section Functions
child_spec(init_arg)
Returns a specification to start this module under a supervisor.
See Supervisor
.
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()}
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.
put_loose_object(repository, object)
put_loose_object(repository :: t(), object :: Xgit.Core.Object.t()) ::
:ok | {:error, reason :: put_loose_object_reason()}
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.
start_link(module, init_arg, options)
start_link(module :: module(), init_arg :: term(), GenServer.options()) ::
GenServer.on_start()
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
valid?(repository)
Returns true
if the argument is a PID representing a valid Repository
process.
Link to this section Callbacks
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()}
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.
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()}
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.