Module B0_vcs_repo

Version control system (VCS) repositories.

The toplevel module abstracts operations over VCS. The Hg and Git modules offer VCS specific operations.

Dry runs

type dry_run = B0_std.Cmd.t -> unit

The type for dry runs. In dry run for effectful operations, the actual command is given to this function and the operation succeeds without performing it.

VCS kinds

type kind =
  1. | Git


  2. | Hg



The type of VCS supported by the module.

val pp_kind : kind B0_std.Fmt.t

pp_kind formats kinds of VCS.

val kind_to_string : kind -> string

kind_to_string k is a string for k.

val kinds : kind list

kinds is the list of supported VCS.


type t

The type for VCS repositories.

val kind : t -> kind

kind r is r's VCS kind.

val repo_dir : t -> B0_std.Fpath.t

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

val work_dir : t -> B0_std.Fpath.t

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

val repo_cmd : t -> B0_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. See also Git and Hg.

val pp : t B0_std.Fmt.t

pp formats a repository. This formats repo_dir.

val pp_long : t B0_std.Fmt.t

pp_long formats a repository. This formats kind followed by repo_dir.

Finding local repositories

val find : ?search:B0_std.Cmd.tool_search -> ?kind:kind -> ?dir:B0_std.Fpath.t -> unit -> (t option, string) Stdlib.result

find ~dir () finds, using VCS functionality, a repository starting in directory dir (if unspecified this is the cwd). If kind is specified, will only look for a vcs of kind kind. The VCS tool is looked up with search (default to Os.Cmd.find ?search.

val get : ?search:B0_std.Cmd.tool_search -> ?kind:kind -> ?dir:B0_std.Fpath.t -> unit -> (t, string) Stdlib.result

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


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. The module sometimes appends the string "-dirty" to these identifiers in which case they are no longer proper identifiers.

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

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

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

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

val changes : t -> ?after:commit_ish -> ?last:commit_ish -> unit -> ((commit_id * string) list, string) Stdlib.result

changes repo ~after ~last is the list of commits with their one-line synopsis from commit-ish after (defaults to the start of the branch) to commit-ish last (defaults to head).

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

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

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

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

val pp_commit : commit_ish B0_std.Fmt.t

pp_commit formats a commit.

Working directory

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

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

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

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

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

file_is_dirty repo file is Ok true iff file has uncommited changes.

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

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

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

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

val pp_dirty : unit B0_std.Fmt.t

pp_dirty formats the string "dirty".


type tag = string

The type for VCS tags.

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

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

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

tag repo ~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 : ?dry_run:dry_run -> t -> tag -> (unit, string) Stdlib.result

delete_tag repo t deletes tag t in repo.

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

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

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

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

val find_greatest_version_tag : t -> (tag option, string) Stdlib.result

find_latest_version_tag repo lists tags with tags sorts those who parse with B0_std.String.to_version in increasing order and takes the greatest ones.

VCS specific operations

module Git : sig ... end

Git specific operations.

module Hg : sig ... end

Mercurial specific operations.