Development:Git for developers: Difference between revisions
Helen Foster (talk | contribs) m (Development:Quick Git start guide for Moodle development moved to Development:Git for developers: by request from David) |
David Mudrak (talk | contribs) mNo edit summary |
||
Line 3: | Line 3: | ||
== General workflow == | == General workflow == | ||
[[image:git-pushpull-model.png|right| | [[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]] | ||
In short, the Moodle development with Git looks like this: | In short, the Moodle development with Git looks like this: | ||
Line 15: | Line 15: | ||
Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github. | Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github. | ||
== Install Git on your computer == | == Install Git on your computer == | ||
Line 31: | Line 29: | ||
1. Go to [http://github.com/ Github] and create an account. | 1. Go to [http://github.com/ Github] and create an account. | ||
2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own | 2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository. | ||
3. | 3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part! | ||
== Set-up the local repository at your computer == | == Set-up the local repository at your computer == | ||
Create a local clone repository of your Github repository. In a terminal: | |||
git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git YOUR_LOCAL_MOODLE_FOLDER | |||
This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone. | |||
== Keeping your public repository up-to-date == | |||
[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]] | |||
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable. | |||
To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory. | |||
To register the upstream remote: | |||
git remote add upstream git://git.moodle.org/moodle.git | |||
The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated. | |||
git remote add upstream git://git.moodle.org/moodle.git | |||
git fetch upstream | git fetch upstream | ||
git | for BRANCH in MOODLE_19_STABLE MOODLE_20_STABLE master; do | ||
git push github refs/remotes/upstream/$BRANCH:$BRANCH | |||
done | |||
=== How it works === | |||
The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page. | |||
Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week. | |||
== Preparing the patchset == | |||
Now you can work on a new issue. You can use a Git UI tool like SmartGit for these steps: | |||
* Run the update script (the script will switch to "master" branch, so take care to stash/commit the changes of your current branch). To check the current branch: | * Run the update script (the script will switch to "master" branch, so take care to stash/commit the changes of your current branch). To check the current branch: | ||
<code bash> | <code bash> | ||
Line 96: | Line 98: | ||
</code> | </code> | ||
2. Add the remote upstream. You want to update your local MOODLE_19_STABLE branch and your | 2. Add the remote upstream. You want to update your local MOODLE_19_STABLE branch and your Github (called "origin") MOODLE_19_STABLE branch from the official Moodle upstream. | ||
<code bash> | <code bash> | ||
cd ./YOUR_LOCAL_MOODLE_19_FOLDER/ | cd ./YOUR_LOCAL_MOODLE_19_FOLDER/ | ||
Line 116: | Line 118: | ||
</code> | </code> | ||
5. Run the script. Your | 5. Run the script. Your Github MOODLE_19_STABLE branch and your local MOODLE_19_STABLE branch are now updated. | ||
6. You can now work on an issue. You can use a Git UI tool like SmartGit for these steps: | 6. You can now work on an issue. You can use a Git UI tool like SmartGit for these steps: | ||
Line 125: | Line 127: | ||
== Peer review some code == | == Peer review some code == | ||
You need to review someone else work, They must have pushed their work into | You need to review someone else work, They must have pushed their work into Github: | ||
* | * Github repository url: git://github.com/PEER_USERNAME/moodle.git | ||
* branch name: MDL-XXXXX | * branch name: MDL-XXXXX | ||
Line 162: | Line 164: | ||
</code> | </code> | ||
== Update a branch before pushing your changes == | == Update a branch before pushing your changes == | ||
To make diff easy on | To make diff easy on Github for weekly pull request review, you want to update your branch before to push it to Github. First commit your changes, then run the update script. You have been switched on master branch, so first thing is to go back to your working branch | ||
<code bash> | <code bash> | ||
git checkout MLD-XXXX | git checkout MLD-XXXX | ||
Line 184: | Line 186: | ||
git config --global core.filemode false | git config --global core.filemode false | ||
</code> | </code> | ||
* If you want to delete a remote branch on | * If you want to delete a remote branch on Github: | ||
<code bash> | <code bash> | ||
git push origin :CONFLICTING_REMOTE_BRANCH_NAME | git push origin :CONFLICTING_REMOTE_BRANCH_NAME | ||
</code> | </code> | ||
* PHPStorm (beta version) named your 'origin' => 'master' when you cloned your | * PHPStorm (beta version) named your 'origin' => 'master' when you cloned your Github repository. It is better to rename it as 'origin'. | ||
<code bash> | <code bash> | ||
git remote rename master origin | git remote rename master origin | ||
</code> | </code> | ||
* You've been working with Git in the early stages when Moodle HQ were experimenting with it. They now changed 'cvshead' to 'master' into upstream (moodle.org Git). You need to rename all your 'cvshead' | * You've been working with Git in the early stages when Moodle HQ were experimenting with it. They now changed 'cvshead' to 'master' into upstream (moodle.org Git). You need to rename all your 'cvshead' Github and local branches as 'master'. There what you should do (this is not a script to run, execute the command one at the time following the instructions): | ||
<code bash> | <code bash> | ||
#go to your root git folder | #go to your root git folder | ||
Line 205: | Line 207: | ||
git push origin master | git push origin master | ||
#on | #on Github, in your repository administration, change the default to 'master' | ||
git push origin :cvshead | git push origin :cvshead |
Revision as of 15:18, 1 April 2011
This document is for helping you get started on Moodle development with Git. For further details of Git, see Category:Git.
General workflow
In short, the Moodle development with Git looks like this:
- You as the contributor commit changes into your personal repository at your computer
- You push the changes into your public repository and ask for their inclusion via so called PULL request
- Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
- The integrated change is tested and finally pushed into Moodle production repository
- You update your local repository with all changes from the production repository and the next cycle may start again
This workflow runs in roughly weekly cycles. The integration happens on Monday and the testing on Tuesday. On Wednesday, the production repository moodle.git is usually updated with changes from the last development week.
Most Moodle developers have their public repositories hosted at Github. Alternatively you may want to try Gitorious or the legendary repo.or.cz. In the examples in this guide we assume you'll set up your public repository at Github.
Install Git on your computer
Install Git on your computer. Most Linux distributions have Git available as a package to install. If you are on Mac, git-osx-installer installs it in few click. If you are Windows user, you should switch to Linux or Mac anyway :-p
Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".
git config --global user.name "Your Name" git config --global user.email yourmail@domain.tld
Set-up the public repository
1. Go to Github and create an account.
2. Go to the official Moodle Github repository and click on the Fork button. You now have your own Github Moodle repository.
3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this Github help page. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!
Set-up the local repository at your computer
Create a local clone repository of your Github repository. In a terminal:
git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git YOUR_LOCAL_MOODLE_FOLDER
This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.
Keeping your public repository up-to-date
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. Remember: never commit directly into master and MOODLE_xx_STABLE branches. In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.
To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.
To register the upstream remote:
git remote add upstream git://git.moodle.org/moodle.git
The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.
git fetch upstream for BRANCH in MOODLE_19_STABLE MOODLE_20_STABLE master; do git push github refs/remotes/upstream/$BRANCH:$BRANCH done
How it works
The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.
Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.
Preparing the patchset
Now you can work on a new issue. You can use a Git UI tool like SmartGit for these steps:
- Run the update script (the script will switch to "master" branch, so take care to stash/commit the changes of your current branch). To check the current branch:
git branch -a
- Create a new branch and switch to it. You should never work in your local master branch:
cd YOUR_LOCAL_MOODLE_FOLDER
git branch BRANCH_NAME
git checkout BRANCH_NAME
- Fix your issue with your favorite IDE. Check updated files:
cd YOUR_LOCAL_MOODLE_FOLDER
git status
- Commit, push and do a pull request (FILE_NAME can be either a single file or a folder, for a folder the "add" command will be performed recursively)
git add FILE_NAME
git commit
git push origin BRANCH_NAME
Working on 1.9 or earlier branches
This is just a tiny little bit more complicated that working on 2.0. Even though you could work in the same folder as for 2.0, you should create another folder for working on 1.9. It will make things less messy and easier to understand.
1. In a terminal
git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git ./YOUR_LOCAL_MOODLE_19_FOLDER/
2. Add the remote upstream. You want to update your local MOODLE_19_STABLE branch and your Github (called "origin") MOODLE_19_STABLE branch from the official Moodle upstream.
cd ./YOUR_LOCAL_MOODLE_19_FOLDER/
git remote add upstream git://git.moodle.org/moodle.git
git fetch upstream
3. Now you are going to create a local 1.9 branch. You will keep this branch updated (the branch will track upstream) and you are never going to work in it.
git checkout -b MOODLE_19_STABLE upstream/MOODLE_19_STABLE
4. Create the update script in ./update_github
cd YOUR_LOCAL_MOODLE_19_FOLDER
git checkout MOODLE_19_STABLE
git pull
git push origin refs/remotes/upstream/MOODLE_19_STABLE:MOODLE_19_STABLE
5. Run the script. Your Github MOODLE_19_STABLE branch and your local MOODLE_19_STABLE branch are now updated.
6. You can now work on an issue. You can use a Git UI tool like SmartGit for these steps:
- Run the update script (don't forget to stash/commit the change of your current local branch, you are going to switch to MOODLE_19_STABLE local branch)
- Create a new branch for your issue and switch to it
- Fix your issue with your favorite IDE
- Commit, push and do a pull request
Peer review some code
You need to review someone else work, They must have pushed their work into Github:
- Github repository url: git://github.com/PEER_USERNAME/moodle.git
- branch name: MDL-XXXXX
1. Run the update script (it will switch to your local master branch and update the code)
2. Add the remote repository (only first time ever, then skip this step)
git remote add PEER_USERNAME git://github.com/PEER_USERNAME/moodle.git
3. Fetch the repository, so Git knows about the last changes in it
git fetch PEER_USERNAME
4. Switch to a new local 'testing' branch
git checkout -b PEER_USERNAME-MDL-XXXXX
5. Import the remote change into this local branch (but not marked as 'committed' so you can see the changes into your IDE)
git merge --squash PEER_USERNAME/MDL-XXXXX
6. You can now test in your favorite IDE. If it supports Git you should see the difference with your local master.
7. Finally you are going to delete this testing branch:
- Warning: if you didn't switch, you should still be on testing branch.
- the first command revert all the changes to the 'master' state.
git reset --hard
git checkout master
git branch -d PEER_USERNAME-MDL-XXXXX
Update a branch before pushing your changes
To make diff easy on Github for weekly pull request review, you want to update your branch before to push it to Github. First commit your changes, then run the update script. You have been switched on master branch, so first thing is to go back to your working branch
git checkout MLD-XXXX
git rebase master
At this moment either it worked fine and your branch is updated, either you had some conflicts with one of your previous branch commits.
Fix all your conflicts in your editor (like you will fo with CVS) and add the files with 'git add' command.
git add file1 file2 file3 ...
Now continue the rebasing.
git rebase --continue
Either it worked and your branch is updated, either one of your other commit created again some other conflicts. Restart the Fix, add, continue rebase steps until you have no conflict. Your branch is updated.
Troubleshooting
- do not push your file permission to any repository
git config --global core.filemode false
- If you want to delete a remote branch on Github:
git push origin :CONFLICTING_REMOTE_BRANCH_NAME
- PHPStorm (beta version) named your 'origin' => 'master' when you cloned your Github repository. It is better to rename it as 'origin'.
git remote rename master origin
- You've been working with Git in the early stages when Moodle HQ were experimenting with it. They now changed 'cvshead' to 'master' into upstream (moodle.org Git). You need to rename all your 'cvshead' Github and local branches as 'master'. There what you should do (this is not a script to run, execute the command one at the time following the instructions):
- go to your root git folder
git fetch origin
git fetch upstream
git remote prune upstream
git remote prune origin
/// FIRST TIME YOU RUN THIS SCRIPT
git checkout -b master upstream/master
git push origin master
- on Github, in your repository administration, change the default to 'master'
git push origin :cvshead
git branch -d cvshead
/// END OF FIRST TIME
git remote set-head origin -a
git remote set-head upstream -a
/// OTHER TIME - FOR YOUR OTHER GIT MOODLE FOLDERS
git checkout -b master upstream/master
git branch -d cvshead
/// END OF OTHER TIME
- check .git/config that there is no references to 'cvshead', if there are replace with 'master'
- optional:
- update your update script ('cvshead' => 'master')
- To know about your branches (the current branch is marked with an asterix)
git branch -a
- For any help
git any_command --help