repo_manager 0.7.1

data/Rakefile

@@ -0,0 +1,94 @@
+# encoding: utf-8
+
+# Bundler is managing $LOAD_PATH, any gem needed by this Rakefile must be
+# listed as a development dependency in the gemspec
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+
+require 'rbconfig'
+WINDOWS = RbConfig::CONFIG['host_os'] =~ /msdos|mswin|win32|mingw/i unless defined?(WINDOWS)
+
+require 'rspec/core/rake_task'
+desc "Run RSpec"
+RSpec::Core::RakeTask.new do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new do |t|
+
+  opts =  []
+  opts <<  ["--color"]
+  opts << ["--format pretty"]
+  opts << ["--strict"]
+  opts << ["-r features"]
+  opts << ["--no-profile"]
+  opts << ["--tags ~@wip"]
+  opts << ["--tags ~@windows"] unless WINDOWS
+  opts << ["--tags ~@posix"] if WINDOWS
+
+  t.cucumber_opts = opts
+end
+
+desc "Run specs, both RSpec and Cucumber"
+task :test => [:spec, :cucumber]
+
+task :default => :test
+
+namespace :doc do
+
+  doc_version = File.open(File.join(File.dirname(__FILE__), 'VERSION'), "r") { |f| f.read }
+  project_root = File.expand_path(File.dirname(__FILE__))
+  doc_destination = File.join(project_root, 'rdoc')
+
+  require 'yard'
+
+  YARD::Rake::YardocTask.new(:generate) do |yt|
+    yt.options = ['--output-dir', doc_destination,
+                  '--title', "RepoManager #{doc_version} Documentation",
+                  '--main', "README.markdown"
+                 ]
+  end
+
+  desc "Remove generated documenation"
+  task :clean do
+    rm_r doc_destination if File.exists?(doc_destination)
+  end
+
+  desc "List undocumented objects"
+  task :undocumented do
+    system('yard stats --list-undoc')
+  end
+
+end
+
+# put the gemfiles task in the bundler dependency chain
+task :build => [:gemfiles]
+task :install => [:gemfiles]
+task :release => [:gemfiles]
+
+desc "Generate .gemfiles via 'git ls-files'"
+task :gemfiles do
+  files = `git ls-files`
+
+  filename  = File.join(File.dirname(__FILE__), '.gemfiles')
+  cached_files = nil
+  if File.exists?(filename)
+    puts ".gemfiles exists, reading..."
+    cached_files = File.open(filename, "rb") {|f| f.read}
+  end
+
+  if cached_files && cached_files.match("\r\n")
+    puts ".gemfiles using DOS EOL"
+    files.gsub!(/\n/, "\r\n")
+  end
+
+  if cached_files != files
+    puts ".gemfiles updating"
+    File.open(filename, 'wb') {|f| f.write(files)}
+  else
+    puts ".gemfiles update not required"
+  end
+
+  raise "unable to process .gemfiles" unless files
+end

data/TODO.markdown

@@ -0,0 +1,15 @@
+TODO
+====
+
+* remove git gem and duplicate needed method.  The use of ENV[] will break on
+  win32 and ruby 1.9.3
+* add find action that finds a repo based on all strings in the repo config
+* provide native repo completion via --completion option so the entire ARGV can
+  be scanned and passed back to bash.  We have to load ruby anyway, might as
+  well provide completion for commands and options too.
+* status should show summary at the end
+* add feature tests for all combinations of XY result codes from 'git status --porcelain'
+* status command should have option to show last commit information
+* native git commands need to preserve ANSI escape codes for coloring
+* add man page via markdown and ronn.  Change 'help' action to call man
+  page if man available.

data/VERSION

@@ -0,0 +1 @@
+0.7.1

data/bin/repo

@@ -0,0 +1,151 @@
+#!/usr/bin/env ruby
+
+require 'repo_manager'
+require 'optparse'
+require 'term/ansicolor'
+require 'fileutils'
+
+available_actions = RepoManager::AVAILABLE_ACTIONS
+
+banner = <<BANNER
+repo: CLI for batch management of multiple Git repositories
+
+  Usage: repo [options] action [filters|action pass-through options] [options]
+BANNER
+banner << "\nActions: #{available_actions.join(' ')}\n" unless available_actions.empty?
+
+help = banner
+help += <<HELP
+
+Use 'repo help' for help on actions.
+
+  repo help task
+  repo help git
+
+Examples:
+
+  repo list my_repo1 my_repo2
+  repo list --filter=my_repo1,my_repo2
+
+  repo list --filter=my.*
+  repo list my.*
+
+  repo --verbose --no-color config --list --filter=my_repo1,my_repo2
+  repo --verbose --no-color config core.autocrlf true filter=my.*
+  repo --verbose --no-color git config --list
+  repo --verbose --no-color config --list
+
+Most Git commands can be passed directly, these are equivalent
+
+  repo add .
+  repo git add .
+
+General options:
+(use 'repo help action' for action options)
+
+HELP
+
+# get options from the command line, these options override both config files
+# and defaults
+options = {}
+optparser = OptionParser.new do |opts|
+  opts.banner = help
+
+  opts.on("-T", "--tasks", "List tasks") do |t|
+    options[:tasks] = t
+  end
+
+  opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
+    options[:verbose] = v
+  end
+
+  opts.on("-c", "--[no-]coloring [MODE]", "--[no-]color [MODE]", "ANSI color in output. MODE=AUTO (default) or ALWAYS") do |c|
+    options[:color] = c.nil? ? "AUTO" : c
+    options[:color].upcase! if options[:color]
+    unless [nil, false, "AUTO", "ALWAYS"].include?(options[:color])
+      puts "repo, invalid color option: #{options[:color]}"
+      exit 1
+    end
+  end
+
+  opts.on("--[no-]config FILE", "Load configuration options from FILE") do |file|
+    options[:config] = file
+  end
+
+  opts.on("--version", "Display current version and exit") do
+    puts "repo_manager, version " + RepoManager.version
+    exit 0
+  end
+
+  # no argument, shows at tail.  This will print an options summary.
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit 0
+  end
+
+end
+
+# first pass, process until the action/subcommand, errors will be raised for
+# invalid options that occur before the action/subcommand
+begin
+  optparser.order!
+rescue OptionParser::InvalidOption => e
+  puts "repo #{e}"
+  puts "repo --help for more information"
+  exit 1
+end
+
+
+# OptionParser is too helpful and matches short options with long.  Before the
+# second pass, replace short git options with long because we can't tell
+# OptionParser to stop matching short options to long.
+ARGV.each_with_index do |arg, index|
+  # check and replace each short git option
+  # that could be parsed by main parser
+  case arg
+    when '-m'
+      ARGV[index] = '--message'
+  end
+end
+
+# second pass find all global options that may come after the action/subcommand
+# and its args, no errors raised, validity will be checked by action parser
+argv = []
+while unknown_arg = ARGV.shift
+  argv << unknown_arg
+  begin
+    optparser.order!
+  rescue OptionParser::InvalidOption => e
+    # put unknown args back on ARGV
+    e.recover(ARGV)
+  end
+end
+
+# settings from config file, if it exists, will not overwrite command line options
+settings = RepoManager::Settings.new(FileUtils.pwd, options)
+color = settings.options[:color]
+
+# add summary of general options for use by action help commands
+configuration = settings.to_hash
+
+if STDOUT.isatty || (color == 'ALWAYS')
+  Term::ANSIColor::coloring = color
+
+  if color && RepoManager::WINDOWS
+    unless ENV['ANSICON']
+      begin
+        require 'Win32/Console/ANSI'
+      rescue LoadError
+        Term::ANSIColor::coloring = false
+        STDERR.puts 'WARNING: You must "gem install win32console" (1.2.0 or higher) or use the ANSICON driver (https://github.com/adoxa/ansicon) to get color output on MRI/Windows'
+      end
+    end
+  end
+
+else
+  Term::ANSIColor::coloring = false
+end
+
+app = RepoManager::App.new(argv, configuration)
+app.option_parser = optparser
+app.execute

data/cucumber.yml

@@ -0,0 +1,28 @@
+<%
+  require 'rbconfig'
+  WINDOWS = RbConfig::CONFIG['host_os'] =~ /msdos|mswin|win32|mingw/i unless defined?(WINDOWS)
+
+  opts =  []
+  opts << ["--color"]
+  opts << ["--format pretty"]
+  opts << ["--strict"]
+  opts << ["-r features"]
+  opts << ["--no-profile"]
+  opts << ["--tags ~@wip"]
+  opts << ["--tags ~@windows"] unless WINDOWS
+  opts << ["--tags ~@posix"] if WINDOWS
+
+  std_opts = opts.join(' ')
+  rerun = File.file?('rerun.txt') ? IO.read('rerun.txt') : ""
+  rerun_opts = rerun.to_s.strip.empty? ? "--format pretty" : "--format pretty #{rerun}"
+
+%>
+# define cucumber profiles
+#
+# Example usage:
+#
+#     bundle exec cucumber --profile wip
+---
+default: <%= std_opts %> -r features
+wip: --tags @wip:3 --wip -r features
+rerun: <%= rerun_opts %> --format rerun --out rerun.txt --strict --tags ~@wip -r features

data/examples/pc_saved_game_backup/.gitignore

@@ -0,0 +1,2 @@
+/repo.log
+/repo_manager/tmp

data/examples/pc_saved_game_backup/INSTALL.markdown

@@ -0,0 +1,420 @@
+Creating the RepoManager Saved Game Backup Configuration
+====================================================
+
+> NOTE for Windows users
+>
+> The given instruction are intended for a Bash shell.  Bash is not
+> required to use RepoManager, but it does make using the command prompt much
+> more flexible and productive. The MSYS distribution of portable Git
+> includes a lean and stable Bash environment.
+
+Initial configuration
+---------------------
+
+### install repo_manager
+
+    gem install repo_manager
+
+### create configuration
+
+The following commands were used to create this example folder from
+scratch.
+
+    mkdir -p examples/pc_saved_game_backup && cd examples/pc_saved_game_backup
+
+Create configuration structure with the built-in 'generate:init' task
+
+> NOTE
+>
+> We are creating a local configuration.  For a global configuration, you would
+> execute the init command in your home folder
+
+    repo generate:init repo_manager
+
+We are going to keep this under version control
+
+    git init
+    git add .
+    git commit -m "initial commit"
+    echo "/repo.log" > .gitignore
+    echo "/repo_manager/tmp" >> .gitignore
+
+Change the generated paths from absolute to relative to make this example
+portable.
+
+    diff --git a/repo_manager/repo.conf b/repo_manager/repo.conf
+    index ce4418d..3cc6dbe 100644
+    --- a/repo_manager/repo.conf
+    +++ b/repo_manager/repo.conf
+    @@ -11,7 +11,7 @@ options:
+     folders:
+
+       # main repo configuration files
+    -  assets  : /home/robert/examples/pc_saved_game_backup/repo_manager/assets
+    +  assets  : assets
+
+       #
+       # repo user tasks, file extentions can be '.rb' or '.thor'
+    @@ -26,7 +26,7 @@ folders:
+       #
+       #         c:/dat/condenser/tasks
+       #
+    -  tasks        : /home/robert/examples/pc_saved_game_backup/repo_manager/tasks
+    +  tasks        : tasks
+
+     # git commands must be whitelisted
+     commands:
+    @@ -55,7 +55,7 @@ logging:
+           name          : logfile
+           level         : info
+           truncate      : true
+    -      filename      : '/home/robert/examples/pc_saved_game_backup/repo_manager/repo.log'
+    +      filename      : 'repo.log'
+           layout:
+             type        : Pattern
+             pattern     : '[%d] %l %c : %m\n'
+
+### add sample data
+
+Add a few example save game folder.  These folders would normally be
+scattered over the file system.
+
+mines
+
+    mkdir -p saved_games/mines/saves
+
+    # profile data will not be stored in the Git repo since it may differ from PC to PC
+    echo "# dummy profile data" > mines/my_profile.ini
+
+    echo "# dummy save" > saved_games/mines/saves/save1
+    echo "# dummy save" > saved_games/mines/saves/save2
+
+hearts
+
+    mkdir -p saved_games/hearts
+
+    echo "# dummy save" > saved_games/hearts/save1
+    echo "# dummy save" > saved_games/hearts/save2
+
+### create remote folder
+
+This folder will act as a remote to hold bare Git repositories. These
+repos will store backups of our game saves, normally, this folder would be
+on a remote server, NAS, or Drop Box like service.
+
+    mkdir remote
+
+remote/.gitignore
+
+    *
+    !/.gitignore
+
+
+Create the specialized 'git init' task
+--------------------------------------
+
+User tasks can be added directly to the repo_manager/tasks folder.  This one
+is 'repo_manager/tasks/remote.rb'.  It doesn't use any RepoManager specific features,
+instead, it calls git directly via Thor's 'run' command. Adding the script
+this way will keep this related functionality with this specific RepoManager
+configuration.  Run 'repo -T' to see a full list of built-in tasks as well
+as user defined tasks.
+
+repo_manager/tasks/remote.rb
+
+    require 'fileutils'
+
+    module RepoManager
+
+      class Generate < Thor
+
+        # full path to the remote folder
+        REMOTE = File.expand_path('remote')
+
+        # Create, add, and commit the contents of the current working directory and
+        # then push it to a predefined remote folder
+        #
+        # @example From the repo working
+        #
+        #   cd ~/my_repo_name
+        #   repo generate:remote my_repo_name
+        #
+        # @example Specify the path to the working folder
+        #
+        #   repo generate:remote my_repo_name --path=/path/to/my_repo_name
+
+        method_option :remote, :type => :string, :desc => "remote folder or git host, defaults to '#{REMOTE}'"
+        method_option :path, :type => :string, :desc => "path to working folder, defaults to CWD"
+
+        desc "remote REPO_NAME", "init a git repo in CWD and push to remote '#{REMOTE}'"
+        def remote(name)
+          path = options[:path] || FileUtils.pwd
+          remote = options[:remote] || "#{File.join(REMOTE, name + '.git')}"
+
+          Dir.chdir path do
+            run("git init")
+
+            # core config with windows in mind but works fine on POSIX
+            run("git config core.autocrlf false")
+            run("git config core.filemode false")
+            exit $?.exitstatus if ($?.exitstatus > 1)
+
+            # add everthing and commit
+            run("git add .")
+            run("git commit --message #{shell_quote('initial commit')}")
+            exit $?.exitstatus if ($?.exitstatus > 1)
+
+            # remove old origin first, if it exists
+            run("git remote add origin #{remote}")
+            run("git config branch.master.remote origin")
+            run("git config branch.master.merge refs/heads/master")
+            exit $?.exitstatus if ($?.exitstatus > 1)
+          end
+
+          run("git clone --bare #{shell_quote(path)} #{remote}")
+          exit $?.exitstatus if ($?.exitstatus > 1)
+
+          say "init done on '#{name}'", :green
+        end
+
+      end
+    end
+
+### add remotes
+
+In one step, we will initialize a new git repository with the working folder's
+content and push to a new bare repository for backup.
+
+> Normally, you don't need to specify the --path if you are already in the
+> working folder and the repo_manager can find its global config file.  For this
+> example, we are using relative paths and will specify the working folder
+> on the command line via the '--path' option.
+
+    repo generate:remote mines --path=saved_games/mines/saves
+    repo generate:remote hearts --path=saved_games/hearts
+
+### create the repo_manager asset configuration files
+
+    repo add:asset saved_games/mines/saves --name=mines --force
+    repo add:asset saved_games/hearts --force
+
+
+Create the specialized Update task
+----------------------------------
+
+repo_manager/tasks/update.rb
+
+    module RepoManager
+      class Action < Thor
+        namespace :action
+        include Thor::Actions
+        include RepoManager::ThorHelper
+
+        class_option :force, :type => :boolean, :desc => "Force overwrite and answer 'yes' to any prompts"
+
+        method_option :repos, :type => :string, :desc => "Restrict update to comma delimited list of repo names", :banner => "repo1,repo2"
+        method_option :message, :type => :string, :desc => "Override 'automatic commit' message"
+        method_option 'no-push', :type => :boolean, :default => false, :desc => "Force overwrite of existing config file"
+
+        desc "update", "run repo add -A, repo commit, and repo push on all modified repos"
+        def update
+
+          initial_filter = options[:repos] ? "--repos=#{options[:repos]}" : ""
+          output = run("repo status --short --unmodified=HIDE --no-verbose --no-color #{initial_filter}", :capture => true)
+
+          case $?.exitstatus
+            when 0
+              say 'no changed repos', :green
+            else
+
+              unless output
+                say "failed to successfully run 'repo status'", :red
+                exit $?.exitstatus
+              end
+
+              repos = []
+              output = output.split("\n")
+              while line = output.shift
+                st,repo = line.split("\t")
+                repos << repo
+              end
+              filter = repos.join(',')
+
+              unless options[:force]
+                say "Repo(s) '#{filter}' have changed."
+                unless ask("Add, commit and push them? (y/n)") == 'y'
+                  say "aborting"
+                  exit 0
+                end
+              end
+
+              say "updating #{filter}"
+
+              run "repo add -A --no-verbose --repos #{filter}"
+              exit $?.exitstatus if ($?.exitstatus > 1)
+
+              commit_message = options[:message] || "automatic commit @ #{Time.now}"
+              run "repo commit --message=#{shell_quote(commit_message)} --no-verbose --repos #{filter}"
+              exit $?.exitstatus if ($?.exitstatus > 1)
+
+              unless options['no-push']
+                run "repo push --no-verbose --repos #{filter}"
+                exit $?.exitstatus if ($?.exitstatus > 1)
+              end
+
+              say "update finished", :green
+            end
+
+        end
+      end
+    end
+
+### whitelist non-default Git commands
+
+Only a small subset of non-destructive git commands are enabled by default.  We will
+add the commands needed by our user task to the commands whitelist.
+
+Add 'push, add, and commit' to the commands whitelist
+
+    diff --git a/repo_manager/repo.conf b/repo_manager/repo.conf
+    index 3cc6dbe..226b8c0 100644
+    --- a/repo_manager/repo.conf
+    +++ b/repo_manager/repo.conf
+    @@ -36,6 +36,9 @@ commands:
+     - ls-files
+     - show
+     - status
+    +- push
+    +- add
+    +- commit
+
+Testing user tasks with Cucumber
+--------------------------------------
+
+### Add a Gemfile for use by Bundler
+
+repo_manager/Gemfile
+
+    source "http://rubygems.org"
+
+    gem "repo_manager"
+
+    gem "bundler", ">= 1.0.14"
+    gem "rspec", ">= 2.6.0"
+    gem "cucumber", "~> 1.0"
+    gem "aruba", "= 0.4.5"
+
+    gem "win32console", :platforms => [:mingw, :mswin]
+
+### Install the dependencies
+
+    gem install bundler
+
+    cd repo_manager
+    bundle
+
+### Add Cucumber features and support files
+
+repo_manager/features/tasks/update.feature
+
+> NOTE: This is an excerpt, see the file for the full listing of functional tests
+
+    @announce
+    Feature: Automatically commit and update multiple repos
+
+      Background: Test repositories and a valid config file
+        Given a repo in folder "test_path_1" with the following:
+          | filename         | status | content  |
+          | .gitignore       | C      |          |
+        And a repo in folder "test_path_2" with the following:
+          | filename         | status | content  |
+          | .gitignore       | C      |          |
+        And a file named "repo.conf" with:
+          """
+          ---
+          folders:
+            assets : repo/asset/configuration/files
+          """
+        And the folder "repo/asset/configuration/files" with the following asset configurations:
+          | name    | path         |
+          | test1   | test_path_1  |
+          | test2   | test_path_2  |
+
+
+      Scenario: No uncommitted changes
+        When I run `repo action:update`
+        Then the output should contain:
+          """
+          no changed repos
+          """
+
+      ...
+
+repo_manager/features/support/steps.rb
+
+    require 'repo_manager/test/base_steps'
+    require 'repo_manager/test/asset_steps'
+    require 'repo_manager/test/repo_steps'
+
+repo_manager/features/support/env.rb
+
+    require 'repo_manager'
+    require 'aruba/cucumber'
+    require 'rspec/expectations'
+
+repo_manager/features/support/aruba.rb
+
+    require 'aruba/api'
+    require 'fileutils'
+
+    module Aruba
+      module Api
+
+        # override aruba avoid 'current_ruby' call and make sure
+        # that binary run on Win32 without the binstubs
+        def detect_ruby(cmd)
+          wrapper = which('repo')
+          cmd = cmd.gsub(/^repo/, "ruby -S #{wrapper}") if wrapper
+          cmd
+        end
+      end
+    end
+
+### Run tests
+
+    bundle exec cucumber
+
+Bash completion
+---------------
+
+Handy functions for use under Bash.  These work fine on Win32 using
+Git-Bash.
+
+### CD command for working folders
+
+rpushd: repo pushd (push directory).  Wrapper for 'pushd'.
+
+### Completion for repo names
+
+rcd: repo cd (change directory).  Wrapper for 'cd', allows for simple cd <repo
+name> to the working folder on the filesystem referenced by the 'path'
+configuration variable.
+
+Source these functions in your .bashrc
+
+    function rcd(){ cd "$(repo --match=ONE --no-color path $@)"; }
+    function rpushd(){ pushd "$(repo path --match=ONE --no-color $@)"; }
+    alias rpopd="popd"
+
+    # provide completion for repo names
+    function _repo_names()
+    {
+      local cur opts prev
+      COMPREPLY=()
+      cur="${COMP_WORDS[COMP_CWORD]}"
+      opts=`repo list --list=name --no-color`
+
+      COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+      return 0
+    }
+    complete -F _repo_names rcd rpushd repo