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