We anticipate the next release of googledrive will have version v2.0.0.
As of 2020-09-30, Drive no longer allows a file to be placed in multiple folders; going forward, every file will have exactly 1 parent folder. In many cases that parent is just the top-level or root folder of your “My Drive” or of a shared drive.
This change has been accompanied by the introduction of file shortcuts, which function much like symbolic or “soft” links. Shortcuts are the new way to make a file appear to be in more than one place or, said another way, the new way for one Drive file to be associated with more than one Drive filepath. A shortcut is a special type of Drive file, characterized by the
application/vnd.google-apps.shortcut MIME type. You can make a shortcut to any Drive file, including to a Drive folder.
Drive has been migrating existing files to the one-parent state, i.e., “single parenting” them. Drive selects the most suitable parent folder to keep, “based on the hierarchy’s properties”, and replaces any other parent-child relationships with a shortcut.
New functions related to shortcuts:
shortcut_create(): creates a shortcut to a specific Drive file (or folder).
shortcut_resolve(): resolves a shortcut to its target, i.e. the file it refers to. Works for multiple files at once, i.e. the input can be a mix of shortcuts and non-shortcuts. The non-shortcuts are passed through and the shortcuts are replaced by their targets.
How interacts with googledrive’s support for specifying file by filepath:
drive_reveal(what = "path")returns the canonical path, i.e. there will be no shortcuts among the non-terminal “folder” parts of the returned path.
drive_get(path = "foo/")can retrieve a folder named “foo” or a shortcut named “foo”, whose target is a folder.
path, in a context where it unambiguously specifies a parent folder, the
pathis auto-resolved to its target folder. This is the exception to the “no automatic resolution” rule. Functions affected:
Further reading about changes to the Drive folder model:
The user interface has gotten more stylish, thanks to the cli package (https://cli.r-lib.org). All informational messages, warnings, and errors are now emitted via cli, which uses rlang’s condition functions under-the-hood.
googledrive_quiet is a new option to suppress informational messages from googledrive. Unless it’s explicitly set to
FALSE, the default is to message.
verbose argument of all
drive_*() functions is deprecated and will be removed in a future release. In the current release,
verbose = FALSE is still honored, but generates a warning.
drive_reveal(what = "property_name") now works for any property found in the file metadata stored in the
drive_resource column. The new column is also simplified in more cases now, e.g. to
logical. If the
property_name suggests it’s a date-time, we return
We’ve modernized the mechanisms by which the
dribble class is (or is not) retained by various data frame operations. This boils down to updating or adding methods used by the base, dplyr, pillar/tibble, and vctrs packages.
We focus on compatibility with dplyr >= 1.0.0, which was released a year ago. googledrive only Suggests dplyr, so all this really means is that
dribble manipulation via dplyr now works best with dplyr >= 1.0.0.
Patch release to modify a test for compatibility with an upcoming release of gargle.
Better handling of filenames that include characters that have special meaning in a regular expression (#292).
drive_find() explicitly checks for and eliminates duplicate records for a file ID, guarding against repetition in the paginated results returned by the API. It would seem that this should never happen, but there is some indication that it does. (#272, #277, #279, #281)
drive_share_anyone() is a new convenience wrapper that makes a file readable by “anyone with a link”.
as_tibble() method for
dribble objects now passes
... through, which could apply, for example, to tibble’s
The release of version 1.0.0 marks two events:
There is also new functionality that makes it less likely you’ll create multiple files with the same name, without actually meaning to.
googledrive’s auth functionality now comes from the gargle package, which provides R infrastructure to work with Google APIs, in general. The same transition is happening in several other packages, such as bigrquery and gmailr. This makes user interfaces more consistent and makes two new token flows available in googledrive:
Where to learn more:
drive_auth()all that most users need
OAuth2 tokens are now cached at the user level, by default, instead of in
.httr-oauth in the current project. We recommend that you delete any vestigial
.httr-oauth files lying around your googledrive projects and re-authorize googledrive, i.e. get a new token, stored in the new way.
The local OAuth2 token key-value store now incorporates the associated Google user when indexing, which makes it easier to switch between Google identities.
The arguments and usage of
drive_auth() have changed.
Previous signature (v0.1.3 and earlier)
Current signature (>= v1.0.0)
For full details see the resources listed in Where to learn more above. The change that probably affects the most code is the way to provide a service account token:
drive_auth(service_token = "/path/to/your/service-account-token.json")(v0.1.3 and earlier)
drive_auth(path = "/path/to/your/service-account-token.json")(>= v1.0.0)
Auth configuration has also changed:
drive_auth_configure()is a variant of the now-deprecated
drive_auth_config()whose explicit and only job is to set aspects of the configuration, i.e. the OAuth app or API key.
drive_deauth()is how you go into a de-authorized state, i.e. send an API key in lieu of a token.
drive_has_token() is a new helper that simply reports whether a token is in place, without triggering the auth flow.
There are other small changes to the low-level developer-facing API:
generate_request()has been renamed to
make_request()had been renamed to
request_make()and is a very thin wrapper around
gargle::request_make()that only adds googledrive’s user agent.
build_request()has been removed. If you can’t do what you need with
process_response()has been removed. Instead, use
gargle::response_process(response), as we do inside googledrive.
Google Drive doesn’t impose a 1-to-1 relationship between files and filepaths, the way your local file system does. Therefore, when working via the Drive API (instead of in the browser), it’s fairly easy to create multiple Drive files with the same name or filepath, without actually meaning to. This is perfectly valid on Drive, which identifies file by ID, but can be confusing and undesirable for humans.
googledrive v1.0.0 offers some new ways to fight this:
drive_put()is a new convenience wrapper that figures out whether to call
Changes inspired by #230.
These functions gain an
drive_create()this whole function is new
The default of
overwrite = NA corresponds to the current behaviour, which is to “Just. Do. It.”, i.e. to not consider pre-existing files at all.
overwrite = TRUE requests to move a pre-existing file at the target filepath to the trash, prior to creating the new item. If 2 or more files are found, an error is thrown, because it’s not clear which one(s) to trash.
overwrite = FALSE means the new item will only be created if there is no pre-existing file at that filepath.
Existence checks based on filepath (or name) can be expensive. This is why the default is
overwrite = NA, in addition to backwards compatibility.
Sometimes you have a file you will repeatedly send to Drive, i.e. the first time you run an analysis, you create the file and, when you re-run it, you update the file. Previously this was hard to express with googledrive.
In pseudo-code, here’s the basic idea of
All functions that support
... as a way to pass more parameters to the Drive API now have “tidy dots semantics”:
!!! is supported for splicing and
!! can be used on the LHS of
:=. Full docs are in
drive_find() now sorts by “recency”, by default.
drive_create() is a new function that creates a new empty file, with an optional file type specification (#258, @ianmcook).
drive_mkdir() becomes a thin wrapper around
drive_create(), with the file type hard-wired to “folder”.
drive_mkdir(), the optional parent directory is now known as
path instead of
parent. This is more consistent with everything else in googledrive, which became very obvious when adding
drive_create() and the general
Colaboratory notebooks now have some MIME type support, in terms of the
type argument in various functions (https://colab.research.google.com/). The internal table of known MIME types includes
"application/vnd.google.colab", which is associated with the file extension
.ipynb and the human-oriented nickname
R 3.1 is no longer explicitly supported or tested. Our general practice is to support the current release (3.6), devel, and the 4 previous versions of R (3.5, 3.4, 3.3, 3.2). See Which versions of R do tidyverse packages support?.
gargle and magrittr are newly Imported.
rprojroot has been removed from Suggests, because we can now use a version of testthat recent enough to offer
Minor patch release for compatibility with the imminent release of purrr 0.3.0.