upload_files: Upload files and create a commit

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

Description

This function uploads the specified files to a repository in GitHub and creates a commit on the specified branch.

Usage

upload_files(
  from_path,
  to_path,
  branch,
  message,
  repo,
  author,
  committer,
  parent,
  force = FALSE,
  ...
)

Arguments

from_path	(string) The paths to the files to upload. They must be readable.
to_path	(string) The paths to write the files to, within the repository.
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.
parent	(string, optional) Reference for the commit to use as a parent, 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.
force	(boolean, optional) Whether to force the update if it is not a simple fast-forward. Default: FALSE.
...	Parameters passed to gh_request().

Details

This function uploads the specified files to a repository and creates a new commit on the specified branch. Note: the files are created, or updated if they already exist, and any other files in the parent are left unchanged.

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

If a parent has been specified the files are created or updated. If a parent has not been specified, but the branch exists the current head commit is used as a parent. If the branch does not exist then an orphan commit is created.

Note: The GitHub API imposes a file size limit of 100MB for this request.

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_files() 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: 

  # Upload files to the main branch
  upload_files(
    from_path = c("c:/test/file1.txt", "c:/test/file2.txt"),
    to_path   = c("file1.txt", "file2.txt"),
    branch    = "main",
    message   = "Commit to test upload_files()",
    repo      = "ChadGoymer/githapi"
  )

  # Upload files into directories within the main branch
  upload_files(
    from_path = c(
      "c:/test/file1.txt",
      "c:/test/file2.txt",
      "c:/test/file3.txt"
    ),
    to_path   = c(
      "dir-1/file-1.txt",
      "dir-1/dir-1-1/file-2.txt",
      "dir-2/file-3.txt"
    ),
    branch    = "main",
    message   = "Commit to test upload_files()",
    repo      = str_c("ChadGoymer/test-files-", now)
  )

  # Upload files to the main branch specifying an author and committer
  upload_files(
    from_path = c("c:/test/file1.txt", "c:/test/file2.txt"),
    to_path   = c("file1.txt", "file2.txt"),
    branch    = "main",
    message   = "Commit to test upload_files()",
    repo      = "ChadGoymer/githapi",
    author    = list(name = "Bob",  email = "[e-mail]"),
    committer = list(name = "Jane", email = "[e-mail]")
  )

  # Create a new branch from the main branch
  upload_files(
    from_path = c("c:/test/file1.txt", "c:/test/file2.txt"),
    to_path   = c("file1.txt", "file2.txt"),
    branch    = "new-branch",
    message   = "Commit to test upload_files()",
    repo      = "ChadGoymer/githapi",
    parent    = "main"
  )


## End(Not run)

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