Clear git guide for Admins (not developers)

Clear git guide for Admins (not developers)

by Stuart Mealor -
Number of replies: 5
Picture of Particularly helpful Moodlers

I would like to try and improve the documentation here:
http://docs.moodle.org/25/en/Git_for_Administrators

There are lots of discussions between developers of how to use git (which logically focus on local code changes and including these in branches).  However, I want to deal with a typical school/company Moodle Administrator (likely a semi-technical person), who wants to a) Install Moodle via git, b) Install one or two plugins, and c) Keep Moodle and plugins up-to-date.

Following the instructions on Git_for_Administrators (Iḿ working on a new 2.5 install) there seem to be some inaccuracies?  Note: The example given is adding the Book module.  This is out-of-date anyway now the Book mod is in core, so perhaps we should change this to something else?!

$ 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)

Note: 2: Instructions below this say ¨The command (3) creates a new local branch that will track the remote branch with a Book version for Moodle 2.1."  In this case I think this should say 2.2.

Also, working through this example (but adding a non standard Theme), adapted from the above example, I emcountered an error:

$ cd /var/www/themes
$ cd themes
$ git clone git://github.com/freshbreeze/Moodle_Themes_Simple_2.4.git simple (Note: this 2.4 Theme also works with 2.5) 
$ cd simple
$ git checkout -b MOODLE_25_STABLE origin/MOODLE_25_STABLE
$ git branch -d master

When issuing the second to last line it produces the following error:

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?

OK, so now Iḿ confused because I didnt think I was switching branches?

So, anyone able to help with advice here (Iḿ still new to git really), and also contribute towards improving documentation for a typical Moodle Admin that is correct, up-to-date, and useful ?

Stu

Average of ratings: -
In reply to Stuart Mealor

Re: Clear git guide for Admins (not developers)

by Mary Cooch -
Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Testers Picture of Translators

HI Stuart. I think it's a great idea to improve that Git documentation for non-developers - I have noticed myself some parts are out of date but haven't wanted to change them since I don't know enough about Git myself, but I will certainly test out the improved textsmile  Hopefully some Git experts will come along and offer some advice.

Average of ratings: -
In reply to Mary Cooch

Re: Clear git guide for Admins (not developers)

by Matteo Scaramuccia -

Hi All,
I've made a small change: please review it because I'm not English native and I always doubt my English wink.

Following that change, the answer for Stuart is:

§ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

i.e.  no other branch than master has been defined so you don't need to switch to a branch different from that, already checked out - see the *, prefixing master to tell the user that it is the current branch.
That makes sense with the inline comment saying that both 2.4 and 2.5 are supported.

Unfortunately there will be always cases that will require some more info or examples.

HTH,
Matteo

Average of ratings: -
In reply to Matteo Scaramuccia

Re: Clear git guide for Admins (not developers)

by Stuart Mealor -
Picture of Particularly helpful Moodlers

Thanks for contributing to this thread Matteo smile

The command you've referred to "see the *, prefixing master to tell the user that it is the current branch." might be useful.  However, there's nothing in the command: "$ git checkout -b MOODLE_25_STABLE origin/MOODLE_25_STABLE" that suggests switching to another branch.

In the documentation, this command is being used to update (I think?)

And I am testing against the documentation as its presented.

That doesn't seem to address the fact that the command "$ git checkout -b MOODLE_25_STABLE origin/MOODLE_25_STABLE" causes the error message: "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?"

Stu ?

Average of ratings: -
In reply to Stuart Mealor

Re: Clear git guide for Admins (not developers)

by Matteo Scaramuccia -

Hi Stuart,
Howard has already reply to you: I just want to add some notes, git is a bad beast because of its learning curve but you'll be addicted to it the same as to Moodle, some day wink.

First: when you clone the repo from somewhere into your PC, it will extract by default the files contained in the master branch which - as per a gentle agreement - should contain the last development efforts, kind of unstable version, sometime; it depends on the conventions adopted by the developer(s) of the module you want to grab using git. IF you're fine with the master branch you've done.

If you know that the master branch is not for you, then you should extract (git checkout) the branch you want by creating a local branch usually named as the remote one in order to track the remote branch. "Track" means that whenever you'll want to update your local branch with the last commits of the remote one you need to issue the command git pull to take the remote changes into your local branch. Again keeping the same name for your local branch is a convention: for example I'm used to track even the integration repository and the local branches are named "<remote branch name>-integration".
Setting the tracking branch is done once, the first time.

By checking out a branch you're phisically extracting files into your Moodle instance and you'll install that code into it: it is wise NOT to track more than a remote branch because otherwise you could downgrade or upgrade the code using a not consistent branch for your Moodle instance.
You should take care of this aspect because, when you have more than one local branch (git branch, no -a or -r, issue git help branch for the details) you can go back and forth by simply issueing git checkout <branchname>.

Short recap:

  1. Select a module compatible with your Moodle instance
  2. Read docs / Ask the mantainer of the module what is the branch targetting your Moodle instance
  3. Clone the repo and if the required branch is not master, checkout the right one using -b to track and immediately checkout it; do it once, per remote branch
  4. You've done: git pull will be your friend when you'll want to update your local branch with the new commits (compared to the date you made the clone) of the remote one
  5. [OT] You can play with some hacks and if you've done some mistakes you can reset the file by simply issueing git checkout -- <filename>, otherwise you could store the changes in a new commit but the process you should adopt to do that operation at best is out of this topic and it could confuse you right now if I'll start describing a possible workflow

HTH,
Matteo

Average of ratings: -
In reply to Stuart Mealor

Re: Clear git guide for Admins (not developers)

by Howard Miller -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers

The problem with the theme example is that it assumes that the the repository has branches that match the Moodle core branches. This is probably good practice but is rarely followed. In your example, the theme repo simply doesn't have a MOODLE_25_STABLE branch. Most likely because it hasn't been written yet or simply because it doesn't have multiple branches at all (I didn't look). 

When dealing with non core plugins, you really need to use your initiative. Issue a

git branch -r

...and see what branches there are and go from there. In many cases, you may be as well trying the code you get from the original clone without changing branches as this will be (should be!) the latest development code. Obviously, there are risks there too. 

Ultimately, I suppose, you may have to ask the developer "what is the correct branch to use for Moodle 2.x?" if it is not otherwise clear. 

Average of ratings: -