git-lite-version-bump 0.17.0

data/README.md

@@ -0,0 +1,157 @@
+Maintain your program versions entirely within git.  No local files
+required!  All versioning information is stored using git tags.
+
+This gem contains a command-line tool and set of Rake tasks to increment
+and display your version numbers via git tags, and some associated Ruby code to use
+inside a gemspec or your program to retrieve the current version number, for
+use in builds and at runtime.
+
+
+# Usage
+
+Most of your day-to-day usage of `git-version-bump` will be via the command
+line.  When you bump a version, a new tag will be created representing the newly
+incremented version number at the current commit.  If no tags currently
+exist, the previous version will be taken to be `0.0.0` and then incremented
+accordingly.
+
+
+## On the command line
+
+Pretty damned trivial:
+
+    git version-bump <major|minor|patch|show>
+
+You can also shorten the specifier to any unique substring:
+
+    git version-bump ma
+    git version-bump mi
+    git version-bump p
+    git version-bump s
+
+I recommend adding an alias to your `~/.gitconfig` file, for less typing:
+
+    [alias]
+        vb = version-bump
+
+You can also add your own release notes to your release tags, by using the
+`-n` (or `--notes`, if you like typing) option:
+
+    git version-bump -n minor
+
+This will open an editor, containing a list of the commits since the last
+release tag, in which you can type your release notes.  If you follow
+standard git commit style (a "heading" line, then a blank line, followed by
+free-form text) you're perfectly positioned to use
+[github-release](http://theshed.hezmatt.org/github-release) to make
+gorgeous-looking release announcements to Github.
+
+
+## In your `Rakefile`
+
+If you'd like to have access to the version-bumping goodness via `rake`, add
+the following line to your `Rakefile`:
+
+    require 'git-version-bump/rake-tasks'
+
+You will now have the following rake tasks available:
+
+    rake version:bump:major  # bump major version (x.y.z -> x+1.0.0)
+    rake version:bump:minor  # bump minor version (x.y.z -> x.y+1.0)
+    rake version:bump:patch  # bump patch version (x.y.z -> x.y.z+1)
+    rake version:bump:show   # Print current version number
+
+(Since `version:bump:major` is a lot of typing, there are also shortcuts:
+`v:b:major`, `v:b:maj`, `v:b:minor`, `v:b:min`, `v:b:patch`, `v:b:pat`, and
+`v:b:p`)
+
+
+## In your Ruby code
+
+To get access to this version information in your code (such as in your
+`gemspec`, or the definition of a `::VERSION` constant), you can `require
+'git-version-bump'` and use the following methods:
+
+    GVB.version            # Return the entire version string
+    GVB.major_version      # Return just the 'major' portion of the version
+    GVB.minor_version      # Return just the 'minor' portion of the version
+    GVB.patch_version      # Return just the 'patch' portion of the version
+    GVB.internal_revision  # Return "internal revision" information, or nil
+    GVB.date               # Return the date of the most recent commit, or
+                           # today's date if the tree is dirty
+
+The "internal revision" is set when the tree is dirty, or when the latest
+git commit doesn't correspond with a tag.  In that case, the internal
+revision will describe, in the manner of `git describe`, the full details of
+the version of the code in use.  This information will be part of the
+version string provided by `gvb_version`.
+
+If any of these methods are called when there isn't a tag or other version
+information available, the version will be assumed to be `0.0.0.1.ENOTAG`
+with a date of `1970-01-01`.
+
+
+### In your gemspec
+
+Typically, you want to encode your version and commit date into your
+gemspec, like this:
+
+    Gem::Specification.new do |s|
+      s.version = GVB.version
+      s.date    = GVB.date
+
+      ...
+    end
+
+The beauty of this method is that whenever you run a `rake build`, you'll
+get a gem which is *accurately* versioned for the current state of your
+repository.  No more wondering if the `foobar-1.2.3` gem installed on your
+system was built from pristine sources, or with that experimental patch you
+were trying out...
+
+
+### In your gem
+
+If, like me, you're one of those people who likes to be able to easily see
+what version of a library you're running, then you probably like to define a
+`VERSION` constant somewhere in your gem's namespace.  That, too, is simple
+to do:
+
+    require 'git-version-bump'
+
+    class Foobar
+      VERSION = GVB.version
+    end
+
+This will work correctly inside your git tree, and also in your installed
+gem.  Magical!
+
+#### For projects using lite tags
+
+If you are using GitHub releases for your project or some other method that
+involves light tags (tags with no annotations), you might notice that these
+tags are not detected by git-version-bump by default.  If you want these
+commits to be detected then use the following configuration:
+
+    require 'git-version-bump'
+
+    class Foobar
+      # First parameter is use_local_git, second is include_lite_tags
+      VERSION = GVB.version(false, true)
+    end
+
+
+# Contributing
+
+Send your pull requests to the [Github
+repo](https://github.com/mpalmer/git-version-bump), or send patches to
+`theshed+git-version-bump@hezmatt.org`.  Bug reports can be sent to the same
+place, although I greatly prefer patches.
+
+
+# Licence
+
+Unless otherwise specified, all code in this repository is licenced under
+the terms of the GNU Public Licence, version 3, as published by the Free
+Software Foundation.  The full terms of this licence can be found in the
+file LICENCE.

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+require 'rdoc/task'
+
+Rake::RDocTask.new do |rd|
+	rd.main = "README.md"
+	rd.title = 'git-version-bump'
+	rd.rdoc_files.include("README.md", "lib/**/*.rb")
+end
+
+task :release do
+	sh "git push --follow-tags"
+	sh "git release"
+end

data/bin/git-version-bump

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+require 'git-version-bump'
+
+if ARGV[0].nil? or
+   ARGV[0].empty? or
+   (ARGV.length == 1 && (ARGV[0] == "-d" || ARGV[0] == "--dry-run")) or
+   ARGV[0] == '-h' or
+   ARGV[0] == '--help'
+	$stderr.puts <<-EOF.gsub(/^\t\t/, '')
+		Usage: git version-bump [-n|--notes] [-d|--dry-run] <major|minor|patch|show>
+
+		'major': x.y.z -> x+1.0.0
+		'minor': x.y.z -> x.y+1.0
+		'patch': x.y.z -> x.y.z+1
+
+		'show': Display the current GVB version
+
+		-d, --dry-run: Calculate and return the bump value, but don't update git workspace or remote
+		-n, --notes: Prompt for "release notes" to add to the release tag
+		-l, --lite-tags: Include non-annotated git tags
+	EOF
+end
+
+release_notes = ARGV.delete('-n') || ARGV.delete('--notes')
+dry_run = ARGV.delete('-d') || ARGV.delete('--dry-run')
+lite_tags = ARGV.delete('-l') || ARGV.delete('--lite-tags')
+
+if ARGV[0].nil? or ARGV[0].empty?
+	exit 1
+elsif ARGV[0] == '-h' or ARGV[0] == '--help'
+	exit 0
+end
+
+result = case ARGV[0].downcase
+	when /^maj?o?r?$/
+		"#{GVB.major_version(true) + 1}.0.0"
+	when /^min?o?r?$/
+		"#{GVB.major_version(true)}.#{GVB.minor_version(true)+1}.0"
+	when /^pa?t?c?h?$/
+		"#{GVB.major_version(true)}.#{GVB.minor_version(true)}.#{GVB.patch_version(true)+1}"
+	when /^sh?o?w?$/
+		puts GVB.version(true)
+		exit 0
+	else
+		$stderr.puts "Unknown argument: #{ARGV[0]}.  Try --help."
+		exit 1
+end
+
+if dry_run
+	puts result
+else
+	GVB.tag_version result, release_notes, lite_tags
+	puts "Version is now #{GVB.version(true)}."
+end

data/git-version-bump.gemspec

@@ -0,0 +1,26 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'git-version-bump'
+
+Gem::Specification.new do |s|
+	s.name = "git-lite-version-bump"
+
+	s.version = GVB.version
+	s.date    = GVB.date
+
+	s.platform              = Gem::Platform::RUBY
+	s.required_ruby_version = ">= 1.8.7"
+
+	s.homepage = "http://github.com/rbclark/git-version-bump"
+	s.summary = "Manage your app version entirely via git tags (even lite tags)"
+	s.authors = ["Matt Palmer"]
+
+	s.extra_rdoc_files = ["README.md"]
+	s.files = `git ls-files`.split("\n")
+	s.executables = ["git-version-bump"]
+
+	s.add_development_dependency 'github-release'
+	s.add_development_dependency 'rake'
+	s.add_development_dependency 'bundler'
+	s.add_development_dependency 'rdoc'
+end

data/lib/git-version-bump.rb

@@ -0,0 +1,324 @@
+require 'tempfile'
+require 'digest/sha1'
+require 'pathname'
+
+module GitVersionBump
+	class VersionUnobtainable < StandardError; end
+
+	DEVNULL = Gem.win_platform? ? "NUL" : "/dev/null"
+
+	def self.version(use_local_git=false, include_lite_tags=false)
+		if use_local_git
+			unless git_available?
+				raise RuntimeError,
+				      "GVB.version(use_local_git=true) called, but git isn't installed"
+			end
+
+			sq_git_dir = shell_quoted_string(Dir.pwd)
+		else
+			sq_git_dir = shell_quoted_string((File.dirname(caller_file) rescue nil || Dir.pwd))
+		end
+
+		git_cmd = "git -C #{sq_git_dir} describe --dirty='.1.dirty.#{Time.now.strftime("%Y%m%d.%H%M%S")}' --match='v[0-9]*.[0-9]*.*[0-9]'"
+		git_cmd << " --tags" if include_lite_tags
+
+		git_ver = `#{git_cmd} 2> #{DEVNULL}`.
+		            strip.
+		            gsub(/^v/, '').
+		            gsub('-', '.')
+
+		# If git returned success, then it gave us a described version.
+		# Success!
+		return git_ver if $? == 0
+
+		# git failed us; we're either not in a git repo or else we've never
+		# tagged anything before.
+
+		# Are we in a git repo with no tags?  If so, dump out our
+		# super-special version and be done with it, otherwise try to use the
+		# gem version.
+		system("git -C #{sq_git_dir} status > #{DEVNULL} 2>&1")
+		$? == 0 ? "0.0.0.1.ENOTAG" : gem_version(use_local_git)
+	end
+
+	def self.major_version(use_local_git=false, include_lite_tags=false)
+		ver = version(use_local_git, include_lite_tags)
+		v   = ver.split('.')[0]
+
+		unless v =~ /^[0-9]+$/
+			raise ArgumentError,
+			        "#{v} (part of #{ver.inspect}) is not a numeric version component.  Abandon ship!"
+		end
+
+		return v.to_i
+	end
+
+	def self.minor_version(use_local_git=false, include_lite_tags=false)
+		ver = version(use_local_git, include_lite_tags)
+		v   = ver.split('.')[1]
+
+		unless v =~ /^[0-9]+$/
+			raise ArgumentError,
+			        "#{v} (part of #{ver.inspect}) is not a numeric version component.  Abandon ship!"
+		end
+
+		return v.to_i
+	end
+
+	def self.patch_version(use_local_git=false, include_lite_tags=false)
+		ver = version(use_local_git, include_lite_tags)
+		v   = ver.split('.')[2]
+
+		unless v =~ /^[0-9]+$/
+			raise ArgumentError,
+			        "#{v} (part of #{ver.inspect}) is not a numeric version component.  Abandon ship!"
+		end
+
+		return v.to_i
+	end
+
+	def self.internal_revision(use_local_git=false, include_lite_tags=false)
+		version(use_local_git, include_lite_tags).split('.', 4)[3].to_s
+	end
+
+	def self.date(use_local_git=false)
+		if use_local_git
+			unless git_available?
+				raise RuntimeError,
+				      "GVB.date(use_local_git=true), but git is not installed"
+			end
+
+			sq_git_dir = shell_quoted_string(Dir.pwd)
+		else
+			sq_git_dir = shell_quoted_string((File.dirname(caller_file) rescue nil || Dir.pwd))
+		end
+
+		# Are we in a git tree?
+		system("git -C #{sq_git_dir} status > #{DEVNULL} 2>&1")
+		if $? == 0
+			# Yes, we're in git.
+
+			if dirty_tree?
+				return Time.now.strftime("%F")
+			else
+				# Clean tree.  Date of last commit is needed.
+				return `git -C #{sq_git_dir} show --no-show-signature --format=format:%cd --date=short`.lines.first.strip
+			end
+		else
+			if use_local_git
+				raise RuntimeError,
+				      "GVB.date(use_local_git=true) called from non-git location"
+			end
+
+			# Not in git; time to hit the gemspecs
+			if spec = caller_gemspec
+				return spec.date.strftime("%F")
+			end
+
+			raise RuntimeError,
+			      "GVB.date called from mysterious, non-gem location."
+		end
+	end
+
+	def self.tag_version(v, release_notes = false, include_lite_tags=false)
+		if dirty_tree?
+			puts "You have uncommitted files.  Refusing to tag a dirty tree."
+		else
+			if release_notes
+				# We need to find the tag before this one, so we can list all the commits
+				# between the two.  This is not a trivial operation.
+				git_cmd = 'git describe --always'
+				git_cmd << ' --tags' if include_lite_tags
+				prev_tag = `#{git_cmd}`.strip.gsub(/-\d+-g[0-9a-f]+$/, '')
+
+				log_file = Tempfile.new('gvb')
+
+				log_file.puts <<-EOF.gsub(/^\t\t\t\t\t/, '')
+
+
+
+					# Write your release notes above.  The first line should be the release name.
+					# To help you remember what's in here, the commits since your last release
+					# are listed below. This will become v#{v}
+					#
+				EOF
+
+				log_file.close
+				system("git log --no-show-signature --format='# %h  %s' #{prev_tag}..HEAD >>#{log_file.path}")
+
+				pre_hash = Digest::SHA1.hexdigest(File.read(log_file.path))
+				system("git config -e -f #{log_file.path}")
+				if Digest::SHA1.hexdigest(File.read(log_file.path)) == pre_hash
+					puts "Release notes not edited; aborting"
+					log_file.unlink
+					return
+				end
+
+				puts "Tagging version #{v}..."
+				system("git tag -a -F #{log_file.path} v#{v}")
+				log_file.unlink
+			else
+				# Crikey this is a lot simpler
+				system("git tag -a -m 'Version v#{v}' v#{v}")
+			end
+
+			system("git push > #{DEVNULL} 2>&1")
+			system("git push --tags > #{DEVNULL} 2>&1")
+		end
+	end
+
+	# Calculate a version number based on the date of the most recent git commit.
+	#
+	# Return a version format string of the form `"0.YYYYMMDD.N"`, where
+	# `YYYYMMDD` is the date of the "top-most" commit in the tree, and `N` is
+	# the number of other commits also made on that date.
+	#
+	# This version format is not recommented for general use.  It has benefit
+	# only in situations where the principles of Semantic Versioning have no
+	# real meaning, such as packages where there is little or no concept of
+	# "backwards compatibility" (eg packages which only contain images and
+	# other assets), or where the package can, for reasons outside that of
+	# the package itself, never break backwards compatibility (definitions of
+	# binary-packed structures shared amongst multiple systems).
+	#
+	# The format of this commit-date-based version format allows for a strictly
+	# monotonically-increasing version number, aligned with the progression of the
+	# underlying git commit log.
+	#
+	# One limitation of the format is that it doesn't deal with the issue of
+	# package builds made from multiple divergent trees.  Unlike
+	# `git-describe`-based output, there is no "commit hash" identity
+	# included in the version string.  This is because of (ludicrous)
+	# limitations of the Rubygems format definition -- the moment there's a
+	# letter in the version number, the package is considered a "pre-release"
+	# version.  Since hashes are hex, we're boned.  Sorry about that.  Don't
+	# make builds off a branch, basically.
+	#
+	def self.commit_date_version(use_local_git = false)
+		if use_local_git
+			unless git_available?
+				raise RuntimeError,
+				      "GVB.commit_date_version(use_local_git=true) called, but git isn't installed"
+			end
+
+			sq_git_dir = shell_quoted_string(Dir.pwd)
+		else
+			sq_git_dir = shell_quoted_string((File.dirname(caller_file) rescue nil || Dir.pwd))
+		end
+
+		commit_dates = `git -C #{sq_git_dir} log --format=%at`.
+		               split("\n").
+		               map { |l| Time.at(Integer(l)).strftime("%Y%m%d") }
+
+		if $? == 0
+			# We got a log; calculate our version number and we're done.
+			version_date = commit_dates.first
+			commit_count = commit_dates.select { |d| d == version_date }.length - 1
+			dirty_suffix = if dirty_tree?
+				".dirty.#{Time.now.strftime("%Y%m%d.%H%M%S")}"
+			else
+				""
+			end
+
+			return "0.#{version_date}.#{commit_count}#{dirty_suffix}"
+		end
+
+		# git failed us; either we're not in a git repo or else it's a git
+		# repo that's not got any commits.
+
+		# Are we in a git repo with no tags?  If so, dump out our
+		# super-special version and be done with it.
+		system("git -C #{sq_git_dir} status > #{DEVNULL} 2>&1")
+		$? == 0 ? "0.0.0.1.ENOCOMMITS" : gem_version(use_local_git)
+	end
+
+	private
+
+	def self.git_available?
+		system("git --version > #{DEVNULL} 2>&1")
+
+		$? == 0
+	end
+
+	def self.dirty_tree?
+		# Are we in a dirty, dirty tree?
+		system("! git diff --no-ext-diff --quiet --exit-code 2> #{DEVNULL} || ! git diff-index --cached --quiet HEAD 2> #{DEVNULL}")
+
+		$? == 0
+	end
+
+	def self.caller_file
+		# Who called us?  Because this method gets called from other methods
+		# within this file, we can't just look at Gem.location_of_caller, but
+		# instead we need to parse the caller stack ourselves to find which
+		# gem we're trying to version all over.
+		Pathname(
+		  caller.
+		  map  { |l| l.split(':')[0] }.
+		  find { |l| l != __FILE__ }
+		).realpath.to_s rescue nil
+	end
+
+	def self.caller_gemspec
+		cf = caller_file or return nil
+
+		# Grovel through all the loaded gems to try and find the gem
+		# that contains the caller's file.
+		Gem.loaded_specs.values.each do |spec|
+			search_dirs = spec.require_paths.map { |d| "#{spec.full_gem_path}/#{d}" } +
+			              [File.join(spec.full_gem_path, spec.bindir)]
+			search_dirs.map! do |d|
+				begin
+					Pathname(d).realpath.to_s
+				rescue Errno::ENOENT
+					nil
+				end
+			end.compact!
+
+			if search_dirs.find { |d| cf.index(d) == 0 }
+				return spec
+			end
+		end
+
+		raise VersionUnobtainable,
+		      "Unable to find gemspec for caller file #{cf}"
+	end
+
+	def self.gem_version(use_local_git = false)
+		if use_local_git
+			raise VersionUnobtainable,
+			      "Unable to determine version from local git repo.  This should never happen."
+		end
+
+		if spec = caller_gemspec
+			return spec.version.to_s
+		else
+			# If we got here, something went *badly* wrong -- presumably, we
+			# weren't called from within a loaded gem, and so we've got *no*
+			# idea what's going on.  Time to bail!
+			if git_available?
+				raise VersionUnobtainable,
+				      "GVB.version(#{use_local_git.inspect}) failed, and I really don't know why."
+			else
+				raise VersionUnobtainable,
+				      "GVB.version(#{use_local_git.inspect}) failed; perhaps you need to install git?"
+			end
+		end
+	end
+
+	def self.shell_quoted_string(dir_string)
+		if Gem.win_platform?
+			return "\"#{dir_string}\""
+		else
+			# Shell Quoted, for your convenience
+			return "'#{dir_string.gsub("'", "'\\''")}'"
+		end
+	end
+
+	private_class_method :shell_quoted_string
+
+end
+
+GVB = GitVersionBump unless defined? GVB
+
+require 'git-version-bump/version'