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

t()

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

Reason codes that can be returned by read_tree/3.

Link to this type

reset_dir_cache_reason()

View Source
reset_dir_cache_reason() :: Xgit.DirCache.to_iodevice_reason()

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.

Link to this type

write_tree_reason()

View Source
write_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.

Link to this function

dir_cache(working_tree)

View Source
dir_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

Link to this function

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

View Source
read_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

Link to this function

reset_dir_cache(working_tree)

View Source
reset_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:

Link to this function

start_link(repository, work_dir, options \\ [])

View Source
start_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

See GenServer.start_link/3.

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

Link to this function

update_dir_cache(working_tree, add, remove)

View Source
update_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:

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

Link to this function

valid?(working_tree)

View Source
valid?(working_tree :: term()) :: boolean()

Returns true if the argument is a PID representing a valid WorkingTree process.

Link to this function

write_tree(working_tree, opts \\ [])

View Source
write_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: