box_dir_diff: Compare the contents of Remote and Local Directories

Description Usage Arguments Details Value Author(s) References See Also


box_dir_diff is the internal function used by box_fetch and box_push to determine how to which files and folders should be uploaded/downloaded, updated, or deleted, to synchronize remote and local directories.


box_dir_diff(dir_id = box_getwd(), local_dir = getwd(), load = "up",
  folders = FALSE)



The id of the folder which you'd like to use for the comparison


The path of the local folder which you'd like to use for the comparison


logical. Should the results be in the context of an upload or a download operation? Permitted values are "up" or "down"


logical. Should folders/directories be included in the result?


box_dir_diff works by comparing files in the 'origin' to those in the 'destination'.

For downloading files (e.g. with box_fetch), the origin is the remote folder on specified with dir_id, and the destination would be the local directory specified by local_dir.

The reverse is true for uploads (e.g. via box_fetch).

box_dir_diff decides what should happen to a file based on three peices of information:


Is the file present in both the origin and destination? The filename (within the directory structure) is used to determine this.


If a file is present in both the origin and the destination, does it have the same content? The defintion comes from the file's sha1 hash, which for local files is determined using the digest function from the package of the same name. For remote files, it is queried from the API.

Modification Date

If a file is present in both the origin and destination, and the content is different in each, boxr will prefer the file which was most recently modified.

For local files, the 'content modified time' is used; the mtime variable returned by

For remote files, the modified_at date returned by the API. This is the time that the file was modified on the servers, as opposed to the time that the content itself was modified.

Why not use the content modified time for both?
With regards to the API, modified_at is preferred to content_modified_at, as it includes changes to the file outside of just it's content. This means that, for example, a collaborator could roll back to a previous version of a file, or upload a preferred but older version. These actions count as modifications on the servers, but not to the content of the file itself (they are reflected in modified_at, but not content_modified_at).

Implementing similar functionality for local files is not possible in a platform-independent manner; content modified time is the only file-based timestamp which has a consistent defintion for UNIX and Windows systems.


An object of class boxr_dir_comparison, describing the differences between the files.

It is a named list, it's entries containing data.frames, describing the files in each of the following categories:


Files which are present in the origin, but not the destination. These will be downloaded by box_fetch/uploaded by box_push.


These are files which are present in the destination, but not the origin. If delete is set to TRUE in box_fetch/box_push, they will be deleted.


Files which are present in both the orign and the destination, but which have more recently modified copies in the origin. If downloading with box_fetch, and overwrite set to TRUE, new files will overwrite existing local copies. If uploading with box_push (and overwrite set to TRUE), the new version will be uploaded to, with a new version number, and the old version still being available.


Files present in both origin and destination, with the same content. Note: A file may be modified at later date, but if it has identical contents according to it's sha1 hash, it will be considered up-to-date.

box_fetch/box_push do nothing for these files.


Files which are present in both origin and destination, but where the content differs, and the version in the destination has been more recently updated.

box_fetch/box_push do nothing for these files.


Analogous to the file operation, but for directories/folders.


Analogous to the file operation, but for directories/folders.


Brendan Rocks


See Also

box_fetch and box_push, which depend on this internal function, for timestamps describing local files, digest for details of the sha1 algorithm implementation.

Search within the boxr package
Search all R packages, documentation and source code

Questions? Problems? Suggestions? or email at

Please suggest features or report bugs with the GitHub issue tracker.

All documentation is copyright its authors; we didn't write any of that.