R/branches.R

In ChadGoymer/githapi: User-friendly access to the GitHub API for R

#  FUNCTION: create_branch -----------------------------------------------------
#
#' Create a branch in a repository
#'
#' This function creates a new branch in the specified repository in GitHub. It
#' must be pointed at a commit by providing a Git reference, which can be either
#' a SHA, branch or tag. For a branch, the head commit is used.
#'
#' For more details see the GitHub API documentation:
#'
#' - <https://docs.github.com/en/rest/reference/git#create-a-reference>
#'
#' @param name (string) The name of the branch.
#' @param ref (string) Either a SHA, branch or tag used to identify the commit.
#' @param repo (string) The repository specified in the format: `owner/repo`.
#' @param ... Parameters passed to [gh_request()].
#'
#' @return `create_branch()` returns a list of the branch's properties.
#'
#' **Branch Properties:**
#'
#' - **name**: The name of the branch.
#' - **sha**: The commit SHA the branch is pointing at.
#' - **protected**: Whether the branch is protected.
#' - **html_url**: The address of the branch's web page in GitHub.
#'
#' @examples
#' \dontrun{
#'
#'   create_branch(
#'     name = "new-branch",
#'     ref  = "main",
#'     repo = "ChadGoymer/githapi"
#'   )
#'
#' }
#'
#' @export
#'
create_branch <- function(
  name,
  ref,
  repo,
  ...
) {
  assert_ref(name)
  assert_repo(repo)
  if (!is_sha(ref)) {
    ref <- view_sha(ref = ref, repo = repo, ...)
  }
  assert_sha(ref)

  payload <- list(ref = str_c("refs/heads/", name), sha = ref)

  info("Creating branch '", name, "' in repository '", repo, "'")
  branch_lst <- gh_url("repos", repo, "git/refs") %>%
    gh_request("POST", payload = payload, ...)

  info("Transforming results", level = 4)
  branch_gh <- gh_url("repos", repo, "branches", name) %>%
    gh_request("GET", ...) %>%
    select_properties(properties$branch)

  info("Done", level = 7)
  structure(
    branch_gh,
    url     = attr(branch_lst, "url"),
    request = attr(branch_lst, "request"),
    status  = attr(branch_lst, "status"),
    header  = attr(branch_lst, "header")
  )
}


#  FUNCTION: update_branch -----------------------------------------------------
#
#' Update a branch in a repository
#'
#' This function updates a branch in the specified repository to point at a new
#' commit. It must be pointed at a commit by providing a Git reference, which
#' can be either a SHA, branch or tag. For a branch, the head commit is used.
#'
#' For more details see the GitHub API documentation:
#'
#' - <https://docs.github.com/en/rest/reference/git#update-a-reference>
#'
#' @param branch (string) The name of the branch.
#' @param ref (string) Either a SHA, branch or tag used to identify the new
#'   commit.
#' @param repo (string) The repository specified in the format: `owner/repo`.
#' @param force (boolean, optional) Whether to force the update if it is not a
#'   simple fast-forward. Default: `FALSE`.
#' @param ... Parameters passed to [gh_request()].
#'
#' @return `update_branch()` returns a list of the branch properties.
#'
#' **Branch Properties:**
#'
#' - **name**: The name of the branch.
#' - **sha**: The commit SHA the branch is pointing at.
#' - **protected**: Whether the branch is protected.
#' - **html_url**: The address of the branch's web page in GitHub.
#'
#' @examples
#' \dontrun{
#'
#'   update_branch(
#'     name = "new-branch",
#'     repo = "ChadGoymer/githapi",
#'     ref  = "6b7b5a090d47fd3ef495620513a3f80da2487b1d"
#'   )
#'
#' }
#'
#' @export
#'
update_branch <- function(
  branch,
  ref,
  repo,
  force = FALSE,
  ...
) {
  assert_ref(branch)
  assert_repo(repo)
  assert_logical(force, n = 1)
  if (!is_sha(ref)) {
    ref <- view_sha(ref = ref, repo = repo, ...)
  }
  assert_sha(ref)

  info("Updating branch '", branch, "' in repository '", repo, "'")
  branch_lst <- gh_url("repos", repo, "git/refs/heads", branch) %>%
    gh_request("PATCH", payload = list(sha = ref, force = force), ...)

  info("Transforming results", level = 4)
  branch_gh <- gh_url("repos", repo, "branches", branch) %>%
    gh_request("GET", ...) %>%
    select_properties(properties$branch)

  info("Done", level = 7)
  structure(
    branch_gh,
    url     = attr(branch_lst, "url"),
    request = attr(branch_lst, "request"),
    status  = attr(branch_lst, "status"),
    header  = attr(branch_lst, "header")
  )
}


#  FUNCTION: view_branches -----------------------------------------------------
#
#' View branches within a repository
#'
#' `view_branches()` summarises branches in a table with the properties as
#' columns and a row for each branch in the repository. `view_branch()` returns
#' a list of all properties for a single branch.
#'
#' For more details see the GitHub API documentation:
#'
#' - <https://docs.github.com/en/rest/reference/repos#list-branches>
#' - <https://docs.github.com/en/rest/reference/repos#get-a-branch>
#'
#' @param branch (string) The name of the branch.
#' @param repo (string) The repository specified in the format: `owner/repo`.
#' @param n_max (integer, optional) Maximum number to return. Default: `1000`.
#' @param ... Parameters passed to [gh_page()] or [gh_request()].
#'
#' @return `view_branches()` returns a tibble of branch properties.
#'   `view_branch()` returns a list of properties for a single branch.
#'
#' **Branch Properties:**
#'
#' - **name**: The name of the branch.
#' - **sha**: The commit SHA the branch is pointing at.
#' - **protected**: Whether the branch is protected.
#' - **html_url**: The address of the branch's web page in GitHub.
#'
#' @examples
#' \dontrun{
#'
#'   # View all branches in a repository
#'   view_branches(repo = "ChadGoymer/githapi")
#'
#'   # View a single branch
#'   view_branch(branch = "new-branch", repo = "ChadGoymer/githapi")
#'
#' }
#'
#' @export
#'
view_branches <- function(
  repo,
  n_max = 1000,
  ...
) {
  assert_repo(repo)
  assert_natural(n_max, n = 1)

  info("Viewing branches for repository '", repo, "'")
  branches_lst <- gh_url("repos", repo, "branches") %>%
    gh_page(n_max = n_max, ...)

  info("Transforming results", level = 4)
  branches_gh <- bind_properties(branches_lst, properties$branch)

  info("Done", level = 7)
  branches_gh
}


#  FUNCTION: view_branch -------------------------------------------------------
#
#' @rdname view_branches
#' @export
#'
view_branch <- function(
  branch,
  repo,
  ...
) {
  assert_ref(branch)
  assert_repo(repo)

  info("Viewing branch '", branch, "' in repository '", repo, "'")
  branch_lst <- gh_url("repos", repo, "branches", branch) %>%
    gh_request("GET", ...)

  info("Transforming results", level = 4)
  branch_gh <- select_properties(branch_lst, properties$branch)

  info("Done", level = 7)
  branch_gh
}


#  FUNCTION: delete_branch -----------------------------------------------------
#
#' Delete a branch from a repository
#'
#' This function deletes a branch from a repository, as long as you have
#' appropriate permissions. Care should be taken as it will not be recoverable.
#'
#' For more details see the GitHub API documentation:
#'
#' - <https://docs.github.com/en/rest/reference/git#delete-a-reference>
#'
#' @param branch (string) The name of the branch.
#' @param repo (string) The repository specified in the format: `owner/repo`.
#' @param ... Parameters passed to [gh_request()].
#'
#' @return `delete_branch()` returns a TRUE if successfully deleted.
#'
#' @examples
#' \dontrun{
#'
#'   delete_branch(branch = "new-branch", repo = "ChadGoymer/githapi")
#'
#' }
#'
#' @export
#'
delete_branch <- function(
  branch,
  repo,
  ...
) {
  assert_ref(branch)
  assert_repo(repo)

  info("Deleting branch '", branch, "' in repository '", repo, "'")
  response <- gh_url("repos", repo, "git/refs/heads", branch) %>%
    gh_request("DELETE", ...)

  info("Done", level = 7)
  structure(
    TRUE,
    class   = c("github", "logical"),
    url     = attr(response, "url"),
    request = attr(response, "request"),
    status  = attr(response, "status"),
    header  = attr(response, "header")
  )
}