Recommend using bundler to ensure the correct dependencies are installed

[matt-allan]

Hi Hoodies,

I was looking for a starter issue and saw the comments on this post about having trouble setting up jekyll locally. Then I tried and had the same issues :)

I was able to get everything working correctly by doing a bundle install and then using bundle exec jekyll * instead of jekyll *.

Since the jekyll-redirect-from and jekyll-paginate plugins are already specified in the github-pages gem, bundle install will always install the correct versions.

I wasn't sure why bundle exec worked better, but here is what I found on the bundler website:

In some cases, running executables without bundle exec may work, if the executable happens to be installed in your system and does not pull in any gems that conflict with your bundle.

However, this is unreliable and is the source of considerable pain. Even if it looks like it works, it may not work in the future or on another machine.

[gr2m]

Thanks @yuloh, I can confirm that bundle exec also worked for me when I run into this.
LGTM 👍

[gr2m]

can you leave the white space? It’s needed for line breaks. Same in line 99

[matt-allan]

Sorry, editor preferences 😄

[gr2m]

I’ve another question, it’s been a while since my ruby days :) We have Gemfile.lock in .gitignore. The bundler website suggests to add it to git though: git add Gemfile Gemfile.lock. What do you think would be recommended for us?

[janl]

If we do this, we need to add how to install bundler to the instructions ;)

> bundle install
-bash: bundle: command not found

Also, we are using https://github.com/jekyll/jekyll-redirect-from and it’s not defined in our Gemfile, we should all fix this in one go.

[janl]

@yuloh great initiative! :)

[steveklabnik]

Yes, this is correct. bundle exec will ensure that only the gems in your Gemfile and their dependencies are in the path.

I’ve another question, it’s been a while since my ruby days :) We have Gemfile.lock in .gitignore. The bundler website suggests to add it to git though: git add Gemfile Gemfile.lock. What do you think would be recommended for us?

It should be in ignore for libraries, but not for applications. This site is an application, so it should be in source control, not ignored.

[matt-allan]

Another option is to not commit the lock file and parse the versions.json provided by github, which would ensure the local version of the github-pages gem is always up to date. It's explained in the jekyll docs under the "Use the github-pages gem" heading. If we commit the gemfile.lock we will just need to run bundle update regularly.

If we do this, we need to add how to install bundler to the instructions ;)

Good point. I will push an update to the readme.

Also, we are using https://github.com/jekyll/jekyll-redirect-from and it’s not defined in our Gemfile, we should all fix this in one go.

I thought the same thing initially but it's actually installed by the github pages gem. All of the github pages gem dependencies are listed here. Since github pages builds with the --safe option, any dependencies not listed in the github-pages gem are ignored.

[janl]

I thought the same thing initially but it's actually installed by the github pages gem.

@yuloh perfect!

[matt-allan]

These instructions are paraphrased from the github pages instructions.

[matt-allan]

I got some clarification on the downsides of using the versions.json approach over here. Every time you do bundle exec jekyll serve it will make an HTTP call, which isn't really ideal.

I'm going to update this pull request to version the Gemfile.lock, since that seems like the best way to go. It does mean contributors will occasionally need to run bundle update github-pages to keep the local version in sync.

[matt-allan]

This change allows the github-pages gem to set jekyll config settings, like enabling Github flavored markdown. The full config it's using is in this file.

[gr2m]

Tested it locally and worked flawlessly, great work everyone :) LGTM

[gr2m]

@janl can you double check before we merge?

[gr2m]

merged via 7b040c2, 44575e0, 412af70, a5d6910