repository.R

#' Create or discover a local Git repository
#'
#' * `git_init()` creates a new repository
#' * `git_find()` to discover an existing local repository.
#' * `git_info()` shows basic information about a repository, such as the SHA
#'   and branch of the current HEAD.
#'
#' @section Path:
#'
#' For `git_init()` the `path` parameter sets the directory of the git repository
#' to create. If this directory already exists, it must be empty. If it does
#' not exist, it is created, along with any intermediate directories that don't
#' yet exist.
#'
#' For `git_find()`, the `path` parameter specifies the directory at
#' which to start the search for a git repository. If it is not a git repository
#' itself, then its parent directory is consulted, then the parent's parent, and
#' so on.
#'
#' @export
#' @rdname git_repo
#' @name git_repo
#' @family git
#' @useDynLib gert R_git_repository_init
#' @inheritParams git_open
#' @param path the location of the git repository, see the "path" section.
#' @param bare if true, a Git repository without a working directory is created
#' @git repository
#' @return
#' * `git_find()` and `git_init()`: the path to the Git repository.
#' * `git_info()`: A list of information of the Git repository.
#' @examples
#' # directory does not yet exist
#' r <- tempfile(pattern = "gert")
#' git_init(r)
#' git_find(r)
#' git_info(r)
#'
#' # create a child directory, then a grandchild, then search
#' r_grandchild_dir <- file.path(r, "aaa", "bbb")
#' dir.create(r_grandchild_dir, recursive = TRUE)
#' git_find(r_grandchild_dir)
#'
#' # cleanup
#' unlink(r, recursive = TRUE)
#'
#' # directory exists but is empty
#' r <- tempfile(pattern = "gert")
#' dir.create(r)
#' git_init(r)
#' git_find(r)
#'
#' # cleanup
#' unlink(r, recursive = TRUE)
git_init <- function(path = '.', bare = FALSE) {
  path <- normalizePath(path.expand(path), mustWork = FALSE)
  repo <- .Call(R_git_repository_init, path, as.logical(bare))
  git_repo_path(repo)
}

#' @export
#' @rdname git_repo
#' @useDynLib gert R_git_repository_find
git_find <- function(path = '.') {
  path <- normalizePath(path.expand(path), mustWork = FALSE)
  out <- .Call(R_git_repository_find, path)
  dirname(out)
}

#' @export
#' @rdname git_repo
#' @useDynLib gert R_git_repository_info
#' @section Detached head:
#' If `git_info()$shorthand` is equal to `HEAD`,
#' it means the repository is in a [detached head state](https://jvns.ca/blog/2023/11/01/confusing-git-terminology/#detached-head-state).
git_info <- function(repo = '.') {
  repo <- git_open(repo)
  .Call(R_git_repository_info, repo)
}