From 681ec868370ab6c4606eafaa770fba298ca7e727 Mon Sep 17 00:00:00 2001 From: Leif Madsen Date: Thu, 22 Oct 2009 21:28:44 +0000 Subject: [PATCH] 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 | 237 ++++++++++++++++++ include/asterisk/doxyref.h | 1 + 2 files changed, 238 insertions(+) create mode 100644 include/asterisk/doxygen/asterisk-git-howto.h diff --git a/include/asterisk/doxygen/asterisk-git-howto.h b/include/asterisk/doxygen/asterisk-git-howto.h new file mode 100644 index 0000000000..ee35b76f34 --- /dev/null +++ b/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 + * + *
+ * + * \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. + *
+ * + * \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 + * + *
+ * + * \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. + *
+ * + * \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 + v1.2.28 v1.2.28.1 + + asterisk$ git show v1.2.28:c + 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 + 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' + # is any place on graph of branches: HEAD, name of a branch or + # a tag, commit ID, and some others + git show # The top commit in this tree (log + diff) + git show :directory # directory listing + git show :some/file # get that file + git log # 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 + * + *
+ * + * \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. + * + *
+ */ diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index 2c1d3b1f8c..3cbe21a359 100644 --- a/include/asterisk/doxyref.h +++ b/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