workflowr (version 0.3.0)

wflow_commit: Commit the website files

Description

wflow_commit builds and commits the website files, ensuring that the website files are created by the proper R Markdown files that have been committed to the Git repository. Optionally can specify files to be committed before building the website.

Usage

wflow_commit(all = FALSE, commit_files = NULL, commit_message = NULL,
  dry_run = FALSE, include_staged = FALSE, path = ".")

Arguments

all

logical indicating if every R Markdown file should be rendered when building and committing the site (default: FALSE).

commit_files

Files to be committed to Git before building and committing website files (default: NULL).

commit_message

A commit message. Only used if specific files are specified to the argument files (default: NULL).

dry_run

Identifies R Markdown files that have been updated, but does not render them.

include_staged

logical. By default wflow_commit will stop if it detects any files in the staging area. Set to TRUE ff you want these files to be included in the commit created by wflow_commit (not recommended).

path

By default the function assumes the current working directory is within the project. If this is not true, you'll need to provide the path to the project directory.

Value

If dry_run = TRUE, returns the character vector of R Markdown files that would be rendered. Otherwise invisibly returns this vector.

Details

worklowr facilitates reproducibility by placing the current SHA-1 of the Git repository at the top of each HTML file. This indicates which version of the code could be used to reproduce the results. In order for this to be meaningful, the R Markdown file must not have changed since it was last committed. wflow_commit can be invoked in 3 different (though not mutually exclusive) modes.

First, running wflow_commit with the default arguments will identify all R Markdown files which have been modified more recently in the Git commit history than their corresponding HTML files. Furthermore these files must not currently have any subsequent changes that have not been committed. The files will be built and the correspoding HTML committed.

Second, you can have wflow_commit first add and commit files specified with the argument commit_files. A message for this commit can also be specified with the argument commit_message. After this commit has been made, wflow_commit then searches the Git commit history as described above.

Third, you can have wflow_commit re-build and commit all the webpages by setting all = TRUE. This is useful if you are making an aesthetic change, e.g. the theme, that needs to be applied regardless of whether the R Markdown file has been edited. Only tracked files without uncommitted changes will be re-built (this prevents the HTML not matching the corresponding R Markdown file).

Examples

# NOT RUN {
# Build and commit the webpages that are out of date
wflow_commit()
# Specify files to commit (with a corresponding commit message),
# prior to building and committing the webpages
wflow_commit(commit_files = c("pipeline.R", "new-analysis.Rmd"),
             commit_message = "Finished new analysis")
# Re-build all the webpages
# (e.g. to implement an aesthetic change)
wflow_commit(all = TRUE)
# }