Git-enabling an Existing Moodle Installation: A Step-by-Step Guide

Did you download the source code when you first installed Moodle instead of cloning it? Perhaps you installed Moodle on your computer using one of the Moodle Installer Packages for Windows or MacOS. Cloning Moodle LMS using the git command can be incredibly beneficial, particularly for reducing the process of updating your site from hours to minutes, managing modifications you may have made to the core code, and improving collaboration among development teams. This step-by-step guide outlines the process of adding Git functionality to an established instance of Moodle.

This article assumes that you already have Git installed. If you do not, you will need to install Git first.

Before you begin, identify the directory/folder containing the Moodle application files. Common webroot/DocumentRoot locations include:

• In Linux, they could be in a directory called /var/www/html, /usr/local/moodle or /srv/moodle.
• In Windows, they could be in c:\Server\moodle or c:\xampp\htdocs or c:\wamp\www.
• In MacOS, they might be in /Applications/MAMP/htdocs/moodleXXX where XXX is the Moodle branch number.

However, the files could easily be placed in a different location.

The following steps assume that you are working in Linux. The commands should be similar in all operating systems but the paths will be different.

Determine if the Moodle code is already Git-enabled

Simply open a terminal or command line prompt, switch (i.e. “cd”) to the root directory/folder of your Moodle site and use the ‘git status’ command. Example:

cd /var/www/html
git status

If your installation of Moodle LMS is not Git enabled, you will see a message similar to the following:

Fatal: not a git repository (or any of the parent directories): .git

The second way to find out is to simply check to see if there is a .git directory in the root directory/folder of your Moodle site.

In Linux and MacOS. Note that the ‘-la’ lists hidden files that start with a dot like .git:

ls -la .git

In Windows, .git is not a hidden file so you can just use the following command:

dir .git

If you see a list of files, you are all set and this article is not for you. Otherwise, you should complete the instructions in this article to GITify your Moodle application files.

Adding the Git repository after Moodle is installed

The only difference between a downloaded version of Moodle LMS and a cloned version is a directory (or folder) called .git. It contains all of the necessary information to allow Git to track the changes in every file of every version of Moodle LMS since version 1.3. This directory is essential for Git to work properly.

If you did not initially clone Moodle for any reason, that .git directory will be missing. Fortunately, there is a pretty simple way to add the .git directory into your Moodle code even at a later date. It can take a few minutes to set it up but it will be well worth your effort.

To achieve this goal, we will be working with the source code of two instances of the Moodle application at the same time – your current active site and a clone from Moodle.org’s repository on GitHub.

PRO TIP: Always try things like applying changes, updates and upgrades on a copy of your live production site first. If anything goes wrong, you never want to risk it affecting your staff and students.

Step 1: Identify the version of Moodle currently installed

Take a look at the last few lines of source code in the version.php file found in the Moodle root directory (e.g. /var/www/html/version.php in our example). They will look something like this:

$version  = 2023042400.05;            // 20230424 = branching date YYYYMMDD - do not modify!
                                      // RR = release increments - 00 in DEV branches.
                                      // .XX = incremental changes.
$release  = '4.2+ (Build: 20230526)'; // Human-friendly version name
$branch   = '402';                    // This version's branch.
$maturity = MATURITY_STABLE;          // This version's maturity level.

We need three pieces of information from this file. The information may be different in your version.php but it should be in the same place. In our example:

• The branch number is 402
• The release number is 4.2+
• The build date is 20230526. Add dashes to format the date as YYYY-MM-DD: 2023-05-26.

Next, use the following command to identify the commit hash for that specific release of Moodle:

git log --pretty=format:"%h - %ad: %s" --grep="4.2+"

… replacing 4.2+ with the release number from step 1. You should see something like this:

6b8884e13bc - 2023-05-26 09:28:41 +0200: weekly release 4.2+
4781b416316 - 2023-05-19 21:13:51 +0800: weekly release 4.2+
f9edf5c1be8 - 2023-05-12 08:56:43 +0800: weekly release 4.2+
29a21ee986e - 2023-05-04 12:42:42 +0200: weekly release 4.2+
4f625c1e2e5 - 2023-04-27 19:28:33 +0800: weekly release 4.2+

Look for the line that has the build date (2023-05-26 in this example). Note that dates may be formatted differently on your system. Take note of the hash to the left of the date, 6b8884e13bc in this example.

Step 2: Clone the .git repository of Moodle LMS from GitHub

Now we need to clone a new copy of Moodle to a different location (e.g. /var/www/tmp-moodle) than your currently installed instance using the following commands. Be sure to replace the 402 in the checkout line with your branch number from Step 1.

Reminder: These are the commands in Linux. You will need to adapt the Windows and Mac OS.

git clone git@github.com/moodle/moodle.git /var/www/tmp-moodle
cd /var/www/tmp-moodle
git checkout MOODLE_402_STABLE

Next, check out that commit has from your current site:

git checkout 6b8884e13bc

Your temporary instance of the Moodle application source code is now at the same branch, release and build as your current installation.

Step 3: Move the new .git directory into your current installation of Moodle

You are almost done. The next step will move the temporary .git file to your current Moodle source code.

mv /var/www/tmp-moodle/.git /var/www/html/
cd /var/www/html/

If you now enter a “git status” command, you should see a list of all of the Moodle core files that you made changes to in the past, if any. These will be listed as Changes not staged for commit. 3^rd party plugins, themes, as well as your site’s config.php file will be listed under Untracked files.

If you have any files under Changes not staged for commit, add them to a new Git commit in your repository so that Git can start tracking these changes. Enter the following command:

git commit -a -m "Rollup of my customized core files."

Take note of the commit hash that Git will display. If you can’t complete the update process successfully, you can put things back to the way they were using this hash and the git checkout <hash> command.

IMPORTANT: Once you complete the database upgrade, you cannot roll Moodle back to a previous version.

Note that you don’t need to do anything with the Untracked files. These are files that Git will be ignoring. This is why Git will not affect your config.php, your additional plugins and themes when you ask it to update Moodle.

At this point, you no longer need the temporary Moodle application files as they have served their purpose. They may safely be deleted. Just don’t delete your production files.

You can now apply Moodle updates as often as you want by simply:

• Issuing a git pull --rebase command (that’s two dashes before the word rebase).
• Reset the user:group and permissions of the files and folders for your Moodle application, especially on Linux and MacOS.
• Accessing your website right away. It will prompt you to complete the update. Be sure to resolve all issues mentioned on the Server Checks page even if they are just warnings, unavailable, missing or failed dependencies.

Don’t forget to push your changes to your online git repository.

What does this git pull --rebase command do? It will quickly do all of the following for you:

1. Download the latest update for your release of Moodle.
2. Roll back any committed customizations that you made to your site’s Moodle core code.
3. Update the core Moodle code.
4. Re-apply any customizations that you made.
5. Notify you of any custom changes that cannot be integrated into the new codebase. At this point, you can choose to resolve the issue, git add the changed file names and git rebase –continue; or use the git rebase --abort command to cancel.

Again, it will not touch any of your 3^rd party plugins, themes, config.php file or any other files not part of Moodle.

Additional topics beyond the scope of this article:

• How to handle issues when core source code customization cannot be integrated into the upgraded version of the Moodle code. These are known as Git Merge Conflicts. They happen when Git cannot figure out where to patch your code – usually due to major changes in Moodle’s code.
• Upgrading Moodle (e.g. from 4.1 to 4.4). One should take several additional steps to ensure Moodle will still work after the upgrade. Things like ensuring that your themes and plugins are compatible with the new version of Moodle and upgrading them, replacing them with an alternative or removing them if they are no longer used; not skipping key versions of Moodle (e.g. you cannot upgrade directly from Moodle 3.6 to 4.2); ensuring that your environment meets all of Moodle’s system requirements; cherry picking your custom core commits into the new branch; and testing everything to make sure it all still works. These are essential steps when performing an upgrade.

Conclusion

Integrating Git with an existing Moodle installation offers a powerful way to manage and track changes within the Moodle Learning Management System. This step-by-step guide has outlined the process of adding Git functionality to an established instance of Moodle. Using Git will make it possible to apply smoother, faster (minutes instead of hours), more reliable and frequent updates, efficiently track core customizations, and improve collaboration among development teams.

Hope you found this helpful.

Michael Milette