Provides a workflow for your analysis projects by combining literate programming ('knitr' and 'rmarkdown') and version control ('Git', via 'git2r') to generate a website containing time-stamped, versioned, and documented results.
This release overhauls the layout of the reproducibility report, adds support for GitLab, introduces some safety checks and warnings related to caching, provides more documentation, and more.
While it has always been possible to host workflowr projects using platforms other than GitHub, it was less convenient and not all the features were supported. With this release, a workflowr project hosted on GitLab has all the same features as a workflowr project hosted on GitHub, including links to past versions of the R Markdown, HTML, and figure files. It's also possible to use workflowr with GitHub Enterprise or a custom GitLab instance, but you'll have to coordinate with your administrators to make sure it's possible to host the website.
wflow_git_remote()to allow specifying any remote Git host, e.g.
domain = "gitlab.com"
wflow_use_gitlab()to automate GitLab setup
The layout of the reproducibility report and other content that workflowr inserts in the HTML output has been overhauled to be both highly informative but also collapsed by default. This way the information is there if you need it, but otherwise is minimally distracting.
wflow_use_gitlab()to insert a link to your workflowr project into the navigation bar
A popular knitr/rmarkdown feature is caching slow-running chunks. This can be
problematic for workflowr because it assumes that the results are newly created
wflow_publish() publishes the results with a given version of the code.
In this release, workflowr now provides warnings, safety checks, and some
convience arguments for safely using caching.
cache=TRUE) but is not set to re-run if its upstream chunks are changed (
wflow_build(). The default for
FALSE, so that old figures are not removed. This is useful for iterative development when plots from cached chunks may not be regenerated during a build. However,
clean_fig_filesis fixed to
wflow_publish()to ensure that the final results are produced during the build (suggested by @lazappi, #113)
wflow_publish(). The defult is
FALSE, but if set to
TRUEit will delete the cache directory prior to building each R Markdown file. This helps ensure reproducibility of the published results
wflow_build()send message about status of cache directory
In addition to the new vignette on GitLab, this release has multiple other new vignettes plus updates to existing ones.
_workflowr.ymlremoves the file extension from the figure subdirectories, allowing them to be viewed on Shiny Server (implemented by @Tutuchan, #119, #122)
fig.path, which workflowr ignores (idea from @lazappi, #114)
wflow_start(). It creates a Git pre-push hook that disables the ability to push to a remote repository. Useful for confidential projects. Currently only available for Linux and macOS (suggested by @rgayler, #141)
wflow_html()to facilitate integrating workflowr features into other R Markdown output formats such as blogdown (suggested by @docmanny, #126)
wflow_rename()to rename files and directories, including committing the change with Git
wflow_git_commit()fail early if any of the files have merge conflicts
wflow_git_push()set the upstream tracking branch by default (see git2r Issue 375)
wflow_build()report the current working directory. If the knit directory (where the code is executed) is different than the working directory, have
wflow_build()report where the code in each file is being executed
Fix unit test on CRAN Windows servers.
workflowr 1.1.0 is a maintenance release. It includes some minor new features, improved error handling, and bug fixes. Critically, it makes workflowr compatible with the latest release of git2r.
The most noticeable changes are 1)
wflow_status() are now
much faster, especially if your project has many R Markdown files and/or many
Git commits, 2) the rmarkdown package is no longer loaded automatically when you
load workflowr, and 3) the new function
wflow_open() (based on a previous
version in workflowrBeta) to open new or existing R Markdown files.
wflow_open(). Since there is no longer a workflowr template in workflowr 1.0+, it creates a file with a minimal YAML header (@xiangzhu, #107)
wflow_publish()to display the build log in the R console as each file is built. Useful for monitoring long-running code chunks (idea from @pcarbo)
latestto display the most recently modified HTML file
filesnow requires correct paths to existing R Markdown or HTML files. Previously,
wflow_view()would guess the correct path. While convenient, it was also potentially confusing since it was inconsistent with the other workflowr functions
latestis no longer mutually-exclusive with
files. If the most recently modified HTML is different than those specified by
files, they will all be opened for viewing
getOption("browser")does not provide a default option
git2r::odb_blobs()to obtain past commit times of files (if these functions are still slow for you, try running
git gcin the Terminal)
excludefrom the template
_site.yml. Also remove the file
analysis/.nojekyll(related to point above). Unlike
wflow_site()does not copy the entire directory to the output directory, so these fields have no effect. See the R Markdown documentation on Included files for more information
Fix Windows-specific bug in
wflow_git_commit(). The bug prevented Windows users from running these
functions from a subdirectory of a workflowr project
Restore all files in website directory if
wflow_publish() fails to build any
of the files (reported by @pcarbo)
If a user has not set the Git configuration variables
user.email, any workflowr function that creates a Git commit will throw an
informative error message. Previously this was only done for
but has been expanded to
wflow_remove() (idea from @pcarbo)
wflow_build() creates a new
.nojekyll file if necessary and
wflow_publish() commits it. This is most useful when changing the name of
the output directory (#72)
Various minor changes to documentation, tests, and package infrastructure to prepare for CRAN submission.
The 1.0.0 release is a major change. Instead of relying on the external code chunks
chunks.R to implement the reproducibility features, workflowr 1.0.0 replaces
chunks.R with the output format
wflow_html() and site generator
wflow_site(). This enables a much more informative reproducibility report to
# Install from GitHub devtools::install_github("jdblischak/workflowr") # Start a new project to test out the new features wflow_start("testproject") # Learn about the new ways to customize your site ?wflow_html # Update an existing project wflow_update()
wflow_site()to overhaul the reproduciblity features of workflowr
wflow_update()to udpate a pre-1.0 workflowr project to a post-1.0 project
create_links_page()(not widely used, if at all)
wflow_publish()is ignored if using
wflow_publish(republish = TRUE)does not build HTML files that have unstaged/staged changes
wflow_build()reports the total number of files that will be built
wflow_start()to set local Git user.name and user.email. Preferred method for most users is still to set global Git user.name and user.email with
wflow_publish() now views the website by default if run interactively (
view = interactive()) just like
Pin the dependency git2r to version 0.21.0 or lower because of the
forthcoming breaking changes in the git2r API. This is not a
great solution because
install.packages() always installs the latest version,
which will cause an error in the installation. If you are having trouble with
this, first install git2r with
and then retry installing workflowr. If your machine is running macOS or
Windows, you may need to run
install_version("git2r", "0.21.0", type = "binary").
Fix minor bug that affected the error message produced for a failed push or pull using the SSH protocol
wflow_git_pull() fails for an unknown reason, the
exact error message from
git2r::pull() is reported to
Multiple other internal changes to make workflowr more robust
Fix bug that caused
wflow_status() (and thus
wflow_publish()) to ignore R
Markdown files with the all lowercase file extension
.rmd (reported by @LSun
and @pcarbo). This was recently introduced in commit
so it only affected versions 0.10.0 and 0.10.1.
Fix bug that prevented deleted files from being committed with
wflow_publish() (reported by @pcarbo)
wflow_build()) now opens the website in the RStudio Viewer if run from within RStudio
wflow_build()automatically removes unused figure files
tempdir()instead of to
/tmp/workflowr. This prevents failures due to permission issues when mutliple workflowr users try to use the same machine (e.g. a compute node on a HPC cluster) (#86)
wflow_build()to build the R Markdown files in an external R process, it now runs
render_site()in the global environment of the external R process. This better mimics the results of the RStudio "Knit" button.
wflow_git_config()sets the Git options
wflow_git_push()pushes changes from the local computer to GitHub
wflow_git_pull()pulls the changes from GitHub to the local computer
wflow_build()automatically opens the website after building files, thus it's not necessary to always run
wflow_view()manually afterwards. If one file is built, then that file is opened. If more than one file is built, then the index page is opened. (#41)
wflow_build()adds objects to the global environment when building files locally in the R console (i.e.
local = TRUE) (#53)
wflow_remove()removes R Markdown files and all their associated files (e.g. HTML and figures)
wflow_remove()also works on non-Rmd files
wflow_convert()fail gracefully if the
diffutility is not available and inform the user to install Rtools
This minor release fixes a bug in how filepaths are resolved so that workflowr can run on Windows.
This release changes the interface of some of the main workflowr functions. The
wflow_status() are introduced, and the
wflow_commit() are re-designed.
wflow_status() reports which analysis files require user
attention (inspired by
Defines R Markdown files whose HTML has been committed as part of the Git repo
as "Published", R Markdown files which have been committed to the Git repo but
not their HTML as "Unpublished", and R Markdown files that are untracked by Git
as "Scratch". Furthermore, previously published files that have been
subsequently edited are classified as "Modified". See the man page
?wflow_status for more details.
This new function replaces the previous functionality of
basic interface is much simpler.
wflow_publish("analysis/file.Rmd") will 1) commit
analysis/file.Rmd in its own separate R session with
and 3) commit
docs/file.html and any generated figures. These 3 steps are
referred to as "publishing a file".
wflow_publish(all = TRUE) will publish all tracked analysis files, analogous
git commit -a.
To change the theme or make some other change to the entire site, run
wflow_publish("analysis/_site.yml", republish = TRUE), which will 1) commit
the configuration file
analysis/_site.yml, 2) re-build all the previously
published analysis files using the new configuration options, and 3) commit the
re-built HTML files.
wflow_build() runs in "Make"-mode, only building R Markdown
files that have been updated more recently than their corresponding HTML files.
If instead files are specfically stated, those files will be built.
By default, R Markdown files are now built each in their own separate R
session (similar in function to the "Knit HTML" button in RStudio). This
prevents undesirable behavior like sharing variables and loaded packages across
separate files. Set
local = TRUE to build the files in the local R console
(useful for debugging, but otherwise discouraged).
By default, the seed for random number generation is set to the arbitrary
set.seed()). This ensures that any code that produces
random numbers will be reproducible.
wflow_commit() has been demoted to only being a wrapper for the equivalent
git add and
git commit. This can be useful for committing
non-analysis files or R Markdown files that you aren't ready to publish yet.
However, you should use
wflow_publish() for the standard workflow.
all = TRUE to run the equivalent of
git commit -a.
wflow_update()to better explain its functionality. It will attempt to convert all R Markdown files present to use the latest version of the workflowr R Markdown template; however, it will only commit R Markdown files that are tracked by Git.
All workflowr functions should now accept the file extesion
.rmd in addition
.Rmd (Issue #10)
Replaced the shared argument
project to clarify that this
argument specifies the path to a directory in the workflowr project
wflow_start() now includes
Change dependency to R >= 3.2.5 (Issue #32)
Change stringr dependency (>= 1.1.0)
Started a vignette with Frequently Asked Questions
Added sections to README (Quick start, Upgrading, Related work, and Citation)
wflow_start()API has been simplified. Now the first (and only required) argument is the directory to be created. By default, the name of the project will be determined from the directory name. For example,
wflow_start("~/projects/proj-x")will create a workflowr project with the name "proj-x". To specify a different name, provide the argument
change_wd = TRUEchanges the working directory to the newly created project.
existing = FALSEis a safety feature so that by default workflowr projects are only created in new directories
wflow_start()no longer adds "BuildType: Website" to RStudio project file. Users should run
wflow_update()removes the build specification for existing workflowr projects
wflow_convert()to convert an R Markdown file based on the previous template to use the latest version
standalone = TRUEfor
path = NULL
wflow_update()function updates workflowr projects to use the latest version of the template
wflow_convert()converts an existing R Markdown file to use the workflowr template (can also update a file that uses a previous version of the template)
wflow_view()opens the website in the browser
wflow_remotes()manages remote Git repositories on GitHub. It can add a remote, remove a remote, or update the URL for an existing remote
Second alpha release. Major API overhaul.
Improved naming of functions:
wflow_commit can optionally add and commit provided files (argument is
commit_files) before re-building website and commiting HTML files
wflow_open accepts multiple filenames
wflow_commit have the argument
all to optionally build all the HTML files
First alpha release. Contains enough functions to create workflowr project from scratch.