gitbak 0.3.0 → 0.4.0

data/README.md

@@ -2,10 +2,10 @@
 
     File        : README
     Maintainer  : Felix C. Stegerman <flx@obfusk.net>
-    Date        : 2012-12-29
+    Date        : 2013-01-03
 
-    Copyright   : Copyright (C) 2012  Felix C. Stegerman
-    Version     : v0.3.0
+    Copyright   : Copyright (C) 2013  Felix C. Stegerman
+    Version     : v0.4.0
 
 <!-- }}}1 -->
 
@@ -14,30 +14,73 @@
 
   gitbak - bitbucket/github/gist backup
 
-  GitBak allows you to mirror Bitbucket/GitHub/Gist repositories
-  easily; you only need to specify paths, users, and authentication in
-  ~/.gitbak and it does the rest.
+  GitBak mirrors Bitbucket/GitHub/Gist repositories; paths, users, and
+  authentication are specified in ~/.gitbak.
+
+  When run, gitbak:
+
+  * asks for unspecified passwords;
+  * lists repositories using APIs - authenticating if necessary;
+  * clones/updates repositories;
+  * shows a summary (if verbose)
 
 <!-- }}}1 -->
 
 ## Usage
 <!-- \{{{1 -->
 
-    $ gitbak --help                 # read documentation
-    $ vim ~/.gitbak                 # configure
-    $ gitbak -v                     # mirror
+    $ gitbak --help                   # show options
+    $ vim ~/.gitbak                   # configure
+    $ gitbak -v                       # mirror
+    $ time gitbak -v 2>&1 | tee log   # w/ logfile
+
+  You may want to run gitbak as a cron job.                       TODO
 
 <!-- }}}1 -->
 
 ## Installing
 <!-- \{{{1 -->
 
-    $ gem install gitbak            # rubygems
+    $ gem install gitbak              # rubygems
 
   Get it at https://github.com/obfusk/gitbak.  Depends: git, ruby.
 
 <!-- }}}1 -->
 
+## Configuration
+<!-- \{{{1 -->
+
+### Example
+
+```ruby
+# ~/.gitbak
+
+dir = "#{ Dir.home }/__mirror__/#{ Time.new.strftime '%Y%m%d' }"
+
+GitBak.configure do |auth, services|
+  %w{ bob alice }.each do |u|
+    services.bitbucket  "#{dir}/#{u}/bitbucket", u, auth: true
+    services.github     "#{dir}/#{u}/github"   , u, auth: true
+    services.gist       "#{dir}/#{u}/gist"     , u, auth: true
+  end
+end
+```
+
+### Methods
+
+    auth.<service>        user[, password]
+    services.<service>    dir, user[, options]
+
+  The (default) services are: bitbucket, github, gist.  GitBak will
+  prompt for unspecified passwords.
+
+#### Repository Options
+
+    :auth     can be true (same user) or 'username'.
+    :method   defaults to :ssh.
+
+<!-- }}}1 -->
+
 ## TODO
 <!-- \{{{1 -->
 
@@ -47,6 +90,8 @@
   * tests?
   * better error handling?
 
+<!-- -->
+
   * custom services (should be easy to add already)
   * metadata (issues, wikis, ...)
   * teams/organisations
@@ -54,6 +99,8 @@
   * filtering
   * oauth?
 
+<!-- -->
+
   * specify ssh key(s)?
   * https clone auth?
 

data/bin/gitbak

@@ -3,5 +3,3 @@
 require 'gitbak/exec'
 
 GitBak::Executable.main
-
-# vim: set tw=70 sw=2 sts=2 et fdm=marker :

data/lib/gitbak/config.rb

@@ -1,3 +1,14 @@
+# --                                                            ; {{{1
+#
+# File        : gitbak/config.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-01-03
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
 require 'gitbak/eval'
 require 'gitbak/misc'
 require 'gitbak/services'
@@ -15,45 +26,6 @@ module GitBak
 
     # --
 
-    # description
-    INFO = 'gitbak - bitbucket/github/gist backup'
-
-    # configuration example
-    CONFIG_EX = <<-END.gsub(/^ {6}/, '')                        # {{{2
-      === Example Configuration ===
-
-        $ cat >> ~/.gitbak
-        dir = '/path/to/mirrors/dir'
-
-        GitBak.configure do |auth, repos|
-          %w{ user1 user2 }.each do |u|
-            repos.bitbucket "\#{dir}/\#{u}/bitbucket", u, auth: true
-            repos.github    "\#{dir}/\#{u}/github"   , u, auth: true
-            repos.gist      "\#{dir}/\#{u}/gist"     , u, auth: true
-          end
-        end
-        ^D
-
-
-      === Configuration Methods ===
-
-        auth.<service>    user[, password]
-        repos.<service>   dir, user[, options]
-
-
-      The (default) services are: bitbucket, github, gist.
-      If a password is not specified, gitbak will prompt for it.
-
-
-      === Optional Repository Options ===
-
-        :auth     can be true (same user) or 'username'.
-        :method   defaults to :ssh.
-    END
-                                                                # }}}2
-
-    # --
-
     # configuration base class
     class ServiceCfg                                            # {{{2
       # data
@@ -115,6 +87,7 @@ module GitBak
     # --
 
     # load configuration file
+    # @raise ConfigError unless file returns Cfg
     def self.load (file)                                        # {{{2
       cfg = eval File.read(file), GitBak::Eval.new.binding, file # ???
 

data/lib/gitbak/exec.rb

@@ -1,3 +1,14 @@
+# --                                                            ; {{{1
+#
+# File        : gitbak/exec.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-01-03
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
 require 'gitbak'
 require 'gitbak/config'
 
@@ -7,12 +18,18 @@ require 'optparse'
 
 # gitbak namespace
 module GitBak
+
   # command-line executable
   module Executable
 
+    # description
+    INFO = 'gitbak - bitbucket/github/gist backup'
+
     # command-line usage
     USAGE = 'gitbak [<option(s)>]'
 
+    # --
+
     # parse command line options; die on failure
     def self.parse_options (args)                               # {{{1
       args_   = args.dup
@@ -36,13 +53,7 @@ module GitBak
         end
 
         opts.on_tail('-h', '--help', 'Show this message') do
-          puts GitBak::Config::INFO, '', opts
-          exit
-        end
-
-        opts.on_tail('-e', '--example',
-                     'Show example configuration') do
-          puts GitBak::Config::CONFIG_EX
+          puts INFO, '', opts
           exit
         end
 

data/lib/gitbak/misc.rb

@@ -1,3 +1,14 @@
+# --                                                            ; {{{1
+#
+# File        : gitbak/misc.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-01-03
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
 require 'io/console'
 
 # --
@@ -47,13 +58,28 @@ module GitBak
       line and line.chomp
     end                                                         # }}}1
 
-    # execute command; raises SysError on failure; optionally verbose
-    def self.sys (verbose, cmd, *args)
-      puts "$ #{ ([cmd] + args).join ' ' }" if verbose
+    # execute command
+    # @raise SysError on failure
+    def self.sys_ (cmd, *args)
       system [cmd, cmd], *args or raise SysError,
         "failed to run command #{ ([cmd] + args) } (#$?)"
     end
 
+    # execute command (unless noact); optionally verbose
+    # @see sys_
+    def self.sys (cmd, *args)                                   # {{{1
+      opts = Hash === args.last ? args.pop : {}
+
+      puts "$ #{ ([cmd] + args).join ' ' }" \
+        if opts[:verbose] or opts[:noact]
+
+      if opts[:noact]
+        puts '(not actually doing anything)'
+      else
+        sys_ cmd, *args
+      end
+    end                                                         # }}}1
+
   end
 end
 

data/lib/gitbak/services.rb

@@ -1,3 +1,14 @@
+# --                                                            ; {{{1
+#
+# File        : gitbak/services.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-01-03
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
 require 'gitbak/misc'
 
 require 'json'
@@ -7,7 +18,8 @@ require 'open-uri'
 
 # gitbak namespace
 module GitBak
-  # git services
+
+  # git hosting services
   module Services
 
     # authentication error
@@ -51,6 +63,7 @@ module GitBak
     # --
 
     # get data from API
+    # @raise AuthError on 401
     def self.api_get (service, user, auth)                      # {{{1
       url   = "https://#{APIS[service][user]}"
       opts  = auth ? { AUTH => [auth[:user], auth[:pass]] } : {}
@@ -71,7 +84,8 @@ module GitBak
 
     # get repositories from service; uses api_get if service in APIS,
     # api_get_<service> otherwise
-    #   -> [{name:,remote:,description:},...]
+    #
+    # @return [<Hash>] [!{name:, remote:, description:},...]
     def self.repositories (service, cfg, auth)
       rem   = REMOTES[service][cfg.fetch(:method, :ssh).to_sym]
       args  = [service, cfg[:user], auth]

data/lib/gitbak/version.rb

@@ -1,7 +1,7 @@
 module GitBak
   # version and ...
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 
   # ... date (for gemspec) ;-)
-  DATE = '2012-12-29'
+  DATE = '2013-01-03'
 end

data/lib/gitbak.rb

@@ -1,3 +1,14 @@
+# --                                                            ; {{{1
+#
+# File        : gitbak.rb
+# Maintainer  : Felix C. Stegerman <flx@obfusk.net>
+# Date        : 2013-01-03
+#
+# Copyright   : Copyright (C) 2013  Felix C. Stegerman
+# Licence     : GPLv2
+#
+# --                                                            ; }}}1
+
 require 'gitbak/misc'
 require 'gitbak/services'
 require 'gitbak/version'
@@ -17,23 +28,24 @@ module GitBak
 
   # clone (from remote) or update repository (in dir); optionally
   # verbose
-  def self.mirror_repo (verbose, remote, dir)                   # {{{1
+  def self.mirror_repo (verbose, noact, remote, dir)            # {{{1
     name      = repo_name remote
     name_     = name + '.git'
     repo_dir  = "#{dir}/#{name_}"
 
+    sys = ->(args) { Misc.sys *args, verbose: verbose, noact: noact }
+
     FileUtils.mkdir_p dir
 
     if Misc.exists? repo_dir
-      puts "$ cd #{repo_dir}" if verbose
+      puts "$ cd #{repo_dir}" if verbose or noact
       FileUtils.cd(repo_dir) do
-        Misc.sys verbose, *%w{ git remote update }
+        sys[ %w{ git remote update } ]
       end
     else
-      puts "$ cd #{dir}" if verbose
+      puts "$ cd #{dir}" if verbose or noact
       FileUtils.cd(dir) do
-        Misc.sys verbose,
-          *( %w{ git clone --mirror -n } + [remote, name_] )
+        sys[ %w{ git clone --mirror -n } + [remote, name_] ]
       end
     end
   end                                                           # }}}1
@@ -82,19 +94,19 @@ module GitBak
   end                                                           # }}}1
 
   # mirror repositories; optionally verbose
-  def self.mirror verbose, repos                                # {{{1
+  def self.mirror (verbose, noact, repos)                       # {{{1
     repos.each do |s, usr, dir, rs|
       rs.each do |r|
         name, desc = r[:name], r[:description]
         puts "==> #{s} | #{usr} | #{name} | #{desc} <==" if verbose
-        mirror_repo verbose, r[:remote], dir
+        mirror_repo verbose, noact, r[:remote], dir
         puts if verbose
       end
     end
   end                                                           # }}}1
 
   # print summary
-  def self.summary repos                                        # {{{1
+  def self.summary (repos)                                      # {{{1
     puts '', '=== Summary ===', ''
     repos.each do |service, usr, dir, rs|
       printf "  %-15s for %-20s: %10s repositories\n",
@@ -109,7 +121,7 @@ module GitBak
   def self.main (verbose, noact, config)
     auth, repos   = process_config config
     repositories  = fetch verbose, auth, repos
-    mirror verbose, repositories unless noact
+    mirror verbose, noact, repositories
     summary repositories if verbose
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitbak
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-29 00:00:00.000000000 Z
+date: 2013-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &9773800 !ruby/object:Gem::Requirement
+  requirement: &8112480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,12 +21,22 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *9773800
-description: ! 'GitBak allows you to mirror Bitbucket/GitHub/Gist repositories
+  version_requirements: *8112480
+description: ! 'GitBak mirrors Bitbucket/GitHub/Gist repositories; paths, users,
 
-  easily; you only need to specify paths, users, and authentication
+  and authentication are specified in ~/.gitbak.
 
-  in ~/.gitbak and it does the rest.
+
+  When run, gitbak:
+
+
+  * asks for unspecified passwords;
+
+  * lists repositories using APIs - authenticating if necessary;
+
+  * clones/updates repositories;
+
+  * shows a summary (if verbose)
 
 '
 email: