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

read_tree_reason()

Reason codes that can be returned by read_tree/3.

reset_dir_cache_reason()

Error code reasons returned by reset_dir_cache/1.

t()

The process ID for a WorkingTree process.

update_dir_cache_reason()

Error code reasons returned by update_dir_cache/3.

write_tree_reason()

Reason codes that can be returned by write_tree/2.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

dir_cache(working_tree)

Returns a current snapshot of the working tree state.

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

Read a tree object and any trees it may refer to and populate the dir cache accordingly.

reset_dir_cache(working_tree)

Reset the dir cache to empty and rewrite the index file accordingly.

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

Starts a WorkingTree process linked to the current process.

update_dir_cache(working_tree, add, remove)

Apply updates to the dir cache and rewrite the index tree accordingly.

valid?(working_tree)

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

write_tree(working_tree, opts \\ [])

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

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

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

Error code reasons returned by reset_dir_cache/1.

t()

t() :: pid()

The process ID for a WorkingTree process.

update_dir_cache_reason()

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

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

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

dir_cache(working_tree)

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

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

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

reset_dir_cache(working_tree)

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:

Xgit.DirCache.to_iodevice/2.

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

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

update_dir_cache(working_tree, add, remove)

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

valid?(working_tree)

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

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

write_tree(working_tree, opts \\ [])

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: