Add Asterisk Git HowTo documentation.

Added documentation on how to create a local git repository from
SVN. This documentation was added via doxygen.


(closes issue #15814)
Reported by: tzafrir
Patches:
      git-asterisk-howto uploaded by tzafrir (license 46)

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@225483 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/doxygen/asterisk-git-howto.h

@@ -0,0 +1,237 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 1999 - 2009, Digium, Inc.
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*!
+ * \file
+ */
+
+/*!
+ * \page AsteriskGitHowto How to setup a local GIT mirror of the Asterisk SVN repository
+ *
+ * \AsteriskTrunkWarning
+ *
+ * <hr/>
+ *
+ * \section Introduction Introduction
+ * This document will instruct you how to setup a local git mirror of the 
+ * Asterisk SVN repository.
+ * 
+ * Why would you want that? for starters, it's a fast repository browser
+ * and works well even when offline. More on why and why not at 'Pros and Cons'
+ * in the end of this document. 
+ * <hr/>
+ *
+ * \section Setup Setup
+ *
+ * Make sure you have the package
+ *
+ \verbatim
+  git-svn
+ \endverbatim
+ *
+ * installed. It is part of the standard git distribution and included in
+ * any recent Linux distribution.
+ *
+ * Next, get the files from this repository: 
+ *
+ \verbatim
+  git clone http://git.tzafrir.org.il/git/asterisk-tools.git
+ \endverbatim
+ *
+ * Which will create the subdirectory 'asterisk-tools' under your working 
+ * directory. For the purpose of this HOWTO I assume that you will later 
+ * download Asterisk under the same directory.
+ * 
+ * Now let's get Asterisk:
+ * 
+ \verbatim
+  git svn clone -s http://svn.digium.com/svn/asterisk
+ \endverbatim
+ * 
+ * This will download the whole /trunk , /tags and /branches hirarchies
+ * to a new git repository under asterisk/ .
+ * This will take a   L  O  N  G   time. In the order of magnitude of a
+ * day. If it stops in the middle:
+ *
+ \verbatim
+  # cd asterisk; git svn fetch --fetch-all
+ \endverbatim
+ *
+ * All commands as of this point are run from the newly-created subdirectory
+ * 'asterisk'
+ *
+ \verbatim
+  cd asterisk
+ \endverbatim
+ *
+ * Next make your repository more compact:
+ * 
+ * \note FIXME: I now get a .git subdirectory of the size of 135MB. This seems
+ *       overly large considering what I got a few monthes ago.
+ *
+ \verbatim
+  git repack -a
+ \endverbatim
+ *
+ * Now fix the menuselect bits. One possible venue is to use submodules.
+ * This would require setting a separate menuselect repository . And
+ * fixing the submodule references in every new tag to point to the right
+ * place. I gave up at this stage, and instead reimplememented menuselect
+ *
+ \verbatim
+  cp -a ../asterisk-tools/menuselect menuselect
+  make -C menuselect dummies
+  chmod +x menuselect/menuselect
+ \endverbatim
+ * 
+ * Next thing to do is ignore generated files. .gitignore is somewhat
+ * like svn:ignore . Though it is possible to use one at the top
+ * directory. Hence I decided to make it ignore itself as well:
+ *
+ \verbatim
+  cp ../asterisk-tools/asterisk_gitignore .gitignore
+ \endverbatim
+ * 
+ * Now let's generate tags that will point to the tags/* branches.
+ * e.g. tag 'v1.4.8' will point to the head of branch tags/1.4.8 .
+ * If you don't like the extra 'v', just edit the sed command.
+ *
+ \verbatim
+  ../asterisk-tools/update-tags
+ \endverbatim
+ * 
+ * Example configuration (refer to menuselect/menuselelct for more
+ * information). For instance: res_snmp breaks building 1.4 from git:
+ *
+ \verbatim
+  echo 'exclude res_snmp' >build_tools/conf
+ \endverbatim
+ *
+ * <hr/>
+ *
+ * \section Update Update
+ * The main Asterisk repository tends to get new commits occasionally. I
+ * suppose you want those updates in your local copy. The following command
+ * should normally be done from the master branch. If you actually use branches, 
+ * it is recommended to switch to it beforehand:
+ *
+ \verbatim
+  git checkout master
+ \endverbatim
+ *
+ * Next, get all updates.
+ * <hr/>
+ *
+ * \section Usage Usage
+ *
+ * If you use git from the command-line, it is highly recommended to enable
+ * programmable bash completion. The git command-line is way more complex
+ * than svn, but the completion makes it usable:
+ *
+ *
+ \verbatim
+  asterisk$ git show v1.2.28<tab><tab>
+  v1.2.28     v1.2.28.1
+
+  asterisk$ git show v1.2.28:c<tab><tab>
+  callerid.c     channel.c      cli.c          coef_out.h     contrib/
+  cdr/           channels/      codecs/        config.c       cryptostub.c
+  cdr.c          chanvars.c     coef_in.h      configs/       cygwin/
+
+  asterisk$ git svn<tab><tab>
+  clone            fetch            log              set-tree
+  commit-diff      find-rev         propget          show-externals
+  create-ignore    info             proplist         show-ignore
+  dcommit          init             rebase
+
+  asterisk$ git svn rebase --f
+  --fetch-all       --follow-parent
+ \endverbatim
+ * 
+ * Some useful commands:
+ *
+ \verbatim
+  git svn rebase --fetch-all # pull updates from upstream
+  man git-FOO                # documentation for 'git FOO'
+  # <tree> is any place on graph of branches: HEAD, name of a branch or
+  # a tag, commit ID, and some others
+  git show <tree>            # The top commit in this tree (log + diff)
+  git show <tree>:directory  # directory listing
+  git show <tree>:some/file  # get that file
+  git log <tree>             # commit log up to that point
+  git branch                 # shows local branches and in which one you are
+  git branch -r              # List remote branches. Such are SVN ones.
+ \endverbatim
+ *
+ * For more information, see the man page gittutorial as well as
+ * \arg http://git-scm.com/documentation
+ *
+ \verbatim
+  git svn rebase --fetch-all
+ \endverbatim
+ *
+ * <hr/>
+ *
+ * \section ProsAndCons Pros and Cons
+ *
+ * \subsection TheGood The Good
+ *
+ * Working off-line:
+ *  If you want to be able to use 'svn log' and 'svn diff' to a different
+ *  branch, now you can.
+ *
+ * Efficient repository browser:
+ *  With git you can effectively browse commit logs and working copies of
+ *  various branches. In fact, using it merely as a logs and versions
+ *  browser can be useful on its own.
+ *
+ * Branches really work:
+ *  With SVN merging a branch is complicated. Partially because lack of
+ *  separate merge tracking.With git you don't need the extra svnmerge:
+ *  changes that don't collide with your branch merge in a quick merge
+ *  operation.
+ *
+ * \subsection Limitations Limitations
+ * 
+ * svn:externals :
+ *  does not really work well with git-svn (and similar systems: svk,
+ *  bzr-svn and hg-svn). Git has something called submodules that allows
+ *  emulating the basic functionality of svn:externals, but is not as
+ *  transparent.
+ *
+ * Commiting:
+ *  Not sure how safe it is to commit from such a copy. In most places I
+ *  see that it is not recommended to commit directly from git-svn. OTOH,
+ *  git has some tools that make it easy to prepare a patch set out of a
+ *  branch (e.g. git format-patch).
+ *
+ *  IIRC there are also some issues for git-svn with https certificate
+ *  authentication in the first place.
+ *
+ * Tags:
+ *  /tags are branches. SVN tags are really branches that we pretend not
+ *  to change. And in fact in Asterisk we practically do change. But see
+ *  workaround below to generate tags from the tag branches.
+ *
+ * /team branches::
+ *  At least with git 1.5.x you can't easily follow all the team branches.
+ *  This is due to a bug in their handling of wildcards in branches
+ *  description. I believe this has been resolved in 1.6 but I didn't get
+ *  to test that. Even if it will, it will require an extra step of manual
+ *  editing.
+ *
+ * <hr/>
+ */

include/asterisk/doxyref.h

@@ -38,6 +38,7 @@
  * \arg \ref ReleasePolicies : Asterisk Release and Commit Policies
  * \arg \ref Reviewboard : Reviewboard Usage and Guidelines
  * \arg \ref MantisWorkflow : Workflow Guidelines for Asterisk Open Source Issue Tracker
+ * \arg \ref AsteriskGitHowto : How to setup a local GIT mirror of the Asterisk SVN repository
  * \arg \ref AstCREDITS : A Thank You to contributors (unfortunately out of date)
  *
  * \section apisandinterfaces Asterisk APIs and Interfaces