For more background on this post, see this
on the Bioc-devel mailing list. The short story is that I use Hadley
pkgdown package to
build a website for my packages and then publish it on GitHub.
The easiest is to create a
./docs package directory that contains
the whole site and configure GitHub pages to use it directly to
produce, for example, the
./docs directory ends in the package’s source which, on one hand
is nice as it simplifies tracking/committing of the site pages with
the package itself, but, on the other hand, the site also ends up on
the Bioconductor subversion server, where it doesn’t serve any purpose
other than taking space (5.5M in the case above).
Ignoring site from package tarball
It is straightforward to exclude the site’s
docs directory in the
package tarball/zipfile by amending the
.Rbuildignore file - adding
docs will do the trick.
Excluding from svn
It is not straightforward, however, to ignore the
docs directory on
hedgehog subversion server if you use
manage the GitHub and subversion repositories together.
git doesn’t support branch-specific
files or directives. Using different
.gitignore files for different
branches requires a hack described
how I have implemented it when documenting my Bioconductor packages
Define files to ignore
Instead of have a single static
.gitignore files, we are going to
create as branch-specific files and one general file defining what to
ignore. They all come in a new
gitignores directory. I choose to
name the general file
all and the branch-specific ones using the
branch name (
Each file contains exactly what a
.gitignore file would contain.
Dynamic generation of
When I’m in
master, I want my
.gitignore file to list files in
.gitignores/all only. When I’m in
devel, I want both files from
.gitignores/devel to be listed in
.gitignore. This can be achieved with a
post-checkout hook, that
will be triggered after each
git checkout. Mine is currently pretty
simple. I will always create a new
.gitignore file from
.gitignores/all and will append the content of a file in
.gitignores/ that matches the branch name.
I seems to work as expected.
I find this solution rather easy to implement. The major benefit is
that once it is in place, I can forget about it and things should work
irrespective of the
There is one drawback with this solution, however. When comparing the
master branches with
git diff, the ignored files are
Robert M. Flight
to use the good old original orphaned
gh-pages branch solution.
svn ignore property
If one doesn’t use
git-svn and manages
independently, then setting the svn ignore property with
should work. It doesn’t when managing both together.
I suggest to add a header to
.gitignores indicating that
is generated automatically and any updates will be overwritten.
And to ignore the
.gitignores directory completely, suffices to add
it to the general
excludes file. I prefer to keep it in
not svn, and ignore it when building the package bundle) to keep track
from what I ignore.