wiki:DeveloperGuidelines/Git

Version 21 (modified by Fran Boon, 10 years ago) ( diff )

--

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

Attachments (2)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.