-
-
Notifications
You must be signed in to change notification settings - Fork 2.4k
GitGuide
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!
This page was first created 20 October 2011 and may contain errors. If you have trouble with it, feel free to contact us, or change it if needed.
First, set up a GitHub account if you don't already have one at https://github.com/signup/free.
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).
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 https://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 https://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.
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!
In the future we hope to move to a more strict model where builds fail if the Code Style isn't obeyed but we're not quite there yet.
###Working with branches
Git starts out in the main branch, but this should be left alone in order to be updated with K-9's main 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.
Check the build instructions.
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.
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.
So, you've forked K-9 and cloned your fork, maybe have your own branches, but you haven't changed
your main, and some time later K-9 is ahead of your main. Now you need your own main
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 main:
$ git checkout main
Next, fetch it:
$ git fetch upstream
Now, merge the changes from upstream/main to your local main:
$ git merge upstream/main
Finally, update your repo's main:
$ git push origin main
Now you can create new branches from the updated main. Yay!
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.
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 (main) $
(where ashley@tantrum is green, k-9 and $ are blue, and (main) 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)