README.md

In richfitz/ghwiki: A GitHub Wiki Workflow

Wiki Workflow

This package sets up a lab notebook on a GitHub wiki by running a series of R scripts and knitr documents, collecting figures and updating a wiki. It has grown out of a set of scripts, but is currently used across many of my (not-yet-open) research projects.

The wiki for rodeint is updated using ghwiki. This page was generated from this script and can be recomputed and updated by running a single command.

ghwiki needs to be used within a project that is a git repository. The git repository must have a github remote, and the first remote that has a github url will be used. The remote must already have a wiki.

Install with (from R)

devtools::install_github("richfitz/ghwiki")

Initialise with

Rscript -e "ghwiki::init()"

This will also clone the github wiki into a directory 'wiki' in the project root. If the command failed (e.g., the wiki was not initialised yet), pull down the project wiki manually with:

make wiki_clone

Add names of R or Rmd scripts to the file .wiki_scripts. A template is generated by running the command above. Blank lines and lines beginning with "#" are ignored, and whitespace is trimmed. If .md files are added, they will be copied to the wiki, along with any figures named following the same conventions we convince knitr to follow. At the moment, any file not ending with .R, .Rmd or .md is simply ignored.

Run

make

to run all the scripts listed in .wiki_scripts, generating md files, figures etc. A bunch of knit tweaks are applied to normalise figure paths, improve default settings, etc.

Run

make wiki_update

to update the local copy of the wiki repo, and

make wiki_publish

to push it up. You're on your own with resolving conflicts. Other make targets:

• make clean -- clean up generated .md and .Rmd files.
• make wiki_rollback -- undo a commit in the wiki repo
• make wiki_reset -- destructively clean up an unclean state in the wiki repo

Other commands can be run via ./.ghwiki:

• ./.ghwiki reset_to <SHA> -- move the wiki to a particular SHA (can undo a rollback this way)
• ./.ghwiki git [commands] -- run git commands in the wiki repo (e.g., ./.ghwiki git log)

And yet more commands via ./.ghwiki scripts

• ./.ghwiki scripts list -- list of scripts that we know about
• ./.ghwiki scripts base -- basename of the scripts (without extension)
• ./.ghwiki scripts generated_Rmd -- Rmd files that are candidates for deletion during cleanup
• ./.ghwiki scripts targets -- list of md files that will be generated by make.

If you get fed up with typing ./.ghwiki (which gets tedious) run

Rscript -e "ghwiki:::install_scripts('~/bin')"

which will install the scripts ghwiki into "~/bin" (assuming that it exists!). If that is in your $PATH then you can run ghwiki git log and things like that. Note that these scripts just redirect to the true scripts within the package, so can be left in place through package upgrades -- the scripts that are run are those in the package.

richfitz/ghwiki documentation built on May 27, 2019, 8:18 a.m.