buildr 1.3.3 → 1.3.4

data/doc/preface.textile

@@ -0,0 +1,28 @@
+---
+layout: preface
+---
+
+div(title). !{width:20em}images/buildr-hires.png!
+
+#(toc) "Getting Started":getting_started.html
+# "Projects":projects.html
+# "Building":building.html
+# "Artifacts":artifacts.html
+# "Packaging":packaging.html
+# "Testing":testing.html
+# "Settings & Profiles":settings_profiles.html
+# "Languages":languages.html
+# "More Stuff":more_stuff.html
+# "Extending Buildr":extending.html
+# "Contributing":contributing.html
+
+
+p(preface). Copyright 2007-2009 Apache Buildr
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+"http://www.apache.org/licenses/LICENSE-2.0":http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+p(preface). <blank>

data/doc/{pages/projects.textile → projects.textile}

@@ -1,6 +1,10 @@
-h1. Projects
+---
+layout: default
+title: Projects
+---
 
-h2. Starting Out
+
+h2(#starting). Starting Out
 
 In Java, most projects are built the same way: compile source code, run test cases, package the code, release it.  Rinse, repeat.
 
@@ -8,16 +12,17 @@ Feed it a project definition, and Buildr will set up all these tasks for you. Th
 
 The remainder of this guide deals with what it takes to build a project.  But first, let's pick up a sample project to work with.  We'll call it _killer-app_:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 require 'buildr'
  
 VERSION_NUMBER = '1.0'
  
 AXIS2 = 'org.apache.axis2:axis2:jar:1.2'
-AXIOM  = group('axiom-api', 'axiom-impl', 'axiom-dom',
+AXIOM = group('axiom-api', 'axiom-impl', 'axiom-dom',
   :under=>'org.apache.ws.commons.axiom', :version=>'1.2.4')
 AXIS_OF_WS = [AXIOM, AXIS2]
-OPENJPA = ['org.apache.openjpa:openjpa-all:jar:0.9.7',
+OPENJPA = ['org.apache.openjpa:openjpa:jar:1.2.0',
   'net.sourceforge.serp:serp:jar:1.12.0']
  
 repositories.remote << 'http://www.ibiblio.org/maven2/'
@@ -44,7 +49,7 @@ define 'killer-app' do
 
   desc 'What our users see'
   define 'la-web' do
-    test.using AXIS_OF_WS
+    test.with AXIS_OF_WS
     package(:war).with :libs=>projects('teh-api', 'teh-impl')
   end
 
@@ -52,14 +57,15 @@ define 'killer-app' do
   package :javadoc
 
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 A project definition requires four pieces of information: the project name, group identifier, version number and base directory.  The project name ... do we need to explain why its necessary?  The group identifier and version number are used for packaging and deployment, we'll talk more about that in the "Packaging":packaging.html section.  The base directory lets you find files inside the project.
 
 Everything else depends on what that particular project is building.  And it all goes inside the project definition block, the piece of code that comes between @define <name> ..  do@ and @end@.
 
 
-h2. The Directory Structure
+h2(#dir_structure). The Directory Structure
 
 Buildr follows a convention we picked from years of working with Apache projects.
 
@@ -84,7 +90,7 @@ And yes, you can have two top projects in the same Buildfile.  For example, you
 When you start with a new project you won't see the @target@ or @reports@ directories.  Buildr creates these when it needs to.  Just know that they're there.
 
 
-h2. Naming And Finding Projects
+h2(#naming). Naming And Finding Projects
 
 Each project has a given name, the first argument you pass when calling @define@.  The project name is just a string, but we advise to stay clear of colon (@:@) and slashes (@/@ and @\@), which could conflict with other task and file names.  Also, avoid using common Buildr task names, don't pick @compile@ or @build@ for your project name.
 
@@ -96,7 +102,8 @@ The @projects@ method takes a list of names and returns a list of projects.  If
 
 Let's illustrate this with a few examples:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 puts projects.inspect
 => [project("killer-app"), project("killer-app:teh-api") ... ]
 
@@ -111,20 +118,18 @@ puts project('killer-app:teh-api').inspect
 
 puts project('killer-app').project('teh-api').inspect
 => project("killer-app:teh-api")
-}}}
-
-To see a list of all projects defined in your Buildfile:
+{% endhighlight %}
+</notextile>
 
-{{{!sh
-$ buildr help:projects
-}}}
+To see a list of all projects defined in your Buildfile run @buildr help:projects@.
 
 
-h2. Running Project Tasks
+h2(#tasks). Running Project Tasks
 
 Most times, you run tasks like @build@ or @package@ that operate on the current project and recursively on its sub-projects.  The "current project" is the one that uses the current working directory.  So if you're in the @la-web/src@ directory looking at source files, _la-web_ is the current project.  For example: 
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 # build killer-app and all its sub-projects
 $ buildr build
 
@@ -135,11 +140,13 @@ $ buildr test
 # switch to and package only la-web
 $ cd ../la-web
 $ buildr package
-}}}
+{% endhighlight %}
+</notextile>
 
 You can use the project's full name to invoke one of its tasks directly, and it doesn't matter which directory you're in.  For example:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 # build killer-app and all its sub-projects
 $ buildr killer-app:build
 
@@ -148,11 +155,13 @@ $ buildr killer-app:teh-impl:test
 
 # package only la-web
 $ buildr killer-app:la-web:package
-}}}
+{% endhighlight %}
+</notextile>
 
 Buildr provides the following tasks that you can run on the current project, or on a specific project by prefixing them with the project's full name:
 
-{{{
+<notextile>
+{% highlight text %}
 clean     # Clean files generated during a build
 compile   # Compile all projects
 build     # Build the project
@@ -162,21 +171,20 @@ javadoc   # Create the Javadocs for this project
 package   # Create packages
 test      # Run all test cases
 uninstall # Remove previously installed packages
-}}}
+{% endhighlight %}
+</notextile>
 
-To see a list of all the tasks provided by Buildr:
+To see a list of all the tasks provided by Buildr run @buildr help:tasks@.
 
-{{{!sh
-$ buildr help:tasks
-}}}
 
-h2. Setting Project Properties
+h2(#properties). Setting Project Properties
 
 We mentioned the group identifier, version number and base directory.  These are project properties.  There are a few more properties we'll cover later on.
 
 There are two ways to set project properties.  You can pass them as a hash when you call @define@, or use accessors to set them on the project directly.  For example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 define 'silly', :version=>'1.0' do
   project.group = 'acme'
 end
@@ -185,12 +193,13 @@ puts project('silly').version
 => 1.0
 puts project('silly').group
 => acme
-}}}
+{% endhighlight %}
+</notextile>
 
 Project properties are inherited.  You can specify them once in the parent project, and they'll have the same value in all its sub-projects.  In the example, we only specify the version number once, for use in all sub-projects.
 
 
-h2. Resolving Paths
+h2(#paths). Resolving Paths
 
 You can run @buildr@ from any directory in your project.  To keep tasks consistent and happy, it switches over to the Buildfile directory and executes all the tasks from there, before returning back to your working directory. Your tasks can all rely on relative paths that start from the same directory as the Buildfile.
 
@@ -200,7 +209,8 @@ The @path_to@ method takes an array of strings and concatenates them into a path
 
 For example:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 # Relative to the current project
 path_to('src', 'main', 'java')
 
@@ -209,16 +219,18 @@ _('src/main/java')
 
 # Relative to the teh-impl project
 project('teh-impl')._('src/main/java')
-}}}
+{% endhighlight %}
+</notextile>
 
 
-h2. Defining The Project
+h2(#defining). Defining The Project
 
 The project definition itself gives you a lot of pre-canned tasks to start with, but that's not enough to build a project.  You need to specify what gets built and how, which dependencies to use, the packages you want to create and so forth.  You can configure existing tasks, extend them to do additional work, and create new tasks.  All that magic happens inside the project definition block.
 
 Since the project definition executes each time you run Buildr, you don't want to perform any work directly inside the project definition block.  Rather, you want to use it to specify how different build task work when you invoke them. Here's an example to illustrate the point:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 define 'silly' do
   puts 'Running buildr'
 
@@ -226,7 +238,8 @@ define 'silly' do
     puts 'Building silly'
   end
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 Each time you run Buildr, it will execute the project definition and print out "Running buildr".  We also extend the @build@ task, and whenever we run it, it will print "Building silly".  Incidentally, @build@ is the default task, so if you run Buildr with no arguments, it will print both messages while executing the build.  If you run Buildr with a different task, say @clean@, it will only print the first message.
 
@@ -240,7 +253,8 @@ One project can reference another ahead of its definition.  If Buildr detects a
 
 In this example we define one project in terms of another, using the same dependencies, so we only need to specify them once:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 define 'bar' do
   compile.with project('foo').compile.dependencies
 end
@@ -248,20 +262,21 @@ end
 define 'foo' do
   compile.with ..lots of stuff..
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 One last thing to remember.  Actually three, but they all go hand in hand.
 
 *Self is project* Each of these project definition blocks executes in the context of that project, just as if it was a method defined on the project.  So when you call the @compile@ method, you're essentially calling that method on the current project: @compile@, @self.compile@ and @project.compile@ are all the same.
 
-*Blocks are closures* The project definition is also a closure, which can reference variables from enclosing scopes.  You can use that, for example, to define constants, variables and even functions in your Buildfile, and reference them from your project definition.  As you'll see later on, in the "Artifacts":#artifacts section, it will save you a lot of work.
+*Blocks are closures* The project definition is also a closure, which can reference variables from enclosing scopes.  You can use that, for example, to define constants, variables and even functions in your Buildfile, and reference them from your project definition.  As you'll see later on, in the "Artifacts":artifacts.html section, it will save you a lot of work.
 
 *Projects are namespaces* While executing the project definition, Buildr switches the namespace to the project name.  If you define the task "do-this" inside the _teh-impl_ project, the actual task name is "killer-app:teh-impl:do-this".  Likewise, the @compile@ task is actually "killer-app:teh-impl:compile".
 
 From outside the project you can reference a task by its full name, either @task('foo:do')@ or @project('foo').task('do')@.  If you need to reference a task defined outside the project from within the project, prefix it with "rake:", for example, @task('rake:globally-defined')@.
 
 
-h2. Writing Your Own Tasks
+h2(#your_own_tasks). Writing Your Own Tasks
 
 Of all the features Buildr provide, it doesn't have a task for making coffee. Yet.  If you need to write your own tasks, you get all the power of Rake: you can use regular tasks, file tasks, task rules and even write your own custom task classes.  Check out the "Rake documentation":http://docs.rubyrake.org/ for more information.
 

data/doc/scripts/buildr-git.rb

@@ -16,79 +16,377 @@
 
 
 # This script helps buildr developers to obtain their own git clone from
-# github, having a set of pre-defined aliases to work with Apache's SVN.
+# github, and also provides GitFlow commands to keep the git mirror in sync
+# with Apache SVN.
 #
-# You dont need to have a buildr copy to use it, just execute the buildr-git balloon:
+# If you already have a buildr clone, just do the following:
 #
-#   ruby -ropen-uri -e 'eval(open("http://balloon.hobix.com/buildr-git").read)'
+#    git config alias.apache '!'"ruby $PWD/doc/scripts/buildr-git.rb"
+#
+# After this, you have a 'git apache' command and you can try (be sure to read the help)
+#
+#    git apache help
+#    git apache setup svn --help
+#    git apache sync --help
+#
+# To configure your local repo for svn synchronization, 
+#
+#    git apache update-authors
+#    git remote add upstream git@github.com:buildr/buildr.git
+#    git apache setup svn --username apacheLogin --apache-git upstream
+#    git apache sync
+#
+# This script can also be run without having a local buildr clone:
+#
+#   ruby -ropen-uri -e 'eval(open("http://svn.apache.org/viewvc/buildr/trunk/doc/scripts/buildr-git.rb?view=co").read)' help
+
+
 
 require 'yaml'
-require 'optparse'
-require 'ostruct'
-
-# Pager from http://nex-3.com/posts/73-git-style-automatic-paging-in-ruby
-def run_pager
-  return if RUBY_PLATFORM =~ /win32/
-  return unless STDOUT.tty?
-
-  read, write = IO.pipe
-
-  unless Kernel.fork # Child process
-    STDOUT.reopen(write)
-    STDERR.reopen(write) if STDERR.tty?
-    read.close
-    write.close
-    return
+require 'open-uri'
+
+if $0 == '-e' # invoked from open-uri
+  gitflow = "http://svn.apache.org/viewvc/buildr/trunk/doc/scripts/gitflow.rb?view=co"
+  eval(open(gitflow).read)
+else
+  require File.expand_path('gitflow', File.dirname(__FILE__))
+end
+
+GitFlow.program = 'buildr-git'
+
+module BuildrGit
+
+  class UpdateUsersCommand < GitFlow/'update-users'
+
+    @help = "Update list of Apache SVN committers from Jukka's list."
+    @@url = 'http://people.apache.org/~jukka/authors.txt'
+
+    def self.authors_file
+      File.expand_path('.git/authors.txt', Dir.pwd)
+    end
+
+    def self.user_email(apache_login, authors_file = nil)
+      authors_file ||= self.authors_file
+      authors = YAML.load(File.read(authors_file).gsub!(/\s+=\s+/, ': '))
+      contact = authors[apache_login]
+      fail "You are not listed as apache commiter on #{authors_file}" unless contact
+      fail "Not a valid contact line: #{contact}" unless contact =~ /\s+<(.*)>/
+      [$`, $1]
+    end
+
+    def options(opts)
+      opts.url = @@url
+      opts.file = self.class.authors_file
+      [['-u', '--url URL', 
+        "From URL. defaults to: #{opts.url}", lambda { |url|
+          opts.url = url
+       }],
+       ['-f', '--file FILE', 
+        "Write to FILE, defaults to #{opts.file}", lambda { |path|
+          opts.file = path
+        }]
+      ]
+    end
+
+    def execute(opts, argv)
+      FileUtils.mkdir_p(File.dirname(opts.file))
+      content = open(opts.url).read
+      File.open(opts.file, "w") { |f| f.print content }
+    end
   end
 
-  # Parent process, become pager
-  STDIN.reopen(read)
-  read.close
-  write.close
+  class CloneCommand < GitFlow/:clone
+    @help = "Create a clone from github.com/buildr repository."
+    
+    def options(opts)
+      opts.origin = 'git://github.com/buildr/buildr.git'
+      opts.svn_prefix = 'apache'
+      opts.project = 'buildr'
+      opts.local = expand_path(opts.project)
+      [['--prefix SVN_PREFIX', opts.svn_prefix, lambda { |p|
+          opts.svn_prefix = p }],
+       ['--origin GIT_ORIGIN', opts.origin, lambda { |o|
+          opts.origin = o }],
+       ['-d', '--dir DIR', opts.local, lambda { |d| opts.local = d }]
+      ]
+    end
 
-  ENV['LESS'] = 'FSRX' # Don't page if the input is short enough
+    def execute(opts, argv)
+      git 'clone', opts.origin, opts.local
+      Dir.chdir(opts.local) do 
+        run 'update-users'
+        run 'setup'
+      end
+    end
+  end
 
-  Kernel.select [STDIN] # Wait until we have input before we start the pager
-  pager = ENV['PAGER'] || 'less'
-  exec pager rescue exec "/bin/sh", "-c", pager
-end
+  class SetupCommand < GitFlow/:setup
+    @help = "Setup your buildr clone to be used with git mirror."
+    def options(opt)
+      []
+    end
+    
+    def execute(opt, argv)
+      run 'setup', 'alias'
+      run 'setup', 'svn'
+    end
+  end
 
-def header
-  <<HEADER
+  class SetupAliasCommand < SetupCommand/:alias
+    def execute(opt, argv)
+      me = expand_path('doc/scripts/buildr-git.rb')
+      git 'config', 'alias.apache', "!ruby #{me}"
+    end
+  end
+
+  class SetupSvnCommand < SetupCommand/:svn
+    @help = "Setup for getting changes from Apache SVN."
+
+    def options(opt)
+      opt.svn_prefix = 'apache'
+      opt.svn_path = 'buildr'
+      opt.townhall = 'origin'
+      [['--username SVN_USER', 'Use Apache svn username for this svn remote', 
+        lambda { |e| opt.apache_login = e  }],
+       ['--svn-prefix PREFIX', 'The name of svn remote to use for project.',
+        "Defaults to #{opt.svn_prefix}", 
+        lambda{|p| opt.svn_prefix = p }],
+       ['--svn-uri URI', lambda {|p| opt.svn_uri = p  }],
+       ['--svn-rev REVISION', lambda {|p| opt.svn_rev = p  }],
+       ['--svn-path PATH', 'The path to append to svn-uri.',
+        "Defaults to #{opt.svn_path}", lambda {|p| opt.svn_path = p  }],
+       ['--apache-git REMOTE', 'The name of remote you are using as town-hall git repo.',
+        "Defaults to #{opt.townhall}",
+        lambda {|p| opt.townhall = p }]
+      ]
+    end
+
+    def execute(opt, argv)
+      authors_file = UpdateUsersCommand.authors_file
+      git 'config', 'svn.authorsfile', authors_file
+      git 'config', 'apache.svn', opt.svn_prefix
+      git 'config', 'apache.git', opt.townhall
+      
+      if opt.apache_login
+        user, email = UpdateUsersCommand.user_email(opt.apache_login, authors_file)
+        puts "You claim to be #{user} <#{email}> with apache login: #{opt.apache_login}"
+        git('config', 'user.name', user)
+        git('config', 'user.email', email)
+      end
+      
+      if opt.svn_rev
+        revision = opt.svn_rev
+      else
+        location, revision = svn_loc_rev
+        revision = opt.svn_rev || revision
+      end
+      
+      if opt.svn_uri
+        repo = opt.svn_uri
+      else
+        fail "No #{opt.svn_path} directory on #{location}" unless
+          location =~ /\/#{opt.svn_path}/
+        repo = $`
+      end
+
+      # Tell git where the svn repository is 
+      git('config', "svn-remote.#{opt.svn_prefix}.url", repo)
+      git('config', "svn-remote.#{opt.svn_prefix}.fetch",
+          "#{opt.svn_path}/trunk:refs/remotes/#{opt.svn_prefix}/trunk")
+      git('config', "svn-remote.#{opt.svn_prefix}.branches", 
+          "#{opt.svn_path}/branches/*:refs/remotes/#{opt.svn_prefix}/*")
+      git('config', "svn-remote.#{opt.svn_prefix}.tags", 
+          "#{opt.svn_path}/tags/*:refs/remotes/#{opt.svn_prefix}/tags/*")
+
+      # Store the user for svn dcommit
+      if opt.apache_login
+        git('config', "svn-remote.#{opt.svn_prefix}.username", opt.apache_login)
+      end
+
+      # Create the svn branch, do this instead of pulling the full svn history
+      git('update-ref', "refs/remotes/#{opt.svn_prefix}/trunk",
+          'refs/remotes/origin/master')
+      # create tags from git
+      git('tag').split.each do |tag|
+        git('update-ref', "refs/remotes/#{opt.svn_prefix}/tags/#{tag}",
+            "refs/tags/#{tag}")
+      end
+      # update svn metadata
+      mkdir_p(expand_path('.git/svn'))
+      svn_meta = expand_path('.git/svn/.metadata')
+      git('config', '--file', svn_meta, 
+          "svn-remote.#{opt.svn_prefix}.branches-maxRev", revision)
+      git('config', '--file', svn_meta, 
+          "svn-remote.#{opt.svn_prefix}.tags-maxRev", revision)
+    end
+
+    def svn_loc_rev
+      meta = sh('git log -n 10 | grep git-svn-id | head -n 1').chomp
+      fail "No svn metadata on last 10 commits" if meta.empty?
+      meta.split[1].split('@')
+    end
+  end
+
+  class FetchCommand < GitFlow/:fetch
+    @help = "Get changes from svn, creating tags, branches on townhall"
+    @documentation = <<-DOC
+This command can be used to fetch changes from Apache\'s SVN repo.
+
+GIT CONFIG VALUES:
+
+apache.svn  - The svn remote using to get changes from Apache SVN.
+              Set by setup-svn --svn-prefix.
+    DOC
+
+    def options(opt)
+      opt.apache_svn = git('config', '--get', 'apache.svn').chomp rescue nil
+      [['--apache-svn SVN_REMOTE', 'The SVN remote used to get changes from Apache',
+        "Current value: #{opt.apache_svn}",
+        lambda { |r| opt.apache_svn = r }]
+       ]
+    end
+
+    def execute(opt, argv)
+      fail "Missing apache.svn config value" unless opt.apache_svn
+      git('svn', 'fetch', opt.apache_svn)
+    end
+  end
+
+  class SyncCommand < GitFlow/:sync
+    @help = "Synchronizes between Apache svn and git townhall."
+    @documentation = <<-DOC
+This command will perform the following actions: 
+  * fetch changes from apache svn.
+  * rebase them on the current branch or on the one specified with --onto
+  * dcommit (this will push your changes to Apache trunk)
+
+GIT CONFIG VALUES:
+
+apache.svn  
+  The svn remote using to get changes from Apache SVN.
+  Set by setup-svn --svn-prefix.
+
+apache.git 
+  The git remote used as townhall repository.
+  Set by setup-svn --townhall.
+
+svn-remote.APACHE_GIT.username
+  If configured, sync will use this svn username while dcommiting.
+DOC
+
+    def options(opt)
+      git('branch').split.tap { |n| opt.current = n[n.index('*')+1] }
+      opt.branch = opt.current
+      opt.svn_branch = 'trunk'
+      opt.git_branch = 'master'
+      opt.apache_git = git('config', '--get', 'apache.git').chomp rescue nil
+      opt.apache_svn = git('config', '--get', 'apache.svn').chomp rescue nil
+      opt.svn_username = git('config', '--get', 
+                             "svn-remote.#{opt.apache_svn}.username").chomp rescue nil
+      [['--apache-svn SVN_REMOTE', 'The SVN remote used to get changes from Apache',
+        "Current value: #{opt.apache_svn}",
+        lambda { |r| opt.apache_svn = r }],
+       ['--apache-git REMOTE', 'The git remote used as town-hall repository.',
+        "Current value: #{opt.apache_git}",
+        lambda { |r| opt.apache_git = r }],
+       ['--username SVN_USER', 
+        'Specify the SVN username for dcommit',
+        "Defaults to: #{opt.svn_username}",
+        lambda { |b| opt.svn_username = b }],
+       ['--svn-branch SVN_BRANCH',
+        'Specify the SVN branch to rebase changes from, and where to dcommit', 
+        "Defaults to: #{opt.svn_branch}",
+        lambda { |b| opt.svn_branch = b }],
+       ['--git-branch REMOTE_BRANCH', 
+        'Specify the remote town-hall branch (on apache.git) to update',
+        "Defaults to: #{opt.git_branch}",
+        lambda { |b| opt.git_branch = b }],
+       ['--branch BRANCH', 'Specify the local branch to take changes from',
+        "Current branch: #{opt.branch}",
+        lambda { |b| opt.branch = b }]
+      ]
+    end
+
+    def execute(opt, argv)
+      # obtain the svn url
+      url = git('config', '--get', "svn-remote.#{opt.apache_svn}.url").chomp
+      # obtain the path for project
+      path = git('config', '--get', "svn-remote.#{opt.apache_svn}.branches").
+        chomp.split('/branches').first
+      commit_url = "#{url}/#{path}/#{opt.svn_branch}"
+
+      # obtain latest changes from svn
+      git('svn', 'fetch', '--svn-remote', opt.apache_svn)
+      # obtain latest changes from git
+      git('fetch', opt.apache_git, 
+          "#{opt.git_branch}:refs/remotes/#{opt.apache_git}/#{opt.git_branch}")
+
+      # rebase svn changes in the desired branch
+      git('rebase', "#{opt.apache_svn}/#{opt.svn_branch}", opt.branch)
+      git('rebase', "#{opt.apache_git}/#{opt.git_branch}", opt.branch)
+      
+      # dcommit to the specific svn branch
+      ['svn', 'dcommit', 
+       '--svn-remote', opt.apache_svn, '--commit-url', commit_url].tap do |cmd|
+        if opt.svn_username
+          cmd << '--username' << opt.svn_username
+        end
+        git(*cmd)
+      end
+      
+      # update townhall remote ref
+      git('update-ref', 
+          "refs/remotes/#{opt.apache_git}/#{opt.git_branch}",
+          "refs/remotes/#{opt.apache_svn}/#{opt.svn_branch}")
+
+      # forward the remote townhall/master to apache/trunk
+      git('push', opt.apache_git, 
+          "refs/remotes/#{opt.apache_git}/#{opt.git_branch}:#{opt.git_branch}")
+
+      # get back to the original branch
+      git('checkout', opt.current)
+    end
+  end
+
+
+  # This one is displayed when the user executes this script using 
+  # open-uri -e
+  HEADER = <<HEADER
 
 Buildr official commit channel is Apache's svn repository, however some
 developers may prefer to use git while working on several features and
 merging other's changes.
 
-This script will configure a buildr-git copy on so you can commit to svn.
+This script will configure a gitflow copy on so you can commit to svn.
 
 Enter <-h> to see options, <-H> to see notes about configured aliases
 and recommended workflow, or any other option.
 
 Ctrl+D or an invalid option to abort
 HEADER
-end
-
-def notice
-  <<NOTICE
+  
+  # When fork is completed, we display the following notice on a 
+  # pager, giving the user a brief overview of git aliases used
+  # to keep the mirror in sync.
+  NOTICE = <<NOTICE
 ALIASES:
 
   Some git aliases have been created for developer convenience:
 
-    git apache-fetch    # get changes from apache/trunk without merging them
+    git apache fetch    # get changes from apache/trunk without merging them
                         # you can inspect what's happening on trunk without
                         # having to worry about merging conflicts.
                         # Inspect the remote branch with `git log apache/trunk`
                         # Or if you have a git-ui like `tig` you can use that.
 
-    git apache-merge    # Merge already fetched changes on the current branch
+    git apache merge    # Merge already fetched changes on the current branch
                         # Use this command to get up to date with trunk changes
                         # you can always cherry-pick from the apache/trunk 
                         # branch.
 
-    git apache-pull     # get apache-fetch && git apache-merge
+    git apache pull     # get apache-fetch && git apache-merge
    
-    git apache-push     # Push to Apache's SVN. Only staged changes (those 
+    git apache push     # Push to Apache's SVN. Only staged changes (those 
                         # recorded using `git commit`) will be sent to SVN. 
                         # You need not to be on the master branch.
                         # Actually you can work on a tiny-feature branch and
@@ -108,24 +406,30 @@ ALIASES:
 
 THE GITHUB MIRROR:
 
-   Buildr has an unofficial git mirror on github, maintained by Victor: 
+   Buildr has an unofficial git mirror on github, maintained by Apache committers:
 
-     http://github.com/vic/buildr
+     http://github.com/buildr/buildr
 
-   Actually it's not Victor who manually updates it, he has a cron-job on his
-   server, that only runs
+   This mirror DOES NOT replace Apache's SVN repository. We really care about 
+   using Apache infrastructure and following Apache project guidelines for 
+   contributions. This git mirror is provided only for developers convenience,
+   allowing them to easily create experimental branches or review code from
+   other committers. 
 
-     git synchronize 
+   All code that wants to make it to the official Apache Buildr repository needs
+   to be committed to the Apache SVN repository by using the command:
 
-   A command you also have configured on your .git/config file.
+      git synchronize
 
-   However there are some limitations due to the fact that git-svn cannot 
-   commit as multiple authors (unless all of them provided their passwords
-   to Victor, yet he doesn't want to take over the world.)
-   This means that if a commit is pushed to vic/buildr/master and has not
-   already been pushed by YOU to Apache's SVN by using `git apache-push` 
-   your change will be commited to apache/trunk having Victor as the author
-   (that's how he gains meritocratic points at Apache :P). 
+   This command will synchronize both ways svn<->git to keep trunk upto date.
+   You need to be an Apache committer and have permissions on the SVN repo.
+   
+   It's VERY IMPORTANT for Buildr committers to remember that contributions from
+   external entities wanting to be accepted will require them to sign the Apache ICLA.
+   We provide the git mirror to make it easier for people to experiment and 
+   contribute back to Buildr, before merging their code in, please remember they
+   have to create create a JIRA issue granting ASF permission to include their code, 
+   just like any other contribution following Apache's guidelines.
 
    So, it's very important - if you care about meritocracy - to follow or at 
    least that you get an idea of the recommended workflow.
@@ -139,7 +443,7 @@ RECOMMENDED WORKFLOW:
    As all things git, you can always follow your own workflow and even create
    aliases on you .git/config file to avoid typing much. So, here they are:
 
-   1) get your buildr-git configured 
+   1) get your gitflow configured 
      (you have already do so, this was the most difficult part)
 
    2) create a topic branch to work on, say.. you want to add cool-feature:
@@ -175,15 +479,15 @@ RECOMMENDED WORKFLOW:
       license to include your code:
 
         https://issues.apache.org/jira/browse/BUILDR
-        buildr-dev@incubator.apache.org
+        dev@buildr.apache.org
 
    7.b) Now you have everyhing on staging area and merged important changes 
       from apache/trunk, it's time to commit them to Apache's SVN.
 
         git apache-push 
 
-   8) Optional. If you can push to vic/buildr/master mirror, you can just 
-     synchronize the mirror helping others to get changes without having to 
+   8) Optional. If you are a buildr committer you may want to synchronize
+     the github mirror for helping others to get changes without having to 
      wait on Victor's cronjob to run every hour (useful for urgent changes).
 
         git synchronize
@@ -194,219 +498,15 @@ RECOMMENDED WORKFLOW:
         git rebase --onto origin/master master master
 
    10) Unconditionally, Go to step 2 ;)
-       Share your buildr-git workflow, git tips, etc.
+       Share your gitflow workflow, git tips, etc.
 
 RESOURCES:
 
-   http://github.com/vic/buildr/tree/master
+   http://github.com/buildr/buildr/tree/master
    http://git.or.cz/gitwiki/GitCheatSheet
    http://groups.google.com/group/git-users/web/git-references
 
 NOTICE
-end # notice method
-
-def optparse(options = OpenStruct.new, argv = ARGV)
-  opt = OptionParser.new do |opt|
-    
-    if `git status 2>/dev/null`.chomp.empty?
-      options.local = File.expand_path('buildr', Dir.pwd)
-    else
-      puts "Current directory is a git repo: #{Dir.pwd}"
-      options.local = Dir.pwd 
-    end
-
-    options.svn_branch = "apache/trunk"
-    options.origin = "git://github.com/vic/buildr.git"
-    options.member = false
-
-    opt.banner = "Usage: buildr-git.rb [options]"
-    opt.separator ""
-    opt.separator "OPTIONS:"
-
-    opt.on('-a', "--anon", "Use git://github.com/vic/buildr.git as origin") do 
-      options.origin = "git://github.com/vic/buildr.git"
-    end
-    opt.on('-A', "--auth", "Use git@github.com:vic/buildr.git as origin") do
-      options.origin = "git@github.com:vic/buildr.git"
-    end
-    opt.on("-o", "--origin GIT_URL", "Clone from GIT_URL origin") do |value|
-      options.origin = value
-    end
-    opt.on('-l', "--local DIRECTORY", "Create local git clone on DIRECTORY") do |value|
-      options.local = value
-    end
-    opt.on('-b', "--branch GIT_SVN_BRANCH", 
-           "Set the name for svn branch instead of apache/trunk") do |value|
-      options.svn_branch = value
-    end
-    opt.on('-e', "--email EMAIL", 
-           "Configure git to use EMAIL for commits") do |value|
-      options.email = value
-    end
-    opt.on('-n', "--name USER_NAME", 
-           "Configure your USER_NAME for git commits") do |value|
-      options.user_name = value
-    end
-    opt.on('-h', "--help", "Show buildr-git help") do 
-      puts opt
-      throw :exit
-    end
-    opt.on('-H', "--notice", "Show notice about aliases and git workflow") do
-      run_pager
-      puts notice
-      throw :exit
-    end
-  end
-  opt.parse!(argv)
-  options
-end # optparse method
-
-
-def main
-  catch :exit do
-    options = optparse
-    puts header
-    puts 
-    print '> '
-    if input = gets
-      options = optparse(options, input.split)
-    end
-    if input.nil? || (input != "\n" && input.empty?)
-      puts "Aborting."
-      return
-    end
-    perform(options)
-  end  
-end
-
-def perform(options)
-  origin = options.origin
-  member = origin =~ /@/
-  local = options.local
-  svn_branch = options.svn_branch
-  user_email = options.email
-  user_name = options.user_name
-  
-  `git clone #{origin} #{local} 1>&2` unless File.directory?(File.join('.git', origin))
+  #' for emacs
   
-  puts
-  puts "Entering #{local} directory"
-  puts
-  Dir.chdir(local) do
-    
-    # Load the list of git-svn committers
-    svn_authors_file = File.expand_path('etc/git-svn-authors', Dir.pwd)
-    svn_authors = File.read(svn_authors_file)
-    svn_authors.gsub!(/\s+=\s+/, ': ')
-    svn_authors = YAML.load(svn_authors)
-
-    # set the git-svn-authors file
-    `git config svn.authorsfile "#{svn_authors_file}"`
-
-    # Check that git is configured for the developer
-    user_email ||= `git config --get user.email`.chomp
-    if user_email.empty?
-      if member
-        puts "Enter your email as listed on #{svn_authors_file}"
-        print "> "
-        user_email = gets.chomp
-      else
-        puts "Provide an email address for git usage:"
-        user_email = gets.chomp
-      end
-    end
-
-    # Check user is listed
-    unless user_email.empty?
-      svn_user, git_contact = *svn_authors.find { |entry| /#{user_email}/ === entry.join(' ') }
-    end
-
-    if member 
-      if git_contact.nil? # if using the authenticated git, he must be listed
-        puts <<-NOTICE
-          You need to be a buildr commmitter listed on #{svn_authors_file}. 
-          Perhaps you need to add yourself to it, commit it using SVN, and 
-          and run this script again.
-          Also checks your git global values for user.email and user.name
-        NOTICE
-        return
-      elsif /\s*(.*?)\s+\<(.+)\>\s*/ === git_contact
-        user_name, user_email = $1, $2
-      else
-        puts "Invalid contact string for #{svn_user}: #{git_contact.inspect}"
-        return
-      end
-    elsif user_email =~ /^\s*$/
-      puts "User email shall not include spaces: #{user_email.inspect}"
-      return
-    end
-    
-    user_name ||= `git config --get user.name`.chomp
-    if git_contact.nil? && user_name.empty?
-      puts "Provide a developer name for git usage:"
-      user_name = gets.chomp
-    end
-    
-    # Start the pager
-    run_pager
-    puts
-
-
-    old_origin = `git config --get remote.origin.url`.chomp
-    if member && old_origin !~ /@/
-      puts "Switching to authenticated origin #{origin}", ""
-      `git config remote.origin.url "#{origin}"`
-    elsif !member && old_origin =~ /@/
-      puts "Switching to anonymous origin #{origin}", ""
-      `git config remote.origin.url "#{origin}"`
-    end
-    
-    # Configure user name and email for git sake (and github's gravatar)
-    puts "You claim to be #{user_name.inspect} <#{user_email}> "
-    puts "with apache-svn user: #{svn_user}" if svn_user
-    puts
-    `git config user.name  "#{user_name}"`
-    `git config user.email "#{user_email}"`
-    
-    # Ok, now obtain the last svn commit from history
-    last_svn_log = `git log -n 10 | grep git-svn-id | head -n 1`
-    fail "No svn metadata on last 10 commits" unless last_svn_log =~ /git-svn-id/
-    svn_repo, svn_prev = last_svn_log.split[1].split("@")
-    
-    # Tell git where the svn repository is.
-    `git config svn-remote.#{svn_branch}.url #{svn_repo}`
-    `git config svn-remote.#{svn_branch}.fetch :refs/remotes/#{svn_branch}`
-    
-    # Create the svn branch, do this instead of pulling the full svn history
-    `git push --force . refs/remotes/origin/master:refs/remotes/#{svn_branch}`
-    
-    # Create apache aliases for developers git-workflow.
-    `git config alias.apache-fetch "!git-svn fetch #{svn_branch}"`
-    `git config alias.apache-merge "!git merge #{svn_branch}"`
-    `git config alias.apache-pull  "!git apache-fetch && git apache-merge"`
-    if svn_user
-      `git config alias.apache-push  "!git-svn dcommit --username #{svn_user}"`
-    else
-      `git config alias.apache-push  "!git-svn dcommit"`
-    end
-    
-    # Create github origin aliases
-    `git config alias.get "!git apache-fetch && git fetch origin"`
-    `git config alias.mrg "!git apache-merge && git merge origin"`
-    `git config alias.rbs "!git rebase --onto #{svn_branch} origin/master master"`
-    `git config alias.put "!git apache-push && git push origin"`
-    
-    # This is Victor's cronjob
-    `git config alias.synchronize "!git get && git rbs && git put"`
-    
-    # Final notices.
-    puts <<-NOTICE + notice
-
-    Your git repo #{local} has been configured, please review the 
-       #{File.join(local, '.git/config')} file.
-
-    NOTICE
-  end  
-end # perform method
-
-main
+end