Wed Jan 27 20:02:04 2016

Asterisk developer's documentation


asterisk-git-howto.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2009, Digium, Inc.
00005  *
00006  * See http://www.asterisk.org for more information about
00007  * the Asterisk project. Please do not directly contact
00008  * any of the maintainers of this project for assistance;
00009  * the project provides a web site, mailing lists and IRC
00010  * channels for your use.
00011  *
00012  * This program is free software, distributed under the terms of
00013  * the GNU General Public License Version 2. See the LICENSE file
00014  * at the top of the source tree.
00015  */
00016 
00017 /*!
00018  * \file
00019  */
00020 
00021 /*!
00022  * \page AsteriskGitHowto How to setup a local GIT mirror of the Asterisk SVN repository
00023  *
00024  * \AsteriskTrunkWarning
00025  *
00026  * <hr/>
00027  *
00028  * \section Introduction Introduction
00029  * This document will instruct you how to setup a local git mirror of the 
00030  * Asterisk SVN repository.
00031  * 
00032  * Why would you want that? for starters, it's a fast repository browser
00033  * and works well even when offline. More on why and why not at 'Pros and Cons'
00034  * in the end of this document. 
00035  * <hr/>
00036  *
00037  * \section Setup Setup
00038  *
00039  * Make sure you have the package
00040  *
00041  \verbatim
00042   git-svn
00043  \endverbatim
00044  *
00045  * installed. It is part of the standard git distribution and included in
00046  * any recent Linux distribution.
00047  *
00048  * Next, get the files from this repository: 
00049  *
00050  \verbatim
00051   git clone http://git.tzafrir.org.il/git/asterisk-tools.git
00052  \endverbatim
00053  *
00054  * Which will create the subdirectory 'asterisk-tools' under your working 
00055  * directory. For the purpose of this HOWTO I assume that you will later 
00056  * download Asterisk under the same directory.
00057  * 
00058  * Now let's get Asterisk:
00059  * 
00060  \verbatim
00061   git svn clone -s http://svn.digium.com/svn/asterisk
00062  \endverbatim
00063  * 
00064  * This will download the whole /trunk , /tags and /branches hirarchies
00065  * to a new git repository under asterisk/ .
00066  * This will take a   L  O  N  G   time. In the order of magnitude of a
00067  * day. If it stops in the middle:
00068  *
00069  \verbatim
00070   # cd asterisk; git svn fetch --fetch-all
00071  \endverbatim
00072  *
00073  * All commands as of this point are run from the newly-created subdirectory
00074  * 'asterisk'
00075  *
00076  \verbatim
00077   cd asterisk
00078  \endverbatim
00079  *
00080  * Next make your repository more compact:
00081  * 
00082  * \note FIXME: I now get a .git subdirectory of the size of 135MB. This seems
00083  *       overly large considering what I got a few monthes ago.
00084  *
00085  \verbatim
00086   git repack -a
00087  \endverbatim
00088  *
00089  * Now fix the menuselect bits. One possible venue is to use submodules.
00090  * This would require setting a separate menuselect repository . And
00091  * fixing the submodule references in every new tag to point to the right
00092  * place. I gave up at this stage, and instead reimplememented menuselect
00093  *
00094  \verbatim
00095   cp -a ../asterisk-tools/menuselect menuselect
00096   make -C menuselect dummies
00097   chmod +x menuselect/menuselect
00098  \endverbatim
00099  * 
00100  * Next thing to do is ignore generated files. .gitignore is somewhat
00101  * like svn:ignore . Though it is possible to use one at the top
00102  * directory. Hence I decided to make it ignore itself as well:
00103  *
00104  \verbatim
00105   cp ../asterisk-tools/asterisk_gitignore .gitignore
00106  \endverbatim
00107  * 
00108  * Now let's generate tags that will point to the tags/* branches.
00109  * e.g. tag 'v1.4.8' will point to the head of branch tags/1.4.8 .
00110  * If you don't like the extra 'v', just edit the sed command.
00111  *
00112  \verbatim
00113   ../asterisk-tools/update-tags
00114  \endverbatim
00115  * 
00116  * Example configuration (refer to menuselect/menuselelct for more
00117  * information). For instance: res_snmp breaks building 1.4 from git:
00118  *
00119  \verbatim
00120   echo 'exclude res_snmp' >build_tools/conf
00121  \endverbatim
00122  *
00123  * <hr/>
00124  *
00125  * \section Update Update
00126  * The main Asterisk repository tends to get new commits occasionally. I
00127  * suppose you want those updates in your local copy. The following command
00128  * should normally be done from the master branch. If you actually use branches, 
00129  * it is recommended to switch to it beforehand:
00130  *
00131  \verbatim
00132   git checkout master
00133  \endverbatim
00134  *
00135  * Next, get all updates.
00136  * <hr/>
00137  *
00138  * \section Usage Usage
00139  *
00140  * If you use git from the command-line, it is highly recommended to enable
00141  * programmable bash completion. The git command-line is way more complex
00142  * than svn, but the completion makes it usable:
00143  *
00144  *
00145  \verbatim
00146   asterisk$ git show v1.2.28<tab><tab>
00147   v1.2.28     v1.2.28.1
00148 
00149   asterisk$ git show v1.2.28:c<tab><tab>
00150   callerid.c     channel.c      cli.c          coef_out.h     contrib/
00151   cdr/           channels/      codecs/        config.c       cryptostub.c
00152   cdr.c          chanvars.c     coef_in.h      configs/       cygwin/
00153 
00154   asterisk$ git svn<tab><tab>
00155   clone            fetch            log              set-tree
00156   commit-diff      find-rev         propget          show-externals
00157   create-ignore    info             proplist         show-ignore
00158   dcommit          init             rebase
00159 
00160   asterisk$ git svn rebase --f
00161   --fetch-all       --follow-parent
00162  \endverbatim
00163  * 
00164  * Some useful commands:
00165  *
00166  \verbatim
00167   git svn rebase --fetch-all # pull updates from upstream
00168   man git-FOO                # documentation for 'git FOO'
00169   # <tree> is any place on graph of branches: HEAD, name of a branch or
00170   # a tag, commit ID, and some others
00171   git show <tree>            # The top commit in this tree (log + diff)
00172   git show <tree>:directory  # directory listing
00173   git show <tree>:some/file  # get that file
00174   git log <tree>             # commit log up to that point
00175   git branch                 # shows local branches and in which one you are
00176   git branch -r              # List remote branches. Such are SVN ones.
00177  \endverbatim
00178  *
00179  * For more information, see the man page gittutorial as well as
00180  * \arg http://git-scm.com/documentation
00181  *
00182  \verbatim
00183   git svn rebase --fetch-all
00184  \endverbatim
00185  *
00186  * <hr/>
00187  *
00188  * \section ProsAndCons Pros and Cons
00189  *
00190  * \subsection TheGood The Good
00191  *
00192  * Working off-line:
00193  *  If you want to be able to use 'svn log' and 'svn diff' to a different
00194  *  branch, now you can.
00195  *
00196  * Efficient repository browser:
00197  *  With git you can effectively browse commit logs and working copies of
00198  *  various branches. In fact, using it merely as a logs and versions
00199  *  browser can be useful on its own.
00200  *
00201  * Branches really work:
00202  *  With SVN merging a branch is complicated. Partially because lack of
00203  *  separate merge tracking.With git you don't need the extra svnmerge:
00204  *  changes that don't collide with your branch merge in a quick merge
00205  *  operation.
00206  *
00207  * \subsection Limitations Limitations
00208  * 
00209  * svn:externals :
00210  *  does not really work well with git-svn (and similar systems: svk,
00211  *  bzr-svn and hg-svn). Git has something called submodules that allows
00212  *  emulating the basic functionality of svn:externals, but is not as
00213  *  transparent.
00214  *
00215  * Commiting:
00216  *  Not sure how safe it is to commit from such a copy. In most places I
00217  *  see that it is not recommended to commit directly from git-svn. OTOH,
00218  *  git has some tools that make it easy to prepare a patch set out of a
00219  *  branch (e.g. git format-patch).
00220  *
00221  *  IIRC there are also some issues for git-svn with https certificate
00222  *  authentication in the first place.
00223  *
00224  * Tags:
00225  *  /tags are branches. SVN tags are really branches that we pretend not
00226  *  to change. And in fact in Asterisk we practically do change. But see
00227  *  workaround below to generate tags from the tag branches.
00228  *
00229  * /team branches::
00230  *  At least with git 1.5.x you can't easily follow all the team branches.
00231  *  This is due to a bug in their handling of wildcards in branches
00232  *  description. I believe this has been resolved in 1.6 but I didn't get
00233  *  to test that. Even if it will, it will require an extra step of manual
00234  *  editing.
00235  *
00236  * <hr/>
00237  */

Generated on 27 Jan 2016 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1