Git is a free & open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

Every Git clone is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Branching and merging are fast and easy to do.

In order to work with GIT you first have to understand and get used to work with multiple branches.

For a better understanding of the branch meaning and philosophy, one can be inspired from here: http://www-cs-students.stanford.edu/~blynn/gitmagic/ch04.html

This document examples are based on Douglas Hubler's repository on git-hub: http://github.com/dhubler/sipxecs

Working with GIT repository in local mode

A developer should be aware of three things in order to locally work with GIT repositories:

  1. Download source code from the repository
  2. Make your changes
  3. Generate patches

There are two repositories involved: the remote repository (Douglas's on git-hub called origin repository) and your copy, called local repository

Download source code from the repository

Sources have to be downloaded in read-only mode on a chosen path on local computer, so there is no danger to overwrite the original code:

git clone git://github.com/dhubler/sipxecs.git

Example:

[user@localhost~]$ mkdir work
[user@localhost~]$ cd work
[user@localhost]$ git clone git://github.com/dhubler/sipxecs.git
Initialized empty Git repository in /home/mirceac/work/sipxecs/.git/remote:
Counting objects: 127119, done.remote:
Compressing objects: 100% (29946/29946), done.remote:
Total 127119 (delta 84094), reused 126491 (delta 83609)Receiving objects: 100% (127119/127119), 751.56 MiB | 1.69 MiB/s, done.
Resolving deltas: 100% (84094/84094), done.Checking out files: 100% (11021/11021), done.
[user@localhost]$ ls
sipxecs

Now, verify to what branch you are positioned using the following command:

git status

Use the following command to list all visible branches

git branch

The origin repository has many branches and you have to relay your work on one of them: master Sometimes this branch is hidden and you have to make it visible

Use the following command to list all branches

git branch -a

How to make branch master visible and be positioned on it

git checkout -b master origin/master

Watch the following code-snipped to accomplish this

Example:

[user@localhostsipxecs]$ git branch
* master
[user@localhostsipxecs]$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/release-4.2
[user@localhostsipxecs]$ git checkout -b master origin/master
Branch master set up to track remote branch master from origin.
Switched to a new branch 'master'
[user@localhostsipxecs]$ git status
# On branch master
nothing to commit (working directory clean)
[user@localhostsipxecs]$ git branch
  master
* master
[user@localhostsipxecs]$
Make your changes

Before starting working, you have to make sure that you are in sync with the latest source code. Assuming that you have to base your work on master branch follow the steps from below:

ATTENTION: do not make any change or commit on master branch. Always create a new branch for your changes

Run the commands from below:

git fetch origin //make sure that you are in sync with the remote repository (origin)
git checkout master //move to master branch, because we want to base our work on this
git rebase origin/master //rebase your master branch with the origin master branch just to keep in sync with the latest source code
git checkout -b TEST //create an position to a new branch called TEST, the branch were your changes will be performed

TIP: if there is a branch you don't like you can always delete it using:

git branch -D TEST

...after all your changes are done and you are prepared for the final step: generate patch, run the following commands

git status //to verify what files are new and what are changed
git add <file_path> //if there are newly created files on your branch
git commit -a //commit your work

use git commit -a --amend if you want that your changes to be on top on a previous commit - in this way all will be included in a single patch

NOTE: for every commit will be generated one single patch (unless git commit -a --amend was used)

When git commit -a is used a vi editor is opened. Please the comments about the patch there and use :wq to actually write the changes (perform the commit)

git commt -a --amend will preserve previous commit comments and changes

TEST: Test Title

Description
# Please enter the commit message for your changes. Lines starting# with '#' will be ignored, and an empty message aborts the commit.
# Committer: Mircea Carasel
# On branch TEST
# Changes to be committed:
#   (use "git reset HEAD ..." to unstage)
#       modified:   sipXconfig/neoconf/etc/freeswitch/freeswitch.xml
#~   

As a rule, after the title a blank line should be inserted and then the patch description

Example:

[user@localhostsipxecs]$ git checkout master
Switched to branch 'master'
[user@localhostsipxecs]$ git status
# On branch masternothing to commit
(working directory clean)
[user@localhostsipxecs]$ git rebase origin/master
Current branch master is up to date.
[user@localhostsipxecs]$ git status
# On branch master
nothing to commit (working directory clean)
[user@localhostsipxecs]$ git checkout -b TEST
Switched to a new branch 'TEST'
[user@localhostsipxecs]$ git status
# On branch TEST
nothing to commit (working directory clean)
[user@localhostsipxecs]$

****after all your changes are done****

[user@localhostsipxecs]$ git status
# On branch TEST
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#    modified:   sipXconfig/neoconf/etc/freeswitch/freeswitch.xml
#
no changes added to commit (use "git add" and/or "git commit -a")
[user@localhostsipxecs]$ git commit -a
[TEST 747365d] UC-TEST: Patch title
 1 files changed, 1 insertions(+), 1 deletions(-)
[user@localhostsipxecs]$ git status
# On branch TEST
nothing to commit (working directory clean)
Generate patches

In order to correctly generate a patch you have to make sure that your branch is rebased with the origin's master branch, because while you performed your changes it is very likey

that some other developers performed other changes that are commited on the remote branch (origin)

Run the commands from below:

git fetch origin //make sure that you are in sync with the remote repository (origin)
git checkout master //move to master branch, because we want to base our work on this
git rebase origin/master //rebase your master branch with the origin master branch just to keep in sync with the latest source code
git checkout TEST //move to your branch
git rebase master //keep in sync your branch with your master branch that now is in sync with origin's master

If rebase cannot be performed automatically, git may require you to manually perform some changes.

Example:

Falling back to patching base and 3-way merge...
Auto-merging sipXconfig/neoconf/src/org/sipfoundry/sipxconfig/bulk/csv/Index.java
CONFLICT (content): Merge conflict in sipXconfig/neoconf/src/org/sipfoundry/sipxconfig/bulk/csv/Index.java
Auto-merging sipXconfig/neoconf/src/org/sipfoundry/sipxconfig/common/AbstractUser.java
Auto-merging sipXconfig/neoconf/test/org/sipfoundry/sipxconfig/bulk/ldap/UserMapperTest.java
CONFLICT (add/add): Merge conflict in sipXconfig/neoconf/test/org/sipfoundry/sipxconfig/bulk/ldap/UserMapperTest.java
Auto-merging sipXconfig/web/src/org/sipfoundry/sipxconfig/site/admin/ldap/LdapServer.java
Failed to merge in the changes.Patch failed at 0001 XX-6279: Import contact information from LDAP
When you have resolved this problem run "git rebase --continue".If you would prefer to skip this patch, instead run "git rebase --skip".
To restore the original branch and stop rebasing run "git rebase --abort".
[user@localhostsipxecs]$ git add sipXconfig/neoconf/src/org/sipfoundry/sipxconfig/bulk/csv/Index.java
[user@localhostsipxecs]$ git add sipXconfig/neoconf/test/org/sipfoundry/sipxconfig/bulk/ldap/UserMapperTest.java
[user@localhostsipxecs]$ git rebase --continue

git format-patch master -o <output directory>

[user@localhostsipxecs]$ git format-patch master -o /home/mirceac/patches/
/home/mirceac/patches/0001-UC-TEST-Patch-title.patch
[user@localhostsipxecs]$

git checkout sipXconfig/neoconf/etc/freeswitch/freeswitch.xml

Working with GIT repository in remote mode

The work in remote mode introduces a new term: upstream

Basically we will have:

  1. upstream repository is git-hub Douglas's repository
  2. origin your git-hub repository after forking
  3. local is your local copy of your origin repository

Essentially, there are not big differences but you have to be aware that you are working now with three repositories. What is nice working in remote mode is that all your work will be stored on git-hub, you can create your own branches to keep any experimental/prototyping work you may want and in the same time to share it with everyone on git-hub

In order to set-up such environment follow below steps
  1. Create an account on git-hub and add open-source repository (free)
  2. From git-hub project page, fork Douglas's project into your own repository
  3. Create ssh keys on both sides: local and on your git account(to prepare your local clone):  http://www.question-defense.com/2009/02/04/add-a-ssh-key-to-your-github-account-for-a-linux-server
  4. Clone your project in read/write mode
    NOTE: Use: ssh-add ~/.ssh/id_rsa if you cannot get sources in read-write mode after adding ssh key
    Commands:
  git clone git@github.com:mirceac/sipxecs.git
  //At this point you have tracked only your repository (origin)
  git remote (or git remote -v)
  return: origin

Track upstream remote repository (Douglas's):

   git remote add upstream git://github.com/dhubler/sipxecs.git (note the read-only url, there is no chance to write on upstream)
   git remote
   return: origin
           upstream
In order to keep in sync the upstream repository and origin repository (yours)
git checkout master //move to master branch
git fetch upstream //get latest code from upstream
git rebase upstream/master //rebase your local master branch repository with upstream
git status //to verify if your local branch has something that needs to be pushed to origin
git push origin +: //push on origin

NOTE: In order to automatically update a specific branch (master),
instead of git fetch upstream it is recommended to use:
git pull upstream master
This command will automatically align your master branch with the upstream master performing automatic rebase

NOTE: +: means that during rebase you may need to do some manual merging and your local git history may become different than origin git history and you need force push

Assuming that you developed on branch TEST, follow below steps to push them on origin

  1. Perform any commit/rebase operation as explained above
  2. Merge changes on your local master repository
  3. Push your master repo on origin

   Commands:

git checkout master  //move to master branch
git rebase TEST //push TEST changes on top of your master branch
git push origin +: //push your local master branch on origin

Send your changes upstream: From your project's page, click the "pull request" button

The upstream owner may accept or may reject your commit

Some documentation links:

http://git-scm.com/

http://help.github.com/forking/
http://stackoverflow.com/questions/67699/how-do-i-clone-all-remote-branches-with-git
http://www.question-defense.com/2009/02/04/add-a-ssh-key-to-your-github-account-for-a-linux-server
http://www.kernel.org/pub/software/scm/git/docs/git-merge.html

More tips

There is several git GUIs - if you use Gnome giggle is a good choice

yum install giggle
giggle &

If you encounter problems when rebasing or merging 'git mergetool' command can be used to launch graphical 3-way merging tool. Make sure that you run it from the root of your git repository.

git rebase master

  1. ... reports merge conflicts
    git mergetool
  2. launches your favorite merge tool (meld in my case)
  3. after you merge all conflicting changes
    git rebase --continue

'checkout' and 'status' are probably 2 most commonly used commands. To add svn-like aliases for them:

git config --global alias.co checkout
git config --global alias.st status

And now you can use those aliases, 'st' and 'co' instead of the fully spelled out keywords:

git st # instead of git status
git co master # instead of git checkout master

Enable colorized output for various commands:

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

If you use bash, use git-completion.bash. It enables simply pressing: <TAB> to display a list of potential commands, arguments and parameters. For example: 

git checkout <TAB>

will show the list of branches.

Source it in your ~/.bashrc:

. /path-to/git-completion.bash

To have the current branch appear on your bash prompt:

export PS1='[xecsdev:\u@\h`__git_ps1` \W]\$ '

If you want to roll back to a particular point in history ( say some feature that is currently broken, but formerly worked a week ago and is blocking your progress ): Look at your git repository using giggle. You will see each commit has a global UUID. You can pick out the specific point in history when the world still looked rosy by doing:

git checkout -b proxy-still-worked UUID