git-topic 0.2.5 → 0.2.6

data/.gitignore

@@ -2,3 +2,4 @@
 /pkg
 /.yardoc
 /doc
+/.bundle

data/Gemfile

@@ -3,19 +3,26 @@
 source :gemcutter
 
 group :runtime do
-  gem 'activesupport',  '>= 3.0.0.beta4'
+  gem 'activesupport',  '~> 3.0'
   gem 'trollop'
+
+  # This nutiness makes very little sense, but I can't find a sane way of
+  # calling ‘gemspec’ that works.  Of course, the non-exisistant documentation
+  # is of little help.
+  gem 'git-topic'
 end
 
 group :development do
   gem 'jeweler'
   gem 'rake'
-  gem 'rspec',          '>= 2.0.0.beta.16'
-  gem 'ZenTest'
+  gem 'rspec',          '~> 2.0.0'
   gem 'yard'
-  gem 'gemcutter'
+  gem 'gemcutter',      '~> 0.5.0'
 
+  gem 'autotest'
   gem 'autotest-screen'
+
+  gem 'ruby-debug19'
 end
 
 

data/Gemfile.lock

@@ -1,42 +1,64 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    ZenTest (4.3.3)
-    activesupport (3.0.0.beta4)
+    activesupport (3.0.1)
+    archive-tar-minitar (0.5.2)
+    autotest (4.4.1)
     autotest-screen (0.1.0.1)
+    columnize (0.3.1)
     diff-lcs (1.1.2)
     gemcutter (0.5.0)
       json_pure
     git (1.2.5)
+    git-topic (0.2.5)
+      activesupport (~> 3.0)
+      git-topic
+      trollop
     jeweler (1.4.0)
       gemcutter (>= 0.1.0)
       git (>= 1.2.5)
       rubyforge (>= 2.0.0)
-    json_pure (1.4.3)
+    json_pure (1.4.6)
+    linecache19 (0.5.11)
+      ruby_core_source (>= 0.1.4)
     rake (0.8.7)
-    rspec (2.0.0.beta.17)
-      rspec-core (= 2.0.0.beta.17)
-      rspec-expectations (= 2.0.0.beta.17)
-      rspec-mocks (= 2.0.0.beta.17)
-    rspec-core (2.0.0.beta.17)
-    rspec-expectations (2.0.0.beta.17)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
       diff-lcs (>= 1.1.2)
-    rspec-mocks (2.0.0.beta.17)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+    ruby-debug-base19 (0.11.24)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.4)
+      archive-tar-minitar (>= 0.5.2)
     rubyforge (2.0.4)
       json_pure (>= 1.1.7)
     trollop (1.16.2)
-    yard (0.5.8)
+    yard (0.6.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  ZenTest
-  activesupport (>= 3.0.0.beta4)
+  activesupport (~> 3.0)
+  autotest
   autotest-screen
-  gemcutter
+  gemcutter (~> 0.5.0)
+  git-topic
   jeweler
   rake
-  rspec (>= 2.0.0.beta.16)
+  rspec (~> 2.0.0)
+  ruby-debug19
   trollop
   yard

data/History.rdoc

@@ -1,3 +1,22 @@
+===   0.2.6
+
+* issues closed
+  - 15  git review will now attempt to automatically FF rebase.
+  - 18  git commands and error now logged.
+  - 21  git work-on --continue will now assume an <upstream> of the user's
+        latest review topic.
+  - 23  git work-on <topic> will no longer erroneously report the existence of
+        reviewer comments because of comments made to an earlier (and now
+        accepted) topic of the same name.
+  - 6   git-topic learned abandon [<topic>] command, to delete topics.
+  - 5   git-topic status now shows age of review branches in summary.
+
+* other changes
+  -     git work-on <review-topic> will now remove the review branch and reset,
+        just as it does for <rejected-topic>, and as the help documentation
+        claims.
+  -     comment formatting in git comment now respects paragraph breaks.
+
 ===   0.2.5
 
 * issues closed

data/README.rdoc

@@ -1,12 +1,24 @@
 =       git-topic
 
-git-topic is a git command to help with a particular kind of workflow, in which
++git-topic+ is a git command to help with a particular kind of workflow, in which
 all work is written by an author, and reviewed by someone else.
 
+Units of work are organized into _topics_.  Conceptually _topics_ are similar to
+git branches, except that they are namespaced, either in _wip_ (work in
+progress), _review_ or _rejected_.
+
+Authors begin by _working\ on_ a topic.  When they are done, they indicate the
+topic is ready for _review_.  A reviewer then either _accepts_ the topic (merges
+into master) or _rejects_ the topic, usually with comments.
+
+This is all fairly easy to do with policy, e.g. by indicating the state of a
+topic by the name of its branch.  +git-topic+ helps to automate one particular
+policy.
+
 
 =       Requirements
 
-* git-topic has only been tested on debian flavours of linux.  Other unix-like
+* +git-topic+ has only been tested on debian flavours of linux.  Other unix-like
   environments should work.
 * git >= 1.7.1        (older versions may work, sans comment[s] commands)
 * ruby >= 1.9.2-rc1   (older versions may work)
@@ -30,94 +42,13 @@ all work is written by an author, and reviewed by someone else.
 
 1.          Create a local branch from a review branch somebody else pushed.
 2.          Review their work.
-3.  a.i.    Accept; merge (fast-forward) master
-    ii.     Destroy the review branch. 
-    b.      Reject; add notes and push to the rejected namespace and remove from
+3.          either:
+  a.i::     Accept; merge (fast-forward) master
+   ii::     Destroy the review branch. 
+  b::       Reject; add notes and push to the rejected namespace and remove from
             the review namespace.
 
 
-==      Workflow without git-topic
-===     Working on a topic (e.g. feature, or bugfix) foo
-
-    # Create a new branch and switch to it.
-    git checkout -b wip/hal/foo
-
-    # do some work, create lots of temporary commits
-    # when ready to get the code into master, first update so we're rebasing against
-    # the latest code
-    git fetch origin
-
-    # rebase against latest code
-    git rebase --interactive origin/master
-
-    # when done rebasing so wip/hal/foo now has a nice clean commit history, push to
-    # a review branch and destroy the remote wip branch
-    git push origin wip/hal/foo:review/hal/foo  :wip/hal/foo
-
-    # alternatively if you never pushed your wip branch to the remote there's no
-    # need to destroy it, instead only push your local wip branch as a review branch
-    #
-    # git push origin wip/hal/foo:review/hal/foo
-
-
-    # later, after your changes have been merged into master, you can delete your
-    # local branch
-    #
-    # git checkout master
-    # git branch -d wip/hal/foo
-
-
-
-===     Reviewing a  topic (no proposed changes)
-
-    # update origin
-    git fetch origin
-
-    # notice there's a review branch
-    git branch -r
-
-    # create a local branch that tracks the remote review branch
-    git checkout -b review/djh/bar origin/review/djh/bar
-
-    # examine code and examine the local (proposed) commits
-    git log master..
-
-    # when done reviewing, merge into master
-    git checkout master
-    # This should be a fast-forward merge.  If not, it's because something has been
-    # added to master since the rebase
-    git merge review/djh/bar
-    git branch -d review/djh/bar
-
-    # update the new master and destroy the old review branch
-    git push origin master :review/djh/bar
-
-
-
-===     Reviewing a topic (proposed changes)
-
-As above, but if, after examining the code you feel some changes are
-appropriate, you can either:
-
-====    do them yourself and have the other person review and merge
-
-    # do some changes, then destroy the old review branch and make a new one
-    # with the cleaned up code.  Now the owner is changed from djh to hal, so
-    # djh must review and merge into master
-    git push origin review/djh/bar:review/hal/bar :review/djh/bar
-
-====    do some (or no) changes, but with some TODOs for the original author.
-
-    # do your changes on review/djh/bar
-
-    # then update the remote, moving the branch to rejected, indicating the
-    # author has some TODOs left.
-    git push origin review/djh/bar:rejected/djh/bar :review/djh/bar
-
-    # when the author has resolved the TODOs they will move the branch back to
-    # review/djh/bar
-
-
 ==      Workflow with git-topic
 ===     Doing Work
 
@@ -139,8 +70,8 @@ appropriate, you can either:
     git topic accept
 
     # unhappy with the review
-    # edit files to add file-specific comments (see git-topic comment --help for
-    # details).
+    # edit files to add file-specific comments (see +git-topic+ +comment+
+    # +--help+ for details).
    
     # save your file specific comments, and launch an editor to enter general
     # comments about the topic.
@@ -149,14 +80,13 @@ appropriate, you can either:
     # push the topic to rejected.
     git topic reject
 
-==      Again, but with aliases
+===     Again, but with aliases
 
     # first install aliases
     #   add --local if you don't want to update your global aliases
     git topic install-aliases
 
     # alternatively
-    #   git w <topic>
     git work-on <topic>
 
     # see reviewer's comments
@@ -179,18 +109,73 @@ appropriate, you can either:
     git comment
     git reject
 
+
+==      Commenting
+===     Reviewer Comments
+
+When initially rejecting a branch, the reviewer can, and should, write comments
+explaining why the branch was rejected.  These fall into two categories:
++genera+ and +line-specific+ comments.  To make line-specific comments easier,
+the reviewer can add comments directly in source files before invoking +git+
++comment+.
+
+Each line of those annotations should begin with a pound sign.  +git+ +comment+
+will convert these comments into formatted plain text.  Paragraphs are
+automatically formatted, but indented lines are left intact.  So, for instance,
+editing +foo.rb+ from
+
+    def foo
+      x = initial_value_of_x
+      x.change!
+    end
+
+to
+
+    # This is an exciting name for a function, but I fear it is perhaps not as
+    # descriptive as it could be.  And this comment is a little long, but I
+    # think it's to make the point that source comments are automatically
+    # formatted.  In any case, how about
+    #
+    #    def a_much_better_function_name
+    #        excellent_implementation
+    #    end
+    # 
+    def foo
+      x = initial_value_of_x
+      x.change!
+    end
+
+and then invoking +git+ +comment+ will format the above paragraph, annotated
+with +git+ +config+ +user.name+ and wrapped, but leaving the indented lines
+unformatted.
+
+The actual changes to +foo.rb+ will then be discarded.  +git+ +comment+ tries
+hard not to discard non-comment changes and will do nothing if any of the output
+of +git+ +diff+ reports lines that do not meet the above format.
+
+After the diff comments have been applied, +git+ +comment+ will start an
+instance of your +EDITOR+ so you can write general comments.
+
+===     Responding to Comments
+
+The author can view the reviewer's comments with +git+ +comments+, and reply
+with +git+ +comment+.  The latter will start an instance of their +EDITOR+,
+from which replies can be made inline.
+
 ==      Bash autocompletion
 
-See git-topic --completion-help for details.  In short, you have to do some
+See +git-topic+ +--completion-help+ for details.  In short, you have to do some
 manual work, because loading completions as a gem is too slow (see Misc, below,
 and ruby issue 3465[1]).
 
 1.  Make sure you source share/completion.bash __before__ sourcing git's standard
     completion.
 
-2.  Copy bin/git-topic-completion to your gem env's default bin dir, overriding
-    the generated git-topic-completion.  Otherwise, autocompletion will be too
-    slow to be useful.
+2.  Copy +bin/git-topic-completion+ to your gem env's default bin dir,
+    overriding the generated +git-topic-completion+.  Otherwise, autocompletion
+    will be too slow to be useful.
+
+3.  Alternatively, install +git-topic+ with the +--no-wrappers+ flag.
 
 ==      Misc
 

data/VERSION.yml

@@ -1,5 +1,5 @@
 --- 
 :major: 0
 :minor: 2
-:patch: 5
+:patch: 6
 :build: 

data/lib/git_topic.rb

@@ -1,13 +1,22 @@
 #!/usr/bin/env ruby
 # encoding: utf-8
 
+require 'rubygems'
+require 'bundler'
+
+# Work around absurd bundler API
+ENV['BUNDLE_GEMFILE'] = "#{File.dirname __FILE__}/../Gemfile"
+Bundler.setup :runtime
+ENV.delete 'BUNDLE_GEMFILE'
+
 require 'active_support'
 require 'active_support/core_ext/hash/keys'
 
-require 'core_ext'
+require 'git_topic/core_ext'
 require 'git_topic/git'
 require 'git_topic/naming'
 require 'git_topic/comment'
+require 'git_topic/logger'
 
 
 module GitTopic
@@ -17,16 +26,27 @@ module GitTopic
 
   GlobalOptKeys = [
     :verbose, :help, :verbose_given, :version, :completion_help,
-    :completion_help_given
+    :completion_help_given, :no_log
   ]
 
 
   class << self
 
     # Switch to a branch for the given topic.
-    def work_on( topic, opts={} )
+    def work_on topic, opts={}
+      opts.assert_valid_keys  :continue, :upstream, *GlobalOptKeys
       raise "Topic must be specified" if topic.nil?
 
+      upstream =
+        if opts[:upstream] && opts[:continue]
+          raise "upstream and continue options mutually exclusive."
+        elsif opts[:upstream]
+          opts[:upstream]
+        elsif opts[:continue]
+          newest_pending_branch
+        end
+
+
       # setup a remote branch, if necessary
       wb = wip_branch( topic )
       git(
@@ -34,19 +54,21 @@ module GitTopic
       ) unless remote_branches.include? "origin/#{wb}"
       # switch to the new branch
       git [ switch_to_branch( wb, "origin/#{wb}" )]
-     
-      # Check for rejected branch
-      rej_branch = rejected_branch( topic )
-      if remote_branches.include? "origin/#{rej_branch}"
-        git [
-          "reset --hard origin/#{rej_branch}",
-          "push origin :refs/heads/#{rej_branch} HEAD:refs/heads/#{wb}",
-        ]
+  
+
+      # Check for rejected or review branch
+      [ rejected_branch( topic ), review_branch( topic ) ].each do |b|
+        if remote_branches.include? "origin/#{b}"
+          git [
+            "reset --hard origin/#{b}",
+            "push origin :refs/heads/#{b} HEAD:refs/heads/#{wb}",
+          ]
+        end
       end
 
       # Reset upstream, if specified
-      if opts[:upstream]
-        git "reset --hard #{opts[:upstream]}"
+      if upstream
+        git "reset --hard #{upstream}"
       end
 
       report "Switching branches to work on #{topic}."
@@ -56,9 +78,39 @@ module GitTopic
     end
 
 
+    # Delete +topic+ locally and remotely.  Defaults to current topic if
+    # unspecified.
+    #
+    def abandon topic=nil, opts={}
+      local_branch =
+        if topic.nil?
+          parts = topic_parts current_branch
+          if parts && parts[:namespace] == "wip" && parts[:user] == user
+            topic = current_topic
+            current_branch
+          else
+            raise "Cannot abandon #{current_branch}."
+          end
+        else
+          wip_branch  topic
+        end
+
+      unless rb = remote_branch( topic, :strip_remote => true )
+        raise "No such topic #{topic}."
+      end
+
+      git [
+        ( "checkout master"           if current_branch == local_branch ),
+        ( "branch -D #{local_branch}" if branches.include? local_branch ),
+        "push origin :#{rb}",
+      ].compact
+
+      report "Topic #{topic} abandoned."
+    end
+
     # Done with the given topic.  If none is specified, then topic is assumed to
     # be the current branch (if it's a topic branch).
-    def done( topic=nil, opts={} )
+    def done  topic=nil, opts={}
       if topic.nil?
         raise "
           Current branch is not a topic branch.  Switch to a topic branch or
@@ -105,7 +157,7 @@ module GitTopic
     #   # 2 of your topics were rejected.
     #   #   dragons
     #   #   liches
-    def status( opts={} )
+    def status  opts={}
       opts.assert_valid_keys  :prepended, :prepended_given, *GlobalOptKeys
 
       sb = ''
@@ -114,12 +166,17 @@ module GitTopic
       rejected_ut = rb[:rejected]
 
       unless review_ut.empty?
-        prep = review_ut.size == 1 ? "is 1" : "are #{review_ut.size}"
-        sb << "# There #{prep} #{'topic'.pluralize( review_ut.size )} you can review.\n\n"
+        topic_count = review_ut.inject( 0 ){ |a, uts| a + uts.size }
+        prep = topic_count == 1 ? "is 1" : "are #{topic_count}"
+        sb << "# There #{prep} #{'topic'.pluralize( topic_count )} you can review.\n\n"
 
         sb << review_ut.map do |user, topics|
           sb2 = "  from #{user}:\n"
-          sb2 << topics.map{|t| "    #{t}"}.join( "\n" )
+          sb2 << topics.map do |t|
+            age = ref_age( review_branch( t, user, :remote => true ))
+            age_str = " (#{age} days)" if age && age > 0
+            "    #{t}#{age_str}"
+          end.join( "\n" )
           sb2
         end.join( "\n" )
       end
@@ -148,7 +205,7 @@ module GitTopic
 
 
     # Switch to a review branch to check somebody else's code.
-    def review( ref=nil, opts={} )
+    def review  ref=nil, opts={}
       rb = remote_branches_organized
       review_branches = rb[:review]
 
@@ -176,13 +233,28 @@ module GitTopic
       else
         raise "No review topic found matching ‘#{ref}’"
       end
-
       report  "Reviewing topic #{user}/#{topic}."
+
+      unless rebased_to_master?
+        git "rebase --quiet master"
+        report(
+          "
+            #{user}/#{topic} was not rebased to master, but has successfully
+            been automatically rebased.
+          ".unindent,
+          "
+            #{user}/#{topic} was not rebased to master, and I could not
+            automatically rebase it.  You will not be able to accept this topic.
+            Either
+              1) rebase the topic manually or
+              2) reject the topic and ask the author to rebase.
+          ".unindent )
+      end
     end
 
 
     # Accept the branch currently being reviewed.
-    def accept( topic=nil, opts={} )
+    def accept  topic=nil, opts={}
       raise "Must be on a review branch." unless on_review_branch?
       raise "Working tree must be clean" unless working_tree_clean?
       
@@ -203,7 +275,7 @@ module GitTopic
         raise "
           review branch is not up to date: merge not a fast-forward.  Either
           rebase or reject this branch.
-        ".cleanup
+        ".unindent
       end
 
       rem_review_branch   = find_remote_review_branch( topic ).gsub( %r{^origin/}, '' )
@@ -216,11 +288,10 @@ module GitTopic
     end
 
 
-    def comment( opts={} )
+    def comment opts={}
       diff_legal = 
         git( "diff --diff-filter=ACDRTUXB --quiet" )          && 
-        git( "diff --cached --diff-filter=ACDRTUXB --quiet" ) && 
-        $?.success?
+        git( "diff --cached --diff-filter=ACDRTUXB --quiet" )
     
       raise "
         Diffs are not comments.  Files have been added, deleted or had their
@@ -228,10 +299,10 @@ module GitTopic
           git diff --diff-filter=ACDRTUXB
         for a list of changes preventing git-topic comment from saving your
         comments.
-      ".cleanup unless diff_legal
+      ".unindent unless diff_legal
 
 
-      diff_empty          = git( "diff --diff-filter=M --quiet" ) && $?.success?
+      diff_empty          = git( "diff --diff-filter=M --quiet" )
 
       added_comments = 
         case current_namespace
@@ -275,7 +346,7 @@ module GitTopic
       end
     end
 
-    def comments( spec=nil, opts={} )
+    def comments  spec=nil, opts={}
       args = [ spec ].compact
       if args.empty? && current_branch.nil?
         if guess = guess_branch
@@ -306,7 +377,7 @@ module GitTopic
 
 
     # Reject the branch currently being reviewed.
-    def reject( topic_or_opts=nil, opts={} )
+    def reject  topic_or_opts=nil, opts={}
       if topic_or_opts.is_a? Hash
         topic = nil
         opts = topic_or_opts
@@ -352,7 +423,7 @@ module GitTopic
     #   1. refspecs for origin fetching for review comments.
     #   2. notes.rewriteRef for copying review comments on rebase.
     #
-    def setup( opts={} )
+    def setup opts={}
       cmds = []
 
       cmds <<(
@@ -366,7 +437,7 @@ module GitTopic
       git cmds.compact
     end
 
-    def install_aliases( opts={} )
+    def install_aliases opts={}
       opts.assert_valid_keys  :local, :local_given, *GlobalOptKeys
 
       flags = "--global" unless opts[:local]
@@ -391,8 +462,8 @@ module GitTopic
 
     protected
 
-    def report( success_msg, error_msg=nil )
-      if $?.success?
+    def report  success_msg, error_msg=nil
+      if $pstatus && $pstatus.success?
         puts success_msg
       else
         error_msg ||= "Error running command.  re-run with --verbose for details"
@@ -428,7 +499,7 @@ module GitTopic
                 GIT_NOTES_REWRITE_REF=refs/notes/reviews/* git rebase
 
               instead of `git rebase`
-        ".cleanup
+        ".unindent
       end
     end