Recipe: Show history of project updates in your project automatically

If you are using Git to track changes to your book (or other project), you can mark a major update with an annotated tag at the appropriate commit. The following code will automatically include that information in your book, showing the most recent changes first. If there are no tags, it will add nothing at all to your project.

``` {r echo=FALSE, results='asis'}
cmd0 = "git fetch --all --tags"
cmd1 = "git tag -l --sort=-*creatordate --format='%(*creatordate:short) | %(tag) | %(contents)'"
system(cmd0,intern=FALSE)
updates = system(cmd1,intern=TRUE)
if (length(updates) != 0) {
    cat('#### Latest updates to this book {-}', updates, sep='\n\n')
}
    ```


The output will look like this:


Latest updates to this book

2020-09-22 | v0.1.2 | proofed through chapter 2 section 1

2020-08-16 | v0.1.1 | proofed through intro

2020-08-10 | v0.1 | full clean text, including footnotes


I'm pumped that I got it working, so I thought I'd share it here. Here are the commands necessary to make an annotated tag, if you don't know how:

How to create an annotated tag and push it to Github

  • Creating a tag for the current commit:
    • git tag -a v0.2 -m "full clean text, including footnotes"
  • Creating a tag for an older commit:
    • git tag -a v0.1 132e843 -m "full clean text, including footnotes"
  • Push all your tags to Github:
    • git push origin --tags

To remove a tag, delete it locally and remotely, respectively, with these two commands (in case you make a mistake)

  • git tag -d v0.1
  • git push --delete origin v0.1

You could also show every commit, with its message, or just the 5 most recent ones, or any other info you can lookup with a git command by replacing cmd1 above with whatever gets you the info you want.

Hope you like it!

Edit: If you are only building locally and not using something like Travis CI, you don't need to push your tags to Github. You can just create them locally.

3 Likes

That is cool ! Thanks !

I believe you could also use R code I guess to do part of that and not call git command directly with the gert package (or git2r)

And if pushing tags to Github, that would allow to use the Github API I think, using gh package for api V3, or httr or new grapql github API V4 with package like ghql

Just sharing as your way is nice already !

1 Like

I should probably have explained why I’ve done this instead of just manually inserting the update info into the book, which is easy enough with one book.

However, this is going on a cover page that gets inserted as a child Rmd into every project. This way, every project gets this info without having to go through and edit every book or report etc.

1 Like

@cderv, this just stopped working on my Travis-CI built books. At first it didn't work on Travis because the tags didn't get downloaded to the local repo by default. That's why there are two commands--one to get the tags to show up in the local repo, and the second to lookup the tag info. But now I can't figure out any reason why it wouldn't work. Any ideas?

On a related note, I'm assuming this broke because of a new version of bookdown. (I haven't setup renv yet. I'm still just installing the latest version with Rscript -e "install.packages('bookdown')" as part of my build script.) But the odd thing is that I can tell bookdown has been updated because it installed a new JS plugin called anchor-sections, which says it was "written by Atsushi Yasumoto on Oct 3rd, 2020." But I don't see any evidence of that change on Github. In fact, I can't find that plugin in the bookdown project on Github at all. Is development actually happening somewhere else or am I just terribly confused?

This had been added in rmarkdown, and reflect to bookdown because it is a hard dependency

But it is currently in dev version. Are you sure you are installing CRAN version ?

Like that, without seeing how your thing is working, I don't really have any idea. Your git project worflow with tag should not be impacted by dependencies. but your build can.

Can you share the repo ?

Ah. Got it. Thanks!

Well... I know that the above command is what I added to the Travis YAML. I know that it gets me a newer (strike that, different) version of bookdown than what I would get otherwise (because I'm doing this to avoid a bug in the version installed by default). And I don't think that it gets me the GitHub dev version. So, the question remains, what version is it getting, and from where? I probably knew at one point, but I don't anymore.

Here's what I added to my Travis YAML, based on my understanding at the time:

  - Rscript -e "install.packages('bookdown')" #installs latest version of bookdown. 
#  - Rscript -e "remotes::install_github('rstudio/bookdown', upgrade = TRUE)" # Installs dev version of bookdown. Should not be necessary most of the time.

However, the place where bookdown is specified for installation by default is in the last line of the DESCRIPTION file:

Package: placeholder
Type: Book
Title: Does not matter.
Version: 0.0.1
Imports: bookdown
Remotes: rstudio/bookdown

Perhaps I'm mistaken about what exactly I'm doing?

EDIT:

Here is what the Travis log says:

$ Rscript -e "install.packages('bookdown')"
898 Installing package into ‘/home/travis/R/Library’
899 (as ‘lib’ is unspecified)
900 trying URL 'https://cloud.r-project.org/src/contrib/bookdown_0.20.tar.gz'

Take care on how Travis is working
See https://docs.travis-ci.com/user/languages/r/#dependencies

FWIU, It will install dependencies based on what is in the DESCRIPTION

So depending when the line which install bookdown is run, it could be overwrite by github version because you got a Remote field in DESCRIPTION.

You could add a SessionInfo() at the end of your pipeline for checking. Or before building. :man_shrugging:

Thanks. I think I've got it nailed down. remotes/bookdown means that the latest dev version of bookdown and rmarkdown will be installed from Github. Then I'm apparently downgrading to a previous version of bookdown that behaves the way I want. :frowning: This has been helpful, but I've definitely gotten us off topic. I'll open a new topic if I have further questions about that in particular.

I'm still trying to figure out why the Travis build doesn't work with the recipe above, though.

This topic was automatically closed 21 days after the last reply. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.