documents based on my mailing list posts

2 files changed, 148 insertions, 0 deletions

diff --git a/git-asterisk-howto b/git-asterisk-howto
new file mode 100644
index 0000000..3d34a8c
--- /dev/null
+++ b/git-asterisk-howto
@@ -0,0 +1,130 @@
+Asterisk GIT HOWTO
+==================
+Tzafrir Cohen <tzafrir.cohen@xorcom.com>
+
+
+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. 
+
+Setup
+-----
+Make sure you have the package
+
+  git-svn
+
+installed. It is part of the standard git distribution and included in
+any recent Linux distribution.
+
+Next, get the files from this repository: 
+
+  git clone http://git.tzafrir.org.il/git/asterisk-tools.git
+
+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:
+
+  git svn clone -s http://svn.digium.com/svn/asterisk
+
+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:
+
+  #cd asterisk; git svn fetch --fetch-all
+
+All commands as of this point are run from the newly-created subdirectory
+'asterisk'
+
+  cd asterisk
+
+Next make your repository more compact:
+
+FIXME: I now get a .git subdirectory of the size of 135MB . This seems
+overly large considering what I got a few monthes ago
+
+  git repack -a
+
+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
+
+  cp -a ../asterisk-tools/menuselect menuselect
+  make -C menuselect dummies
+  chmod +x menuselect/menuselect
+
+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:
+
+  cp ../asterisk-tools/asterisk_gitignore .gitignore
+
+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.
+
+  ../asterisk-tools/update-tags
+
+Example configuration (refer to menuselect/menuselelct for more
+information). For instance: res_snmp breaks building 1.4 from git:
+
+  echo 'exclude res_snmp' >build_tools/conf
+
+
+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:
+
+  git checkout master
+
+Next: get all updates:
+
+  git svn rebase --fetch-all
+
+
+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:
+
+  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
diff --git a/git-dahdi-tools-howto b/git-dahdi-tools-howto
new file mode 100644
index 0000000..c71f0fd
--- /dev/null
+++ b/git-dahdi-tools-howto
@@ -0,0 +1,18 @@
+Basically the same as the asterisk HOWTO.
+
+Changes:
+
+Initial clone is:
+
+  git svn clone -s http://svn.digium.com/svn/dahdi/tools dahdi-tools
+
+The .gitignore file is:
+
+  cp ../asterisk-tools/dahdi-tools_gitignore .gitignore
+
+And most importantly: cheating and not using menuselect at all:
+
+  mkdir menuselect
+  cp ../asterisk-tools/menuselect/Makefile menuselect
+  ln -s /bin/true menuselect/menuselect
+