Xgit v0.7.1 Xgit.Repository.Plumbing View Source
Implements the "plumbing"-level commands for a git repository.
The functions in this module, like the "plumbing" commands in command-line git, are typically not of interest to an end-user developer. Instead, these are the raw building-block operations that are often composed together to make the user-targeted "porcelain" commands.
Most of the functions in this module expect a repository
argument, which
should be the process ID (PID) for a process that implements the Xgit.Repository.Storage
behaviour. It's not stated for each individual function, but if repository
is some other value, the error Xgit.Repository.InvalidRepositoryError
is
raised.
Link to this section Summary
Types
Cache info tuple {mode, object_id, path}
to add to the index file.
Reason codes that can be returned by cat_file_commit/2
.
Reason codes that can be returned by cat_file/2
.
Reason codes that can be returned by cat_file_tag/2
.
Reason codes that can be returned by cat_file_tree/2
.
Reason codes that can be returned by commit_tree/2
.
Reason codes that can be returned by delete_symbolic_ref/2
.
Reason codes that can be returned by get_symbolic_ref/2
.
Reason codes that can be returned by hash_object/2
.
Reason codes that can be returned by ls_files_stage_/1
.
Reason codes that can be returned by put_symbolic_ref/4
.
Reason codes that can be returned by read_tree/3
.
Reason codes that can be returned by update_index_cache_info/2
.
Reason codes that can be returned by update_ref/4
.
Reason codes that can be returned by write_tree/2
.
Functions
Retrieves the content, type, and size information for a single object in a repository's object store.
Retrieves a commit
object from a repository's object store and renders
it as an Xgit.Commit
struct.
Retrieves a tag
object from a repository's object store and renders
it as an Xgit.Tag
struct.
Retrieves a tree
object from a repository's object store and renders
it as an Xgit.Tree
struct.
Creates a new commit object based on the provided tree object and parent commits.
Deletes a symbolic ref.
Returns the target ref for an existing symbolic ref.
Computes an object ID and optionally writes that into the repository's object store.
Retrieves information about files in the working tree as described by the index file.
Creates or updates a symbolic ref to point at a specific branch.
Read a tree
object (and its descendants) and populate the index accordingly.
Update the index file to reflect new contents.
Update the object name stored in a ref.
Translates the current working tree, as reflected in its index file, to one or more tree objects.
Link to this section Types
add_entry()
View Sourceadd_entry() :: {mode :: Xgit.FileMode.t(), object_id :: Xgit.ObjectId.t(), path :: Xgit.FilePath.t()}
Cache info tuple {mode, object_id, path}
to add to the index file.
cat_file_commit_reason()
View Sourcecat_file_commit_reason() :: :invalid_object_id | Xgit.Commit.from_object_reason() | Xgit.Repository.Storage.get_object_reason()
Reason codes that can be returned by cat_file_commit/2
.
cat_file_reason()
View Sourcecat_file_reason() :: :invalid_object_id | Xgit.Repository.Storage.get_object_reason()
Reason codes that can be returned by cat_file/2
.
cat_file_tag_reason()
View Sourcecat_file_tag_reason() :: :invalid_object_id | Xgit.Repository.Storage.get_object_reason() | Xgit.Tag.from_object_reason()
Reason codes that can be returned by cat_file_tag/2
.
cat_file_tree_reason()
View Sourcecat_file_tree_reason() :: :invalid_object_id | Xgit.Repository.Storage.get_object_reason() | Xgit.Tree.from_object_reason()
Reason codes that can be returned by cat_file_tree/2
.
commit_tree_reason()
View Sourcecommit_tree_reason() :: :invalid_tree | :invalid_parents | :invalid_parent_ids | :invalid_message | :invalid_author | :invalid_committer | Xgit.Repository.Storage.put_loose_object_reason()
Reason codes that can be returned by commit_tree/2
.
delete_symbolic_ref_reason()
View Sourcedelete_symbolic_ref_reason() :: Xgit.Repository.Storage.delete_ref_reason()
Reason codes that can be returned by delete_symbolic_ref/2
.
get_symbolic_ref_reason()
View Sourceget_symbolic_ref_reason() :: :not_symbolic_ref | Xgit.Repository.Storage.get_ref_reason()
Reason codes that can be returned by get_symbolic_ref/2
.
hash_object_reason()
View Sourcehash_object_reason() :: Xgit.Object.check_reason() | Xgit.FilePath.check_path_reason() | Xgit.FilePath.check_path_segment_reason() | Xgit.Repository.Storage.put_loose_object_reason()
Reason codes that can be returned by hash_object/2
.
ls_files_stage_reason()
View Sourcels_files_stage_reason() :: Xgit.DirCache.from_iodevice_reason()
Reason codes that can be returned by ls_files_stage_/1
.
put_symbolic_ref_reason()
View Sourceput_symbolic_ref_reason() :: Xgit.Repository.Storage.put_ref_reason()
Reason codes that can be returned by put_symbolic_ref/4
.
read_tree_reason()
View Sourceread_tree_reason() :: :bare | Xgit.Repository.WorkingTree.read_tree_reason()
Reason codes that can be returned by read_tree/3
.
update_index_cache_info_reason()
View Sourceupdate_index_cache_info_reason() :: :invalid_entry | :bare | Xgit.Repository.WorkingTree.update_dir_cache_reason()
Reason codes that can be returned by update_index_cache_info/2
.
update_ref_reason()
View Sourceupdate_ref_reason() :: Xgit.Repository.Storage.put_ref_reason()
Reason codes that can be returned by update_ref/4
.
write_tree_reason()
View Sourcewrite_tree_reason() :: :bare | Xgit.DirCache.to_tree_objects_reason() | Xgit.DirCache.from_iodevice_reason() | Xgit.Repository.Storage.put_loose_object_reason() | Xgit.Repository.WorkingTree.write_tree_reason()
Reason codes that can be returned by write_tree/2
.
Link to this section Functions
cat_file(repository, object_id)
View Sourcecat_file( repository :: Xgit.Repository.Storage.t(), object_id :: Xgit.ObjectId.t() ) :: {:ok, Xgit.Object} | {:error, reason :: cat_file_reason()}
Retrieves the content, type, and size information for a single object in a repository's object store.
Analogous to the first form of git cat-file
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
object_id
is a string identifying the object.
Return Value
{:ok, object}
if the object could be found. object
is an instance of
Xgit.Object
and can be used to retrieve content and other information
about the underlying git object.
{:error, :invalid_object_id}
if object_id
can't be parsed as a valid git object ID.
{:error, :not_found}
if the object does not exist in the database.
{:error, :invalid_object}
if object was found, but invalid.
cat_file_commit(repository, object_id)
View Sourcecat_file_commit( repository :: Xgit.Repository.Storage.t(), object_id :: Xgit.ObjectId.t() ) :: {:ok, commit :: Xgit.Commit.t()} | {:error, reason :: cat_file_commit_reason()}
Retrieves a commit
object from a repository's object store and renders
it as an Xgit.Commit
struct.
Analogous to
git cat-file -p
when the target object is a commit
object.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
object_id
is a string identifying the object.
Return Value
{:ok, commit}
if the object could be found and understood as a commit.
commit
is an instance of Xgit.Commit
and can be used to retrieve
references to the members of that commit.
{:error, :invalid_object_id}
if object_id
can't be parsed as a valid git object ID.
{:error, reason}
if otherwise unable. The relevant reason codes may come from:
cat_file_tag(repository, object_id)
View Sourcecat_file_tag( repository :: Xgit.Repository.Storage.t(), object_id :: Xgit.ObjectId.t() ) :: {:ok, tag :: Xgit.Tag.t()} | {:error, reason :: cat_file_tag_reason()}
Retrieves a tag
object from a repository's object store and renders
it as an Xgit.Tag
struct.
Analogous to
git cat-file -p
when the target object is a tag
object.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
object_id
is a string identifying the object.
Return Value
{:ok, tag}
if the object could be found and understood as a tag.
tag
is an instance of Xgit.Tag
and can be used to retrieve
references to the members of that tag.
{:error, :invalid_object_id}
if object_id
can't be parsed as a valid git object ID.
{:error, reason}
if otherwise unable. The relevant reason codes may come from:
cat_file_tree(repository, object_id)
View Sourcecat_file_tree( repository :: Xgit.Repository.Storage.t(), object_id :: Xgit.ObjectId.t() ) :: {:ok, tree :: Xgit.Tree.t()} | {:error, reason :: cat_file_tree_reason()}
Retrieves a tree
object from a repository's object store and renders
it as an Xgit.Tree
struct.
Analogous to
git cat-file -p
when the target object is a tree
object.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
object_id
is a string identifying the object.
Return Value
{:ok, tree}
if the object could be found and understood as a tree.
tree
is an instance of Xgit.Tree
and can be used to retrieve
references to the members of that tree.
{:error, :invalid_object_id}
if object_id
can't be parsed as a valid git object ID.
{:error, reason}
if otherwise unable. The relevant reason codes may come from:
commit_tree(repository, opts \\ [])
View Sourcecommit_tree(repository :: Xgit.Repository.Storage.t(), tree: Xgit.ObjectId.t(), parents: [Xgit.ObjectId.t()], message: [byte()], author: Xgit.PersonIdent.t(), committer: Xgit.PersonIdent.t() ) :: {:ok, object_id :: Xgit.ObjectId.t()} | {:error, reason :: commit_tree_reason()}
Creates a new commit object based on the provided tree object and parent commits.
A commit object may have any number of parents. With exactly one parent, it is an ordinary commit. Having more than one parent makes the commit a merge between several lines of history. Initial (root) commits have no parents.
Analogous to
git commit-tree
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
Options
tree
: (Xgit.ObjectId
, required) ID of tree object
parents
: (list of Xgit.ObjectId
) parent commit object IDs
message
: (byte list, required) commit message
author
: (Xgit.PersonIdent
, required) author name, email, timestamp
committer
: (Xgit.PersonIdent
) committer name, email timestamp
(defaults to author
if not specified)
Return Value
{:ok, object_id}
with the object ID for the commit that was generated.
{:error, :invalid_tree}
if the :tree
option refers to a tree that
does not exist.
{:error, :invalid_parents}
if the :parents
option is not a list.
{:error, :invalid_parent_ids}
if the :parents
option contains any entries that
do not reference valid commit objects.
{:error, :invalid_message}
if the :message
option isn't a valid byte string.
{:error, :invalid_author}
if the :author
option isn't a valid PersonIdent
struct.
{:error, :invalid_committer}
if the :committer
option isn't a valid PersonIdent
struct.
Reason codes may also come from Xgit.Repository.Storage.put_loose_object/2
.
delete_symbolic_ref(repository, name)
View Sourcedelete_symbolic_ref( repository :: Xgit.Repository.Storage.t(), name :: Xgit.Ref.name() ) :: :ok | {:error, reason :: delete_symbolic_ref_reason()}
Deletes a symbolic ref.
Analogous to git symbolic-ref --delete
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) in which to create the symbolic reference.
name
is the name of the symbolic reference to delete. (See t/Xgit.Ref.name
.)
Return Value
:ok
if deleted successfully.
Reason codes may also come from the following functions:
get_symbolic_ref(repository, name)
View Sourceget_symbolic_ref( repository :: Xgit.Repository.Storage.t(), name :: Xgit.Ref.name() ) :: {:ok, name :: Xgit.Ref.name()} | {:error, reason :: get_symbolic_ref_reason()}
Returns the target ref for an existing symbolic ref.
Analogous to the one-argument form of
git symbolic-ref
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) in which to create the symbolic reference.
name
is the name of the symbolic reference to read. (See t/Xgit.Ref.name
.)
Return Value
{:ok, ref_name}
if read successfully. ref_name
is the name of the targeted reference.
{:error, :not_symbolic_ref}
if name
refers to a ref that is not a symbolic ref.
Reason codes may also come from the following functions:
hash_object(content, opts \\ [])
View Sourcehash_object(content :: Xgit.ContentSource.t(), type: Xgit.ObjectType.t(), validate?: boolean(), repo: Xgit.Repository.Storage.t(), write?: boolean() ) :: {:ok, object_id :: Xgit.ObjectId.t()} | {:error, reason :: hash_object_reason()}
Computes an object ID and optionally writes that into the repository's object store.
Analogous to git hash-object
.
Parameters
content
describes how this function should obtain the content.
(See Xgit.ContentSource
.)
Options
:type
: the object's type
- Type:
Xgit.ObjectType
- Default:
:blob
- See
-t
option ongit hash-object
.
:validate?
: true
to verify that the object is valid for :type
- Type: boolean
- Default:
true
- This is the inverse of the
--literally
option ongit hash-object
.
:repo
: where the content should be stored
- Type:
Xgit.Repository.Storage
(PID) - Default:
nil
:write?
: true
to write the object into the repository
- Type: boolean
- Default:
false
- This option is meaningless if
:repo
is not specified. - See
-w
option ongit hash-object
.
TO DO: There is no support, at present, for filters as defined in a
.gitattributes
file. See issue #18.
Return Values
{:ok, object_id}
if the object could be validated and assigned an ID.
{:error, :reason}
if unable. The relevant reason codes may come from:
ls_files_stage(repository)
View Sourcels_files_stage(repository :: Xgit.Repository.Storage.t()) :: {:ok, entries :: [Xgit.DirCache.Entry.t()]} | {:error, reason :: ls_files_stage_reason()}
Retrieves information about files in the working tree as described by the index file.
Analogous to
git ls-files --stage
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
Return Value
{:ok, entries}
. entries
will be a list of Xgit.DirCache.Entry
structs
in sorted order.
{:error, :bare}
if repository
doesn't have a working tree.
{:error, reason}
if the index file for repository
isn't valid. (See
Xgit.DirCache.from_iodevice/1
for possible reason codes.)
put_symbolic_ref(repository, name, new_target, opts \\ [])
View Sourceput_symbolic_ref( repository :: Xgit.Repository.Storage.t(), name :: Xgit.Ref.name(), new_target :: Xgit.Ref.name(), opts :: Keyword.t() ) :: :ok | {:error, reason :: put_symbolic_ref_reason()}
Creates or updates a symbolic ref to point at a specific branch.
Analogous to the two-argument form of
git symbolic-ref
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) in which to create the symbolic reference.
name
is the name of the symbolic reference to create or update. (See t/Xgit.Ref.name
.)
new_target
is the name of the reference that should be targeted by this symbolic reference.
This reference need not exist.
Options
TO DO: Add option to specify ref log message. https://github.com/elixir-git/xgit/issues/251
Return Value
:ok
if written successfully.
Reason codes may also come from the following functions:
read_tree(repository, object_id, opts \\ [])
View Sourceread_tree( repository :: Xgit.Repository.Storage.t(), object_id :: Xgit.ObjectId.t(), [{:missing_ok?, boolean()}] ) :: :ok | {:error, reason :: read_tree_reason()}
Read a tree
object (and its descendants) and populate the index accordingly.
Does not update files in the working tree itself.
Analogous to git read-tree
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
object_id
is the object ID of the root working tree. The special name :empty
may be used to empty the index.
Options
:missing_ok?
: true
to ignore any objects that are referenced by the tree
structures that are not present in the object database. Normally this would be an error.
Return Value
:ok
if successful.
{:error, :bare}
if repository
doesn't have a working tree.
Reason codes may also come from the following functions:
Xgit.DirCache.to_iodevice/2
Xgit.Repository.Storage.get_object/2
Xgit.Repository.Storage.WorkingTree.read_tree/3
Xgit.Tree.from_object/1
TO DO
Implement --prefix
option. https://github.com/elixir-git/xgit/issues/175
update_index_cache_info(repository, add, remove \\ [])
View Sourceupdate_index_cache_info( repository :: Xgit.Repository.Storage.t(), add :: [add_entry()], remove :: [Xgit.FilePath.t()] ) :: :ok | {:error, update_index_cache_info_reason()}
Update the index file to reflect new contents.
Analogous to the --cacheinfo
form of
git update-index
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to which the new entries should be written.
add
: a list of tuples of {mode, object_id, path}
entries to add to the dir cache.
In the event of collisions with existing entries, the existing entries will
be replaced with the corresponding new entries.
remove
: a list of paths to remove from the dir cache. All versions of the file,
regardless of stage, will be removed.
Return Value
:ok
if successful.
{:error, :bare}
if repository
doesn't have a working tree.
{:error, :invalid_entry}
if any tuple passed to add
or remove
was invalid.
{:error, :reason}
if unable. The relevant reason codes may come from
Xgit.Repository.WorkingTree.update_dir_cache/3
.
update_ref(repository, name, new_value, opts \\ [])
View Sourceupdate_ref( repository :: Xgit.Repository.Storage.t(), name :: Xgit.Ref.name(), new_value :: Xgit.ObjectId.t(), [{:old_target, Xgit.ObjectId.t()}] ) :: :ok | {:error, reason :: update_ref_reason()}
Update the object name stored in a ref.
Analogous to git update-ref
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
name
is the name of the reference to update. (See t/Xgit.Ref.name
.)
new_value
is the object ID to be written at this reference. (Use Xgit.ObjectId.zero/0
to delete the reference.)
Options
old_target
: If present, a ref with this name must already exist and the target
value must match the object ID provided in this option. (There is a special value :new
which instead requires that the named ref must not exist.)
TO DO
Follow symbolic links, but only if they start with refs/
.
(https://github.com/elixir-git/xgit/issues/241)
Return Value
:ok
if written successfully.
Reason codes may also come from the following functions:
write_tree(repository, opts \\ [])
View Sourcewrite_tree(repository :: Xgit.Repository.Storage.t(), missing_ok?: boolean(), prefix: Xgit.FilePath.t() ) :: {:ok, object_id :: Xgit.ObjectId.t()} | {:error, reason :: write_tree_reason()}
Translates the current working tree, as reflected in its index file, to one or more tree objects.
The working tree must be in a fully-merged state.
Analogous to git write-tree
.
Parameters
repository
is the Xgit.Repository.Storage
(PID) to search for the object.
Options
:missing_ok?
: true
to ignore any objects that are referenced by the index
file that are not present in the object database. Normally this would be an error.
:prefix
: (Xgit.FilePath
) if present, returns the object_id
for the tree at
the given subdirectory. If not present, writes a tree corresponding to the root.
(The entire tree is written in either case.)
Return Value
{:ok, object_id}
with the object ID for the tree that was generated. (If the exact tree
specified by the index already existed, it will return that existing tree's ID.)
{:error, :bare}
if repository
doesn't have a working tree.
Reason codes may also come from the following functions:
Xgit.DirCache.to_tree_objects/2
Xgit.DirCache.from_iodevice/1
Xgit.Repository.Storage.put_loose_object/2
Xgit.Repository.Storage.WorkingTree.write_tree/2