From 401dbc8428fd5d2d85af0f75d094a6483b466e7a Mon Sep 17 00:00:00 2001 From: Tzafrir Cohen Date: Wed, 23 Jun 2010 12:10:58 +0300 Subject: A basic document to clone and use Asterisk from git --- git-howto | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 git-howto diff --git a/git-howto b/git-howto new file mode 100644 index 0000000..fe42cc4 --- /dev/null +++ b/git-howto @@ -0,0 +1,186 @@ +Asterisk-Tools GIT HOWTO +======================== +Tzafrir Cohen + +http://gitorious.org/asterisk-tools includes a partial git mirror of the +various Subversion project in svn.asterisk.org, as well as the tools +to help them. + +This document explains how to use this mirror and how to create your own +mirror local git mirror of Asterisk SVN repository [Not written yet, see +other partial documents here]. + +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. + + +The Gitorious Repo +------------------ + +Setup +^^^^^ +This document assumes you clone both this small repository (asterisk-tools) +and the repository or repositories you want to work on under the same +top-level directory. Say, $HOME/git . It also assumes you have git +installed. This normally requires installing a package called 'git-core' +through your package manager. + + mkdir git + cd git + git clone http://git.gitorious.org/asterisk-tools/asterisk-tools.git + +This copies the small asterisk-tools repository. Once this is done, +you'll have the subdirectory 'asterisk-tools'. Now let's try to fetch a +small repository from there. One that will not require preparing too much +coffee to wait for its download: + + git clone http://git.gitorious.org/asterisk-tools/libpri.git + # It was downloaded to 'libpri' . We still need to do some fixes: + cd libpri + ../asterisk-tools/setup libpri + +You should repeat the same for each repository you want to work on. +For Asterisk it would be: + + git clone http://git.gitorious.org/asterisk-tools/asterisk.git + cd libpri + ../asterisk-tools/setup asterisk + +and the download would take much longer. For dahdi-linux you'd also need +to clone octapi.git, though no extra setup is needed for octapi. + +Now you can work as usual. The original Subversion branches can be +displayed as "remote branches": + + git/libpri$ git branch -r + origin/HEAD -> origin/svn_1.4 + origin/svn_1.0 + origin/svn_1.2 + origin/svn_1.4 + origin/svn_branch-1.4 + origin/svn_trunk + origin/svn_v1-0 + origin/svn_v1-2 + +Tags are created for each subversion tag. Note however that in the +Asterisk repository "tags" are really branches. They may change. In +fact, a release almost always changes after the tag is created (the +changelog). So expect tags to change. And don't rely on 'git describe' +to be able to use tags in any meaningful way. + + git/libpri$ git tag -l + ... + v1.4.2 + v1.4.3 + v1.4.4 + v1.4.5 + ... + + +Updating +^^^^^^^^ + # better checkout master first + git pull + git pull -t + + +Usage +^^^^^ +Creating a feature branch: + + git checkout -b cool_feature origin/svn_1.4 + +Once you're done, commit your changes, and generate patches using either +'git diff' or 'git format-patch'. + + +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: + + 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 + +Some useful commands: + + 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. + +For more information, see the man page gittutorial as well as +http://git-scm.com/documentation + + +Pros and Cons +------------- +===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. Rebasing your changes vs. the current trunk also also much + simpler. + +===Limitations: +svn:externals:: + This repository attempts to work around the places where svn:external + is used to link together two repositories. git submodules may work + better, but they are more complicated to set up and maintain. The + workarounds are, well, ugly. + +Version Number:: + We can't easily figure out a number equivalent to "version number" / SVN + branch + SVN Revision. As mentioend earlier, 'git describe' is not usable + as there are no tags in the branching points of the version "tags". + +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. -- cgit v1.2.3