<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"> <head> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="ProgId" content="Word.Document"> <meta name="Generator" content="Microsoft Word 14"> <meta name="Originator" content="Microsoft Word 14"> <link rel="File-List" href="cid:filelist.xml@01CF42BD.428F1840"><link rel="Edit-Time-Data" href="cid:editdata.mso"><style></style> </head> <body lang="EN-CA" link="blue" vlink="purple" style="tab-interval:36.0pt"> <div class="WordSection1"> As you know, I began migrating ESP-r from Collab.net to git-hub last month. That transfer is largely complete now. I’m passing on an initial set of instructions about how to work with the repository. If you’re new to svn or git, please refer to the many comprehensive tutorials on the web. <o:p> </o:p> <o:p> </o:p> These instructions cover the layout of the new repository, and basic check-out/check-in transactions under git and svn. I haven’t yet jumped into merging, but I understand that merge operations are much easier on github than in the old repository. More details will follow. <o:p></o:p> <o:p> </o:p> - Alex <o:p></o:p> <o:p> </o:p> 1. How to join the ESP-r development community: <o:p></o:p> <o:p> </o:p> If you haven’t already done so, head over to <a href="https://github.com/">https://github.com/</a> and create an account. Send me your username, and I will add you to the ESP-r community. <o:p></o:p> <o:p> </o:p> 2. How to find ESP-r on github: <o:p></o:p> <o:p> </o:p> ESP-r is located here: <a href="https://github.com/ESP-rCommunity">https://github.com/ESP-rCommunity</a><o:p></o:p> <o:p> </o:p> In the ESP-r community, you will find the following ESP-r projects:<o:p></o:p> <![if !supportLists]>·         <![endif]>ESP-rSource: The functional source code, installation scripts and test cases for building ESP-r.<o:p></o:p> <![if !supportLists]>·         <![endif]>ESP-rModels: Training, exemplars and validation models associated with ESP-r. <o:p></o:p> <![if !supportLists]>·         <![endif]>ESP-rDatabases: Core databases and climate files associated with the ESP-r distribution<o:p></o:p> <![if !supportLists]>·         <![endif]>ESP-rDoc:  Documentation associated with the ESP-r project<o:p></o:p> <![if !supportLists]>·         <![endif]>ESP-rExtras: Extra files associated with the ESP-r project. Includes climate, model, training materials<o:p></o:p> <![if !supportLists]>·         <![endif]>CHREM: The Canadian Residential Energy Model<o:p></o:p> <o:p> </o:p> Three of these projects (ESP-rModels, ESP-rDatabases and ESP-rDoc) were formerly subdirectories within the src directory in the old repository. I moved them into separate modules because there is a lot of commit traffic associated with these files, which makes it harder for developers to stay in sync with the master branch. These projects are still needed to build ESP-r; if you clone the ESP-rSource repository in git, git will recognize these as submodules and will pull them in automatically. I’ve also created a script that automates this for svn users (details below). <o:p></o:p> <o:p> </o:p> <o:p> </o:p> 3. How to create a branch, and how to delete it<o:p></o:p> <o:p> </o:p> In github, you can create and delete your own branches.  To do so, click on the branch button and enter an appropriate name:<o:p></o:p> <o:p> </o:p> <img border="0" width="622" height="268" id="Picture_x0020_1" src="cid:image001.jpg@01CF42BD.428F1840"><o:p></o:p> <o:p> </o:p> I strongly encourage you to delete your branches regularly. Once you changes have been pushed to the master branch, delete your branch and start new development. This will make it easier to stay in sync. <o:p></o:p> <o:p> </o:p> <o:p> </o:p> 4. How to recover a branch from the old repository<o:p></o:p> <o:p> </o:p> I’ve kept a complete backup from the old repository; I can reconstitute branches (including their history) on the new repository. Let me know if you want me to resurrect a particular branch. <o:p></o:p> <o:p> </o:p> 5. How to work with ESP-r source code USING SVN<o:p></o:p> <o:p> </o:p> Obtaining the code<o:p></o:p> github provides an SVN api that allows you to work with the ESP-r repository using svn commands. To download a local sandbox, use the checkout (co) command:<o:p></o:p> <o:p> </o:p> svn co <a href="https://github.com/ESP-rCommunity/ESP-rSource.git/branches/%5bMy-Branch-Name"> https://github.com/ESP-rCommunity/ESP-rSource.git/branches/[My-Branch-Name</a>]<o:p></o:p> <o:p> </o:p> For example, to obtain a sandbox from the master branch (formerly development_branch), run:<o:p></o:p> <o:p> </o:p> svn co https://github.com/ESP-rCommunity/ESP-rSource.git/branches/master<o:p></o:p> <o:p> </o:p> To reduce the amount of merges that developers are responsible for, I’ve moved the training, validation, databases and climate directories into separate git modules. Git can automatically resolve these submodules, but with svn, you’ll need to check them out manually into your sandbox.  I’ve created a script called svn-fetch-modules.sh. To use it, move to your sandbox and run ‘./svn-fetch-modules.sh’<o:p></o:p> <o:p> </o:p> <o:p> </o:p> ip-10-97-134-174:~ # cd master<o:p></o:p> ip-10-97-134-174:~/master # ls<o:p></o:p> .gitmodules  .svn  GPL.txt  Install  Readme  Version  src  svn-fetch-modules.sh  tester<o:p></o:p> ip-10-97-134-174:~/master # ./svn-fetch-modules.sh<o:p></o:p> svn-fetch-modules.pl:<o:p></o:p> path: ~/master<o:p></o:p> Checking out documentation via svn...-> doc..<o:p></o:p> A    doc/README.md<o:p></o:p> A    doc/archive<o:p></o:p> <SNIP><o:p></o:p> A    data/databases/readme_plant_dbs<o:p></o:p> Checked out revision 1.<o:p></o:p> Setting svn ignore properties for databases, doc, models...<o:p></o:p> property 'svn:ignore' set on '.'<o:p></o:p> ip-10-97-134-174:~/master # ls<o:p></o:p> .gitmodules  .svn  GPL.txt  Install  Readme  Version  data  doc  models  src  svn-fetch-modules.sh  tester<o:p></o:p> <o:p> </o:p> Compiling<o:p></o:p> You’re now ready to compile ESP-r. From the top directory in your sandbox (e.g. master), run ./Install. <o:p></o:p> <o:p> </o:p> NOTE: Under the new directory structure, run Install from the top-most directory (i.e. ‘master’) and not the src sub-directory (i.e. master/src).<o:p></o:p> <o:p> </o:p> Committing your changes<o:p></o:p> From within your sandbox, run svn commit as you would normally. Note that if you’re making changes to the data, doc, or models directories, you’ll have to make separate commits from within these directories. This is necessary because these directories are now separate git modules. <o:p></o:p> <o:p> </o:p> Updating with changes on your branch<o:p></o:p> From within your sandbox, run svn update as you would normally.<o:p></o:p> <o:p> </o:p> Merging changes<o:p></o:p> svn merge will not work on github. Instead, I believe you can use the web tools on <a href="https://github.com">https://github.com</a> to pull changes from the master branch and to push changes back to your branch. However, I’m still working out the details. More info to come. <o:p></o:p> <o:p> </o:p> 6. How to work with ESP-r source code USING GIT<o:p></o:p> <o:p> </o:p> Git is different than svn. It’s more distributed, more robust and more powerful. But it’s also more complicated and more confusing for beginners. I recommend reading: <o:p></o:p> <![if !supportLists]>·         <![endif]>Why svn users should switch to git: <a href="http://heartmindcode.com/2011/03/27/svn-users-why-you-should-switch-to-git/"> http://heartmindcode.com/2011/03/27/svn-users-why-you-should-switch-to-git/</a><o:p></o:p> <![if !supportLists]>·         <![endif]>Git for svn users: <a href="http://git.or.cz/course/svn.html"> http://git.or.cz/course/svn.html</a>  <o:p></o:p> <o:p> </o:p> Update git <o:p></o:p> <o:p> </o:p> Some older versions of git have proven unstable. Github recommends using git version 1.7.10 or later. Check your version using the command ‘git version’:<o:p></o:p> <o:p> </o:p> ip-10-97-134-174:~/ESP-rSource/src # git version<o:p></o:p> git version 1.7.12.4<o:p></o:p> <o:p> </o:p> Please update to a more recent version if your copy is out of date.<o:p></o:p> <o:p> </o:p> Obtaining the code<o:p></o:p> <o:p> </o:p> The git command ‘clone’ is similar to an ‘svn checkout’. To clone the master branch, use the command:<o:p></o:p> <o:p> </o:p> git clone --recursive https://github.com/ESP-rCommunity/ESP-rSource.git<o:p></o:p> <o:p> </o:p>             EXAMPLE:<o:p></o:p> ip-10-97-134-174:~ # git clone --recursive  https://github.com/ESP-rCommunity/ESP-rSource.git<o:p></o:p> Cloning into 'ESP-rSource'...<o:p></o:p> <SNIP><o:p></o:p> Receiving objects: 100% (45051/45051), 63.79 MiB | 30.61 MiB/s, done.<o:p></o:p> Resolving deltas: 100% (33799/33799), done.<o:p></o:p> <o:p> </o:p> The git clone command may seem like an svn checkout, but it’s more comprehensive. When you run ‘git clone’, you actually make a fully-functional copy of the entire repository (including all branches). Your local repository is now a complete backup of the entire history on all branches of the repository.  While your cloned repository contains a link to the github repository that allows you to synchronize changes (see git pull and git push, below), it also functions as a stand-alone repository.<o:p></o:p> <o:p> </o:p> Inside the ESP-rSource Repository, you’ll find the master branch (formerly development_branch) source code: <![if !supportLineBreakNewLine]> <![endif]><o:p></o:p> ip-10-97-134-174:~ # cd ESP-rSource<o:p></o:p> ip-10-97-134-174:~/ESP-rSource # ls<o:p></o:p> .git  .gitmodules  GPL.txt  Install  Readme  Version  data  doc  models  src  svn-fetch-modules.sh  tester<o:p></o:p> <o:p> </o:p> Git will only show you one branch at a time in this repository. If you’ve cloned with the command above, you will find git has created a copy of the master branch in you the ESP-rSource directory. To find out which branch you’re on, use the ‘git branch’ command <o:p></o:p> <o:p> </o:p> ip-10-97-134-174:~/ESP-rSource # git branch<o:p></o:p> * master<o:p></o:p> <o:p> </o:p> You can also see a list of all branches in the repository: <o:p></o:p> <o:p> </o:p> ip-10-97-134-174:~/ESP-rSource # git branch -a<o:p></o:p> * master<o:p></o:p>   remotes/origin/Achim_Geissler<o:p></o:p>   remotes/origin/Alex_Ferguson<o:p></o:p>   remotes/origin/HEAD -> origin/master<o:p></o:p>   remotes/origin/NRCanOpt<o:p></o:p>   remotes/origin/h3k_switch<o:p></o:p>   remotes/origin/master<o:p></o:p> <o:p> </o:p> <o:p> </o:p> To switch to another branch, use the command ‘git checkout’<o:p></o:p> <o:p> </o:p> ip-10-97-134-174:~/ESP-rSource # git checkout Alex_Ferguson<o:p></o:p> Branch Alex_Ferguson set up to track remote branch Alex_Ferguson from origin.<o:p></o:p> Switched to a new branch 'Alex_Ferguson'<o:p></o:p> <o:p> </o:p> ip-10-97-134-174:~/ESP-rSource # git branch<o:p></o:p> * Alex_Ferguson<o:p></o:p>   master<o:p></o:p> <o:p> </o:p> For svn users, this is one of the most confusing aspects of git. A ‘git checkout’ doesn’t download any code—it just switches between branches on a repository you’ve already cloned. <o:p></o:p> <o:p> </o:p> Note: you can also clone the repository and checkout the branch in a single command:<o:p></o:p> <o:p> </o:p> git clone -b [My-Branch-Name] --recursive https://github.com/ESP-rCommunity/ESP-rSource.git<o:p></o:p> <o:p> </o:p> This is equivalent to running ‘git clone’ and then ‘git checkout [my branch name] ‘<o:p></o:p> <o:p> </o:p> Compiling<o:p></o:p> You’re now ready to compile ESP-r. From the top directory in your branch (e.g. ESP-rSource), run ./Install. <o:p></o:p> <o:p> </o:p> NOTE: Under the new directory structure, run Install from the top-most directory (i.e. ‘master’) and not the src subdirectory (i.e. master/src).<o:p></o:p> <o:p> </o:p> <o:p> </o:p> Committing your changes<o:p></o:p> The git ‘commit’ command is analogous to an svn commit, except it only commits it to your local repository. Remember, ‘git clone’ creates a fully-functional repository on your local machine. To pass your changes up to git hub you must also issue a ‘git push’command.<o:p></o:p> <o:p> </o:p> ip-10-97-134-174:~/ESP-rSource/src # git commit Readme<o:p></o:p> [Alex_Ferguson 3876570] Test commit<o:p></o:p> Committer: fergusoa <root@ip-10-97-134-174.ec2.internal><o:p></o:p> Your name and email address were configured automatically based<o:p></o:p> on your username and hostname. Please check that they are accurate.<o:p></o:p> You can suppress this message by setting them explicitly:<o:p></o:p> <o:p> </o:p>     git config --global user.name "Your Name"<o:p></o:p>     git config --global user.email you@example.com<o:p></o:p> <o:p> </o:p> After doing this, you may fix the identity used for this commit with:<o:p></o:p> <o:p> </o:p>     git commit --amend --reset-author<o:p></o:p> <o:p> </o:p> 1 file changed, 1 insertion(+)<o:p></o:p> <o:p> </o:p> ip-10-97-134-174:~/ESP-rSource/src # git push<o:p></o:p> Username for 'https://github.com': fergusoa<o:p></o:p> Password for 'https://fergusoa@github.com':<o:p></o:p> Counting objects: 7, done.<o:p></o:p> Delta compression using up to 16 threads.<o:p></o:p> Compressing objects: 100% (4/4), done.<o:p></o:p> Writing objects: 100% (4/4), 369 bytes, done.<o:p></o:p> Total 4 (delta 2), reused 0 (delta 0)<o:p></o:p> To https://github.com/ESP-rCommunity/ESP-rSource.git<o:p></o:p>    e84789b..3876570  Alex_Ferguson -> Alex_Ferguson<o:p></o:p> <o:p> </o:p> Remember: Any changes you commit to your local git repository are not available on github until you issue a ‘git push’ command!<o:p></o:p> <o:p> </o:p> Note that if you’re making changes to the data, doc, or models directories, you’ll have to make separate commits from within these directories. This is necessary because these directories are now separate git modules<o:p></o:p> <o:p> </o:p> Updating with changes on your branch<o:p></o:p> You can refresh your local repository with changes on github via the git pull command. Note that you may see traffic on other branches --- this is normal because your local git repository is a clone of the entire github repository (not just your branch). <o:p></o:p> <o:p> </o:p> ip-10-97-134-174:~/ESP-rSource/src # git pull<o:p></o:p> remote: Counting objects: 2, done.<o:p></o:p> remote: Compressing objects: 100% (2/2), done.<o:p></o:p> remote: Total 2 (delta 0), reused 0 (delta 0)<o:p></o:p> Unpacking objects: 100% (2/2), done.<o:p></o:p> From https://github.com/ESP-rCommunity/ESP-rSource<o:p></o:p>    8e205f1..0eb7055  Achim_Geissler -> origin/Achim_Geissler<o:p></o:p> Already up-to-date.<o:p></o:p> <o:p> </o:p> <o:p> </o:p> Merging changes<o:p></o:p> You can use the web tools on <a href="https://github.com">https://github.com</a> to pull changes from the master branch and to push changes back to your branch, or using the git merge command. However, I’m still working out the details. More info to come. <o:p></o:p> <o:p> </o:p> </div> </body> </html>