GitGuide

#Git Guide For K-9

Want to contribute to K-9, but never used git before? Or just need a refresher? Or want to know how the K-9 leaders want things done? Then this guide is for you!

##Notice This page first created 20 October 2011 and may contain errors. If you have trouble with it, feel free to contact me, or change it if needed. You can also join us on IRC on #k-9 on irc.freenode.net, or via webchat. I created this guide as a reference for myself almost as much as for anyone else because I've only been using git for 12 days now.

##Create GitHub account First, set up a GitHub account if you don't already have one at https://github.com/signup/free.

##Set Up Git Here are instructions for setting up git for Linux, OSX, and Windows.

The Linux page covers installing with Synaptic (Debian/Ubuntu), but also includes important set up instructions for any distribution. Use whatever package manager your distribution uses (Gentoo example: $ sudo emerge -av dev-vcs/git).

##Set Up Your Fork

Fork K-9 by going to https://github.com/k9mail/k-9/ and clicking on "Fork" towards the top right. In a few seconds you'll have your own repo, but it's all still just online.

To clone your repo locally, enter

$ git clone git@github.com:USERNAME/k-9.git

This will create a directory called "k-9" in your current directory. USERNAME is your github username (most occurances of code in CAPS in this guide is meant as a variable, with the exceptions of HEAD which is git-specific and the bash code at the end of this document). In order for your code to keep up with K-9's development, you need to configure another remote. The default remote named "origin" points to your fork on GitHub. To keep track of the original repo, add a remote named "upstream":

$ cd k-9
$ git remote add upstream git://github.com/k9mail/k-9.git
$ git fetch upstream

Everything is now set up!

See http://help.github.com/fork-a-repo/ for more information.

##Start Coding With Git

Be sure to check out the K-9 Code Style. It will save you from being told to make a whole bunch of changes that don't actually affect how the program works!

###Working with branches

Git starts out in the master branch, but this should be left alone in order to be updated with K-9's master branch. Each feature or bug fix you do should get it's own branch. As cketti (someone who might be approving your pull requests) told me, "if in doubt, create a branch :)". So, to create a new branch named NEWFEATURE enter

$ git branch NEWFEATURE  

and to switch to that branch enter

$ git checkout NEWFEATURE

You can also combine the above with

$ git checkout -b NEWFEATURE

Now any changes you make will be isolated to this branch. Running $ git branch will show you what branches you have, and which one is active. Or if you're using Bash, see the end of this page to always know what branch is active.

###Compiling and installing

You do have the Android SDK already, don't you?

To compile K-9 enter

$ ant debug

If it compiles, you can install it with

$ adb install bin/K9-debug.apk

or reinstall it with

$ adb install -r bin/K9-debug.apk

You'll need to make sure your Android device is set to USB debugging (Settings -> Applications -> Development -> USB debugging).

If you've made any changes to files outside of src/ then you probably need to $ ant clean before you can compile it (definitely true for changes to files in res/)

Note: Android apps are signed by the publisher (in K-9's case, obra), and the K9-debug.apk is not signed by him, so an install of your build will fail if a released version of K-9 is installed. You can use an emulator, or remove K-9 from your phone first (and probably all of it's data). If you have root on your phone then you can backup your data which is in /data/data/com.fsck.k9. Now you can (re)install your own builds of K-9. Alternatively, you can install a completely separate version of K-9 by always doing ./tools/build-beta debug instead of ant debug (requires perl to be installed in your path).

###Committing changes

Once you're happy, you need to add and commit your changes. Make sure not to add any files that were changed just for you (like build.properties, for example -- use local.properties instead) to be able to compile it on your system.

To add changed files enter

$ git add --interactive

The staged column shows how many changes have been added. The unstaged column shows how many changes have not been added. Enter u to update, then to add files 1, 2 and 4 enter 1 2 4, leaving 3 unstaged. Press enter again, then q to quit.

A shortcut to add all changed files is

$ git add -u

If you need to add new files enter

$ git add FILE1 FILE2 ...

Once you're ready to commit these changes enter

$ git commit

and enter a descriptive summary of your modifications and save the file.

You can also combine "git add --interactive" and "git commit" with

$ git commit --interactive

Once a commit is done (i.e. you should be really happy with it) you can push it to your fork with

$ git push origin NEWFEATURE

Now everyone has access to your new feature or bug fix! But if you actually want it included with K-9 and not just your fork, you need to send a pull request.

###Send A Pull Request Sending a pull request lets the main developers of K-9 know that you think you have something useful to add. On your forked project's main page you need to change the current branch to "NEWFEATURE", then click on "Pull Request". Give a descriptive title to the request, and any more necessary information in the body. Click on "Commits" and "Files Changed" to review what is being sent, and then back to "Preview Discussion". When you're satisfied, click on "Send pull request" and the people to the right will be notified of your contribution. Someone might comment on things that need to be changed, or clarified, or anything else. You'd then go back to your branch, make the changes, commit it (with a new note on what this commit changes) and push it to your fork. This new commit will automatically show up on the pull request.

###Updating your master to K-9's master

So, you've forked K-9 and cloned your fork, maybe have your own branches, but you haven't changed your master, and some time later K-9 is ahead of your master. Now you need your own master to be up to date so you can make changes where code has been changed by others (or even a pull
request of yours that was merged!).

First, make sure you're in master:

$ git checkout master

Next, fetch it:

$ git fetch upstream

Now, merge the changes from upstream/master to your local master:

$ git merge upstream/master

Finally, update your repo's master:

$ git push origin master

Now you can create new branches from the updated master. Yay!

##Some Other Useful Commands

To merge branch NEWFEATURE with branch OTHER:

$ git checkout OTHER
$ git merge NEWFEATURE

To delete a branch:

$ git branch -d NEWFEATURE

To delete a branch from GitHub:

$ git push origin :NEWFEATURE  

To merge the last two commits together (only if you haven't pushed your commit, or BadThingsWillHappen):

$ git rebase -i HEAD~2

or to update a commit (same warning):

$ git commit --amend  

To save your work when you're not ready to make a commit:

$ git stash save

See http://ariejan.net/2008/04/23/git-using-the-stash/ on what to do with the stash.

##Bash Prompt Listing Current Branch It'd be nice to always know what branch you're working on. If your shell is Bash, you can take it from

ashley@tantrum k-9 $ 

to

ashley@tantrum k-9 (master) $ 

(where ashley@tantrum is green, k-9 and $ are blue, and (master) is yellow) by entering the following in your ~/.bashrc file

function parse_git_branch {
  ref=$(git symbolic-ref HEAD 2> /dev/null) || return
  echo "("${ref#refs/heads/}") "
}
PS1='\ [\033[01;32m\]\u@\h\ [\033[01;34m\] \W \ [\033[01;33m\]$(parse_git_branch)\ [\033[01;34m\]\$\ [\033[00m\] '

(but remove all the spaces in PS1 between \ and [, as the wiki thinks it's the start of [\LaTeX] input)