[svn-commits] lmadsen: trunk r225483 - in /trunk/include/asterisk: ./ doxygen/
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Thu Oct 22 16:28:49 CDT 2009
Author: lmadsen
Date: Thu Oct 22 16:28:44 2009
New Revision: 225483
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=225483
Log:
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)
Added:
trunk/include/asterisk/doxygen/asterisk-git-howto.h (with props)
Modified:
trunk/include/asterisk/doxyref.h
Added: trunk/include/asterisk/doxygen/asterisk-git-howto.h
URL: http://svnview.digium.com/svn/asterisk/trunk/include/asterisk/doxygen/asterisk-git-howto.h?view=auto&rev=225483
==============================================================================
--- trunk/include/asterisk/doxygen/asterisk-git-howto.h (added)
+++ trunk/include/asterisk/doxygen/asterisk-git-howto.h Thu Oct 22 16:28:44 2009
@@ -1,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/>
+ */
Propchange: trunk/include/asterisk/doxygen/asterisk-git-howto.h
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: trunk/include/asterisk/doxygen/asterisk-git-howto.h
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: trunk/include/asterisk/doxygen/asterisk-git-howto.h
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: trunk/include/asterisk/doxyref.h
URL: http://svnview.digium.com/svn/asterisk/trunk/include/asterisk/doxyref.h?view=diff&rev=225483&r1=225482&r2=225483
==============================================================================
--- trunk/include/asterisk/doxyref.h (original)
+++ trunk/include/asterisk/doxyref.h Thu Oct 22 16:28:44 2009
@@ -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
More information about the svn-commits
mailing list