Git

Sahana Eden has decided to move from Bzr/LaunchPad to Git/GitHub

Why?

• The current repository is huge & bloated, taking too long to download.
• Even simple changes take an age to Pull down to servers
• Web2py no longer supports Bzr/LaunchPad, so we want to be able to maintain a common tool to work with both repositories.
• New developers are likely to be more familiar with Git/GitHub

How?

The preferred approach is to have a clean repository, in order to get the maximum benefit from the migration...although it is technically possible to ​migrate the commit history. Commit History will instead be maintained on the LaunchPad site as an archive

Fork a fresh Branch

• Sign-up for an account on ​GitHub
  • So that you can contribute code back to the project you will need an SSH public key. There is on-line help at github (select Beginner - Set Up Git and then scroll down to Set Up SSH Keys)
• Fork the Eden Branch: ​https://github.com/flavour/eden/fork_select
• Use Git to clone this down to your PC:

  cd web2py/applications
  git clone git@github.com:mygitusername/eden.git
  

Migrating existing Branches

Merge branch with trunk using normal Bzr tools

Assuming that you have already ​forked Eden Trunk, then you will need to create a new repository manually for additional branches, as you cannot ​fork your own project on GitHub:

• ​https://github.com/repositories/new

  cd web2py/applications
  git clone git@github.com:flavour/eden.git <mybranch>2
  

• Move .git & .gitignore from <mybranch>2 to <mybranch>
• Delete the rest of <mybranch>2
• Edit .git/config:

  [remote "origin"]
      fetch = +refs/heads/*:refs/remotes/origin/*
      url = git@github.com:<mygitusername>/<mybranch>.git
  

• Copy all the contents from <mybranch2> into <mybranch>

  cd <mybranch>
  git add .
  git commit -am "Initial Git version of My branch"
  git push -u origin master
  git remote add upstream git://github.com/flavour/eden.git
  

Developer Workflow

We suggest adopting the ​Story Branch pattern, which allows squashing commits in order to keep the main Trunk as clean as possible

cd <mybranch>
# Update your working directory with latest code from Trunk
git pull upstream master
git checkout -b <mystory>
git commit -am "My Story"
# Quick review of code (no test code left in, etc)
git diff master
# Merge latest Trunk
git checkout master
git pull
git checkout <mystory>
git rebase master
# Push to your branch on GitHub
git checkout master
git merge <mystory>
git push
# Cleanup
git branch -d <mystory>

To resolve merge conflicts, you can create the .THIS & .OTHER files using:

git show :2:file.txt > file.txt.THIS
git show :3:file.txt > file.txt.OTHER

Although on Windows this seems by default to produce UTF-16 files! ('UCS-2 Little Endian'). A script to make this process easier for Windows users is attached: merge.cmd

Developer Configuration

git config --global user.name "Your Name"
git config --global user.email your@email.com
git config --global github.user yourgithubusername
git config --global github.token yourtoken
git config --global core.editor "'C:/Program Files (x86)/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"
git config --global merge.tool diffmerge
git config --global diff.tool diffmerge
git config --global difftool.diffmerge.cmd 'C:/Program Files (x86)/Git/etc/wrappers/git-diff-diffmerge-wrapper.sh' "$LOCAL" "$REMOTE"
git config --global difftool.prompt false
git config --global merge.tool diffmerge
git config --global mergetool.diffmerge.cmd 'C:/Program Files (x86)/Git/etc/wrappers/git-merge-diffmerge-wrapper.sh' "$PWD/$LOCAL" "$PWD/$BASE" "$PWD/$REMOTE" "$PWD/$MERGED"
git config --global mergetool.prompt false
git config --global mergetool.trustExitCode false
git config --global mergetool.keepBackup false

Windows

Install ​Console & ​Diffmerge & ​configure Powershell.

Developer Tools

.gitattributes runs version.py to update the VERSION file on commit

Possibly we could add a pre-commit hook to run tests, e.g. based on ​http://tech.yipit.com/2011/11/16/183772396/ or ​http://blog.penzilla.net/2011/09/git-pre-commit-hook-for-python-now-with.html

How to get your work Merged into Trunk

• Make sure your work is fully tested.
• Tell git about any new files you've added. If you've added a new directory, you can just add the files in the directory and git will add the directory too. (Do "git help add" for a description of how to use the bzr add command.)

  git add filename...
  

• Commit your changes -- this records them in your local git repository. Provide a message that describes what the change is for. If it fixes a bug, include the ticket number.

  git commit -a -m "Describe your change here."
  

• It is really important, that the forked and the main eden repositorys are in sync here as we want to avoid merge-conflicts. To do that we need a branch of the eden master-repository:

   * Make sure that you are in the Eden directory here!
  git remote add upstream https://github.com/flavour/eden.git
  git fetch upstream
  

• Now you have a branch of the original Eden repository. If you want to update your master-branch, you can fetch it again and merge both branches:

  git fetch upstream
  git merge upstream/master
  

• Solve the conflicts if there were any
• Finally commit the merged version, push it to GitHub and send a Pull-Request on the GitHub site:

  git status
  ... add missing files ...
  git commit -a -m "Some message"
  git push
  

Reverting to last committed code

If you want to throw away all uncommitted changes (i.e. 'bzr revert'), then:

git reset --hard HEAD

Resources

• Community Book: ​http://book.git-scm.com
• Tips & Tricks: ​http://gitready.com