Module B00_vcs

Version control system (VCS) repositories.

XXX. This likely needs a cleanup design round. Also make clear that this is not command oriented but repo oriented should make things more clear.

VCS kinds

type kind =
| Git
| Hg

The type for VCS supported by the module.

val pp_kind : kind B00_std.Fmt.t

pp_kind formats types of VCS.

Version control system repositories

type t

The type for VCS repositories.

val kind : t -> kind

kind r is r's kind.

val repo_dir : t -> B00_std.Fpath.t

repo_dir r is r's repository directory (not the working directory).

val work_dir : t -> B00_std.Fpath.t

work_dir r is r's working directory. On a git bare repo this may be Fpath.null.

val repo_cmd : t -> B00_std.Cmd.t

repo_cmd r is the base command to use to act on r. Use only if you need VCS specific functionality not provided by the module.

val pp : t B00_std.Fmt.t

pp formats a repository.

Finding local repositories

val find : ?dir:B00_std.Fpath.t -> unit -> (t option, string) result

find ~dir () finds, using VCS functionality, a repository starting in directory dir (if unspecified this is the cwd).

val get : ?dir:B00_std.Fpath.t -> unit -> (t, string) result

get is like find but errors if no VCS was found.

Commits

type commit_ish = string

The type for symbols resolving to a commit. Important, the module uses "HEAD" for specifying the commit currently checkout in the working directory; use this symbol even if the underlying VCS is Hg.

type commit_id = string

The type for commit identifiers. Note that the module sometimes appends the string "-dirty" to these identifiers in which case they are no longer.

val head : commit_ish

head is "HEAD". A symbol to represent the commit currently checked out in the working directory.

val commit_id : t -> dirty_mark:bool -> commit_ish -> (commit_id, string) result

commit_id r ~dirty_mark ~commit_ish is the object name (identifier) of commit_ish. If commit_ish is "HEAD" and dirty_mark is true (default) and the working tree of r is_dirty, a mark gets appended to the commit identifier.

val commit_ptime_s : t -> commit_ish -> (int, string) result

commit_ptime_s t commit_ish is the POSIX time in seconds of commit commit_ish of repository r.

val changes : t -> after:commit_ish -> until:commit_ish -> ((commit_id * string) list, string) result

changes r ~after ~until is the list of commits with their one-line synopsis from commit-ish after to commit-ish until.

val tracked_files : t -> tree_ish:string -> (B00_std.Fpath.t list, string) result

tracked_files ~tree_ish r are the files tracked by the tree object tree_ish.

val commit_files : ?stdout:B00_std.Os.Cmd.stdo -> ?stderr:B00_std.Os.Cmd.stdo -> ?msg:string -> t -> B00_std.Fpath.t list -> (unit, string) result

commit_files r ~msg files commits the file files with message msg (if unspecified the VCS should prompt).

Working directory

val is_dirty : t -> (bool, string) result

is_dirty r is Ok true iff the working directory of r has uncommited changes.

val not_dirty : t -> (unit, string) result

not_dirty is Ok () iff the working directory of r is not dirty and an error that enjoins to stash or commit otherwise.

val file_is_dirty : t -> B00_std.Fpath.t -> (bool, string) result

file_is_dirty r f is Ok true iff f has uncommited changes.

val checkout : ?and_branch:string -> t -> commit_ish -> (unit, string) result

checkout r ~and_branch commit_ish checks out commit_ish in the working directory of r. Checks out in a new branch and_branch if provided. This fails if the current working directory is_dirty.

val local_clone : t -> dir:B00_std.Fpath.t -> (t, string) result

local_clone r ~dir clones r to a working directory dir and returns a repo to operate on it.

Tags

type tag = string

The type for VCS tags.

val tags : t -> (tag list, string) result

tags r is the list of tags in the repo r.

val tag : ?msg:string -> t -> force:bool -> sign:bool -> commit_ish -> tag -> (unit, string) result

tag r ~force ~sign ~msg commit_ish t tags commit_ish with t and message msg (if unspecified the VCS should prompt). If sign is true (defaults to false) signs the tag (`Git repos only). If force is true (default to false) doesn't fail if the tag already exists.

val delete_tag : t -> tag -> (unit, string) result

delete_tag r t deletes tag t in repo r.

val describe : t -> dirty_mark:bool -> commit_ish -> (string, string) result

describe r dirty_mark commit_ish identifies commit_ish using tags from the repository r. If commit_ish is "HEAD" and dirty_mark is true (default) and the working tree of r is_dirty, a mark gets appended to the description.

val latest_tag : t -> commit_ish -> (tag option, string) result

latest_tag r commit_ish finds the latest tag in the current branch describing commit_ish.

Git specific operations

module Git : sig ... end

Git specific operations.

module Hg : sig ... end