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 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.
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
get_object_reason()
View Sourceget_object_reason() :: :not_found | :invalid_object
Error codes that can be returned by get_object/2
.
put_loose_object_reason()
View Sourceput_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
.
default_working_tree(repository)
View Sourcedefault_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.
get_object(repository, object_id)
View Sourceget_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.
has_all_object_ids?(repository, object_ids)
View Sourcehas_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.
put_loose_object(repository, object)
View Sourceput_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.
set_default_working_tree(repository, working_tree)
View Sourceset_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.
start_link(module, init_arg, options)
View Sourcestart_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
Returns true
if the argument is a PID representing a valid Repository
process.
Link to this section Callbacks
handle_get_object(state, object_id)
View Sourcehandle_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_has_all_object_ids?(state, object_ids)
View Sourcehandle_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.
handle_put_loose_object(state, object)
View Sourcehandle_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.