Git Tips
From FreeSWITCH Wiki
This page is a collection of tips for how to begin as a Developer working on FreeSWITCH.
Install Git
Developers must first install git.
Initial Checkout
Read only
For most developers, you can get the latest code with:
$ git clone git://git.freeswitch.org/freeswitch.git
If you only want to obtain the v1.2.stable branch use:
$ git clone git://git.freeswitch.org/freeswitch.git $ git checkout v1.2.stable
or more simply:
$ git clone -b v1.2.stable git://git.freeswitch.org/freeswitch.git
The contrib area can be downloaded with:
$ git clone git://git.freeswitch.org/freeswitch-contrib.git
Git https via github and behind proxy
If for any reason you can't reach git://git.freeswitch.org (e.g. you are behind corporate firewalls or proxy) you could use the github mirror like this:
$ git clone https://github.com/FreeSWITCH/FreeSWITCH.git Initialized empty Git repository in /home/dev1/fstest/FreeSWITCH/.git/ error: Failed connect to github.com:443; Operation now in progress while accessing https://github.com/FreeSWITCH/FreeSWITCH.git/info/refs fatal: HTTP request failed
Than you could set your proxy like this:
$ git config --global http.proxy <yourproxy:yourport>
and it should work:
git clone https://github.com/FreeSWITCH/FreeSWITCH.git Initialized empty Git repository in /home/dev1/fstest/FreeSWITCH/.git/ ...
Read/Write
To have commit privileges, you need an ssh public key. This key is provided to the FreeSWITCH team so that they can set up your permissions.
Then, get the latest code with:
$ git clone ssh://git@git.freeswitch.org:222/freeswitch.git
Checkout setup
After you check out the code, git needs to be configured for the FreeSWITCH project:
$ cd freeswitch $ scripts/setup-git.sh
Syncing with Trunk
As the main trunk is undergoing lots of changes, you may from time to time want to pull changes from trunk into your local copy. This can allow you to pull in bug fixes, feature enhancements, etc. This is important in making that any of your changes remain compatible with the main trunk.
$ git stash $ git pull $ git stash apply
Applying a Pull Request to Your Local Repository
You may receive a request from someone to try some changes that they've made to the system. They will usually have a repository available somewhere with a branch containing the changes and provide the branch name and URL to you. This is known as a Pull Request (in industry lingo), the branch that they made the changes in is known as a Topic Branch.
For example, if they forked the code on Github, they may provide you a URL like git://github.com/username/FreeSWITCH.git ; with that URL and the name of the branch you can easily pull their changes. The best way to do this is to make a local topic branch to apply these changes to, that way you can easily blow away the branch and switch back to master if you don't like the changes.
Create a local branch and switch to it:
$ git checkout -b username-topic_branch_name
Pull the changes from the user's topic branch into yours:
$ git pull git://github.com/username/FreeSWITCH.git topic_branch_name
Your local working set will now match the user's, you can build and test the changes to your heart's content. There are two possible paths to continue from here, you didn't like the changes and want to get rid of the new branch, or you liked them and want to push them to the main repository.
To delete your local branch just switch back to master and then delete the topic branch:
$ git checkout master $ git branch -D username-topic_branch_name
If you like the changes you can merge them to your local master branch and the push to the public repository:
$ git checkout master $ git merge username-topic_branch_name $ git push origin master $ git branch -d username-topic_branch_name
Github Workflow
Github has put a nice website up around the pull request workflow that makes it very simple for a contributor to initiate the request, and for others to see the changes that have been made, and make comments on those changes without ever having to pull the changes to their local repository.
There are a few shortcuts you can take if the user has sent a pull request via Github. The pull request URL itself can be used to obtain a patch and apply it to your local master branch and push the changes with two easy commands. If the pull request URL is https://github.com/FreeSWITCH/FreeSWITCH/pull/2 simply append .patch to the URL to get a patch file. We can use curl to grab the patch and push it directly into our local repository with the git am command.
$ curl https://github.com/FreeSWITCH/FreeSWITCH/pull/2.patch | git am $ git push origin master
Committing changes
Add your changes to your staging area:
$ git add src/mod/asr_tts/mod_unimrcp/mod_unimrcp.c $ git add conf/autoload_configs/unimrcp.conf.xml
Diff your changes with your local repository:
$ git diff
Commit the changes in your staging area to your local repository:
$ git commit -m "w00t, git commit!"
Diff your changes with the FreeSWITCH remote repository:
$ git diff origin/HEAD
Push changes to FreeSWITCH remote repository (requires write access):
$ git push origin master
Git Bisect - Tracking down breaks and bugs extremely fast with git
If something was working or behaving correctly before but is not any more git has a great tool called bisect which can help find the issue with a binary tree search to find where it broke.
The syntax is:
git bisect start [bad_commit] [good_commit] -- [path1] [path2] ...
Where bad commit is a commit that is known to be bad (ie HEAD) and good_commit is a commit that was known to work. Optionally you can specify only a specific sub path (ie lib/) where it broke and then it will only look at commits that effected that path or other paths. An example of if you knew something broke within the last 10 commits:
git bisect start HEAD HEAD~10
Once you do that you are now in bisect mode you want to compile / test / etc try to repro the bug. Once you know if that version works or not just tell git with:
git bisect bad or git bisect good
then it will move on to the next commit for you to test. If you cannot figure out if it was bad or good use git bisect skip to move on to the next commit. Once it figures out what commit (or commits) would be possible to blame it will let you know. The great part is it is far faster than trying to do it by hand. Lets say in a worst case scenario you only know it worked 6 months ago and now its broken and there are 1000 commits inbetween then and now, you would in the worst case only have to test 11 different builds.
When you are done you can use:
git bisect reset when done
to reset back to where you were.
In addition git bisect can find the place that it first broke on its own if you have a script that can return if it works or doesn't you can use:
git bisect run [my_script] [arguments]
Note that the script (my_script in the above example) should exit with code 0 if the current source code is good, and exit with a code between 1 and 127 (inclusive), except 125, if the current source code is bad.
Then you do not need to do any testing by yourself just let git find the problem commit. Once you know the problem commit there is a far higher chance your bug report will be handled faster when you can tell the developers exactly where to work.
If You Change Code You Should Branch with Git
Git is not like most other source control systems, while branching is easy, its actually so easy that the recommended method of making feature changes is generally to branch. Branching allows you to make changes and commit them locally even though you most likely cannot commit them directly to FreeSWITCH. This also allows you to more easily preserve your changes as you upgrade FreeSWITCH. If you branch for each feature or fix you try to add to FreeSWITCH it makes submitting and updating patches far easier. Branching takes two seconds just run:
git branch [branch_name] [source_branch]
so for example:
git branch codec_g729_windows master
will create a new branch from master for your work. You can switch to a branch by doing:
git checkout [branch_name]
So git checkout master will change you back to master or git checkout codec_g729_windows will change to your branch. You do not need to commit your changes before changing branches it will save your place automatically. To update a branch after you do a git pull on master you would run:
git merge master
In your branch, most of the time git will figure out the proper merging for you without intervention.
Creating Patches with Git
Even though most FreeSWITCH users do not have commit access to the FreeSWITCH git server you should still be working in branches and committing locally changes you make. Users can then get their changes integrated into FreeSWITCH by filing jira tickets with patches of the changes. To generate a patch for a commit of your work you would do:
git format-patch -w -1 [commit_id]
You can get commit ids by looking at the "git log" or using tags. You can also just tell it to generate patches for the last 3 commits by:
git format-patch -w -3
This can then be attached to a ticket. Aside from the benefits of a normal patch a formatted patch also will give you attribution as the one who fixed it and includes some additional information to help with git merging.
Checking out previous revisions
To list commits cd to where you have cloned the git repo and type:
git log
The changelog is also available on fisheye.
Then to switch to that commit do:
git checkout ac59a2a1d67aca74895ceddbc709a467c572144b make && make install
then, if you want to go back to the master, then
git checkout master git pull make current
Note that if the revision you are trying to switch to is newer than your clone then you will need to first bring your clone up to date:
git pull
Cleaning out previous revisions
git clean -fdx
<cypromis> that will kill everythng that is not from the current git
GUIs and Utilities
There are a couple user interfaces to Git available with the Git suite. These GUIs require the tcl/tk toolkits installed.
git-gui
Portable graphical interface to Git. See the git-gui(1) man page.
$ git gui [<command>][arguments]
gitk
The git repository browser. See the gitk(1) man page.
$ gitk [<option>...][<revs>][--][<path>...]
Other cool tools
- tig - Curses-based text GUI for git
- magit - emacs addon for git. Travis Cross says it is beyond cool!
Git resources
- The Git website: http://git-scm.com/
- Git cheat sheet: http://cheat.errtheblog.com/s/git
- Git from the bottom up, very nice Git intro: http://www.newartisans.com/2008/04/git-from-the-bottom-up.html (pdf first link, second paragraph)
- Pro Git, a book on using Git that is freely available online: http://progit.org/
- Git Model: http://nvie.com/git-model
