res_rtp_asterisk.c: Fix rtp source address learning for broken clients
[asterisk/asterisk.git] / include / asterisk / doxygen / asterisk-git-howto.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2009, Digium, Inc.
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16
17 /*!
18  * \file
19  */
20
21 /*!
22  * \page AsteriskGitHowto How to setup a local GIT mirror of the Asterisk SVN repository
23  *
24  * <hr>
25  *
26  * \section Introduction Introduction
27  * This document will instruct you how to setup a local git mirror of the 
28  * Asterisk SVN repository.
29  * 
30  * Why would you want that? for starters, it's a fast repository browser
31  * and works well even when offline. More on why and why not at 'Pros and Cons'
32  * in the end of this document. 
33  * <hr>
34  *
35  * \section Setup Setup
36  *
37  * Make sure you have the package
38  *
39  \verbatim
40   git-svn
41  \endverbatim
42  *
43  * installed. It is part of the standard git distribution and included in
44  * any recent Linux distribution.
45  *
46  * Next, get the files from this repository: 
47  *
48  \verbatim
49   git clone http://git.tzafrir.org.il/git/asterisk-tools.git
50  \endverbatim
51  *
52  * Which will create the subdirectory 'asterisk-tools' under your working 
53  * directory. For the purpose of this HOWTO I assume that you will later 
54  * download Asterisk under the same directory.
55  * 
56  * Now let's get Asterisk:
57  * 
58  \verbatim
59   git svn clone -s http://svn.digium.com/svn/asterisk
60  \endverbatim
61  * 
62  * This will download the whole /trunk , /tags and /branches hirarchies
63  * to a new git repository under asterisk/ .
64  * This will take a   L  O  N  G   time. In the order of magnitude of a
65  * day. If it stops in the middle:
66  *
67  \verbatim
68   # cd asterisk; git svn fetch --fetch-all
69  \endverbatim
70  *
71  * All commands as of this point are run from the newly-created subdirectory
72  * 'asterisk'
73  *
74  \verbatim
75   cd asterisk
76  \endverbatim
77  *
78  * Next make your repository more compact:
79  * 
80  * \note FIXME: I now get a .git subdirectory of the size of 135MB. This seems
81  *       overly large considering what I got a few monthes ago.
82  *
83  \verbatim
84   git repack -a
85  \endverbatim
86  *
87  * Now fix the menuselect bits. One possible venue is to use submodules.
88  * This would require setting a separate menuselect repository . And
89  * fixing the submodule references in every new tag to point to the right
90  * place. I gave up at this stage, and instead reimplememented menuselect
91  *
92  \verbatim
93   cp -a ../asterisk-tools/menuselect menuselect
94   make -C menuselect dummies
95   chmod +x menuselect/menuselect
96  \endverbatim
97  * 
98  * Next thing to do is ignore generated files. .gitignore is somewhat
99  * like svn:ignore . Though it is possible to use one at the top
100  * directory. Hence I decided to make it ignore itself as well:
101  *
102  \verbatim
103   cp ../asterisk-tools/asterisk_gitignore .gitignore
104  \endverbatim
105  * 
106  * Now let's generate tags that will point to the tags/* branches.
107  * e.g. tag 'v1.4.8' will point to the head of branch tags/1.4.8 .
108  * If you don't like the extra 'v', just edit the sed command.
109  *
110  \verbatim
111   ../asterisk-tools/update_tags
112  \endverbatim
113  * 
114  * Example configuration (refer to menuselect/menuselelct for more
115  * information). For instance: res_snmp breaks building 1.4 from git:
116  *
117  \verbatim
118   echo 'exclude res_snmp' >build_tools/conf
119  \endverbatim
120  *
121  * <hr>
122  *
123  * \section Update Update
124  * The main Asterisk repository tends to get new commits occasionally. I
125  * suppose you want those updates in your local copy. The following command
126  * should normally be done from the master branch. If you actually use branches, 
127  * it is recommended to switch to it beforehand:
128  *
129  \verbatim
130   git checkout master
131  \endverbatim
132  *
133  * Next, get all updates.
134  * <hr>
135  *
136  * \section Usage Usage
137  *
138  * If you use git from the command-line, it is highly recommended to enable
139  * programmable bash completion. The git command-line is way more complex
140  * than svn, but the completion makes it usable:
141  *
142  *
143  \verbatim
144   asterisk$ git show v1.2.28<tab><tab>
145   v1.2.28     v1.2.28.1
146
147   asterisk$ git show v1.2.28:c<tab><tab>
148   callerid.c     channel.c      cli.c          coef_out.h     contrib/
149   cdr/           channels/      codecs/        config.c       cryptostub.c
150   cdr.c          chanvars.c     coef_in.h      configs/       cygwin/
151
152   asterisk$ git svn<tab><tab>
153   clone            fetch            log              set-tree
154   commit-diff      find-rev         propget          show-externals
155   create-ignore    info             proplist         show-ignore
156   dcommit          init             rebase
157
158   asterisk$ git svn rebase --f
159   --fetch-all       --follow-parent
160  \endverbatim
161  * 
162  * Some useful commands:
163  *
164  \verbatim
165   git svn rebase --fetch-all # pull updates from upstream
166   man git-FOO                # documentation for 'git FOO'
167   # <tree> is any place on graph of branches: HEAD, name of a branch or
168   # a tag, commit ID, and some others
169   git show <tree>            # The top commit in this tree (log + diff)
170   git show <tree>:directory  # directory listing
171   git show <tree>:some/file  # get that file
172   git log <tree>             # commit log up to that point
173   git branch                 # shows local branches and in which one you are
174   git branch -r              # List remote branches. Such are SVN ones.
175  \endverbatim
176  *
177  * For more information, see the man page gittutorial as well as
178  * \arg http://git-scm.com/documentation
179  *
180  \verbatim
181   git svn rebase --fetch-all
182  \endverbatim
183  *
184  * <hr>
185  *
186  * \section ProsAndCons Pros and Cons
187  *
188  * \subsection TheGood The Good
189  *
190  * Working off-line:
191  *  If you want to be able to use 'svn log' and 'svn diff' to a different
192  *  branch, now you can.
193  *
194  * Efficient repository browser:
195  *  With git you can effectively browse commit logs and working copies of
196  *  various branches. In fact, using it merely as a logs and versions
197  *  browser can be useful on its own.
198  *
199  * Branches really work:
200  *  With SVN merging a branch is complicated. Partially because lack of
201  *  separate merge tracking.With git you don't need the extra svnmerge:
202  *  changes that don't collide with your branch merge in a quick merge
203  *  operation.
204  *
205  * \subsection Limitations Limitations
206  * 
207  * svn:externals :
208  *  does not really work well with git-svn (and similar systems: svk,
209  *  bzr-svn and hg-svn). Git has something called submodules that allows
210  *  emulating the basic functionality of svn:externals, but is not as
211  *  transparent.
212  *
213  * Commiting:
214  *  Not sure how safe it is to commit from such a copy. In most places I
215  *  see that it is not recommended to commit directly from git-svn. OTOH,
216  *  git has some tools that make it easy to prepare a patch set out of a
217  *  branch (e.g. git format-patch).
218  *
219  *  IIRC there are also some issues for git-svn with https certificate
220  *  authentication in the first place.
221  *
222  * Tags:
223  *  /tags are branches. SVN tags are really branches that we pretend not
224  *  to change. And in fact in Asterisk we practically do change. But see
225  *  workaround below to generate tags from the tag branches.
226  *
227  * /team branches::
228  *  At least with git 1.5.x you can't easily follow all the team branches.
229  *  This is due to a bug in their handling of wildcards in branches
230  *  description. I believe this has been resolved in 1.6 but I didn't get
231  *  to test that. Even if it will, it will require an extra step of manual
232  *  editing.
233  *
234  * <hr>
235  */