====== Importing Modules With Full History Into Git ======

Here is how you can import a kamailio module with full history (that means all
previous commits done on the svn will also be visible in git) into the
sip-router git repository.

First off, make sure you have a local copy of the sip-router git repository
with kamailio history merged into it. You can find a step-by-step guide 
[[git:gitconfig|here]].

I suppose that the module you want to import into the git repository will be
based on the sources present in the kamailio svn trunk, so as the next step
create a new branch based on the kamailio trunk:
<code>
$ git co -b sqlops_filtered km/trunk
</code>
The name of the new branch is sqlops_filtered because I am importing kamailio
sqlops module, "_filtered" because this branch will be used to filter commits.

Like revision numbers in svn (and unlike versions in cvs), git commits,
identified by those cryptic sha1 hashes, record the state of __all__ files in
the source tree at the time when the commit was made. But this is a problem
because we only one to import the files in ''modules/sqlops'' directory and ignore
all other files outside this directory. Even if you try to checkout an older
commit which changed only files within modules/sqlops, you always get a full
source tree, including files of all other modules. There is no way you can get
a particular revision of selected files only--like you can do it with cvs.

But there is a solution: ''git-filter-branch''. This is a handy git command which
(among other things) can walk through all commits in the history of the
current branch and tranform the commits into new commits with selected files
only. To include only files in modules/sqlops we can do the following:
<code>
$ git-filter-branch --subdirectory-filter modules/sqlops
</code>
The command rewrite the history of the current branch, your current branch
should be "sqlops_filtered" if you followed this guide from the beginning. If
you investigate the history of the branch with git log, you should see only
commits that are related to files in ''modules/sqlops''. (The module contained
only one commit at the time of writing of this memo so don't be surprised if
you only see one commit in the history).

If you examine your current working directory now, you'll notice that the
directory contains files from ''modules/sqlops'' in the top level directory. We
need to put them back into modules/sqlopts before we can merge the branch into
sip-router tree, this can be done with ''git-filter-branch'' again. But before we
can run the command second time, we need to remove some residual files from
the previous run:
<code>
$ rm -rf .git/refs/original
</code>
And the following command will move all the files back to ''modules/sqlops''
subdirectory:
<code>
$ git-filter-branch --index-filter 'git ls-files -s |
   sed "s-\t-&modules/sqlopt/-" |
   GIT_INDEX_FILE=$GIT_INDEX_FILE.new git update-index --index-info &&
   mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD
</code>
The previous command might look a little scary, but it is documented in ''man
git-filter-branch'' if you are interested in details.

If you examine your current working directory now, it should contain modules
directory with sqlops subdirectory and all the module files there. This branch
is now ready to be merged into the sip-router tree, so create a new branch,
for example sqlops, based on the sip-router master branch:
<code>
$ git co -b sqlops sr/master
</code>
And now you can merge branch ''sqlops_filtered'' into the newly created branch:
<code>
$ git merge sqlops_filtered
</code>
And if everything went well, congratulations, you successfully imported your
first kamailio module into the sip-router git repository. Branch
"sqlops_filtered" is no more needed so you can safely delete it.