Xgit v0.7.1 Xgit.DirCache View Source

A directory cache records the current (intended) contents of a working tree when last scanned or created by git.

In Xgit, the DirCache structure is an abstract, in-memory data structure without any tie to a specific persistence mechanism. Persistence is implemented by a specific implementation of the Xgit.Repository.Storage behaviour.

This content is commonly persisted on disk as an index file at the root of the git tree. This file format can be read using the from_iodevice/1 function and written using to_iodevice/1. If a different persistence mechanism is required, you may provide that e elsewhere.

Changes in the working tree can be detected by comparing the modification times to the cached modification time within the dir cache.

Index files are also used during merges, where the merge happens within the index file first, and the working directory is updated as a post-merge step. Conflicts are stored in the index file to allow tool (and human) based resolutions to be easily performed.

Link to this section Summary

Types

Error reason codes returned by add_entries/2.

An entry for the remove option for remove_entries/2.

Error codes which can be returned by from_iodevice/1.

Error reason codes returned by remove_entries/2.

t()

This struct describes an entire working tree as understood by git.

Error codes which can be returned by to_iodevice/1.

Error reason codes returned by to_tree_objects/2.

Version number for an index file.

Functions

Returns a dir cache that has new directory entries added in.

Returns a dir cache that is the canonical "empty" dir cache (i.e. contains no entries).

Read a git index file from an IO.device (typically an opened file) and returns a corresponding DirCache struct.

Return true if all of the entries in this dir cache are fully merged (stage 0).

Returns a dir cache that has some directory entries removed.

Write index file to an iodevice (typically an opened file) from a DirCache struct.

Convert this DirCache to one or more tree objects.

Return true if the value is a DirCache struct that is valid.

Link to this section Types

Link to this type

add_entries_reason()

View Source
add_entries_reason() ::
  :invalid_dir_cache | :invalid_entries | :duplicate_entries

Error reason codes returned by add_entries/2.

Link to this type

entry_to_remove()

View Source
entry_to_remove() ::
  {path :: Xgit.FilePath.t(), stage :: Xgit.DirCache.Entry.stage_match()}

An entry for the remove option for remove_entries/2.

Link to this type

from_iodevice_reason()

View Source
from_iodevice_reason() ::
  :not_sha_hash_device
  | :invalid_format
  | :unsupported_version
  | :too_many_entries
  | :unsupported_extension
  | :sha_hash_mismatch
  | File.posix()

Error codes which can be returned by from_iodevice/1.

Link to this type

remove_entries_reason()

View Source
remove_entries_reason() :: :invalid_dir_cache | :invalid_entries

Error reason codes returned by remove_entries/2.

Link to this type

t()

View Source
t() :: %Xgit.DirCache{
  entries: [Xgit.DirCache.Entry.t()],
  entry_count: non_neg_integer(),
  version: version()
}

This struct describes an entire working tree as understood by git.

Struct Members

  • :version: the version number as read from disk (typically 2, 3, or 4)
  • :entry_count: the number of items in entries
  • :entries: a list of Entry structs in sorted order
  • :extensions: a list of Extension structs (not yet implemented)
Link to this type

to_iodevice_reason()

View Source
to_iodevice_reason() ::
  :not_sha_hash_device
  | :invalid_dir_cache
  | :unsupported_version
  | File.posix()

Error codes which can be returned by to_iodevice/1.

Link to this type

to_tree_objects_reason()

View Source
to_tree_objects_reason() :: :invalid_dir_cache | :prefix_not_found

Error reason codes returned by to_tree_objects/2.

Link to this type

version()

View Source
version() :: 2..4

Version number for an index file.

Link to this section Functions

Link to this function

add_entries(dir_cache, new_entries)

View Source
add_entries(dir_cache :: t(), new_entries :: [Xgit.DirCache.Entry.t()]) ::
  {:ok, t()} | {:error, add_entries_reason()}

Returns a dir cache that has new directory entries added in.

In the event of a collision between entries (same path and stage), the existing entry will be replaced by the new one.

Parameters

entries a list of entries to add to the existing dir cache

Return Value

{:ok, dir_cache} where dir_cache is the original dir_cache with the new entries added (and properly sorted).

{:error, :invalid_dir_cache} if the original dir_cache was invalid.

{:error, :invalid_entries} if one or more of the entries is invalid.

{:error, :duplicate_entries} if one or more of the entries in the new list are duplicates of other entries in the new list. (As stated earlier, duplicates from the original list are acceptable; in that event, the new entry will replace the old one.)

Returns a dir cache that is the canonical "empty" dir cache (i.e. contains no entries).

Link to this function

from_iodevice(iodevice)

View Source
from_iodevice(iodevice :: IO.device()) ::
  {:ok, dir_cache :: t()} | {:error, reason :: from_iodevice_reason()}

Read a git index file from an IO.device (typically an opened file) and returns a corresponding DirCache struct.

IMPORTANT: The IO.device must be created using Xgit.Util.TrailingHashDevice.

Return Value

{:ok, dir_cache} if the iodevice contains a valid index file.

{:error, :not_sha_hash_device} if the iodevice was not created using Xgit.Util.TrailingHashDevice.

{:error, :invalid_format} if the iodevice can not be parsed as an index file.

{:error, :unsupported_version} if the index file is not a version 2 index file. Other versions are not supported at this time.

{:error, :too_many_entries} if the index files contains more than 100,000 entries. This is an arbitrary limit to guard against malformed files and to prevent overconsumption of memory. With experience, it could be revisited.

{:error, :unsupported_extension} if any index file extensions are present that can not be parsed. Optional extensions will be skipped, but no required extensions are understood at this time. (See issue #172.)

{:error, :sha_hash_mismatch} if the SHA-1 hash written at the end of the file does not match the file contents.

Link to this function

fully_merged?(dir_cache)

View Source
fully_merged?(dir_cache :: t()) :: boolean()

Return true if all of the entries in this dir cache are fully merged (stage 0).

Link to this function

remove_entries(dir_cache, entries_to_remove)

View Source
remove_entries(dir_cache :: t(), entries_to_remove :: [entry_to_remove()]) ::
  {:ok, t()} | {:error, remove_entries_reason()}

Returns a dir cache that has some directory entries removed.

Parameters

entries_to_remove is a list of {path, stage} tuples identifying tuples to be removed.

  • path should be a byte list for the path.
  • stage should be 0..3 or :all, meaning any entry that matches the path, regardless of stage, should be removed.

Return Value

{:ok, dir_cache} where dir_cache is the original dir_cache with any matching entries removed.

{:error, :invalid_dir_cache} if the original dir_cache was invalid.

{:error, :invalid_entries} if one or more of the entries is invalid.

Link to this function

to_iodevice(dir_cache, iodevice)

View Source
to_iodevice(dir_cache :: t(), iodevice :: IO.device()) ::
  :ok | {:error, reason :: to_iodevice_reason()}

Write index file to an iodevice (typically an opened file) from a DirCache struct.

IMPORTANT: The iodevice must be created using Xgit.Util.TrailingHashDevice.

Return Value

:ok if written successfully.

{:error, :not_sha_hash_device} if the iodevice was not created using Xgit.Util.TrailingHashDevice.

{:error, :invalid_dir_cache} if valid?/1 does not return true for this struct.

{:error, :unsupported_version} if the version flag in the dir cache struct is not version. Other versions are not supported at this time.

{:error, posix_reason} if an I/O error occurs.

Link to this function

to_tree_objects(dir_cache, prefix \\ [])

View Source
to_tree_objects(dir_cache :: t(), prefix :: Xgit.FilePath.t()) ::
  {:ok, [Xgit.Object.t()], Xgit.Object.t()} | {:error, to_tree_objects_reason()}

Convert this DirCache to one or more tree objects.

Parameters

prefix: (Xgit.FilePath) if present, return the object ID for the tree pointed to by prefix. All tree objects will be generated, regardless of prefix.

Return Value

{:ok, objects, prefix_tree} where objects is a list of Xgit.Object structs of type tree. All others must be written or must be present in the object database for the top-level tree to be valid. prefix_tree is the tree for the subtree specified by prefix or the top-level tree if no prefix was specified.

{:error, :invalid_dir_cache} if the DirCache is not valid.

{:error, :prefix_not_found} if no tree matching prefix exists.

Link to this function

valid?(dir_cache)

View Source
valid?(dir_cache :: any()) :: boolean()

Return true if the value is a DirCache struct that is valid.

All of the following must be true for this to occur:

  • The value is a DirCache struct.
  • The version is supported by Xgit. (Currently, only version 2 is supported.)
  • The entry_count matches the actual number of entries.
  • The entries are properly sorted.
  • All entries are valid, as determined by Xgit.DirCache.Entry.valid?/1.