Git repositories for contrib modules

The instructions here assume that you have a working knowledge of git.

Managing contrib plugin with git makes it easy to make local modifications and pull in updates.

The best option for managing a contrib plugin with git is to create a self-contained repository for the plugin in a subdirectory of Moodle installation.

Creating a new plugin

If you intend to publish the plugin, it is highly recommended to create a github repository from the start. This will allow you to publish with a single command when you're ready. Just go to the site, sign up for an account, create a new repository. The naming convention for Moodle plugin repositories is moodle-plugintype_pluginname.

Github will give you instructions for cloning your (blank) repository. After that in your local moodle installation navigate to the directory for the plugin type you're developing (e.g. /block, /mod, /local, admin/tool) and run the git clone command there.

(Note: in order to run git clone from the command line, you'll need to configure an SSH key and install it in your github account. See https://help.github.com/en/articles/checking-for-existing-ssh-keys for details.)

For example for the block plugin called "mysuperblock":

 cd blocks/
 git clone git@github.com:yourname/moodle-block_mysuperblock.git mysuperblock

This will create a subdirectory called mysuperblock. cd into this directory to perform git commands on this plugin's repository - outside of this directory will perform them on the main Moodle repository. To ignore this folder from Moodle git repository you can add the path to .git/info/exclude. Do not add paths to .gitignore file because it is also part of moodle repository checkout.

Inside the plugin directory you can then develop and test your changes locally, and when you're ready to publish, run

git push origin

Installing a third-party plugin

Installing a plugin developed by a third party differs depending on whether they have used git or not. If they have used git, you can follow the instructions above, but skip out the part where you create a new github repository and clone their own github (or other public repository) instead.

If they haven't used git, you can still use git (and even github, if you like) to track local modifications to the plugin. Simply create a directory for the plugin

mkdir ~/moodle/blocks/newblock

Initialise a new git repository there

cd ~/moodle/blocks/newblock
git init

unzip or copy the files to the repository

cd ~
tar -xf newblock.tar.gz
cp newblock/* ~/moodle/blocks/newblock

add and commit the files

cd ~/moodle/blocks/newblock
git add .
git commit . -m "Added files for newblock"

When installing updates, you'll need to copy the new files in place of the old one, and re run the git add and git commit commands.

Moving a plugin to its own repository

You may have developed a plugin within your main Moodle repository, but want to move it to a separate one to make it easier to publish. Using git filter-branch, we can achieve this and maintain all existing history for the plugin's files.

First, you'll need a fresh copy of moodle (this will become your new moodle repository)

mkdir ~/newmoodle
cd ~/newmoodle
git clone git://git.moodle.org/moodle.git

This will create a clone of Moodle without your plugins in ~/newmoodle/moodle Next, you need to clone your local Moodle repository (why will become clear).

mkdir ~/moodleclone
cd ~/moodleclone
git clone ~/moodle

This will create a clone of your current moodle development repository, with your plugins, in ~/moodleclone/moodle Now, we'll use the git filter-branch command to reduce this clone to just the plugin.

cd ~/moodleclone/moodle
git filter-branch --subdirectory-filter blocks/myblock/

The files from blocks/myblock/ will now be at the root of the repository. All other files will have been removed (this is why we're using a clone). You can now track the plugin in it's own repository by cloning this reduced repository to a subdirectory of the new moodle clone.

cd ~/newmoodle/blocks
git clone ~/moodleclone/moodle myblock

This will clone the block's files, with the full history, into their own repository in the myblock subdirectory. You can now delete ~/moodleclone/moodle, and repeat with any other plugins you've developed.

See also

• Git for administrators
• Git for developers

Moodle forum discussions

• GIT help needed
• Best way to manage CONTRIB code with GIT
• Handy Git tip for tracking 3rd-party modules and plugins
• Moodle Git repositories

External resources

• Everyday GIT With 20 Commands Or So
• Git Reference
• Pro Git book