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 locally
A developer should be aware of three things in order to locally work with GIT repositories:
- Download source code from the repository
- Make your changes
- 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:
[mirceac@decebal ~]$ mkdir work [mirceac@decebal ~]$ cd work [mirceac@decebal work]$ 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. [mirceac@decebal work]$ 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-4.2 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-4.2 visible and be positioned on it
git checkout -b master-4.2 origin/master-4.2
Watch the following code-snipped to accomplish this
Example:
[mirceac@decebal sipxecs]$ git branch * master [mirceac@decebal sipxecs]$ git branch -a * master remotes/origin/HEAD -> origin/master remotes/origin/master remotes/origin/master-4.2 remotes/origin/release-4.2 [mirceac@decebal sipxecs]$ git checkout -b master-4.2 origin/master-4.2 Branch master-4.2 set up to track remote branch master-4.2 from origin. Switched to a new branch 'master-4.2' [mirceac@decebal sipxecs]$ git status # On branch master-4.2 nothing to commit (working directory clean) [mirceac@decebal sipxecs]$ git branch master * master-4.2 [mirceac@decebal sipxecs]$
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-4.2 branch follow the steps from below:
ATTENTION: do not make any change or commit on master-4.2 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-4.2 //move to master-4.2 branch, because we want to base our work on this git rebase origin/master-4.2 //rebase your master-4.2 branch with the origin master-4.2 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:
[mirceac@decebal sipxecs]$ git checkout master-4.2 Switched to branch 'master-4.2' [mirceac@decebal sipxecs]$ git status # On branch master-4.2nothing to commit (working directory clean) [mirceac@decebal sipxecs]$ git rebase origin/master-4.2 Current branch master-4.2 is up to date. [mirceac@decebal sipxecs]$ git status # On branch master-4.2 nothing to commit (working directory clean) [mirceac@decebal sipxecs]$ git checkout -b TEST Switched to a new branch 'TEST' [mirceac@decebal sipxecs]$ git status # On branch TEST nothing to commit (working directory clean) [mirceac@decebal sipxecs]$ ****after all your changes are done**** [mirceac@decebal sipxecs]$ 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") [mirceac@decebal sipxecs]$ git commit -a [TEST 747365d] UC-TEST: Patch title 1 files changed, 1 insertions(+), 1 deletions(-) [mirceac@decebal sipxecs]$ 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-4.2 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-4.2 //move to master-4.2 branch, because we want to base our work on this git rebase origin/master-4.2 //rebase your master-4.2 branch with the origin master-4.2 branch just to keep in sync with the latest source code git checkout TEST //move to your branch git rebase master-4.2 //keep in sync your branch
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". [mirceac@decebal sipxecs]$ git add sipXconfig/neoconf/src/org/sipfoundry/sipxconfig/bulk/csv/Index.java [mirceac@decebal sipxecs]$ git add sipXconfig/neoconf/test/org/sipfoundry/sipxconfig/bulk/ldap/UserMapperTest.java [mirceac@decebal sipxecs]$ git rebase --continue