Git is a distributed version control system. It has been used for the development of VuFind® since version 2.0.

To get a copy of the latest VuFind® code in Git, you can issue this command:

git clone https://github.com/vufind-org/vufind.git

To update the code at a subsequent date, you can load any changes made since your initial clone with:

git pull

Git can be a useful tool for managing and deploying your local custom installation of VuFind®. This section describes one possible approach. It assumes some familiarity with Git; see below for resources to help you learn more.

1.) Create a fork of the main VuFind® repository. If you plan on tracking your configuration files in Git, be sure that this is private – you can either use a private GitHub repository or host your own Git repository on a local server.

2.) On your server, clone the fork and check out the appropriate branch or tag for your needs. If you want to stay up to date with bleeding-edge development, use dev. If you want to stick to an officially-released version, use a tag like v4.1.3 or v5.0.

3.) From the checked-out branch or tag, create a new branch for your local work on the server (for example, you might create a development branch for your development server, a staging branch for your staging server, and a production branch on your production server).

4.) Set up Composer and run “composer install” to load VuFind®'s dependencies.

5.) Set up and configure VuFind® (you can follow the usual Installation documentation, just use your Git checkout in place of a downloaded .tar.gz file).

6.) Commit your local custom code and configuration, then push everything up to your fork.

Note that, starting with release 9.0, VuFind® includes rules in its .gitignore file that will prevent you from committing certain files from your local/config/vufind directory. This is a safety feature to prevent people from accidentally sharing local content in public. When you actually intend to commit these files to a private repository, you can override this by putting an additional .gitignore file inside local/config/vufind to reverse the instructions:

!*.ini
!*.json
!*.yaml

As suggested in step 3 above, if you have a development –> staging –> production cycle, it is useful to create a separate branch for each server where you are deploying VuFind®. This way, you can use simple Git merges to move changes through the cycle.

Imagine that you have established a branch on your development server called “development” and you have pushed it up to your private Git repository. Now you wish to deploy the code on your staging server. You could follow these steps:

1.) Clone the private repository.

2.) Check out the development branch.

3.) Create a new “staging” branch derived from “development.”

4.) Adjust configurations to reflect the staging server.

5.) Commit the changes and push them up to your private repository.

From this point forward, updating your staging server to receive the latest changes from development is simply a matter of pushing up the development branch from the development server, fetching the changes on the staging server, and merging the latest “development” branch changes into the “staging” branch. Most of the time, this should work seamlessly, though if there are changes in areas where configuration differs between development and staging, you may occasionally need to resolve minor merge conflicts.

You will periodically want to update your fork with upstream changes – for example, when a new feature you need is added to the dev branch, or when a new official release is issued.

For example, suppose that you established a “development” branch based on the v4.1 tag, and you wish to upgrade to VuFind® 5.0. You could follow these steps:

1.) Set up a remote named “upstream” if you do not already have one, pointing at the main VuFind® Git repository.

2.) Perform a “git fetch upstream” to get the upstream changes and new tags.

3.) Perform a “git merge v5.0” to bring in the release 5.0 changes.

4.) Run “composer install” to update dependencies as needed.

5.) Update your local configurations and customizations as described in the migration notes. As noted there, always check the changelog for possible breaking changes. You may be able to automate some of the local updates (configurations and templates) by using the technique described in this article.

The Upgrading VuFind® Using Git video demonstrates a procedure similar to the one described here.

You can learn more about Git in the free online Pro Git book or through the reference manual.

• Automatically updating locally customized files with Git and diff3 - An article on using Git to update locally customized configuration and theme files.
• Useful Git Branches - Branches in the VuFind® repository that may offer useful features beyond the core distribution.