A note from the authors: Some of the information and instructions in this book are now out of date because of changes to Hugo and the blogdown package. If you have suggestions for improving this book, please file an issue in our GitHub repository. Thanks for your patience while we work to update the book, and please stay tuned for the revised version!

In the meantime, you can find an introduction to the changes and new features in the v1.0 release blog post and this "Up & running with blogdown in 2021" blog post.

— Yihui, Amber, & Alison

D.7 Version control

If your website source files are under version control, we recommend that you add at least these two folder names to your .gitignore file41:

/blogdown/
/public/

The blogdown/ directory is used to store cache files, and they are most likely to be useless to the published website. Only knitr may use them, and the published website will not depend on these files.

The public/ directory should be ignored if your website is going to be automatically (re)built on a remote server such as Netlify.

As we mentioned in Section D.5, R plots will be copied to static/, so you may see new files in GIT after you render an Rmd file that has graphics output. You need to add and commit these new files in GIT, because the website will use them.

Although it is not relevant to blogdown, macOS users should remember to ignore .DS_Store and Windows users should ignore Thumbs.db.

If you are relatively familiar with GIT, there is a special technique that may be useful for you to manage Hugo themes, which is called “GIT submodules.” A submodule in GIT allows you to manage a particular folder of the main repository using a different remote repository. For example, if you used the default hugo-lithium from my GitHub repository, you might want to sync it with my repository occasionally, because I may update it from time to time. You can add the GIT submodule via the command line:

git submodule add \
  https://github.com/yihui/hugo-lithium.git \
  themes/hugo-lithium

If the folder themes/hugo-lithium exists, you need to delete it before adding the submodule. Then you can see a SHA string associated with the “folder” themes/hugo-lithium in the GIT status of your main repository indicating the version of the submodule. Note that you will only see the SHA string instead of the full content of the folder. Next time when you want to sync with my repository, you may run the command:

git submodule update --recursive --remote

In general, if you are happy with how your website looks, you do not need to manage the theme using GIT submodules. Future updates in the upstream repository may not really be what you want. In that case, a physical and fixed copy of the theme is more appropriate for you.

  1. In the pattern use, the first / means to not ignore recursively but only from the current directory of the .gitignore. See more about .gitignore pattern in https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring↩︎