git_time_extractor 0.2.0

data/History.txt

@@ -0,0 +1,8 @@
+=== 0.1.0 / 2012-05-05
+
+* 1 major enhancement
+
+  * Birthday of this git_time_extractor gem.
+
+=== 0.1.0 / 2012-02-15
+* Initial code release on https://github.com/rietta/git_time_extractor/ - not a gem.

data/README.txt

@@ -0,0 +1,76 @@
+= git_time_extractor
+
+Project Wiki: https://github.com/rietta/git_time_extractor/wiki
+
+== DESCRIPTION:
+
+EXTRACT REASONABLE TIME RECORDS FROM A GIT REPOSITORY
+
+git_time_extractor is a free tool that goes through a GIT, the popular revision control system, repository's commit log and produces a Comma Seperated Values (CSV) file that indicates the time spent by each developer, per day. 
+
+The working time estimates are based on three assumptions:
+
+    1. A series of commits within a 3 hour window are part of the same development session
+    2. A single commit (or the first commit of the session) is considered to represent 30 minutes of work time
+    3. The more frequent a developer commits to the repository while working, the more accurate the time report will be
+
+This script is based on previous code published publicly by Sharad at http://www.tatvartha.com/2010/01/generating-time-entry-from-git-log/. However, it has been adapted to run without Rails from the command line. The portions of the code written by Rietta are licensed under the terms of the BSD license (see section 3 below).
+
+git_time_extractor is useful for software development companies that want to discover the approximate time spent by developers on particular projects based on real data in the GIT revision control system. This is useful for managers, accountants, and for those who need to back up records for tax purposes.
+
+For example, in the United States there is a Research & Development (R&D) tax credit available for companies who build or improve software for certain purposes.  To claim this credit requires certain types of records.  Check with your accountant to see if the results from this program is appropriate in your particular situation.  You can learn more information about this particular credit at http://www.irs.gov/businesses/article/0,,id=156366,00.html.
+
+== BENEFITS:
+
+	* Compute time records based on the timestamps of each code commit by each developer
+	* Compare these results with other time-sheets or metrics to measure the effectiveness of your team members
+	* Save money on taxes by producing documents required by your accountant to properly apply for certain tax credits
+	* It's a Free Open Source Tool
+	
+== FEATURES:
+
+	* Easy command-line operation
+	* Reads from a local GIT branch in the current directory
+	* Writes to a CSV-file that is compatible with Microsoft Excel, OpenOffice Calc, or Google Docs
+	
+== SYNOPSIS:
+
+  	cd /path/to/your/repository
+  	git_time_extractor > time_log.csv
+
+== REQUIREMENTS:
+
+	The following GEMS are required as dependencies:
+		* git
+		* logger
+
+== INSTALL:
+
+	gem install git_time_extractor
+
+== UNINSTALL:
+	
+	gem install git_time_extractor
+
+== DEVELOPERS:
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+== LICENSE:
+
+(The BSD License)
+
+Copyright (c) 2012 Rietta Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  
+    

data/bin/git_time_extractor

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# Extract Reasonable Developer Time Records from a GIT Repository's Commit Log
+#
+# This is inspired by a RAKE task publicly posted by Sharad at 
+# http://www.tatvartha.com/2010/01/generating-time-entry-from-git-log/. 
+# However, it has been adapted to run without Rails from the command line.
+#
+# Portions (C) 2012 Rietta Inc. and licensed under the terms of the BSD license.
+
+  # Adjust path in case called directly and not through gem
+  $:.unshift "#{File.expand_path(File.dirname(__FILE__))}/../lib"
+
+  require 'git_time_extractor'
+
+  #puts "\n# Arguments #{ARGV.length}\n"
+
+  valid_usage = false
+
+  if ARGV.empty?
+    output_file = "-"
+    path_to_repo = Dir.pwd
+    project_name = ""
+    valid_usage = true
+  elsif "-h" == ARGV[0].downcase || "--help" == ARGV[0].downcase
+    # Show help
+  elsif ARGV.length == 2
+    output_file = ARGV.pop
+    path_to_repo = ARGV.pop
+    valid_usage = true
+  elsif ARGV.length == 1
+    output_file = "-"
+    path_to_repo = ARGV.pop 
+    valid_usage = true
+  end
+
+  unless valid_usage
+    puts "Usage: git_time_extractor PROJECT_NAME [PATH_TO_REPO] [OUTPUT_FILE]"
+    puts "Copyright 2012 Rietta Inc.  http://www.rietta.com"
+    exit 0
+  else 
+    #path_to_repo = File.expand_path(File.dirname(path_to_repo)) if nil != path_to_repo && "" != path_to_repo
+    #puts "\n\nGit Repo Path: #{path_to_repo}\nOutput: #{output_file}\n"
+    GitTimeExtractor.process_git_log_into_time(path_to_repo, output_file)
+  end
+

data/lib/git_time_extractor.rb

@@ -0,0 +1,109 @@
+#
+# Extract Reasonable Developer Time Records from a GIT Repository's Commit Log
+#
+# This is inspired by a RAKE task publicly posted by Sharad at 
+# http://www.tatvartha.com/2010/01/generating-time-entry-from-git-log/. 
+# However, it has been adapted to run without Rails from the command line.
+#
+# Portions (C) 2012 Rietta Inc. and licensed under the terms of the BSD license.
+#
+class GitTimeExtractor
+  VERSION = '0.2.0'
+  
+  require 'rubygems'
+  require 'ostruct'
+  require 'logger'
+  require 'git'
+  require 'csv'
+
+  #
+  # Go through the GIT commit log, to compute the elapsed working time of each committing developer, based
+  # on a few assumptions:
+  #
+  # (1) A series of commits within a 3 hour window are part of the same development session
+  # (2) A single commit (or the first commit of the session) is considered to represent 30 minutes of work time
+  # (3) The more frequent a developer commits to the repository while working, the more accurate the time report will be
+  #
+  #
+  def self.process_git_log_into_time(path_to_git_repo = "./", path_to_output_file = "-", project_name = "")
+
+    if "-" != path_to_output_file
+      raise "Output path not yet implemented. Use a Unix pipe to write to your desired file. For example: git_time_extractor ./ > my_result.csv\n" 
+    end 
+    
+    # Open the GIT Repository for Reading
+    logger = Logger.new(STDOUT)
+    logger.level = Logger::WARN
+    g = Git.open(path_to_git_repo, :log => logger)
+    logs = g.log(1000)
+    log_entries = logs.entries.reverse
+    worklog = {}
+
+    # Go through the GIT commit records and construct the time
+    log_entries.each_with_index do |commit, index|
+      author_date = commit.author_date.to_date
+      daylog = worklog[author_date] || OpenStruct.new(:date => author_date, :duration => 0)
+      daylog.author = commit.author
+      daylog.message = "#{daylog.message} --- #{commit.message}"
+      daylog.duration = daylog.duration + calc_duration_in_minutes(log_entries, index)
+      worklog[author_date] = daylog
+    end # log_entries.each_with_index
+
+    # Print the header row for the CSV
+    puts [
+        'Date',
+        'Minutes',
+        'Hours',
+        'Person',
+        'Email',
+        'Project',
+        'Notes',
+        'Week Number',
+        'Year'
+        ].to_csv
+
+    # Go through the work log  
+    worklog.keys.sort.each do |date|
+
+        start_time = DateTime.parse(date.to_s)
+        duration_in_seconds = (worklog[date].duration.to_f * 60.0).round(0)
+        duration_in_minutes = worklog[date].duration.to_i
+        duration_in_hours = (worklog[date].duration / 60.0).round(1)
+
+        stop_time = start_time + duration_in_seconds
+        row = [
+              start_time.strftime("%m/%d/%Y"), 
+              duration_in_minutes,
+              duration_in_hours,
+              worklog[date].author.name,
+              worklog[date].author.email,
+              project_name,
+              worklog[date].message,
+              start_time.strftime("%W").to_i,
+              start_time.strftime("%Y").to_i]
+        puts row.to_csv
+    end # worklog each
+
+  end # process_git_log_into_time
+
+  # Calculate the duration of work in minutes
+  def self.calc_duration_in_minutes(log_entries, index)
+    commit = log_entries[index]
+    if index > 1
+      previous_commit = log_entries[index-1]
+      # Default duration in Ruby is in seconds
+      duration = commit.author_date - previous_commit.author_date
+      
+      # ASSUMPTION: if the gap between 2 commits is more than 3 hours, reduce it to 1/2 hour
+      duration = 30 * 60 if duration > 3 * 3600
+    else
+      # ASSUMPTION: first commit took 1/2 hour
+      duration = 30 * 60
+    end
+    return duration.to_f / 60.0
+  end # calc_duration_in_minutes
+
+  def self.say_hi
+    "hi"
+  end
+end # class GitTimeExtractor

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: git_time_extractor
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- Frank Rietta
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: git
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Compute the estimated time spent by developers working on code within
+  a GIT respository. Useful for verifying developer timesheets and for tax purposes.
+email: products@rietta.com
+executables:
+- git_time_extractor
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/git_time_extractor
+- README.txt
+- History.txt
+- lib/git_time_extractor.rb
+homepage: https://github.com/rietta/git_time_extractor
+licenses:
+- BSD
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Reasonable developer time log extractor that uses a GIT repository's commit
+  log history.
+test_files: []