# Module Topkg.Vcs

    module Vcs: sig .. end

Version control system repositories.

## Version control system repositories

    type kind = [ `Git | `Hg ]

The type for version control systems (VCS).

    val pp_kind : Stdlib.Format.formatter -> kind -> unit

`pp_kind ppf k` prints an unspecified representation of `k` on `ppf`.

    type commit_ish = string

The type for symbols resolving to a commit. The module uses `"HEAD"` for specifying the current checkout; use this symbol even if the underlying VCS is ``Hg`.

    type t

The type for version control systems repositories.

    val kind : t -> kind

`kind r` is `r`'s VCS kind.

    val dir : t -> Topkg.fpath

`dir r` is `r`'s repository directory.

    val cmd : t -> Topkg.Cmd.t

`cmd r` is the base VCS command to use to act on `r`.

Warning Prefer the functions below to remain VCS independent.

    val find : ?dir:Topkg.fpath -> unit -> t option Topkg.result

`find ~dir ()` looks for a VCS repository in working directory `dir` (not the repository directory like `.git`, default is guessed automatically).

    val get : ?dir:Topkg.fpath -> unit -> t Topkg.result

`get` is like `Topkg.Vcs.find` but returns an error if no VCS was found.

    val pp : Stdlib.Format.formatter -> t -> unit

`pp ppf r` prints an unspecified representation of `r` on `ppf`.

## Repository state

    val is_dirty : t -> bool Topkg.result

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

    val not_dirty : t -> unit Topkg.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 -> Topkg.fpath -> bool Topkg.result

`file_id_dirty r f` is `Ok true` iff `f` has uncommited changes.

    val head : ?dirty:bool -> t -> string Topkg.result

`head ~dirty r` is the HEAD commit identifier of the repository `r`. If `dirty` is `true` (default), and indicator is appended to the commit identifier if the working tree of `r` `Topkg.Vcs.is_dirty`.

    val commit_id : ?dirty:bool ->
           ?commit_ish:commit_ish -> t -> string Topkg.result

`commit_id ~dirty ~commit_ish r` is the object name (identifier) of `commit_ish` (defaults to `"HEAD"`). If `commit_ish` is `"HEAD"` and `dirty` is `true` (default) and indicator is appended to the identifier if the working tree is dirty.

    val commit_ptime_s : ?commit_ish:commit_ish -> t -> int Topkg.result

`commit_ptime_s t ~commit_ish` is the POSIX time in seconds of commit `commit_ish` (defaults to `"HEAD"`) of repository `r`.

    val describe : ?dirty:bool ->
           ?commit_ish:commit_ish -> t -> string Topkg.result

`describe ~dirty ~commit_ish r` identifies `commit_ish` (defaults to `"HEAD"`) using tags from the repository `r`. If `commit_ish` is `"HEAD"` and `dirty` is `true` (default) an indicator is appended to the identifier if the working tree is dirty.

    val tags : t -> string list Topkg.result

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

    val changes : ?until:commit_ish ->
           t ->
           after:commit_ish -> (string * string) list Topkg.result

`changes r ~after ~until` is the list of commits with their one-line message from commit-ish `after` to commit-ish `until` (defaults to `"HEAD"`).

    val tracked_files : ?tree_ish:string -> t -> Topkg.fpath list Topkg.result

`tracked_files ~tree_ish r` are the files tracked by the tree object `tree_ish` (defaults to `"HEAD"`).

## Repository operations

    val clone : t -> dir:Topkg.fpath -> unit Topkg.result

`clone r ~dir` clones `r` in directory `dir`.

    val checkout : ?branch:string ->
           t -> commit_ish:commit_ish -> unit Topkg.result

`checkout r ~branch commit_ish` checks out `commit_ish`. Checks out in a new branch `branch` if provided.

    val commit_files : ?msg:string -> t -> Topkg.fpath list -> unit Topkg.result

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

    val tag : ?force:bool ->
           ?sign:bool ->
           ?msg:string ->
           ?commit_ish:string -> t -> string -> unit Topkg.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 -> string -> unit Topkg.result

`delete_tag r t` deletes tag `t` in repo `r`.