Write file to GitLab repository

Uploads a file to a GitLab repository via GitLab's v4 RESTful API. High-level function that by default skips uploading identical file content and automatically chooses file_create() or file_update() depending on whether the file already exists or not.

Usage

file_write(
  content,
  path,
  id_project = funky::config_val("id_project"),
  start_branch = project_default_branch(id_project = id_project, base_url = base_url,
    token = token, max_tries = max_tries),
  branch = start_branch,
  from_file = FALSE,
  overwrite = TRUE,
  force = FALSE,
  commit_message = "auto: write file via gitlab R pkg",
  author_email = NULL,
  author_name = NULL,
  execute_filemode = FALSE,
  last_commit_id = file_meta(path = path, attribute = "last_commit_id", id_project =
    id_project, ref = branch, base_url = base_url, token = token, max_tries = max_tries),
  base_url = funky::config_val("base_url"),
  token = funky::config_val("token"),
  max_tries = 3L,
  quiet = FALSE
)

Arguments

content

character(1) or raw()
File content, as a character scalar for text files, or a raw vector for binary files. Or the path to a local file as a character scalar if from_file = TRUE.

path

character(1)
File path, relative to the repository root.

id_project

integer(1)
GitLab project identifier.

start_branch

character(1)
Name of the base branch to create branch from if it doesn't already exist.

branch

character(1)
Git branch name to upload the file to.

from_file

logical(1)
Whether or not content indicates the path to a local file instead of the actual file content.

overwrite

logical(1)
Whether or not to overwrite an already existing file. Unless force = TRUE, the file is only overwritten if it is not identical to content.

force

logical(1)
Whether or not to overwrite an already existing file even if it is identical to content.

commit_message

character(1)
Git commit message.

author_email

character(1)
Git commit author's email address. NULL means to default to the token owner.

author_name

character(1)
Git commit author's name. NULL means to default to the token owner.

execute_filemode

logical(1)
Whether or not to mark the uploaded file as executable.

last_commit_id

character(1)
Last known file commit identifier. If provided (and valid), GitLab won't write to the file if a commit made after last_commit_id has modified the file. Intended to avoid concurrency issues (e.g. from CI pipelines). NULL means to skip the check.

base_url

character(1)
Base URL to the GitLab v4 RESTful API root.

token

character(1)
GitLab access token used for authentication. If NULL, the API request is made unauthenticated which results in HTTP 404 Not Found and other errors for non-public resources.

max_tries

integer(1)
Maximum number of request attempts in case of an HTTP error. An integerish scalar. Retries are performed using exponential backoff and jitter, see httr2::req_retry() for details.

quiet

logical(1)
Whether or not to suppress printing status output from internal processing.

Value

path, invisibly.

Details

To save up to two additional HEAD requests, set start_branch and last_commit_id explicitly. Setting last_commit_id = NULL is fine as long as file writes are part of a controlled, single-user process where concurrency is not a concern.

See also

Other functions to manage files on GitLab: commit_files(), file_commit_action(), file_content(), file_create(), file_delete(), file_exists(), file_full(), file_meta(), file_req(), file_update(), files_delete()

Examples

if (FALSE) { # \dontrun{
gitlab::file_write(content = "a line of text",
                   path = "test.md",
                   id_project = 64767928)} # }