====== Hacking SIP-ROUTER with Git ======


====== SIP-ROUTER Git Repository ======
The Git repository for **sip-router** is available through HTTP, SSH,
the proprietary Git protocol and CVS. The HTTP and Git access methods
provide only read-only access to the repository, that means you will
be able to check out your own copy of the repository, but you will not
be able to push your changes back.

To clone the repository using Git protocol do (recommended for
read-only access):
<code>
git clone git://git.sip-router.org/sip-router
</code>

To clone the repository using HTTP do:
<code>
git clone http://git.sip-router.org/sip-router
</code>

If you have write access to the repository and access to the git host
then you can checkout the repository using ssh:
<code>
git clone ssh://username@git.sip-router.org/sip-router
</code>
where username is your username on host git.sip-router.org. Please see
also [[git:quick-start-guide|GIT Quick Start Guide]] if you plan to commit
changes.

After "cloning" the repository the default branch that is checked out is **master**.
Right now there are 3 important branches in the repository:
  - **master** - latest code, all the new development goes here.
  - **sr_3.0** - branch for the future sip-router 3.0 release, in process of being stabilized.
  - **kamailio_3.0** - branch for the kamailio 3.0 release (kamailio 3.0 is the first kamailio release that will be based on sip-router, in this case the sr_3.0 branch).

If you are interested in a different branch then **master**, you have to use git checkout to change the branch, e.g.:
<code>
cd sip-router
git checkout --track -b sr_3.0 origin/sr_3.0
</code>
(replace **sr_3.0** with the desired branch).
The above command will create a local **sr_3.0** branch that will track changes in the remote (repository)
 version of the same branch (**origin/sr_3.0**).
Note that as an alternative, if you have a new git version you could replace the above command and the clone command with:
<code>
git clone --branch sr_3.0 git://git.sip-router.org/sip-router
cd sip-router
</code>

You need to do all of the above only once. After you already have a "clone" you can update your local copy with the latest changes in the repository using git pull. E.g.:
<code>
git fetch origin
git pull --rebase origin sr_3.0
</code>
(replace **sr_3.0** with the branch you are on).


You can also browse the repository through the gitweb WWW interface at
http://git.sip-router.org and you can download daily snapshots from http://sip-router.org/tarballs/sr.
If you prefer you could use cvs instead of git (see below), but it will be significantly slower.

====== Repository Layout ======

The repository is setup so that you can commit only to the following
branches:
  * <your_username>/*
  * tmp/*
  * master

In general you **should not** commit to master. You should use your
own branch for work-in-progress and only when you think it's in a good
enough form (it compiles and looks stable), you should merge it to
master.

====== Commit Messages ======

Please create the commit messages following the git convention:
  * start with one short line, preferably less then 50 chars summarizing the changes
  * follow by exactly one empty line
  * then a more detailed description (if necessary), but make sure you don't have lines longer then 72 characters

Make sure you read [[devel:git-commit-guidelines]].


Example vim/gvim config additions for git commit messages:
<code>
" git commits edit
au BufNewFile,BufRead COMMIT_EDITMSG setf git
au BufNewFile,BufRead COMMIT_EDITMSG set ai tw=66
</code>

====== Commit/push HOWTO ======

Please see [[git:commit-into-master|GIT Commit into master HOWTO]].

====== Merge HOWTO ======

Please see [[git:merge-into-master|GIT Merge into master HOWTO]].

====== CVS Compatibility ======

The repository is also available through cvs for those who do not want
or cannot use git. A recent version of cvs client is needed to access
the repository. You need to have the following two environment
variable set if you want to access the repository anonymously through
the pserver method:

<code>
export CVSROOT=:pserver:anonymous@cvs.sip-router.org/sip-router
export CVS_SERVER=git-cvsserver
</code>

To checkout the source tree you need to specify the name of the
**head** (a.k.a branch) instead of the cvs module!. You can see what
branches are available in the repository in gitweb at
[[http://git.sip-router.org]] (look for heads)

The most important head names are:
  * **master** - This is the main development/unstable branch (HEAD in cvs terminology)
  * **sr_3.0** - This is the (soon to be) stable sip-router 3.0 branch.
  * **kamailio_3.0** - This is the kamailio 3.0 stable branch (based on **sr_3.0**).

So if you want to checkout the latest development version then do:
<code>
cvs co master
</code>

CVS write access is only available through ssh:
<code>
export CVSROOT=:ext:username@cvs.sip-router.org/sip-router
export CVS_SERVER=git-cvsserver

cvs co master
</code>

The cvs compatibility layer does not support tagging and branching, so
you would need to use git for that.