upload_commit: Upload a directory of files and create a commit

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

Description

This function uploads all the files in the directory (except those in the ignore argument) and creates a new commit on the specified branch. Note: the new commit is created with exactly the files uploaded, so if a file in the parent commit has not been uploaded it will be removed in the new commit.

Usage

upload_commit(
  path,
  branch,
  message,
  repo,
  author,
  committer,
  parents,
  ignore = c("\\.git", "\\.Rproj\\.user", "\\.Rhistory", "\\.RData",
    "\\.Ruserdata"),
  force = FALSE,
  ...
)

Arguments

path	(string) The path to the directory to upload. It must be readable.
branch	(string) The name of the branch to make the new commit on.
message	(string) The commit message.
repo	(string) The repository specified in the format: owner/repo.
author	(list, optional) A the name and email address of the user who wrote the changes in the commit.
committer	(list, optional) A the name and email address of the user who created the commit.
parents	(character, optional) References for the commits to use as parents, can be either a SHA, branch or tag. If it is a branch then the head commit is used. See the details section for more information.
ignore	(character, optional) The files to ignore in the directory. Default: ".git", ".Rproj.user", ".Rhistory", ".RData" and ".Ruserdata".
force	(boolean, optional) Whether to force the update if it is not a simple fast-forward. Default: FALSE.
...	Parameters passed to gh_request().

Details

The author and committer arguments are optional and if not supplied the current authenticated user is used. However, if you want to set them explicitly you must specify a named list with name and email as the elements (see examples).

A commit may have none, one or two parents. If none are specified and the branch already exists, the head of the branch will be used as a parent. If the branch does not exist, an orphan commit is created without a parent. If one parent is specified the commit is added and the branch set to the new commit, if it is a simple fast-forward. If you want to set the branch to the new commit no matter what then set the force argument to TRUE. If two parents are specified then a merge commit is created.

For more details see the GitHub API documentation:

• https://docs.github.com/en/rest/reference/git#create-a-blob

• https://docs.github.com/en/rest/reference/git#create-a-tree

• https://docs.github.com/en/rest/reference/git#create-a-commit

Value

upload_commit() returns a list of the commit properties.

Commit Properties:

• sha: The commit SHA.

• message: The commit message.

• author_name: The author's name.

• author_email: The author's email address.

• committer_name: The committer's name.

• committer_email: The committer's email address.

• tree_sha: The SHA of the file tree.

• parent_sha: The commit SHA of the parent(s).

• date: The date the commit was made.

Examples

## Not run: 

  # Add a commit to the main branch
  upload_commit(
    path    = "C:/files-to-upload",
    branch  = "main",
    message = "Commit to test upload_commit()",
    repo    = "ChadGoymer/githapi"
  )

  # override the author and committer
  upload_commit(
    path      = "C:/files-to-upload",
    branch    = "main",
    message   = "Commit to test upload_commit()",
    repo      = "ChadGoymer/githapi",
    author    = list(name = "Bob",   email = "[e-mail]"),
    committer = list(name = "Jane",  email = "[e-mail]")
  )

  # Create a commit on a new branch
  upload_commit(
    path    = "C:/files-to-upload",
    branch  = "test-commits-1",
    message = "Commit to test upload_commit()",
    repo    = "ChadGoymer/githapi",
    parents = "main"
  )

  # Create an orphan commit
  upload_commit(
    path    = "C:/files-to-upload",
    branch  = "test-commits-2",
    message = "Commit to test upload_commit()",
    repo    = "ChadGoymer/githapi"
  )

  # Force branch to point at the new commit
  upload_commit(
    path    = "C:/files-to-upload",
    branch  = "main",
    message = "Commit to test upload_commit()",
    repo    = "ChadGoymer/githapi",
    parents = "test-commits-1",
    force   = TRUE
  )

  # Create a commit merging a branch into the main branch
  upload_commit(
    path    = "C:/files-to-upload",
    branch  = "main",
    message = "Commit to test upload_commit()",
    repo    = "ChadGoymer/githapi",
    parents = c("main", "test-commits-1")
  )

  # Create a commit merging two branches into a new branch
  upload_commit(
    path    = "C:/files-to-upload",
    branch  = "test-commits-3",
    message = "Commit to test upload_commit()",
    repo    = "ChadGoymer/githapi",
    parents = c("main", "test-commits-2")
  )


## End(Not run)

ChadGoymer/githapi documentation built on Oct. 22, 2021, 10:56 a.m.