document git 1.6 issues and AUTHORS

* With git 1.6 we have a problem with a tag that ended with '.'.
* Document using an AUTHORS file.

1 files changed, 53 insertions, 5 deletions

diff --git a/git-asterisk-howto b/git-asterisk-howto
index de887d6..8893769 100644
--- a/git-asterisk-howto
+++ b/git-asterisk-howto
@@ -19,6 +19,8 @@ Make sure you have the package
 installed. It is part of the standard git distribution and included in
 any recent Linux distribution.
 
+TODO: add a few words about gen_authors and -A ../asterisk-tools/AUTHORS
+
 Next, get the files from this repository: 
 
   git clone http://git.tzafrir.org.il/git/asterisk-tools.git
@@ -29,14 +31,22 @@ download Asterisk under the same directory.
 
 Now let's get Asterisk:
 
-  git svn clone -s http://svn.asterisk.org/svn/asterisk
+  git svn clone -r1-47393,47395:HEAD -s http://svn.asterisk.org/svn/asterisk
+
+The explicit list of revisions is intended to avoid one specific revision
+that cuases problems if you use git >= 1.6 , as it has an invalid ref
+name (a tag name that ends with a '.')
+
+See also below regarding an AUTHORS file if you want revisions to have
+proper names and emails in the Author field. Not required, but will
+provide you with a nicer log.
 
 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
+  #cd asterisk; git svn fetch -r1-47393,47395:HEAD --fetch-all
 
 All commands as of this point are run from the newly-created subdirectory
 'asterisk'
@@ -45,10 +55,11 @@ All commands as of this point are run from the newly-created subdirectory
 
 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
+FIXME: I now get a .git subdirectory of the size of 210MB . This seems
+overly large considering what I got a few monthes ago. Note that with
+git >= 1.6 this is already done automatically.
 
-  git repack -a
+  git repack -ad
 
 Now fix the menuselect bits. One possible venue is to use submodules.
 This would require setting a separate menuselect repository . And
@@ -65,6 +76,9 @@ directory. Hence I decided to make it ignore itself as well:
 
   cp ../asterisk-tools/asterisk_gitignore .gitignore
 
+  # To also keep proper email of authors, as above:
+  git config --add svn.authorsfile AUTHORS
+
 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.
@@ -90,6 +104,40 @@ Next: get all updates:
   git svn rebase --fetch-all
 
 
+Author Names
+------------
+With git, every commit is normally identified by an author (with a name
+and an email). In SVN commits are only identified by a Subversion
+username. git-svn will normally just generate a dummy email from that
+username. But in many cases it would be useful to have proper name and
+email address for each username from the Subversion repository. This is
+normally done with an AUTHORS file: a file that identifies the name an
+email of every user. It has lines such as:
+
+  jond = John Doe <john_doe@example.org>
+
+The asterisk-tools repository has a script to generate such a file,
+mostly from the data in the 'authors' file in the repotools repository:
+
+  ../asterisk-tools/gen_authors >AUTHORS
+
+Note that this translation is done when revisions are fetched from the
+remote SVN repository to your local git repository. That is: for most
+revisions this happens at the time of the initial clone. Later on if you
+use 'git svn fetch' or 'git svn rebase' it will also be used. It cannot
+change the author field for revisions that were already fetched.
+
+To use it in the initial clone:
+
+  asterisk-tools/gen_authors >AUTHORS
+  git svn clone --authors-file AUTHORS -s http://svn.asterisk.org/svn/asterisk
+
+If the repository already exists, you can set the file to be used for
+further fetches:
+
+  git config --add svn.authorsfile ../AUTHORS
+
+
 Usage
 -----
 If you use git from the command-line, it is highly recommended to enable