package datakit-client

  1. Overview
  2. Docs

All changes to a branch are made in transactions. When a transaction is committed, it is merged with the current contents of the branch.

Reading

include Datakit_S.READABLE_TREE with type 'a or_error := 'a or_error
type t
val read : t -> Datakit_path.t -> [ `File of Cstruct.t | `Dir of string list | `Link of string ] or_error Lwt.t

read t path is the contents of the object at the path.

val stat : t -> Datakit_path.t -> Datakit_S.stat option or_error Lwt.t

stat t path is the metadata of the object at path.

val exists : t -> Datakit_path.t -> bool or_error Lwt.t

exists t path is true if stat t path isn't None.

val exists_file : t -> Datakit_path.t -> bool or_error Lwt.t

exists_file t path is similar to exists but for files only.

val exists_dir : t -> Datakit_path.t -> bool or_error Lwt.t

exists_dir t path is similar to exists but for directories only.

val read_file : t -> Datakit_path.t -> Cstruct.t or_error Lwt.t

read_file t path resolves path to a file, or returns an error if it isn't a file.

val read_dir : t -> Datakit_path.t -> string list or_error Lwt.t

read_dir t path resolves path to a directory, or returns an error if it isn't one.

read_link t path resolves path to a symlink, or returns an error if it isn't one.

Writing

val create_dir : t -> Datakit_path.t -> unit or_error Lwt.t

create_dir t path creates the directory path.

val create_file : t -> Datakit_path.t -> ?executable:bool -> Cstruct.t -> unit or_error Lwt.t

create_file t path ?executable content creates the file path.

create_symlink t path target creates the symlink path.

val replace_file : t -> Datakit_path.t -> Cstruct.t -> unit or_error Lwt.t

replace_file t path new_content changes the content of the existing file path.

val create_or_replace_file : t -> Datakit_path.t -> Cstruct.t -> unit or_error Lwt.t

create_or_replace_file t path content uses either create_file or replace_file as appropriate to set the contents.

val set_executable : t -> Datakit_path.t -> bool -> unit or_error Lwt.t

set_executable t path flag marks the file at path as executable or not.

val remove : t -> Datakit_path.t -> unit or_error Lwt.t

remove t path removes path. If path is a directory then the entire subtree is removed.

val rename : t -> Datakit_path.t -> string -> unit or_error Lwt.t

rename t path new_name changes the basename of path to new_name. Note: it is only possible to rename within a directory (this is a 9p limitation).

val truncate : t -> Datakit_path.t -> int64 -> unit or_error Lwt.t

truncate t path length sets the length of the file at path to length. If length is longer than the current length, the file is padded with zero bytes.

val make_dirs : t -> Datakit_path.t -> unit or_error Lwt.t

make_dirs t path ensures that path exists and is a directory, creating it and any missing parents as necessary.

Finishing

val commit : t -> message:string -> unit or_error Lwt.t

commit t ~message creates a new commit with the given log message and the current contents of the transaction and then merges it into the branch from which the transaction was created. The transaction cannot be used after calling this.

val abort : t -> unit Lwt.t

abort t aborts the transaction without committing it. The transaction cannot be used after calling this.

Merging and history

type merge_inputs = {
  1. ours : Tree.t;
  2. theirs : Tree.t;
  3. base : Tree.t;
}

When performing a merge, these three directories can be used to calculate the final result. ours is the previous contents of the transaction, theirs is the commit being merged and base is a least common ancestor. If there is no common ancestor then base is an empty tree.

val merge : t -> Commit.t -> (merge_inputs * Datakit_path.t list) or_error Lwt.t

merge t commit merges commit into the transaction. It performs any trivial merges it can and returns (merge_inputs, conflicts) to allow you to resolve the remaining ones. You must write to each path in conflicts at least once before you can commit the transaction. You may perform multiple merges in one transaction, but the merge_inputs returned is only valid until the start of the next merge.

val parents : t -> Commit.t list or_error Lwt.t

parents t is the parents of the transaction (that is, the parents of the commit that would be generated if you committed now.

val set_parents : t -> Commit.t list -> unit or_error Lwt.t

set_parents t new_parents replaces the current list of parents. Note that this does not perform a merge - it only affects the metadata. Note also that merge automatically updates the parents, so it is not necessary to call it manually in that case.

val conflicts : t -> Datakit_path.t list or_error Lwt.t

conflicts t returns the current list of paths that had merge conflicts and have not been written to since. It is not possible to commit while this is non-empty.

diff t c returns the paths differences between c and t's head.

val closed : t -> bool

closed t is true if t is closed and thus it is not valid to read/write on it anymore.