Note: You are currently viewing documentation for Moodle 2.5. Up-to-date documentation for the latest stable version of Moodle may be available here: Git for Administrators.

Git for Administrators: Difference between revisions

From MoodleDocs
(→‎See also: link edit)
 
(26 intermediate revisions by 15 users not shown)
Line 1: Line 1:
An alternative way to maintaining your Moodle server via [[CVS for Administrators|CVS]] is using 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 [[Development:Quick Git start guide for Moodle development|Quick Git start guide for Moodle development]].
{{Installing Moodle}}
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 [[Development:Quick Git start guide for Moodle development|Quick Git start guide for Moodle development]].
 
To get the most of of Git it is worth making the effort to understand its basic concepts - see the See also section below. It can be a bit of a learning curve, especially if you are used to CVS or Subversion.
 
== Getting hold of Git (Windows, OSX, Linux and others) ==
 
Support for Git was, up until recently, mostly confined to Linux but builds are now available for most popular operating systems:
 
* List of downloads from Git site - http://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.


== Obtaining the code from Git ==
== Obtaining the code from Git ==
The command line version of Git is discussed here. Graphical clients are little more than wrappers around the command line version, so you should be able to deduce the correct parameters quite easily.


You can find the official Moodle git repository at git://git.moodle.org/moodle.git (with an official clone at git://github.com/moodle/moodle.git). To initialize your local checkout, use
You can find the official Moodle git repository at git://git.moodle.org/moodle.git (with an official clone at git://github.com/moodle/moodle.git). To initialize your local checkout, use
 
<pre>
    git clone git://git.moodle.org/moodle.git                      (1)
$ git clone git://git.moodle.org/moodle.git                      (1)
    cd moodle
$ cd moodle
    git branch -a                                                  (2)
$ git branch -a                                                  (2)
    git branch --track local_21_STABLE origin/MOODLE_21_STABLE      (3)
$ git branch --track MOODLE_25_STABLE origin/MOODLE_25_STABLE    (3)
    git checkout local_21_STABLE                                    (4)
$ git checkout MOODLE_25_STABLE                                  (4)
 
</pre>
* The command (1) initializes the new local repository as a clone of the upstream moodle.git repository, known as the ''origin'' remote repository by default. It creates a new directory named ''moodle'', where it downloads all the files. This operation can take a while.
* The command (1) initializes the new local repository as a clone of the 'upstream' (i.e. the remote server based) moodle.git repository. The upstream repository is called 'origin' by default. It creates a new directory named ''moodle'', where it downloads all the files. This operation can take a while as it is actually getting the entire history of all Moodle versions
* The command (2) lists all available branches.
* The command (2) lists all available branches.
* Use the command (3) to create a new local branch called local_21_STABLE and set it to track the branch MOODLE_21_STABLE from the upstream repository.
* Use the command (3) to create a new local branch called MOODLE_25_STABLE and set it to track the remote branch MOODLE_25_STABLE from the upstream repository.
* The command (4) actually switches to the newly created local branch. Note that the last two lines can be replaced with
* The command (4) actually switches to the newly created local branch.  


    git checkout -b --track local_21_STABLE origin/MOODLE_21_STABLE        (3 + 4)
Note that Git has a huge number of options for each command and it's actually possible to do the above process with a single command (left as an exercise!!).


that creates a new local tracking branch and switches to it immediately.
==Git from behind a firewall==


The ''master'' local branch, automatically created by git-clone, can then be deleted with the command
Git uses a read-only protocol that may be blocked by your firewall (port 9418). If this is a problem, you can use Github's http version <nowiki>https://github.com/moodle/moodle.git</nowiki>. It's a bit slower, so use the Git protocol if you can.
 
    git branch -d master


== Updating your installation ==
== Updating your installation ==
Line 28: Line 39:
The Moodle development team performs integration and testing of fixed bugs every Monday and Tuesday. On Wednesday you can install all patches by updating your code. Check the [http://git.moodle.org/gw?p=moodle.git;a=summary shortlog] to see if the official repository has been already updated or not.
The Moodle development team performs integration and testing of fixed bugs every Monday and Tuesday. On Wednesday you can install all patches by updating your code. Check the [http://git.moodle.org/gw?p=moodle.git;a=summary shortlog] to see if the official repository has been already updated or not.


    cd /path/to/your/moodle/checkout
To update your code to the latest version (on the MOODLE_22_STABLE branch) '''all''' you have to do is:
    git fetch                                                      (1)
<pre>
    git status                                                      (2)
$ cd /path/to/your/moodle/
    git merge                                                      (3)
$ git pull
 
</pre>
The command (1) downloads new updates from the remote repository without touching your local checkout. The command (2) displays the information about the eventual drift between you local version and the upstream one. The command (3) actually modifies your local files with the updates. The git-fetch + git-merge couple can be replaced with a single command
If this is a production site you should still consider the [[Upgrade]] instructions (e.g. take backups).
 
    git pull                                                        (1 + 3)


== Installing a contributed extension from its Git repository ==
== Installing a contributed extension from its Git repository ==


For example, let us say we want to install the [[Book module]] form its Git repository into our Moodle 2.0.
This is one way to handle adding plugins from other Git repositories into your Moodle repository. Another way is to use Git Submodules. However, at the time of writing, this is one of Git's rougher features and should be regarded as an advanced option.  
 
    cd /path/to/your/moodle/checkout
    cd mod                                                          (1)
    git clone git://github.com/skodak/moodle-mod_book.git book      (2)
    cd book
    git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE        (3)
    git branch -d master                                            (4)
 
The command (1) changes the current directory into the ''mod'' folder of your local Moodle clone. The command (2) creates a new subdirectory ''book'' and makes a local clone of Petr Škoda's vanilla Book repository. The command (3) creates a new local branch that will track the remote branch with a Book version for Moodle 2.0. The command (4) deletes the ''master'' that was created automatically by git-clone in (2) as we do not want it in this production checkout.


Now it is wise to put the new directory mod/book/ to the list of ignored files of the main Moodle clone.
For example, let us say we want to install the [[Book module]] from its Git repository into our Moodle 2.2.
<pre>
$ cd /path/to/your/moodle/
$ cd mod                                                         (1)
$ git clone git://github.com/skodak/moodle-mod_book.git book      (2)
$ cd book
$ git checkout -b MOODLE_22_STABLE origin/MOODLE_22_STABLE        (3)
$ git branch -d master                                            (4)
</pre>
The command (1) changes the current directory into the ''mod'' folder of your local Moodle clone. The command (2) creates a new subdirectory ''book'' and makes a local clone of Petr Škoda's vanilla Book repository. The command (3) creates a new local branch that will track the remote branch with a Book version for Moodle 2.2. The command (4) deletes the ''master'' that was created automatically by git-clone in (2) as we do not want it in this production checkout.


    cd /path/to/your/moodle/checkout
Note: you should check first the compatibility of a module with your Moodle branch by asking directly to the Maintainer before cloning the repo or - if you want to guess it - by issueing the command below before running the command (3), in order to verify what is available among the branches:
    echo /mod/book/ >> .git/info/exclude
<pre>
$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/MOODLE_15_STABLE
  remotes/origin/MOODLE_17_STABLE
  remotes/origin/MOODLE_18_STABLE
  remotes/origin/MOODLE_19_STABLE
  remotes/origin/MOODLE_20_STABLE
  remotes/origin/MOODLE_21_STABLE
  remotes/origin/MOODLE_22_STABLE
  remotes/origin/master
</pre>
This will avoid an error message when you issue the command (3) against a nonexistent branch, e.g.:
<pre>
§ git checkout -b MOODLE_25_STABLE origin/MOODLE_25_STABLE
fatal: git checkout: updating paths is incompatible with switching branches.
Did you intend to checkout 'origin/MOODLE_25_STABLE' which can not be resolved as commit?
</pre>
In this case you should ask the Mantainer, here Petr Škoda, if ''master'' is the correct branch for Moodle 2.3+ and he will reply that the [[Book module]] has been already integrated in Moodle starting from 2.3 so there's no need to install it usit ''git''. Please, as a general rule, before asking the Mantainer for something you should check the online documentation.


Now it is wise to put the new directory mod/book/ to the list of ignored files of the main Moodle clone, otherwise a status of the main clone will keep reminding you that the new code has not been checked in.
<pre>
$ cd /path/to/your/moodle/
$ echo /mod/book/ >> .git/info/exclude
</pre>
To update your Moodle installation now, you must visit both Git repositories and pull changes from upstream.
To update your Moodle installation now, you must visit both Git repositories and pull changes from upstream.
 
<pre>
    cd /path/to/your/moodle/checkout
$ cd /path/to/your/moodle/
    git pull
$ git pull
    cd /path/to/your/moodle/checkout/mod/book
$ cd mod/book
    git pull
$ git pull
 
</pre>
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.
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.


Line 68: Line 101:
; Moodle Docs
; Moodle Docs
* [[Git FAQ]]
* [[Git FAQ]]
* [[CVS for Administrators]]
* [[Windows installation using Git]]
* [[Moodle versions]]
* [[Git for Mac]]
* [[:dev:Moodle versions]]
* For some screenshots see [[User:Frank_Ralf/Git]] (still work in progress)
* For some screenshots see [[User:Frank_Ralf/Git]] (still work in progress)
* For fixing a Tracker Issue (MDL) / Forking Moodle / CONTRIButing code ... [[User:Sam_Hemelryk/My_Moodle_Git_workflow]]
* [[Moodle_Production_Server_with_GIT|Case study Git + Moodle from Technical University Berlin]]


; Moodle forum discussions
; Moodle forum discussions
* [https://moodle.org/mod/forum/discuss.php?d=213695 Got GIT installed on my site- here's how!]
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
Line 78: Line 115:
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183693 Git and CVS]
* [http://moodle.org/mod/forum/discuss.php?d=183693 Git and CVS]
* [http://moodle.org/mod/forum/discuss.php?d=208904 GIT for dummies]
* [http://moodle.org/mod/forum/discuss.php?d=211930 Git and upgrading misunderstanding]
* [https://moodle.org/mod/forum/discuss.php?d=231046 Clear git guide for Admins (not developers)]


; External resources  
; External resources  
Line 83: Line 123:
* [http://gitref.org/ Git Reference]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://progit.org/book/ Pro Git book]
 
* [http://eigenjoy.com/2008/05/15/git-from-the-bottom-up/ Git from the bottom up]
 
[[Category:Git]]
[[Category:Administrator]]


[[ja:管理者用Git]]
[[ja:管理者用Git]]
[[fr:Git_pour_administrateurs]]
[[es:Git para Administradores]]

Latest revision as of 15:14, 16 October 2013

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 Quick Git start guide for Moodle development.

To get the most of of Git it is worth making the effort to understand its basic concepts - see the See also section below. It can be a bit of a learning curve, especially if you are used to CVS or Subversion.

Getting hold of Git (Windows, OSX, Linux and others)

Support for Git was, up until recently, mostly confined to Linux but builds are now available for most popular operating systems:

Once you have downloaded and installed your OS relevant git installation, the git commands in this document should work with your operating system.

Obtaining the code from Git

The command line version of Git is discussed here. Graphical clients are little more than wrappers around the command line version, so you should be able to deduce the correct parameters quite easily.

You can find the official Moodle git repository at git://git.moodle.org/moodle.git (with an official clone at git://github.com/moodle/moodle.git). To initialize your local checkout, use

$ git clone git://git.moodle.org/moodle.git                       (1)
$ cd moodle
$ git branch -a                                                   (2)
$ git branch --track MOODLE_25_STABLE origin/MOODLE_25_STABLE     (3)
$ git checkout MOODLE_25_STABLE                                   (4)
  • The command (1) initializes the new local repository as a clone of the 'upstream' (i.e. the remote server based) moodle.git repository. The upstream repository is called 'origin' by default. It creates a new directory named moodle, where it downloads all the files. This operation can take a while as it is actually getting the entire history of all Moodle versions
  • The command (2) lists all available branches.
  • Use the command (3) to create a new local branch called MOODLE_25_STABLE and set it to track the remote branch MOODLE_25_STABLE from the upstream repository.
  • The command (4) actually switches to the newly created local branch.

Note that Git has a huge number of options for each command and it's actually possible to do the above process with a single command (left as an exercise!!).

Git from behind a firewall

Git uses a read-only protocol that may be blocked by your firewall (port 9418). If this is a problem, you can use Github's http version https://github.com/moodle/moodle.git. It's a bit slower, so use the Git protocol if you can.

Updating your installation

The Moodle development team performs integration and testing of fixed bugs every Monday and Tuesday. On Wednesday you can install all patches by updating your code. Check the shortlog to see if the official repository has been already updated or not.

To update your code to the latest version (on the MOODLE_22_STABLE branch) all you have to do is:

$ cd /path/to/your/moodle/
$ git pull

If this is a production site you should still consider the Upgrade instructions (e.g. take backups).

Installing a contributed extension from its Git repository

This is one way to handle adding plugins from other Git repositories into your Moodle repository. Another way is to use Git Submodules. However, at the time of writing, this is one of Git's rougher features and should be regarded as an advanced option.

For example, let us say we want to install the Book module from its Git repository into our Moodle 2.2.

$ cd /path/to/your/moodle/
$ cd mod                                                          (1)
$ git clone git://github.com/skodak/moodle-mod_book.git book      (2)
$ cd book
$ git checkout -b MOODLE_22_STABLE origin/MOODLE_22_STABLE        (3)
$ git branch -d master                                            (4)

The command (1) changes the current directory into the mod folder of your local Moodle clone. The command (2) creates a new subdirectory book and makes a local clone of Petr Škoda's vanilla Book repository. The command (3) creates a new local branch that will track the remote branch with a Book version for Moodle 2.2. The command (4) deletes the master that was created automatically by git-clone in (2) as we do not want it in this production checkout.

Note: you should check first the compatibility of a module with your Moodle branch by asking directly to the Maintainer before cloning the repo or - if you want to guess it - by issueing the command below before running the command (3), in order to verify what is available among the branches:

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/MOODLE_15_STABLE
  remotes/origin/MOODLE_17_STABLE
  remotes/origin/MOODLE_18_STABLE
  remotes/origin/MOODLE_19_STABLE
  remotes/origin/MOODLE_20_STABLE
  remotes/origin/MOODLE_21_STABLE
  remotes/origin/MOODLE_22_STABLE
  remotes/origin/master

This will avoid an error message when you issue the command (3) against a nonexistent branch, e.g.:

§ git checkout -b MOODLE_25_STABLE origin/MOODLE_25_STABLE
fatal: git checkout: updating paths is incompatible with switching branches.
Did you intend to checkout 'origin/MOODLE_25_STABLE' which can not be resolved as commit?

In this case you should ask the Mantainer, here Petr Škoda, if master is the correct branch for Moodle 2.3+ and he will reply that the Book module has been already integrated in Moodle starting from 2.3 so there's no need to install it usit git. Please, as a general rule, before asking the Mantainer for something you should check the online documentation.

Now it is wise to put the new directory mod/book/ to the list of ignored files of the main Moodle clone, otherwise a status of the main clone will keep reminding you that the new code has not been checked in.

$ cd /path/to/your/moodle/
$ echo /mod/book/ >> .git/info/exclude

To update your Moodle installation now, you must visit both Git repositories and pull changes from upstream.

$ cd /path/to/your/moodle/
$ git pull
$ cd mod/book
$ git pull

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.

See also

Moodle Docs
Moodle forum discussions
External resources