box_fetch: Download/upload directories from/to Box

Description

box_fetch(): download the contents of a Box folder to a local directory
box_push(): upload the contents of a local directory to a Box folder

Files present in the origin but not the destination will be copied over.

Behavior when a file exists in both depends on the arguments supplied.

Usage

box_fetch(
  dir_id = box_getwd(),
  local_dir = getwd(),
  recursive = TRUE,
  overwrite = FALSE,
  delete = FALSE
)
box_push(
  dir_id = box_getwd(),
  local_dir = getwd(),
  ignore_dots = TRUE,
  overwrite = FALSE,
  delete = FALSE
)

Arguments

dir_id

numeric or character, folder ID at Box.

local_dir

character, path to local directory.

recursive

logical, indicates to include subdirectories.

overwrite

logical, indicates that newer files at origin will overwrite older files at destination.

delete

logical, indicates to delete files that exist at destination, but not at origin.

ignore_dots

logical, indicates to ignore directories with names that begin with dots, e.g. .git and .Rproj.user.

Value

Object with S3 class boxr_dir_wide_operation_result.

Overwrite/Update

In the interests of preventing mishaps, overwrite is by default set to FALSE, which means that files which exist in the destination, but which are out of date, are not modified.

Setting overwrite to TRUE is likely to produce expected behavior for most users.

This is a conservative precaution to prevent users unexpectedly overwriting their files, and may change as a default in later releases.

However, files at Box are versioned, and most operating systems have file recovery features (e.g. 'Trash' (Ubuntu/Debian/OSX), or 'Recycle Bin' (Windows)), so unintended modification of files will be revertible for most users.

Implementation

At the time of writing, the Box API allows for only one file at a time to be uploaded/downloaded. As a result, boxr recursively scans the directory tree, uploading/downloading files in loops. Because the Box API can send, but not accept, gzipped files, downloading tends to be faster than uploading.

box_fetch()/box_push() rely on the internal function box_dir_diff() to determine how to process individual files (i.e. which to update, which to leave as is, etc.). See its help page for details.