Xgit v0.8.0 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

add_entry()

Cache info tuple {mode, object_id, path} to add to the index file.

cat_file_commit_reason()

Reason codes that can be returned by cat_file_commit/2.

cat_file_reason()

Reason codes that can be returned by cat_file/2.

cat_file_tag_reason()

Reason codes that can be returned by cat_file_tag/2.

cat_file_tree_reason()

Reason codes that can be returned by cat_file_tree/2.

commit_tree_reason()

Reason codes that can be returned by commit_tree/2.

delete_symbolic_ref_reason()

Reason codes that can be returned by delete_symbolic_ref/2.

get_symbolic_ref_reason()

Reason codes that can be returned by get_symbolic_ref/2.

hash_object_reason()

Reason codes that can be returned by hash_object/2.

ls_files_stage_reason()

Reason codes that can be returned by ls_files_stage/1.

put_symbolic_ref_reason()

Reason codes that can be returned by put_symbolic_ref/4.

read_tree_reason()

Reason codes that can be returned by read_tree/3.

update_index_cache_info_reason()

Reason codes that can be returned by update_index_cache_info/2.

update_ref_reason()

Reason codes that can be returned by update_ref/4.

write_tree_reason()

Reason codes that can be returned by write_tree/2.

Functions

cat_file(repository, object_id)

Retrieves the content, type, and size information for a single object in a repository's object store.

cat_file_commit(repository, object_id)

Retrieves a commit object from a repository's object store and renders it as an Xgit.Commit struct.

cat_file_tag(repository, object_id)

Retrieves a tag object from a repository's object store and renders it as an Xgit.Tag struct.

cat_file_tree(repository, object_id)

Retrieves a tree object from a repository's object store and renders it as an Xgit.Tree struct.

commit_tree(repository, opts \\ [])

Creates a new commit object based on the provided tree object and parent commits.

delete_symbolic_ref(repository, name)

Deletes a symbolic ref.

get_symbolic_ref(repository, name)

Returns the target ref for an existing symbolic ref.

hash_object(content, opts \\ [])

Computes an object ID and optionally writes that into the repository's object store.

ls_files_stage(repository)

Retrieves information about files in the working tree as described by the index file.

put_symbolic_ref(repository, name, new_target, opts \\ [])

Creates or updates a symbolic ref to point at a specific branch.

read_tree(repository, object_id, opts \\ [])

Read a tree object (and its descendants) and populate the index accordingly.

update_index_cache_info(repository, add, remove \\ [])

Update the index file to reflect new contents.

update_ref(repository, name, new_value, opts \\ [])

Update the object name stored in a ref.

write_tree(repository, opts \\ [])

Translates the current working tree, as reflected in its index file, to one or more tree objects.

Link to this section Types

add_entry()

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

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

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

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

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

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

delete_symbolic_ref_reason() :: Xgit.Repository.Storage.delete_ref_reason()

Reason codes that can be returned by delete_symbolic_ref/2.

get_symbolic_ref_reason()

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

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

ls_files_stage_reason() :: Xgit.DirCache.from_iodevice_reason()

Reason codes that can be returned by ls_files_stage/1.

put_symbolic_ref_reason()

put_symbolic_ref_reason() :: Xgit.Repository.Storage.put_ref_reason()

Reason codes that can be returned by put_symbolic_ref/4.

read_tree_reason()

read_tree_reason() :: :bare | Xgit.Repository.WorkingTree.read_tree_reason()

Reason codes that can be returned by read_tree/3.

update_index_cache_info_reason()

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

update_ref_reason() ::
  Xgit.Repository.Storage.put_ref_reason() | :target_not_commit

Reason codes that can be returned by update_ref/4.

write_tree_reason()

write_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)

cat_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)

cat_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)

cat_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)

cat_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 \\ [])

commit_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)

delete_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:

Xgit.Repository.Storage.delete_ref/3

get_symbolic_ref(repository, name)

get_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:

Xgit.Repository.Storage.get_ref/3

hash_object(content, opts \\ [])

hash_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

:validate?: true to verify that the object is valid for :type

Type: boolean
Default: true
This is the inverse of the --literally option on git 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 on git 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)

ls_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 \\ [])

put_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:

Xgit.Repository.Storage.put_ref/3

read_tree(repository, object_id, opts \\ [])

read_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 \\ [])

update_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 \\ [])

update_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.

{:error, :target_not_commit} if the target object is not of type commit.

Reason codes may also come from the following functions:

write_tree(repository, opts \\ [])

write_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