A basic document to clone and use Asterisk from git

1 files changed, 186 insertions, 0 deletions

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 <tzafrir.cohen@xorcom.com>
+
+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<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
+
+Some useful commands:
+
+  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.
+
+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.