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

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