Thu Apr 16 06:48:10 2015

Asterisk developer's documentation


How to setup a local GIT mirror of the Asterisk SVN repository

Note:
The information contained on this page may be out of date. To make sure you get the most current information, please make sure that you are using the documentation generated from Asterisk trunk.

Introduction

This document will instruct you how to setup a local git mirror of the Asterisk SVN repository.

Why would you want that? for starters, it's a fast repository browser and works well even when offline. More on why and why not at 'Pros and Cons' in the end of this document.


Setup

Make sure you have the package

  git-svn
 

installed. It is part of the standard git distribution and included in any recent Linux distribution.

Next, get the files from this repository:

  git clone http://git.tzafrir.org.il/git/asterisk-tools.git
 

Which will create the subdirectory 'asterisk-tools' under your working directory. For the purpose of this HOWTO I assume that you will later download Asterisk under the same directory.

Now let's get Asterisk:

  git svn clone -s http://svn.digium.com/svn/asterisk
 

This will download the whole /trunk , /tags and /branches hirarchies to a new git repository under asterisk/ . This will take a L O N G time. In the order of magnitude of a day. If it stops in the middle:

  # cd asterisk; git svn fetch --fetch-all
 

All commands as of this point are run from the newly-created subdirectory 'asterisk'

  cd asterisk
 

Next make your repository more compact:

Note:
FIXME: I now get a .git subdirectory of the size of 135MB. This seems overly large considering what I got a few monthes ago.
  git repack -a
 

Now fix the menuselect bits. One possible venue is to use submodules. This would require setting a separate menuselect repository . And fixing the submodule references in every new tag to point to the right place. I gave up at this stage, and instead reimplememented menuselect

  cp -a ../asterisk-tools/menuselect menuselect
  make -C menuselect dummies
  chmod +x menuselect/menuselect
 

Next thing to do is ignore generated files. .gitignore is somewhat like svn:ignore . Though it is possible to use one at the top directory. Hence I decided to make it ignore itself as well:

  cp ../asterisk-tools/asterisk_gitignore .gitignore
 

Now let's generate tags that will point to the tags/* branches. e.g. tag 'v1.4.8' will point to the head of branch tags/1.4.8 . If you don't like the extra 'v', just edit the sed command.

  ../asterisk-tools/update-tags
 

Example configuration (refer to menuselect/menuselelct for more information). For instance: res_snmp breaks building 1.4 from git:

  echo 'exclude res_snmp' >build_tools/conf
 


Update

The main Asterisk repository tends to get new commits occasionally. I suppose you want those updates in your local copy. The following command should normally be done from the master branch. If you actually use branches, it is recommended to switch to it beforehand:

  git checkout master
 

Next, get all updates.


Usage

If you use git from the command-line, it is highly recommended to enable programmable bash completion. The git command-line is way more complex than svn, but the completion makes it usable:

  asterisk$ git show v1.2.28<tab><tab>
  v1.2.28     v1.2.28.1

  asterisk$ git show v1.2.28:c<tab><tab>
  callerid.c     channel.c      cli.c          coef_out.h     contrib/
  cdr/           channels/      codecs/        config.c       cryptostub.c
  cdr.c          chanvars.c     coef_in.h      configs/       cygwin/

  asterisk$ git svn<tab><tab>
  clone            fetch            log              set-tree
  commit-diff      find-rev         propget          show-externals
  create-ignore    info             proplist         show-ignore
  dcommit          init             rebase

  asterisk$ git svn rebase --f
  --fetch-all       --follow-parent
 

Some useful commands:

  git svn rebase --fetch-all # pull updates from upstream
  man git-FOO                # documentation for 'git FOO'
  # <tree> is any place on graph of branches: HEAD, name of a branch or
  # a tag, commit ID, and some others
  git show <tree>            # The top commit in this tree (log + diff)
  git show <tree>:directory  # directory listing
  git show <tree>:some/file  # get that file
  git log <tree>             # commit log up to that point
  git branch                 # shows local branches and in which one you are
  git branch -r              # List remote branches. Such are SVN ones.
 

For more information, see the man page gittutorial as well as

  git svn rebase --fetch-all
 


Pros and Cons

The Good

Working off-line: If you want to be able to use 'svn log' and 'svn diff' to a different branch, now you can.

Efficient repository browser: With git you can effectively browse commit logs and working copies of various branches. In fact, using it merely as a logs and versions browser can be useful on its own.

Branches really work: With SVN merging a branch is complicated. Partially because lack of separate merge tracking.With git you don't need the extra svnmerge: changes that don't collide with your branch merge in a quick merge operation.

Limitations

svn:externals : does not really work well with git-svn (and similar systems: svk, bzr-svn and hg-svn). Git has something called submodules that allows emulating the basic functionality of svn:externals, but is not as transparent.

Commiting: Not sure how safe it is to commit from such a copy. In most places I see that it is not recommended to commit directly from git-svn. OTOH, git has some tools that make it easy to prepare a patch set out of a branch (e.g. git format-patch).

IIRC there are also some issues for git-svn with https certificate authentication in the first place.

Tags: /tags are branches. SVN tags are really branches that we pretend not to change. And in fact in Asterisk we practically do change. But see workaround below to generate tags from the tag branches.

/team branches:: At least with git 1.5.x you can't easily follow all the team branches. This is due to a bug in their handling of wildcards in branches description. I believe this has been resolved in 1.6 but I didn't get to test that. Even if it will, it will require an extra step of manual editing.



Generated on Thu Apr 16 06:48:10 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6