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 statusIf 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 .gitIn Windows, .git is not a hidden file so you can simply use the following command:
dir .gitIf 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 at first but will be well worth your effort after that.
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 they 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_STABLENext, check out that commit has from your current site:
git checkout 6b8884e13bcYour 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. 3rd 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 --rebasecommand (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:
- Download the latest update for your release of Moodle.
- Roll back any committed customizations that you made to your site’s Moodle core code.
- Update the core Moodle code.
- Re-apply any customizations that you made.
- 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 addthe changed file names andgit rebase –continue; or use thegit rebase --abortcommand to cancel.
Again, it will not touch any of your 3rd party plugins, themes, config.php file or any other files that are 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.2). There are several additional steps that one should take 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 ensure make it possible to apply smoother, faster (minutes instead of hours), more reliable and frequent updates, efficiently track core customizations, and improved collaboration among development teams.
Hope you found this helpful. See you next month!
Michael Milette
- Debugging SCSS in Moodle LMS – 23rd April 2024
- Moodle LMS Email Deliverability in 2024: Best Practices, Authentication Standards and Troubleshooting – 23rd February 2024
- Terminology for Those New to Moodle LMS – 20th January 2024
Hi Michael,
Thanks for your reply. As a plugin and occasional core developer, I do use Git on the command line for cherry picking and hard resets. For ease of use though, I do use a GUI. Generally each bit of functionality has its own commit. If a bit of work is going to take time and needs to be interleaved with other work, then I’ll branch off, do several commits, then when finished make a ‘merge’ branch, squash the commits and then merge that branch into master. That then gives a single commit that can then be cherry picked to previous versions of Moodle branches. I’ll rebase if needed. Matching versions is easy as I (like core releases) tag them. The tags are used when uploading to the Moodle dot org plugins DB too, thus a match between that and the repository.
Kind regards,
Gareth
Hi Gareth,
Sounds to me like you have some excellent Git processes and practices. I do much of the same except that I usually use just the Git command line. When I first started with Git many years ago, I tried a few Git GUIs. However, I always ended up frustrated with their limitations. So I focused on using Git command line and haven’t looked back since. The only GUI-like tool that I use for Git is lazygit (available for Windows, MacOS and Linux). Despite the fact that it is a text-based tool, it still works with a mouse. I use this to split up changes into multiple commits when I’ve made unrelated fixes along the way but it is capable of so much more. If you are curious. take a look at this open source project at https://github.com/jesseduffield/lazygit.
Best regards,
Michael
A really interesting and different approach Michael. Is there a risk with using Git on a production folder of potential mistakes in the future? And therefore better to do this with a test installation and then update with config.php backup, file remove / copy etc? Also, given that 3rd party plugins have Git repositories too, then could they be migrated in the same light? Possibly added as submodules (https://git-scm.com/book/en/v2/Git-Tools-Submodules) or standalone but just needing to be aware of not removing them untracked wise. I have several development installs and use both methods for no particular reason as not thought about it until now!
Hi Gareth,
Thank you for your questions.
Risk of Mistakes: Certainly, there are risks involved. However, if you maintain discipline in committing your changes to an online Git repository, the risks are significantly lower compared to relying on memory and a manual process for updating the Moodle LMS. Just remember to use the –rebase option, otherwise, your Git log could become messy, making it difficult to differentiate between core code and custom commits.
Use a Test Installation: Absolutely. I recommend utilizing a test installation whenever you make code changes to your Moodle LMS site. Nevertheless, I’ve encountered clients without a test setup and a limited maintenance budget. In such cases, I structured things so that their webmaster simply needed to back up the site, access a terminal, and execute the ‘git pull –rebase’ command a few times annually. If any issues arose during this process, they were instructed to note the error and use ‘git rebase –abort’ to revert changes. If they encountered no errors but the site didn’t function post-update, they were advised to restore the backup. So far, there haven’t been any complaints.
3rd Party Plugins: Managing them using Git is feasible, although each plugin requires individual management since they are separate from Moodle. Note that installing a plugin via Git will prevent Moodle from allowing updates within the platform if it detects the .git directory. Additionally, it might be slightly challenging to identify the matching commit for the installed version. Unless a plugin has been customized, it’s simpler to clone the entire repository, ensuring you checkout the relevant branch for your Moodle version, and then replace existing files. For customized plugins, Git can be handy to update the plugin and reapply customizations over the updated version. Occasionally, I create a bash script to automate Moodle and plugin updates. This script can even roll back changes in case of issues or execute the Moodle database update script, streamlining the process. Just remember to update the script when adding or removing 3rd party plugins.
Submodules: Implementing this with plugins as submodules is indeed possible. The success largely depends on the implementation. When handled correctly, the Moodle Git repository doesn’t distinguish between submodules and non-submodule custom commits. Since custom commits are always integrated atop the base Moodle, it functions similarly to any other custom commit not part of the core.
Tip: I’ve found that maintaining a sustainable, long-term code management solution using Git involves making individual commits for each fix, new feature, or addition/removal of a 3rd party plugin, rather than combining multiple changes into one. Merge (squash) commits related to one issue into a single commit. This approach keeps your Git log clean and understandable. When it comes time to implementing Moodle upgrades down the road, you will be able to simply cherry-pick your custom commits into the new Moodle branch, hopefully with minimal merge conflicts. Using ‘git log’ allows you to view your custom commits at the top of the list, above Moodle core commits.
Git is an invaluable tool for source code management. As you customize your site’s over time, its maintenance process will naturally become more intricate. However, once you grasp Git’s capabilities and learn to harness them, it can significantly reduce your workload.
Git’s learning curve might seem steep, but dedicating time to grasp its fundamental functions pays off in the long run. For example, as a developer, I maintain multiple releases of Moodle locally for compatibility testing. Using ‘git pull –rebase,’ updates each instance of Moodle in a mere minute or two, sometimes even less (depending on your computer and Internet speeds). Git promptly notifies me of the successful application of customizations over the latest Moodle version and of any source code integration issues.
There’s so much more to share about using Git for Moodle site source code management, but I believe this already exceeds the scope of a comment.
Hope you found something helpful in this information.
Best regards,
Michael Milette
Great post Michael !
I’ve always avoided git, bur might actually give it a go after reading this 🙂