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