buildr 1.3.3 → 1.3.4

data/doc/scripts/gitflow.rb

@@ -0,0 +1,296 @@
+#!/usr/bin/env ruby
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with this
+# work for additional information regarding copyright ownership.  The ASF
+# licenses this file to you 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
+#
+# 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.
+
+require 'optparse'
+require 'ostruct'
+require 'fileutils'
+
+module GitFlow
+  extend self
+  
+  attr_accessor :should_run, :trace, :program
+
+  self.program = 'gitflow'
+  self.should_run = true # should we run at exit?
+
+  HELP = <<-HELP
+
+GitFlow is a tool to create custom git commands implemented in ruby.
+It is generic enougth to be used on any git based project besides Apache Buildr.
+
+OVERVIEW:
+
+gitflow is intended to help developers with their daily git workflow,
+performing repetitive git commands for them. It is implemented in 
+ruby so you can do anything, from invoking rake tasks to telling
+people on twitter you are having trouble with their code :P.
+
+To get help for a specific command use:
+    gitflow.rb help command
+    gitflow.rb command --help
+
+For convenience you can create an alias to be execute using git.
+The following example registers buildr-git.rb, which provides apache
+svn and git synchronization commands:
+
+    git config alias.apache '!'"ruby $PWD/doc/scripts/buildr-git.rb"
+
+After that you can use
+    git apache command --help
+
+EXTENDING YOUR WORKFLOW:
+
+You can create your own gitflow commands, to adapt your development 
+workflow.
+
+Simply create a ruby script somewhere say ~/.buildr/gitflow.rb
+And alias it in your local repo:
+
+    git config alias.flow '!'"ruby ~/.buildr/gitflow.rb"
+    git config alias.work '!'"ruby ~/.buildr/gitflow.rb my-flow sub-work"
+
+A sample command would look like this.. (you may want to look at buildr-git.rb)
+
+    #!/usr/bin/env ruby
+    require /path/to/gitflow.rb
+    
+    class MyCommand < GitFlow/'my-flow'
+      
+      @help = "Summary to be displayed when listing commands"
+      @documentation = "Very long help that will be paged if necessary. (for --help)"
+      
+      # takes an openstruct to place default values and option values.
+      # returns an array of arguments given to optparse.on
+      def options(opts)
+        opts.something = 'default'
+        [ 
+         ['--name NAME', lambda { |n| opts.name = n }],
+         ['--yes', lambda { |n| opts.yes = true }]
+        ]
+      end
+
+      # takes the opts openstruct after options have been parsed and
+      # an argv array with non-option arguments.
+      def execute(opts, argv)
+        # you can run another command using
+        run('other-command', '--using-this', 'arg')
+        some = git('config', '--get', 'some.property').chomp rescue nil
+        page { puts "This will be paged on terminal if needed" }
+      end
+
+      class SubCommand < MyCommand/'sub-work'
+        ... # implement a subcommand
+      end
+      
+    end
+
+You would then get help for your command with
+
+    git flow my-flow --help
+    git work --help
+
+Using gitflow you can customize per-project git interface.
+
+HELP
+
+  # Pager from http://nex-3.com/posts/73-git-style-automatic-paging-in-ruby
+  def 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
+    end
+
+    # Parent process, become pager
+    STDIN.reopen(read)
+    read.close
+    write.close
+
+    ENV['LESS'] = 'FSRX' # Don't page if the input is short enough
+
+    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
+
+  # Return a class to be extended in order to register a GitFlow command
+  # if command name is nil, it will be registered as the top level command.
+  # Classes implementing commands also provide this method, allowing for
+  # sub-command creation.
+  def /(command_name)
+    command_name = command_name.to_s unless command_name.nil?
+    cls = Class.new { include GitFlow::Mixin }
+    (class << cls; self; end).module_eval do
+      attr_accessor :help, :documentation, :command
+      define_method(:/) do |subcommand|
+        raise "Subcommand cannot be nil" unless subcommand
+        GitFlow/([command_name, subcommand].compact.join(' '))
+      end
+      define_method(:inherited) do |subclass|
+        subclass.command = command_name
+        GitFlow.commands[command_name] = subclass
+      end
+    end
+    cls
+  end
+
+  def commands
+    @commands ||= Hash.new
+  end
+
+  def optparse
+    optparse = opt = OptionParser.new
+    opt.separator ' '
+    opt.separator 'OPTIONS'
+    opt.separator ' '
+    opt.on('-h', '--help', 'Display this help') do
+      GitFlow.pager; puts opt; throw :exit
+    end
+    opt.on('--trace', 'Display traces') { GitFlow.trace = true }
+    optparse
+  end
+
+  def command(argv)
+    cmds = []
+    argv.each_with_index do |arg, i|
+      arg = argv[0..i].join(' ')
+      cmds << commands[arg] if commands.key?(arg)
+    end
+    cmds.last || commands[nil]
+  end
+
+  def run(*argv)
+    catch :exit do
+      command = self.command(argv).new
+      argv = argv[command.class.command.split.length..-1] if command.class.command
+      parser = optparse
+      parser.banner = "Usage: #{GitFlow.program} #{command.class.command} [options]"
+      options = OpenStruct.new
+      if command.respond_to?(:options)
+        command.options(options).each { |args| parser.on(*args) }
+      end
+      if command.class.documentation && command.class.documentation != ''
+        parser.separator ' '
+        parser.separator command.class.documentation.split(/\n/)
+      end
+      parser.parse!(argv)
+      command.execute(options, argv)
+    end
+  end
+
+  module Mixin
+    include FileUtils
+
+    # Override this method in your command class if it
+    # needs to parse command line options.
+    # 
+    # This method takes an openstruct object as argument
+    # allowing you to store default values on it, and 
+    # set option values.
+    #
+    # The return value must be an array of arguments 
+    # given to optparse.on
+    def options(opt)
+      []
+    end
+    
+    # Override this method in your command class to implement
+    # the command.
+    # First argument is the openstruct object after
+    # it has been populated by the option parser. 
+    # Second argument is the array of non-option arguments.
+    def execute(opt, argv)
+      fail "#{self.class.command} not implemented"
+    end
+    
+    # Run the command line given on argv
+    def run(*argv, &block)
+      GitFlow.run(*argv, &block)
+    end
+
+    # Yield paging the blocks output if necessary.
+    def page
+      GitFlow.pager
+      yield
+    end
+  
+    def trace(*str)
+      STDERR.puts(*str) if GitFlow.trace
+    end
+    
+    def git(*args)
+      cmd = 'git ' + args.map { |arg| arg[' '] ? %Q{"#{arg}"} : arg }.join(' ')
+      trace cmd
+      `#{cmd}`.tap {
+        fail "GIT command `#{cmd}` failed with status #{$?.exitstatus}" unless $?.exitstatus == 0
+      }
+    end
+    
+    def sh(*args)
+      `#{args.join(' ')}`.tap {
+        fail "Shell command `#{args.join(' ')}` failed with status #{$?.exitstatus}" unless $?.exitstatus == 0
+      }
+    end
+    
+    def expand_path(path, dir=Dir.pwd)
+      File.expand_path(path, dir)
+    end
+  end
+
+  class NoSuchCommand < GitFlow/nil
+    @documentation = HELP
+    
+    def execute(opts, argv)
+      page do
+        puts "Command not found: #{argv.join(' ').inspect}"
+        puts "Try `#{GitFlow.program} help` to obtain a list of commands."
+      end
+    end
+  end
+
+  class HelpCommand < GitFlow/:help
+    @help = "Display help for a command or show command list"
+    @documentation = "Displays help for the command given as argument"
+    
+    def execute(opts, argv)
+      if argv.empty?
+        opt = GitFlow.optparse
+        opt.banner = "Usage: #{GitFlow.program} command [options]"
+        opt.separator ' '
+        opt.separator 'COMMANDS'
+        opt.separator ' '
+        commands = GitFlow.commands.map { |name, cls| [nil, name, cls.help] }.
+          sort_by { |a| a[1] || '' }
+        commands.each { |a| opt.separator("%-2s%-25s%s" % a) if a[1] }
+        opt.separator ' '
+        opt.separator 'You can also obtain help for any command giving it --help.'
+        page { puts opt }
+      else
+        run(*(argv + ['--help']))
+      end
+    end
+  end
+    
+end
+
+at_exit { GitFlow.run(*ARGV) if GitFlow.should_run }

data/doc/scripts/install-jruby.sh

@@ -14,11 +14,11 @@
 # License for the specific language governing permissions and limitations under
 # the License.
 if [ -z `which jruby` ] ; then
-  version=1.1
+  version=1.1.6
   target=/opt/jruby
   echo "Installing JRuby ${version} in ${target}"
   sudo mkdir -p $(dirname ${target})
-  wget http://dist.codehaus.org/jruby/jruby-bin-${version}.tar.gz
+  wget http://dist.codehaus.org/jruby/${version}/jruby-bin-${version}.tar.gz
   tar -xz < jruby-bin-${version}.tar.gz
   sudo mv jruby-${version} ${target}
   rm jruby-bin-${version}.tar.gz

data/doc/scripts/install-linux.sh

@@ -26,12 +26,12 @@ if [ -z `which ruby` ] ; then
     sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential 
     # RubyGems broken on Ubunutu, installing directly from source.
     echo "Installing RubyGems from RubyForge"
-    wget http://rubyforge.org/frs/download.php/38646/rubygems-1.2.0.tgz 
-    tar xzf rubygems-1.2.0.tgz
-    cd rubygems-1.2.0
+    wget http://rubyforge.org/frs/download.php/45905/rubygems-1.3.1.tgz
+    tar xzf rubygems-1.3.1.tgz
+    cd rubygems-1.3.1
     sudo ruby setup.rb
     cd ..
-    rm -rf rubygems-1.2.0
+    rm -rf rubygems-1.3.1
     # ruby is same as ruby1.8, we need gem that is same as gem1.8
     sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
   else
@@ -46,8 +46,8 @@ if [ -z $JAVA_HOME ] ; then
   exit 1
 fi
 
-if [ $(gem --version) \< '1.0.1' ] ; then
-  echo "Upgrading to RubyGems 1.0.1"
+if [ $(gem --version) \< '1.3.1' ] ; then
+  echo "Upgrading to latest version of RubyGems"
   sudo gem update --system
   echo
 fi

data/doc/scripts/install-osx.sh

@@ -34,8 +34,8 @@ if [ -z $JAVA_HOME ] ; then
   export JAVA_HOME=/Library/Java/Home
 fi
 
-if [ $(gem --version) \< '1.0.1' ] ; then
-  echo "Upgrading to RubyGems 1.0.1"
+if [ $(gem --version) \< '1.3.1' ] ; then
+  echo "Upgrading to latest version of RubyGems"
   sudo gem update --system
   echo
 fi

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

@@ -1,30 +1,39 @@
-h1. Settings/Profiles
+---
+layout: default
+title: Settings/Profiles
+---
 
 
-h2.  Environment Variables
+h2(#env_vars).  Environment Variables
 
 Buildr uses several environment variables that help you control how it works. Some environment variables you will only set once or change infrequently.  You can set these in your profile, OS settings or any tool you use to launch Buildr (e.g. continuous integration).
 
 For example:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ export HTTP_PROXY=http://myproxy:8080
-}}}
+{% endhighlight %}
+</notextile>
 
 There are other environment variables you will want to set when running Buildr, for example, to do a full build without running the tests:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ buildr test=no
-}}}
+{% endhighlight %}
+</notextile>
 
 For convenience, when you set environment variables on the command line, the variable name is case insensitive, you can use either @test=no@ or @TEST=no@. Any other way (@export@, @ENV@, etc) the variable names are case sensitive.
 
 You can also set environment variables from within your Buildfile.  For example, if you discover that building your project requires gobs of JVM heap space, and you want all other team members to run with the same settings:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 # This project builds a lot of code.
 ENV['JAVA_OPTS'] ||= '-Xms1g -Xmx1g'
-}}}
+{% endhighlight %}
+</notextile>
 
 Make sure to set any environment variables at the very top of the Buildfile, above any Ruby statement (even @require@).
 
@@ -36,25 +45,28 @@ Buildr supports the following environment variables:
 | @BUILDR_ENV@  | Environment name (development, production, test, etc). Another way to set this is using the @-e@ command line option. |
 | @DEBUG@       | Set to @no/off@ if you want Buildr to compile without debugging information (default when running the @release@ task, see "Compiling":building.html#compiling). |
 | @HOME@        | Your home directory. |
-| @HTTP_PROXY@  | URL for HTTP proxy server (see "Specifying Repositories":artifacts.html#specifying_repositories). |
+| @HTTP_PROXY@  | URL for HTTP proxy server (see "Specifying Repositories":artifacts.html#repositories). |
+| @HTTPS_PROXY@ | URL for HTTPS proxy server (see "Specifying Repositories":artifacts.html#repositories). |
 | @JAVA_HOME@   | Points to your JDK, required when using Java and Ant. |
 | @JAVA_OPTS@   | Command line options to pass to the JDK (e.g. @'-Xms1g'@). |
 | @M2_REPO@     | Location of the Maven2 local repository.  Defaults to the @.m2@ directory in your home directory (@ENV['HOME']@). |
-| @NO_PROXY@    | Comma separated list of hosts and domain that should not be proxied (see "Specifying Repositories":artifacts.html#specifying_repositories).  |
-| @TEST@        | Set to @no/off@ to tell Buildr to skip tests, or @all@ to tell Buildr to run all tests and ignore failures (see "Running Tests":testing.html#running_tests). |
+| @NO_PROXY@    | Comma separated list of hosts and domain that should not be proxied (see "Specifying Repositories":artifacts.html#repositories).  |
+| @TEST@        | Set to @no/off@ to tell Buildr to skip tests, or @all@ to tell Buildr to run all tests and ignore failures (see "Running Tests":testing.html#running). |
 | @USER@        | Tasks that need your user name, for example to log to remote servers, will use this environment variable. |
 
 p(note). Buildr does not check any of the arguments in @JAVA_OPTS@.  A common mistake is to pass an option like @mx512mb@, where it should be @Xmx512mb@. Make sure to double check @JAVA_OPTS@.
 
 Some extensions may use additional environment variables, and of course, you can always add your own.  This example uses two environment variables for specifying the username and password:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 repositories.upload_to[:username] = ENV['USERNAME']
 repositories.upload_to[:password] = ENV['PASSWORD']
-}}}
+{% endhighlight %}
+</notextile>
 
 
-h2. Personal Settings
+h2(#personal). Personal Settings
 
 Some things clearly do not belong in the Buildfile.  For example, the username and password you use to upload releases.  If you're working in a team or on an open source project, you'd want to keep these in a separate place.
 
@@ -64,7 +76,8 @@ The prefered way to store personal settings is to create a @.buildr/settings.yam
 
 Here's an example @settings.yaml@:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 # The repositories hash is read automatically by buildr.
 repositories:
 
@@ -87,26 +100,30 @@ im:
   server: jabber.company.com
   usr: notifier@company-jabber.com
   pwd: secret
-}}}
+{% endhighlight %}
+</notextile>
 
 Later your buildfile or addons can reference user preferences using the  hash returned by the @Buildr.settings.user@ accessor.
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 task 'relase-notification' do
  usr, pwd, server = settings.user['im'].values_at('usr', 'pwd', 'server')
  jabber = JabberAPI.new(server, usr, pwd)
  jabber.msg("We are pleased to announce the last stable version #{VERSION}")
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 
-h2. Build Settings
+h2(#build). Build Settings
 
 Build settings are local to the project being built, and are placed in the @build.yaml@ file located in the same directory that the @buildfile@. Normally this file would be managed by the project revision control system, so settings here are shared between developers.
 
 They help keep the buildfile and build.yaml file simple and readable, working to the advantages of each one.  Example for build settings are gems, repositories and artifacts used by that build.
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 # This project requires the following ruby gems, buildr addons
 gems: 
   # Suppose we want to notify developers when testcases fail.
@@ -133,22 +150,26 @@ twitter:
 
 jira: 
   uri: https://jira.corp.org
-}}}
+{% endhighlight %}
+</notextile>
 
 When buildr is loaded, required ruby gems will be installed if needed, thus adding features like the imaginary twitter notifier addon.
 
 Artifacts defined on @build.yaml@ can be referenced on your buildfile by supplying the ruby symbol to the @Buildr.artifact@ and @Buildr.artifacts@ methods.  The @compile.with@, @test.with@ methods can also be given these names.
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 define 'my_project' do 
   compile.with artifacts(:log4j, :j2ee)
   test.with :spring, :j2ee
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 Build settings can be retreived using the @Buildr.settings.build@ accessor.
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
  task 'create_patch' do 
    patch = Git.create_patch :interactive => true
    if patch && agree("Would you like to request inclusion of #{patch}")
@@ -156,9 +177,11 @@ Build settings can be retreived using the @Buildr.settings.build@ accessor.
      jira.create(:improvement, patch.summary, :attachment => patch.blob)
    end
  end
-}}}
+{% endhighlight %}
+</notextile>
 
-h2. Non constant settings
+
+h2(#variable). Non constant settings
 
 Before loading the Buildfile, Buildr will attempt to load two other files: the @buildr.rb@ file it finds in your home directory, followed by the @buildr.rb@ file it finds in the build directory.
 
@@ -166,44 +189,52 @@ The loading order allows you to place global settings that affect all your build
 
 Here's an example @buildr.rb@:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 # Only I should know that
 repositories.upload_to[:username] = 'assaf'
 repositories.upload_to[:password] = 'supersecret'
 # Search here first, it's faster
 repositories.remote << 'http://inside-the-firewall'
-}}} 
+{% endhighlight %}
+</notextile> 
 
 
-h2. Environments
+h2(#environments). Environments
 
 One common use case is adapting the build to different environments.  For example, to compile code with debugging information during development and testing, but strip it for production.  Another example is using different databases for development, testing and production, or running services at different URLs.
 
 So let's start by talking about the build environment.  Buildr has a global attributes that indicates which environment it's running in, accessible from the @environment@ method.  You can set the current build environment in one of two ways.  Using the @-e/--environment@ command line option:
 
-{{{!sh
+<notextile>
+{% highlight sh %}
 $ buildr -e test
 (in /home/john/project, test)
-}}}
+{% endhighlight %}
+</notextile>
 
 Or by setting the environment variable @BUILDR_ENV@:
 
-{{{!
+<notextile>
+{% highlight text %}
 $ export BUILDR_ENV=production
 $ buildr
 (in /home/john/project, production)
-}}}
+{% endhighlight %}
+</notextile>
 
 Unless you tell it otherwise, Buildr assumes you're developing and sets the environment to @development@.
 
 Here's a simple example for handling different environments within the Buildfile:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 project 'db-module' do
   db = (environment == 'production' ? 'oracle' : 'hsql')
-  resources.from(_(:source, :main, db))
+  resources.from(_("src/main/#{db}"))
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 We recommend picking a convention for your different environments and following it across all your projects.  For example:
 
@@ -213,7 +244,7 @@ We recommend picking a convention for your different environments and following
 | production    | Building for release/production. |
 
 
-h2.  Profiles
+h2(#profiles).  Profiles
 
 Different environments may require different configurations, some you will want to control with code, others you will want to specify in the profiles file.
 
@@ -221,7 +252,8 @@ The profiles file is a YAML file called @profiles.yaml@ that you place in the sa
 
 For example, to support three different database configurations, we could write:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 # HSQL, don't bother storing to disk.
 development:
   db: hsql
@@ -236,19 +268,22 @@ test:
 production:
   db: oracle
   jdbc: oracle:thin:@bigstrong:1521:mighty
-}}}
+{% endhighlight %}
+</notextile>
 
 Here's a simple example for a buildfile that uses the profile information:
 
-{{{!ruby
+<notextile>
+{% highlight ruby %}
 project 'db-module' do
   # Copy SQL files specific for the database we're using,
   # for example, everything under src/main/hsql.
-  resources.from(_(:source, :main, profile['db']))
+  resources.from(_("src/main/#{Buildr.settings.profile['db']}"))
   # Set the JDBC URL in copied resource files (config.xml needs this).
-  resources.filter :jdbc=>profile['jdbc']
+  resources.filter.using :jdbc=>Buildr.settings.profile['jdbc']
 end
-}}}
+{% endhighlight %}
+</notextile>
 
 The @profile@ method returns the current profile, selected based on the current "environment":#environments.  You can get a list of all profiles by calling @profiles@.
 
@@ -258,7 +293,8 @@ We recommend following conventions and using the same environments in all your p
 
 YAML allows you to use anchors (@&@), similar to ID attributes in XML, reference the anchored element (@*@) elsewhere, and merge one element into another (@<<@).  For example:
 
-{{{!yaml
+<notextile>
+{% highlight yaml %}
 # We'll reference this one as common.
 development: &common
   db: hsql
@@ -269,6 +305,8 @@ development: &common
 test:
   <<: *common
   jdbc: hsqldb:file:testdb
-}}}
+{% endhighlight %}
+</notextile>
+
 
 You can "learn more about YAML here":http://www.yaml.org, and use this handy "YAML quick reference":http://www.yaml.org/refcard.html.