# GIT
This page describes how to maintain a copy of Moodle on your production server which can easily be upgraded using Git. If you have customisations of Moodle core code, you are advised to follow the instructions in the [Git for developers guide](http://docs.moodle.org/dev/Git_for_developers "dev:Git for developers").
To get the most of Git it is worth making the effort to understand its basic concepts - see the section below. It may be a bit of a steep learning curve if you are used to other version control systems, but it is worth it.
- [1 Getting hold of Git (Windows, OSX, Linux and others)](#bkmrk-getting-hold-of-git--1)
- [2 Moodle branch names](#bkmrk-moodle-branch-names)
- [3 Obtaining the code from Git](#bkmrk-obtaining-the-code-f-1)
- [4 Updating your Moodle Release](#bkmrk-updating-your-moodle-1)
- [4.1 Checking what version you are currently using](#bkmrk-checking-what-versio-1)
- [4.2 Updating your installation with minor releases](#bkmrk-updating-your-instal-1)
- [4.2.1 Upgrading a minor release: If you are using a git tag](#bkmrk-upgrading-a-minor-re-1)
- [4.2.2 Upgrading a minor release: If you are using a major release branch](#bkmrk-upgrading-a-minor-re-3)
- [4.3 Upgrading to a newer major release](#bkmrk-upgrading-to-a-newer-1)
- [4.3.1 Upgrading to a new major release: If you are using a git tag](#bkmrk-upgrading-to-a-new-m-1)
- [4.3.2 Upgrading to a major release: If you are using a git branch](#bkmrk-upgrading-to-a-major-1)
- [4.4 Remember to move your plugins too!](#bkmrk-remember-to-move-you-1)
- [5 Installing Moodle plugins](#bkmrk-installing-moodle-pl-1)
- [5.1 Installing a Moodle plugin from its Git repository](#bkmrk-installing-a-moodle--1)
- [5.1.1 Updating plugins installed from Git repositories](#bkmrk-updating-plugins-ins-1)
- [5.2 Installing and maintaining contributed extensions using Git submodules](#bkmrk-installing-and-maint-1)
- [5.2.1 Installing a new extension into an existing Moodle](#bkmrk-installing-a-new-ext-1)
- [5.2.2 Maintaining Git submodules](#bkmrk-maintaining-git-subm-1)
- [6 Advanced Git concepts](#bkmrk-advanced-git-concept-1)
- [6.1 Creating your own branch](#bkmrk-creating-your-own-br-1)
- [7 See also](#bkmrk-see-also)
## Getting hold of Git (Windows, OSX, Linux and others)
For information on how to download and install Git, see [https://git-scm.com/download](https://git-scm.com/download).
Once you have downloaded and installed your OS relevant git installation, the git commands in this document should work with your operating system.
## Moodle branch names
Each release of Moodle has:
- a git *tag*, which is the version number of the release, prefixed with the letter `v` (for example, `v5.1.0`), and
- a *git branch*, for example `MOODLE_503_STABLE` for the lifetime of that major release.
Git tags are used to identify specific releases of Moodle and are the source of the official releases, the downloadable zip files, tar files, and so on.
We recommend that production Moodle sites always use an officially released version using the git tag, for example `v5.1.0`, or `v5.0.4`.
Whilst you *can* use the branch for each major version, that is `MOODLE_503_STABLE` for the 5.3 major version, it is generally not advised. Whilst new features and improvements are normally only made to the `main` development branch, the major version branches will get weekly updates which may not be suited to production environments.
**Note**: The word `STABLE` in the branch name is intended to indicate that the branch is for a *released* version of Moodle.
**Important**: You should not use alpha, beta, release-candidates, or code from the `main` branch for production sites. It could have significant bugs.
## Obtaining the code from Git
The command line version of Git is discussed here. In most cases you will find that Graphical clients provide the same functionality and will use similar naming for the terminology. Please refer to the documentation for that client for more information.
You can find the official Moodle git repository at git://git.moodle.org/moodle.git (with an official clone at [https://github.com/moodle/moodle.git](https://github.com/moodle/moodle.git)). To initialize your local checkout, use
```
$gitclone-bv5.3.0https://github.com/moodle/moodle.git/path/to/your/moodle/storage/area
```
- The `-b v5.3.0` option tells git to checkout the branch or tag `v5.3.0` after the clone is complete. If you omit this option, git will checkout the default branch, which is `main`.
- The last argument is the path to the directory where you want to store your Moodle installation.
You may want to consider creating your own branch for your production site - see the section below.
**Important**: From Moodle 5.1 onwards you should ***not*** place your git checkout in a web-accessible location. Instead you should either:
- configure your web server to point to the `public` subdirectory of your Moodle installation; or
- use a technique such as symlinking to place the `public` directory into your web root.
**Composer**: After you clone the code, you can install the Composer dependencies by running `composer install --no-dev --classmap-authoritative` from the Moodle root directory. Composer is optional in Moodle 5.3, except for new features such as OAuth 2 Server. See [Installing Moodle#Install Composer dependencies](https://docs.moodle.org/503/en/Installing_Moodle#Install_Composer_dependencies "Installing Moodle").
## Updating your Moodle Release
In most cases these instructions will be very similar whether you are upgrading between major releases (for example, from 5.2 to 5.3), or updating to a newer minor release (for example, from 5.3.0 to 5.3.1).
**Important**: Always ensure you have a full backup of your Moodle site (both code and database) before performing any upgrade or update.
**Important**: If your Moodle root directory has a `vendor/` directory, run `composer install --no-dev --classmap-authoritative` from the Moodle root directory every time you update the code, before you run the upgrade. See [Update Composer dependencies](https://docs.moodle.org/503/en/Upgrading#Update_Composer_dependencies "Upgrading").
If you have any customisations to Moodle core code, you should follow the instructions in the [Git for developers guide](http://docs.moodle.org/dev/Git_for_developers "dev:Git for developers") instead.
If you have any custom plugins installed, you should ensure that they are compatible with the version of Moodle you are upgrading to. You may need to update these plugins separately.
### Checking what version you are currently using
To check which version of Moodle you are currently using, you can use the commands below:
```
# If you are following a major release branch:
gitbranch
# If you are using a git tag and are on Moodle 5.1 or later:
gitlog--oneline-1public/version.php
# If you are using a git tag and are on Moodle 5.0 or earlier:
gitlog--oneline-1version.php
```
If you are tracking a git tag, you should see something like this:
```
➜ examplesite git:(eb47eff071) git log --oneline -1 public/version.php
eb47eff071 (HEAD, tag: v5.1.0) Moodle release 5.1
```
### Updating your installation with minor releases
To update your Moodle installation to the latest minor release of your currently installed major release, you simply need to fetch the latest changes from the Moodle git repository, and then check out the appropriate branch or tag.
#### Upgrading a minor release: If you are using a git tag
To switch to the latest minor release of your currently installed major release, you can use the commands below (replace `v5.3.x` with the appropriate tag for your intended release):
```
cd/path/to/your/moodle
gitfetchorigin
gitcheckoutv5.3.x
```
#### Upgrading a minor release: If you are using a major release branch
```
cd/path/to/your/moodle
gitfetchorigin
gitrebaseorigin/MOODLE_503_STABLE
```
If this is a production site you should still consider the [Upgrade](https://docs.moodle.org/503/en/Upgrade "Upgrade") instructions (including taking backups).
### Upgrading to a newer major release
When you want to upgrade to a newer major release, you will need to tell your git installation to track the newer release instead of the release that you currently have installed and are tracking.
You should ensure that you have updated your installation with the latest minor release of your currently installed Moodle version first (as described in the section above). This will also download the changes for newer Moodle versions (but not yet make use of them).
You should put your site into maintenance mode, or disable the website, before starting the upgrade.
#### Upgrading to a new major release: If you are using a git tag
To switch to a newer major release using git tags, you can use the commands below (replace `v5.3.0` with the appropriate tag for your intended release):
```
cd/path/to/your/moodle/folder
gitfetchorigin
gitcheckoutv5.3.0
```
#### Upgrading to a major release: If you are using a git branch
To switch to a newer major release using git branches, you can use the commands below (replace `MOODLE_503_STABLE` with the appropriate branch for your intended release):
```
cd/path/to/your/moodle/folder
# Make a local branch for the newer release from the remote repo
gitcheckout-bMOODLE_503_STABLEorigin/MOODLE_503_STABLE
```
Your website folder now includes the files for the newer Moodle version, but to complete the Moodle upgrade, you will either need to [complete the upgrade via the web browser](https://docs.moodle.org/503/en/Upgrading "Upgrading"), or [use the command line upgrade script](https://docs.moodle.org/503/en/Administration_via_command_line "Administration via command line").
### Remember to move your plugins too!
If upgrading from Moodle 5.0 or earlier to Moodle 5.1 or later, you will also need to move any plugins you have installed into their new locations under the `/public` subdirectory. This is *not* done automatically when you checkout the new Moodle 5.1 code.
## Installing Moodle plugins
### Installing a Moodle plugin from its Git repository
This is one way to handle adding plugins from other Git repositories into your Moodle repository.
For example, let us say we want to install the [Certificate module](https://docs.moodle.org/503/en/Certificate_module "Certificate module") from its Git repository into our Moodle 5.3.
After finding the location of the code for your desired plugin (in this case, `https://github.com/markn86/moodle-mod_certificate.git`), you can use the following commands:
```
$cd/path/to/your/moodle/
$gitclonehttps://github.com/markn86/moodle-mod_certificate.gitpublic/mod/certificate
```
This will create a new directory public/mod/certificate/ within your Moodle installation and populate it with the code from the plugin's Git repository.
If you check the status of your Moodle repository now, you will see that Git is reporting an untracked directory:
```
$gitstatus
HEADdetachedatv5.1.0
Untrackedfiles:
(use"git add ..."toincludeinwhatwillbecommitted)
public/mod/certificate/
nothingaddedtocommitbutuntrackedfilespresent(use"git add"totrack)
```
You can stop the warning about the untracked directory by adding it to your Git ignore list:
```
$echo/public/mod/certificate/>>.git/info/exclude
```
#### Updating plugins installed from Git repositories
To fetch updates for the plugin, you need to go into the plugin directory and fetch the changes from upstream:
To update your Moodle installation now, you must visit both Git repositories and pull changes from upstream.
```
$cd/path/to/your/moodle/
$cdmod/certificate
$gitfetchorigin
$gitrebase
```
Writing a shell script with these lines in the root of Moodle installation is a very good idea. Otherwise it is easy to forget what Git repositories are there within the main Moodle repository.
### Installing and maintaining contributed extensions using Git submodules
Git submodules are a great way to maintain external Git repositories within your main Moodle repository, but they are a more advanced Git concept.
A step-by-step explanation will be provided, but in order to follow these steps it is helpful to understand, what these commands do.
Advanced options and commands can be found at [Git book](https://git-scm.com/book/en/v2/Git-Tools-Submodules%7Cthe).
If you have any questions about Git submodules, please visit the site above first.
#### Installing a new extension into an existing Moodle
As an example we use the [Certificate module](https://docs.moodle.org/503/en/Certificate_module "Certificate module") from the previous section.
```
$cd/path/to/your/moodle
$gitsubmoduleaddhttps://github.com/markn86/moodle-mod_certificate.gitpublic/mod/certificate
```
Note, that Git is reporting two new files in the repository:
```
$gitstatus
# On branch MOODLE_500_STABLE
# Changes to be committed:
# (use "git reset HEAD ..." to unstage)
#
# new file: .gitmodules
# new file: mod/certificate
#
```
The file .gitmodules contains the local path and url of all your submodules.
It has to be committed, if you intend to clone the repository later (see the page [Moodle development environment with Git submodules](https://docs.moodle.org/503/en/Moodle_development_environment_with_Git_submodules "Moodle development environment with Git submodules")).
Before committing, make sure to check the configuration of the plugin's Git repository, since the automatically generated settings may be not sufficient.
For future updates it is helpful, to track the remote branch, which corresponds to the Moodle version of your repository.
```
$cdmod/certificate
$gitbranch-avv
*main345f5b1[origin/main]Replaceddeprecatedfunction
remotes/origin/HEAD->origin/main
remotes/origin/MOODLE_20_STABLE1aa1040Addedoptiontoprint'grade category'grade
remotes/origin/MOODLE_21_STABLE1aa1040Addedoptiontoprint'grade category'grade
remotes/origin/MOODLE_22_STABLE1aa1040Addedoptiontoprint'grade category'grade
remotes/origin/MOODLE_23_STABLEfe047deCheckthatthefunctionexistsratherthanrelyingontheMoodleversion
remotes/origin/MOODLE_24_STABLE1051f7dCONTRIB-4892Fixedtheemailtoothersfunctionality
remotes/origin/MOODLE_25_STABLEcdb221aCONTRIB-4946:RemovedcharacterfromlanguagefilebreakingAMOS
remotes/origin/MOODLE_26_STABLE696802aIncreasedversion
remotes/origin/MOODLE_27_STABLEd3c0379Increasedversion
remotes/origin/MOODLE_28_STABLEfa8df83Increasedversion
remotes/origin/MOODLE_29_STABLE3f03740Replaceddeprecatedfunction
remotes/origin/main345f5b1Replaceddeprecatedfunction
```
Git created the branch **main** which tracks **origin/main** automatically, because the remote repository has checked out **main**. Therefore, create a new branch, which tracks the appropriate remote branch. Of course, this is only possible, if the remote repository offers those branches.
```
$gitcheckout-bMOODLE_29_STABLEorigin/MOODLE_29_STABLE
BranchMOODLE_29_STABLEsetuptotrackremotebranchMOODLE_29_STABLEfromorigin.
Switchedtoanewbranch'MOODLE_29_STABLE'
$gitbranch-Dmain
Deletedbranchmain(was345f5b1).
```
It is not necessary to delete the **main** branch, but it's useless to keep it. In fact, these settings don't need to be touched afterwards.
The final step is to commit the changes to the main repository.
```
$cd/path/to/your/moodle
$gitcommit-a-m"New extension mod_certificate installed"
```
It has to be ensured, that the commit includes only the changes for the new Git submodule (since **-a** commits all non-staged changes).
#### Maintaining Git submodules
Maintaining a set of submodules is extremely easy. Consider a Moodle repository with several submodules installed. Keep in mind, that the extension **mod\_mylittleextension** is a fake plugin, created for a test scenario in this example. It is not an official Moodle module. For updating all your submodules at once, type in:
```
$cd/path/to/your/moodle
$gitsubmoduleforeachgitpull
Entering'block/coursefeedback'
Alreadyup-to-date.
Entering'mod/certificate'
Alreadyup-to-date.
Entering'mod/mylittleextension'
remote:Countingobjects:6,done.
remote:Compressingobjects:100%(4/4),done.
remote:Total4(delta0),reused0(delta0)
Unpackingobjects:100%(4/4),done.
From/local/repositories/mle
89d9eae..64c122dmain->origin/main
Updating89d9eae..64c122d
Fast-forward
index.html|9+++++++++
version.php|6+++---
2fileschanged,12insertions(+),3deletions(-)
createmode100644index.html
$gitstatus
# On branch MOODLE_29_STABLE
# Changes not staged for commit:
# (use "git add ..." to update what will be committed)
# (use "git checkout -- ..." to discard changes in working directory)
#
# modified: mod/mylittleextension (new commits)
#
```
The command **git submodule foreach \[another command\]** walks through all submodule repositories and executes what is specified by **\[another command\]**. In this case it is **git pull**. Therefore, the module mylittleextension was updated and the main repository isn't clean anymore until changes are committed:
```
$gitcommit-a-m"Plugin updates"
```
Maintaining plugins with Git submodules has also another application than simplifying the update process. In a greater scale it can be used to maintain a Moodle project, where multiple developers need to have an exact copy of your moodle without organizing external plugins manually. You can read more about this topic at the page [Moodle development environment with Git submodules](https://docs.moodle.org/503/en/Moodle_development_environment_with_Git_submodules "Moodle development environment with Git submodules").
## Advanced Git concepts
### Creating your own branch
It's a great idea to create your own branch for your production site, even if you don't plan to make any code changes. This way, if you do need to make any customisations in the future, you can do so without affecting the main Moodle code and you can easily merge in future updates from the official Moodle repository.
To create your own branch, use the following commands:
```
cd/path/to/your/moodle
gitcheckout-bmyproductionbranch
```
You can replace myproductionbranch with a name of your choice. You can then use this branch to make any customisations you need.
You may also wish to create a new branch for each new major version of Moodle that you upgrade to, for example:
```
gitcheckout-b5.1-example.com
```
## See also
- [Windows installation using Git](https://docs.moodle.org/503/en/Windows_installation_using_Git "Windows installation using Git")
- [Git for Mac](https://docs.moodle.org/503/en/Git_for_Mac "Git for Mac")
- [dev:Moodle versions](http://docs.moodle.org/dev/Moodle_versions "dev:Moodle versions")
- For fixing a Tracker Issue (MDL) / Forking Moodle / CONTRIButing code [User:Sam\_Hemelryk/My\_Moodle\_Git\_workflow](http://docs.moodle.org/dev/User:Sam_Hemelryk/My_Moodle_Git_workflow "dev:User:Sam Hemelryk/My Moodle Git workflow")
- [Case study Git + Moodle from Technical University Berlin](https://docs.moodle.org/503/en/Moodle_Production_Server_with_GIT "Moodle Production Server with GIT")
- Moodle forum discussions
- [Github and Moodle deployment for production](https://moodle.org/mod/forum/discuss.php?d=255175)
- [GIT help needed](http://moodle.org/mod/forum/discuss.php?d=168094)
- [Clear git guide for Admins (not developers)](https://moodle.org/mod/forum/discuss.php?d=231046)
- [Best way to use Git](https://moodle.org/mod/forum/discuss.php?d=393756)
- External resources
- [Deploying Moodle from git - Blog post from a production experience](http://thamblings.blogspot.com.au/2013/07/upgrading-moodle-from-git.html)
- [Git Reference](http://gitref.org/)
- [Pro Git book](http://progit.org/book/)
---
Source: [docs.moodle.org/503/en/GIT](https://docs.moodle.org/503/en/GIT) — MoodleDocs (GPL) · Imported 2026-11-10.