Xgit v0.7.2 Xgit.Repository.WorkingTree View Source
A working tree is an on-disk manifestation of a commit or pending commit in a git repository.
An Xgit.Repository.Storage
may have a default working tree associated with it or
it may not. (A repository without a working tree is often referred to as a
"bare" repository.)
More than one working tree may be associated with a repository, though this is not (currently) well-tested in Xgit.
A working tree is itself strictly tied to a file system, but it need not be tied to an on-disk repository instance.
IMPORTANT NOTE: This is intended as a reference implementation largely
for testing purposes and may not necessarily handle all of the edge cases that
the traditional git
command-line interface will handle.
Link to this section Summary
Types
Reason codes that can be returned by read_tree/3
.
Error code reasons returned by reset_dir_cache/1
.
The process ID for a WorkingTree
process.
Error code reasons returned by update_dir_cache/3
.
Reason codes that can be returned by write_tree/2
.
Functions
Returns a specification to start this module under a supervisor.
Returns a current snapshot of the working tree state.
Read a tree
object and any trees it may refer to and populate the dir cache accordingly.
Reset the dir cache to empty and rewrite the index file accordingly.
Starts a WorkingTree
process linked to the current process.
Apply updates to the dir cache and rewrite the index tree accordingly.
Returns true
if the argument is a PID representing a valid WorkingTree
process.
Translates the current dir cache, as reflected in its index file, to one or more tree objects.
Link to this section Types
read_tree_reason()
View Sourceread_tree_reason() :: :objects_missing | Xgit.DirCache.to_iodevice_reason() | Xgit.Repository.Storage.get_object_reason() | Xgit.Tree.from_object_reason()
Reason codes that can be returned by read_tree/3
.
reset_dir_cache_reason()
View Sourcereset_dir_cache_reason() :: Xgit.DirCache.to_iodevice_reason()
Error code reasons returned by reset_dir_cache/1
.
The process ID for a WorkingTree
process.
update_dir_cache_reason()
View Sourceupdate_dir_cache_reason() :: Xgit.DirCache.add_entries_reason() | Xgit.DirCache.from_iodevice_reason() | Xgit.DirCache.remove_entries_reason() | Xgit.DirCache.to_iodevice_reason()
Error code reasons returned by update_dir_cache/3
.
write_tree_reason()
View Sourcewrite_tree_reason() :: :incomplete_merge | :objects_missing | :prefix_not_found | Xgit.DirCache.from_iodevice_reason() | Xgit.DirCache.to_tree_objects_reason() | Xgit.Repository.Storage.put_loose_object_reason()
Reason codes that can be returned by write_tree/2
.
Link to this section Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
dir_cache(working_tree)
View Sourcedir_cache(working_tree :: t()) :: {:ok, Xgit.DirCache.t()} | {:error, reason :: Xgit.DirCache.from_iodevice_reason()}
Returns a current snapshot of the working tree state.
Return Value
{:ok, dir_cache}
if an index file exists and could be parsed as a dir cache file.
{:ok, dir_cache}
if no index file exists. (dir_cache
will have zero entries.)
{:error, reason}
if the file exists but could not be parsed. (See
Xgit.DirCache.from_iodevice/1
for possible reason codes.
TO DO
Find index file in appropriate location (i.e. as potentially modified
by .git/config
file). Issue #86
Cache state of index file so we don't have to parse it for every call. Issue #87
Consider scalability of passing a potentially large Xgit.DirCache
structure
across process boundaries. Issue #88
read_tree(working_tree, object_id, opts \\ [])
View Sourceread_tree(working_tree :: t(), object_id :: Xgit.ObjectId.t(), [ {:missing_ok?, boolean()} ]) :: :ok | {:error, reason :: read_tree_reason()}
Read a tree
object and any trees it may refer to and populate the dir cache accordingly.
Does not update files in the working tree itself.
Analogous to git read-tree
.
Parameters
object_id
is the object ID of the root working tree.
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, :objects_missing}
if any of the objects referenced by the index
are not present in the object store. (Exception: If missing_ok?
is true
,
then this condition will be ignored.)
Reason codes may also come from the following functions:
TO DO
Implement --prefix
option. https://github.com/elixir-git/xgit/issues/175
reset_dir_cache(working_tree)
View Sourcereset_dir_cache(working_tree :: t()) :: :ok | {:error, reset_dir_cache_reason()}
Reset the dir cache to empty and rewrite the index file accordingly.
Return Values
:ok
if successful.
{:error, reason}
if unable. The relevant reason codes may come from:
start_link(repository, work_dir, options \\ [])
View Sourcestart_link( repository :: Xgit.Repository.Storage.t(), work_dir :: Path.t(), GenServer.options() ) :: GenServer.on_start()
Starts a WorkingTree
process linked to the current process.
Parameters
repository
is the associated Xgit.Repository.Storage
process.
work_dir
is the root path for the working tree.
options
are passed to GenServer.start_link/3
.
Return Value
If the process is unable to create the working directory root, the response
will be {:error, {:mkdir, :eexist}}
(or perhaps a different posix error code).
update_dir_cache(working_tree, add, remove)
View Sourceupdate_dir_cache( working_tree :: t(), add :: [Xgit.DirCache.Entry.t()], remove :: [ {path :: Xgit.FilePath.t(), stage :: Xgit.DirCache.Entry.stage_match()} ] ) :: {:ok, Xgit.DirCache.t()} | {:error, update_dir_cache_reason()}
Apply updates to the dir cache and rewrite the index tree accordingly.
Parameters
add
: a list of Xgit.DirCache.Entry
structs 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 {path, stage}
tuples to remove from the dir cache.
stage
must be 0..3
to remove a specific stage entry or :all
to match
any entry for the path
.
Return Values
{:ok, dir_cache}
where dir_cache
is the original dir_cache
with the new
entries added (and properly sorted) and targeted entries removed.
{:error, reason}
if unable. The relevant reason codes may come from:
Xgit.DirCache.add_entries/2
Xgit.DirCache.from_iodevice/1
Xgit.DirCache.remove_entries/2
Xgit.DirCache.to_iodevice/2
.
TO DO
Find index file in appropriate location (i.e. as potentially modified
by .git/config
file). Issue #86
Cache state of index file so we don't have to parse it for every call. Issue #87
Returns true
if the argument is a PID representing a valid WorkingTree
process.
write_tree(working_tree, opts \\ [])
View Sourcewrite_tree(working_tree :: t(), missing_ok?: boolean(), prefix: Xgit.FilePath.t() ) :: {:ok, object_id :: Xgit.ObjectId.t()} | {:error, reason :: write_tree_reason()}
Translates the current dir cache, as reflected in its index file, to one or more tree objects.
The working tree must be in a fully-merged state.
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, :incomplete_merge}
if any entry in the index file is not fully merged.
{:error, :objects_missing}
if any of the objects referenced by the index
are not present in the object store. (Exception: If missing_ok?
is true
,
then this condition will be ignored.)
{:error, :prefix_not_found}
if prefix
was specified, but that prefix is not referenced
in the index file.
Reason codes may also come from the following functions: