Xgit v0.1.6 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 may have a default working tree associated with it or it may not. (Such a repository 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

t()

The process ID for a WorkingTree process.

update_dir_cache_reason()

Error code reasons returned by update_dir_cache/3.

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.

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.

Link to this section Types

t()

t() :: pid()

The process ID for a WorkingTree process.

update_dir_cache_reason()

update_dir_cache_reason() ::
  Xgit.Core.DirCache.add_entries_reason()
  | Xgit.Core.DirCache.remove_entries_reason()
  | Xgit.Repository.WorkingTree.ParseIndexFile.from_iodevice_reason()
  | Xgit.Repository.WorkingTree.WriteIndexFile.to_iodevice_reason()

Error code reasons returned by update_dir_cache/3.

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.Core.DirCache.t()}
  | {:error,
     reason :: Xgit.Repository.WorkingTree.ParseIndexFile.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.Repository.WorkingTree.ParseIndexFile.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.Core.DirCache structure across process boundaries. Issue #88

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

start_link(
  repository :: Xgit.Repository.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 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.Core.DirCache.Entry.t()],
  remove :: [{[path :: [byte()]], stage :: 0..3 | :all}]
) :: {:ok, Xgit.Core.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.Core.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.