Quickly start a workflowr project

Source: R/wflow_quickstart.R

wflow_quickstart provides a simple interface to effortlessly create a workflowr project from an existing data analysis.

wflow_quickstart(
  files,
  username = NULL,
  organization = NULL,
  supporting_files = NULL,
  directory = NULL,
  change_wd = TRUE,
  delete_on_error = TRUE,
  view = getOption("workflowr.view"),
  git.user.name = NULL,
  git.user.email = NULL,
  host = c("github", "gitlab"),
  create_on_github = NULL
)

Arguments

files

character. The R Markdown file(s) to be copied into the subdirectory analysis/ of the newly created workflowr project. If the argument directory is left as NULL, the workflowr project will be named after the first Rmd file. This new directory will be located in the current working directory. Supports file globbing.

username

character (default: NULL). The GitHub or GitLab personal account you want to use to create the remote Git repository. It can also be the name of a GitLab Group that you belong to. However, if it is a GitHub organization, instead use the argument organization.

organization

The GitHub organization account you want to use to create the remote Git repository.

supporting_files

character (default: NULL) Supporting files or directories that are used by the Rmd files. These will be copied to the root of the project. Since by default Rmd files are executed in the root of the project, any relative file paths should still work. Long term it is recommended to move these supporting files to subdirectories of the workflowr project, e.g. data/.

directory

character (default: NULL). The path to the directory to create the workflowr project. This directory will also be used to name the remote Git repository. If left as NULL, the name is derived from the first Rmd file that is passed to the argument files.

change_wd

logical (default: TRUE). Change the working directory to the newly created workflowr project. Passed to wflow_start.

delete_on_error

logical (default: TRUE). Delete the newly created project if any error occurs.

view

logical (default: getOption("workflowr.view")). View the local website after it is built (will open the home page in the RStudio Viewer pane or your web browser).

git.user.name

character (default: NULL). The user name used by Git to sign commits, e.g., "Ada Lovelace". This setting only applies to the workflowr project being created. To specify the global setting for the Git user name, use wflow_git_config instead. When user.name = NULL, no user name is recorded for the project, and the global setting will be used. This setting can be modified later by running git config --local in the Terminal.

git.user.email

character (default: NULL). The email address used by Git to sign commits, e.g., "ada.lovelace@ox.ac.uk". This setting only applies to the workflowr project being created. To specify the global setting for the Git email address, use wflow_git_config instead. When user.name = NULL, no email address is recorded for the project, and the global setting will be used. This setting can be modified later by running git config --local in the Terminal.

host

character. Choose the service for hosting the Git repository. Must be either "github" for GitHub.com or "gitlab" for GitLab.com.

create_on_github

logical (default: NULL). Should workflowr create the repository on GitHub? This requires logging into your GitHub account to authenticate workflowr to act on your behalf. The default behavior is to ask the user. Note that this only works for public repositories on github.com. If you want to create a private repository or are using GitHub Enterprise, you will need to manually create the repository.

Value

Invisibly returns the absolute path to the newly created workflowr project.

Details

wflow_quickstart performs the following steps:

  • Starts a new project with wflow_start

  • Copies the Rmd file(s) to the subdirectory analysis/

  • Copies the supporting file(s) and/or directory(s) to the root of the project (Note: by default Rmd files are executed in the root of the project, so relative file paths should still work)

  • Adds link(s) to the results to the main index page

  • Publishes the Rmd files with wflow_publish

  • Configures the remote repository with wflow_use_github or wflow_use_gitlab

Once it has completed, you can push to the remote service with wflow_git_push. Alternatively you can run git push in the terminal.

If you are using GitHub and you chose to not allow workflowr to create the repository for you, then you will have to login to your account and create the new repository yourself. If you're using GitLab, you don't have to worry about this because the new repository will be automatically created when you push.

Examples

if (FALSE) {

wflow_quickstart(files = "existing-analysis.Rmd", username = "your-github-username")
}