Xgit v0.7.2 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
.
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
add_entries_reason()
View Sourceadd_entries_reason() :: :invalid_dir_cache | :invalid_entries | :duplicate_entries
Error reason codes returned by add_entries/2
.
entry_to_remove()
View Sourceentry_to_remove() :: {path :: Xgit.FilePath.t(), stage :: Xgit.DirCache.Entry.stage_match()}
An entry for the remove
option for remove_entries/2
.
from_iodevice_reason()
View Sourcefrom_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
.
remove_entries_reason()
View Sourceremove_entries_reason() :: :invalid_dir_cache | :invalid_entries
Error reason codes returned by remove_entries/2
.
t()
View Sourcet() :: %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 inentries
:entries
: a list ofEntry
structs in sorted order:extensions
: a list ofExtension
structs (not yet implemented)
to_iodevice_reason()
View Sourceto_iodevice_reason() :: :not_sha_hash_device | :invalid_dir_cache | :unsupported_version | File.posix()
Error codes which can be returned by to_iodevice/1
.
to_tree_objects_reason()
View Sourceto_tree_objects_reason() :: :invalid_dir_cache | :prefix_not_found
Error reason codes returned by to_tree_objects/2
.
Version number for an index file.
Link to this section Functions
add_entries(dir_cache, new_entries)
View Sourceadd_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).
from_iodevice(iodevice)
View Sourcefrom_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.
Return true
if all of the entries in this dir cache are fully merged (stage 0).
remove_entries(dir_cache, entries_to_remove)
View Sourceremove_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 be0..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.
to_iodevice(dir_cache, iodevice)
View Sourceto_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.
to_tree_objects(dir_cache, prefix \\ [])
View Sourceto_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.
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
.