Developer’s Git Guide

This guide is aimed at Amdroid-h developers and the various situations they may find themselves in.

Command-line git is assumed, if you use a GUI version, I'm sure you have the command-line one installed as well.

Personal Gitorious Repo

Creating

After you create yourself a user account on Gitorious, you’re free to create git web repositories. To create a personal clone of the amdroid-h repo go here.

Merging

Once you think your commit/bug fix/feature is ready to be included in the main amdroid-h repo. Send HaaTa a merge request outlining the commits that you would like merged into the main repository.
He will then review the code (make some changes, or ask for some changes), and if all is good, merge the code into the main amdroid-h repository.

Each of the personal clones of amdroid-h have a request merge page. This is the preferred method for requesting a merge.

Deleting

If you’re really sure you want a delete your personal repository (e.g. screwed it up royally, irrelevant, etc.), go to the main Gitorious page of the repository in question. Go “Edit repository” (on the right side), then “Delete repository” (on the right side). You’ll then get a big warning asking whether you really want to delete the repo.

That’s it.

Setting Up Git Environment

Contact Information

If you haven’t done so on your machine, make sure you add the proper contact details to git (name and email). It’s possible to add different details per repository you are using locally, but that’s a pain. So I just use global settings:

$ git config --global user.name "Name Here"
$ git config --global user.email your_email@your_domain.example.com

Color Diff

I'm a command line git user, and happen to like colors, so I enable the color prompts in git:

$ git config --global color.diff auto
$ git config --global color.status auto  
$ git config --global color.branch auto

It’s possible to set these up per local repository, but I don’t really know why you'd want to do that…

Origin Setup

To setup your commit repo as the origin:

$ git remote add origin git@gitorious.org:amdroid-h/amdroid-h.git
$ git push origin master

If this fails for some reason (origin is already set to something else), open up the .git/config file and remove the [remote "origin"] section, and try the above section again.

Pushing Changes

Once you have committed what you want to your personal repo, you’ll have to push the changes to your personal repo for everyone to see (and as a backup of your process).

Note: Never EVER force a push to a public repo. This is sort've ok if you’re the only person using the repo, but otherwise, it just makes people’s life hell. If you find yourself in a case where you think you need to use a --force or -f, message HaaTa. This is especially important for your personal repo (that will probably have to merge into amdroid-h in the future).

Master

Easiest one to remember:

$ git push origin master

If for some reason, “origin” is not setup correctly:

$ git push <location of repository to push to> master

Branches

This is very easy, once you understand the syntax from the push command I outlined above as “master” is just the main branch:

$ git push <location of repository to push to> <branch name>

So something like this works as well:

$ git push origin <branch name>

Pulling Changes

All you have to remember to do for your own repo:

$ git pull --rebase

This command should work in 99% of cases here, so you can brainlessly use it.

When you have to pull in changes from another repo:

$ git pull --rebase <your branch> <location of repository to pull from>

Branching

A very useful feature of git that should be used regularly.

To check all of the current branches available:

$ git branch

Creating

Creating a new branch:

$ git branch <name of new branch>

Changing

Changing to a branch:

$ git checkout <name of branch>

To change to the “master” branch:

$ git checkout master

Deleting

To delete a branch:

$ git branch -d <name of branch to delete>

Git will warn you there are changes that haven’t been merged into another branch before deleting the branch. Otherwise it will delete the branch immediately.

Pulling Changes

You can either pull or push changes between branches, though probably pulling is easier to think about:

$ git pull --rebase <branch to merge changes into> <branch to get changes from>

Or if you are already in the branch to merge changes to:

$ git pull --rebase . <branch to get changes from>

Remote Branches

Pushing remote branches was noted above.

To see all available branches, including the remote ones:

$ git branch -a

To checkout a remote branch (only needs to be done once, then you can treat it like a local branch):

$ git checkout -t origin/<name of branch>

To delete a remote branch:

$ git push <location of repo> :heads/<branch name>

Committing

The preferred method of committing files:

$ git add <files changed or being added>
$ git rm <files being removed>  
$ git commit

If you are not adding any files, do your changes and removals then:

$ git commit -a

Commit Log Messages

To view logs of all of the commits:

$ git log

When writing the commit message, make sure it is as detailed as possible outlining the changes made. Each commit should only have ONE feature or bug fix. If the feature is rather large and cannot be split up, then make long commit message outlining all of the changes done.

Checking your Changes

Diff

Before you do any commit you should always check what you are changing (just in case something gets unexpectedly or accidentally added or removed):

$ git diff

Status

Another good habit is to check which files git is tracking changes from:

$ git status

Cleaning Up Commits

So you screwed up, here are some things to do (probably easiest just to message HaaTa for some advice).
IMPORTANT: Do not use if you've already pushed your changes to the repo.

Last Commit has Mistakes

You messed up the last commit. Maybe the message, or a typo in the code. If you haven’t pushed your changes to your repo yet then:

$ git reset --soft <commit to revert to>

Last Commit is Garbage

Your last commit was garbage, and you want it gone, completely (be VERY careful with this):

$ git reset --hard <commit to revert to>

Reorder/Delete Commits Interactively

The commit tree is completely screwed. In 99.9% of cases you won’t need this, but here it is:

$ git rebase -i HEAD~<number of commits to change/reorder>

Stash/Temporary Branch

Sometimes you have some changes you are working on, and then have to work on something else in another branch. The current changes don’t really warrant a commit, but you don’t want them to interfere with the new changes you are about to make.

Use the Stash

This command takes all of the not committed changes and puts it into a temporary branch for later use:

$ git stash

Reapply the Stash Changes

Once you are ready to work with the changes you stashed again, go to the branch you want to apply the changes to, then:

$ git stash apply

Comments