forkreadme 0.0.1 → 0.0.2

data/.gitignore

@@ -1 +1,2 @@
 Gemfile.lock
+*.gem

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Adam Mckaig
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,34 @@
+This is a command-line utility for generating READMEs for GitHub forks.
+
+I have quite a few forks of popular repos which contain no useful indication of
+why they exist. Mostly they're hanging around waiting for a pull request to be
+merged into or rejected from the upstream repo. And since my changes are tucked
+away in feature branches, it's not immediately obvious to visitors (or me) why I
+created the fork, what I changed, and whether those changes have been merged
+upstream.
+
+My solution is to replace the `README.md` in the master branch of my fork with a
+note detailing what and why.  
+This tool does that automatically.
+
+
+## Usage
+
+```bash
+$ gem install forkreadme
+$ forkreadme generate
+```
+
+Here's an [example of the output] [example].
+
+
+## License
+
+[Fork README] [repo] is available under the [MIT license] [license].
+
+
+
+
+[repo]:    https://github.com/adammck/forkreadme
+[license]: https://raw.github.com/adammck/forkreadme/master/LICENSE
+[example]: https://github.com/adammck/grit

data/bin/forkreadme

@@ -2,24 +2,29 @@
 # vim: et ts=2 sw=2
 
 require "forkreadme"
-require "thor"
-
-module ForkReadme
-  class App < Thor
-
-    desc "generate [DIR]", "Generate a README for a GitHub fork repo"
-    method_option :path, :default=>"."
-    def generate path=""
-      begin
-        dir = File.expand_path path, Dir.pwd
-        puts Generator.new(dir).readme
-
-      rescue ForkReadme::Error => err
-        $stderr.puts err
-        exit false
-      end
-    end
-  end
+require "trollop"
+
+BANNER = <<EOT
+ForkReadme generates a README.md for GitHub forks, containing a list of the pull requests submitted upstream.
+
+Usage:
+  forkreadme [options] [path]
+
+Options:
+EOT
+
+opts = Trollop::options do
+  banner BANNER
+  opt :pullstatus, "Include pullstat.us images", :short=>"i", :type=>:bool, :default=>true
 end
 
-ForkReadme::App.start
+path = ARGV.shift || "."
+
+begin
+  dir = File.expand_path path, Dir.pwd
+  puts ForkReadme::Generator.new(dir, opts[:pullstatus]).readme
+
+rescue ForkReadme::Error => err
+  $stderr.puts err
+  exit false
+end

data/forkreadme.gemspec

@@ -6,13 +6,14 @@ require File.expand_path("../lib/forkreadme/version", __FILE__)
 Gem::Specification.new do |gem|
   gem.name          = "forkreadme"
   gem.version       = ForkReadme::VERSION
+  gem.license       = "MIT"
 
   gem.authors       = ["Adam Mckaig"]
   gem.email         = ["adam.mckaig@gmail.com"]
   gem.summary       = %q{Generate useful READMEs for GitHub forks}
   gem.homepage      = "https://github.com/adammck/forkreadme"
 
-  gem.add_dependency "thor", "~> 0.14.6"
+  gem.add_dependency "trollop", "~> 1.16.2"
   gem.add_dependency "octokit", "~> 1.0.2"
 
   gem.files         = `git ls-files`.split($\)

data/lib/forkreadme/errors.rb

@@ -4,10 +4,13 @@
 module ForkReadme
   class Error < StandardError
   end
-  
-  class NotRepo < Error
+
+  class NotGitRepo < Error
+  end
+
+  class NotGitHubRepo < Error
   end
-  
+
   class NotFork < Error
   end
 end

data/lib/forkreadme/generator.rb

@@ -8,56 +8,83 @@ module ForkReadme
   class Generator
     include URI::REGEXP::PATTERN
 
-    def initialize dir
-      @dir = dir
+    def initialize path, with_images
+      @path = path
+      @with_images = with_images
+
+      repo_name = github_repo_name @path
+      @repo = octokit.repo repo_name
+      @parent = parent_of @repo
     end
 
     def readme
-      repo_name = github_repo_name @dir
+      intro + "\n\n" + (links.join "\n")
+    end
 
-      if repo_name.empty?
-        raise NotRepo.new "Not a GitHub repo: #{@dir}"
-      end
+    # Public: Returns the introduction paragraph.
+    def intro
+      link = link_to(@parent.name, @parent.html_url)
+      "This is a fork of #{link}, with pull requests:"
+    end
 
-      repo = octokit.repo repo_name
+    # Public: Returns a paragraph summarizing the pull requests.
+    def links
+      pull_requests(@parent).select do |pull|
+        pull.head.repo.id == @repo.id
 
-      unless repo.fork
-        raise NotFork.new "Not a GitHub fork: #{repo_name}"
+      end.map do |pull|
+        "* " + line_for(pull, @with_images)
       end
+    end
 
-      parent_name = full_name repo.parent
-      parent = octokit.repo parent_name
-
-      s = []
-      s << "This is a fork of [#{parent.name}] (#{parent.html_url}), with pull requests:"
-      s << ""
+    private
 
-      logins = collaborator_logins repo
-      my_pulls = pull_requests(parent).select do |pull|
-        pull.user and logins.include?(pull.user.login)
+    # Private: Returns a line of Markdown summarizing a pull request.
+    def line_for pull_request, with_images
+      img = if with_images
+        image "Status of ##{pull_request.number}", status_image(pull_request)
       end
 
-      my_pulls.each do |short_pull|
-        pull = pull_request(parent, short_pull.number)
-        if repo_name == full_name(pull.head.repo)
-          s << " * [#{pull.title}] (#{pull.html_url})"
-        end
+      suffix = img ? (" " + img) : ""
+      link_to(pull_request.title, pull_request.html_url) + suffix
+    end
+
+    # Private: Returns the parent repo (as an Octokit repo) of an Octokit repo,
+    # or raises NotFork if the repo does not have a parent.
+    def parent_of child_repo
+      if child_repo.parent
+        parent_repo_name = full_name child_repo.parent
+        octokit.repo parent_repo_name
+      else
+        child_name = full_name child_repo
+        raise NotFork.new "Not a GitHub fork: #{child_name}"
       end
+    end
 
-      s.join "\n"
+    # Private: Returns a link in Markdown format.
+    def link_to text, href
+      "[#{text}] (#{href})"
     end
-  
-  
-    private
-  
-    # Private: Returns an Array containing the logins of all collaborators for an
-    # Octokit repo.
+
+    # Private: Returns an image in Markdown format.
+    def image alt_text, href
+      "!" + link_to(alt_text, href)
+    end
+
+    # Private: Returns an Array containing the logins of all collaborators for
+    # an Octokit repo.
     def collaborator_logins repo
       octokit.collabs(full_name repo).map do |user|
         user.login
       end
     end
-  
+
+    # Private: Returns the URL of the status image (via pullstat.us) for an
+    # Octokit pull request.
+    def status_image pull_request
+      pull_request.html_url.sub "github.com", "pullstat.us"
+    end
+
     # Private: Returns all pull request summaries (as returned by the "List pull
     # requests" API, and wrapped by Octokit) for an Octokit repo.
     def pull_requests repo
@@ -68,16 +95,16 @@ module ForkReadme
       end
     end
   
-    # Private: Return full pull request (as returned by the "Get a single pull
-    # request" API, and wrapped by Octokit) to an Octokit repo and pull number.
-    def pull_request repo, number
-      octokit.pull full_name(repo), number
-    end
-  
-    # Private: Returns the full GitHub repo name of a Git working directory.
+    # Private: Returns the full GitHub repo name (e.g. adammck/forkreadme) of a
+    # Git working directory, or raises NotGitHubRepo.
     def github_repo_name path
       clone_url = parse_url remote_url path
-      chop_extension clone_url.path
+
+      if clone_url.host.downcase != "github.com"
+        raise NotGitHubRepo.new "Not a GitHub repo: #{path}"
+      end
+
+      chop_extension chop_leading_slash clone_url.path
     end
   
     # Private: Returns the full GitHub repo name of an Octokit repo.
@@ -90,8 +117,13 @@ module ForkReadme
       @ok ||= Octokit.new(:auto_traversal=>true)
     end
   
-    # Private: Returns the remote url of a Git working directory.
+    # Private: Returns the remote clone URL of a Git working directory, or
+    # raises NotGitRepo.
     def remote_url path
+      unless is_working_dir path
+        raise NotGitRepo.new "Not a Git repo: #{path}"
+      end
+
       %x{git config --file #{path}/.git/config --get remote.origin.url}
     end
   
@@ -103,17 +135,27 @@ module ForkReadme
   
       rescue URI::InvalidURIError
         if m = url.match("^(#{USERINFO})@(#{HOST}):(#{REL_PATH})$")
-          URI::Generic.new "ssh", m[1], m[2], 22, nil, m[3], nil, nil, nil
+          URI::Generic.new "ssh", m[1], m[2], 22, nil, "/" + m[3], nil, nil, nil
   
         else
           raise
         end
       end
     end
-  
+
+    # Private: Return true if +path+ is a Git working directory.
+    def is_working_dir path
+      File.exist? File.expand_path ".git", path
+    end
+
     # Private: Returns a filename with the extension removed.
     def chop_extension filename
       filename.sub /\.\w+$/, ""
     end
+
+    # Private: Returns a filename with the leading slash removed.
+    def chop_leading_slash filename
+      filename.sub /^\//, ""
+    end
   end
 end

data/lib/forkreadme/version.rb

@@ -2,5 +2,5 @@
 # vim: et ts=2 sw=2
 
 module ForkReadme
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forkreadme
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,22 +9,27 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-26 00:00:00.000000000 Z
+date: 2012-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: thor
-  requirement: &70204084253700 !ruby/object:Gem::Requirement
+  name: trollop
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.14.6
+        version: 1.16.2
   type: :runtime
   prerelease: false
-  version_requirements: *70204084253700
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.16.2
 - !ruby/object:Gem::Dependency
   name: octokit
-  requirement: &70204084253100 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,7 +37,12 @@ dependencies:
         version: 1.0.2
   type: :runtime
   prerelease: false
-  version_requirements: *70204084253100
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.2
 description: 
 email:
 - adam.mckaig@gmail.com
@@ -43,6 +53,8 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- LICENSE
+- README.md
 - bin/forkreadme
 - forkreadme.gemspec
 - lib/forkreadme.rb
@@ -50,7 +62,8 @@ files:
 - lib/forkreadme/generator.rb
 - lib/forkreadme/version.rb
 homepage: https://github.com/adammck/forkreadme
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -69,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Generate useful READMEs for GitHub forks