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 */