ruby_git 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7087b8dd63c3607ba8feab849f53758dab7bd5e9f651d2abde5c0883a0d9540e
-  data.tar.gz: 7955f33dea5ed42578726c5089d3246322618eeee85a6713c1121fe92f0ef2b5
+  metadata.gz: 88ac1dcb3abb6fc749755848f777ebd367e76ef9ae737ef4f778890afd8ff096
+  data.tar.gz: ba110f2ac31a96989e6e486a2377f76b080ea03533d304448848bf351ef96988
 SHA512:
-  metadata.gz: a52889cbf50620fd7edf6b47ad903554e2ae075d6f822d659640c91db33943110a4795e28f1bc40e57474fad71817adc0a78e3081d718df740d03702cabcd29c
-  data.tar.gz: db553459c9cea1e038088eb7d9298ee4bd873d6c5e315f937adbdc487981b27a18cf6445aa5228d6bada9d5e70785fc682725ca8697d44335004a5feaf524285
+  metadata.gz: f4f1d53fd8cc7c4939e7ccf797e39702a6541159c06673fc5ec8e723629008020d8a0371f0365b0c255bc9eb0af83ed8d6b6dc9dd7f52d3f53d1286c2253be59
+  data.tar.gz: 6a11a5211e5554fec26034351e1a7c531ce25d87e9b9c3d3ab53aac3b9569ed997135dfb879c1e3d3a3a80653811ee64082ed4e18baa8a1b300f58ea0d7d1e97

data/.gitignore

@@ -14,3 +14,5 @@
 rubocop-report.json
 
 /Gemfile.lock
+.idea
+.irb_history

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper.rb
+--color
+--format documentation

data/.yardopts

@@ -2,3 +2,4 @@
 --hide-void-return
 --markup-provider=redcarpet
 --markup markdown
+- CHANGELOG.md CONTRIBUTING.md MAINTAINERS.md RELEASING.md LICENSE.md

data/CHANGELOG.md

@@ -1,9 +1,30 @@
 # Change Log
 
-## 0.1.1
+## [v0.1.2](https://github.com/jcouball/ruby_git/releases/tag/v0.1.2) (2020-09-24)
 
-See https://github.com/jcouball/ruby_git/releases/tag/v0.1.1
+[Full Changelog](https://github.com/jcouball/ruby_git/compare/v0.1.1...v0.1.2)
 
-## 0.1.0
+**Merged pull requests:**
 
-See https://github.com/jcouball/ruby_git/releases/tag/v0.1.0
+- Update instructions for creating releases and updating the changelog [\#8](https://github.com/jcouball/ruby_git/pull/8) ([jcouball](https://github.com/jcouball))
+- Changes requested in documentation review [\#7](https://github.com/jcouball/ruby_git/pull/7) ([jcouball](https://github.com/jcouball))
+- Set and retrieve the path to the git binary used by this library [\#6](https://github.com/jcouball/ruby_git/pull/6) ([jcouball](https://github.com/jcouball))
+- Move RSpec config from Rakefile to .rspec [\#5](https://github.com/jcouball/ruby_git/pull/5) ([jcouball](https://github.com/jcouball))
+- Release v0.1.1 [\#4](https://github.com/jcouball/ruby_git/pull/4) ([jcouball](https://github.com/jcouball))
+
+## [v0.1.1](https://github.com/jcouball/ruby_git/releases/tag/v0.1.1) (2020-09-18)
+
+[Full Changelog](https://github.com/jcouball/ruby_git/compare/v0.1.0...v0.1.1)
+
+**Merged pull requests:**
+
+- Add notice saying that this project is a work in progress [\#3](https://github.com/jcouball/ruby_git/pull/3) ([jcouball](https://github.com/jcouball))
+- Remove Gemfile.lock and add it to .gitignore [\#2](https://github.com/jcouball/ruby_git/pull/2) ([jcouball](https://github.com/jcouball))
+
+## [v0.1.0](https://github.com/jcouball/ruby_git/releases/tag/v0.1.0) (2020-09-18)
+
+[Full Changelog](https://github.com/jcouball/ruby_git/compare/04b4b2bc59b0b09ad45a69572450cb393dbe79a1...v0.1.0)
+
+
+
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/CONTRIBUTING.md

@@ -59,7 +59,7 @@ request meets [the project's coding standards](#coding-standards).
 
 ## Coding standards
 
-In order to ensure high quality, all pull requests must meet these requirements:
+All pull requests must meet these requirements:
 
 ### 1 PR = 1 Commit
   * All commits for a PR must be squashed into one commit
@@ -76,14 +76,21 @@ In order to ensure high quality, all pull requests must meet these requirements:
 ### Documentation
   * New and updated public methods must have [YARD](https://yardoc.org/)
     documentation added to them
+      * [The YARD Cheatsheet](https://gist.github.com/thelastinuit/5984665e6ab69d3c0a413a03602c45be)
+        is a good reference
   * New and updated public facing features should be documented in the project's
     [README.md](README.md)
-  * All documentation must pass `yardstick` documentation analysis. 
+  * All documentation must pass `yardstick` documentation analysis
   * The documentation suite must maintain 100% documentation to pass
 
 ### Continuous Integration
   * All tests must pass in the project's [Travis CI](https://travis-ci.org/jcouball/ruby_git)
-    build before the pull request will be merged
+    build before the pull request will be merged.
+  * You can simulate what happens in the Travis CI build by running `bundle exec rake` in 
+    the projects root directory.
+
+### Other Design Guidelines
+  * Use keyword args with defaults instead of an opts hash
 
 ## Licensing
 

data/MAINTAINERS.md

@@ -0,0 +1,8 @@
+# Maintainers
+
+When making changes in this repository, one of the maintainers below must review
+and approve your pull request.
+
+### Maintainers
+
+* [James Couball](https://github.com/jcouball)

data/README.md

@@ -1,12 +1,14 @@
-# Ruby Git
+# RubyGit
 
 **THIS PROJECT IS A WORK IN PROGRESS AND IS NOT USEFUL IN ITS CURRENT STATE**
 
 [![Build Status](https://travis-ci.org/jcouball/ruby_git.svg?branch=main)](https://travis-ci.org/jcouball/ruby_git)
 [![Maintainability](https://api.codeclimate.com/v1/badges/2d8d52a55d655b6a3def/maintainability)](https://codeclimate.com/github/jcouball/ruby_git/maintainability)
 
-Ruby Git is an object-oriented wrapper for the `git` command line tool for working with Worktrees
-and Repositories. It tries to make more sense out of the Git command line. 
+RubyGit is an object-oriented wrapper for the `git` command line tool for working with Worktrees
+and Repositories. It tries to make more sense out of the Git command line. See the object model
+in [this Lucid chart diagram](https://app.lucidchart.com/invitations/accept/7df13bab-3383-4683-8cb4-e76d539de93d)
+(requires sign in).
 
 ## Installation
 
@@ -26,6 +28,16 @@ Or install it directly from the command line:
 
 ## Usage
 
+To configure RubyGit:
+
+```Ruby
+RubyGit.git.path = '/usr/local/bin/git'
+
+# Returns the user set path or searches for 'git' in ENV['PATH']
+RubyGit.git.path #=> '/usr/local/bin/git'
+RubyGit.git.version #=> [2,28,0]
+```
+
 To work with an existing Worktree:
 
 ```Ruby
@@ -56,14 +68,11 @@ The full API is documented in [the RubyGit YARD documentation](https://github.co
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec`
-to run the tests. You can also run `bin/console` for an interactive prompt that will allow
-you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec rake` to run tests, static analysis, and build the gem.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a
-new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push git commits
-and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+For experimentation, you can also run `bin/console` for an interactive (IRB) prompt that
+automatically requires ruby_git.
 
 ## Contributing
 

data/RELEASING.md

@@ -10,18 +10,26 @@ and the new release version to be created is `1.1.0.pre1`.
 
 ## Prepare the release
 
-From a fork of ruby_git, create a PR containing changes to (1) bump the
-version number, (2) update the CHANGELOG.md, and (3) tag the release.
-
-  * Bump the version number in lib/ruby_git/version.rb following [Semantic Versioning](https://semver.org)
-    guidelines
-  * Add a link in CHANGELOG.md to the release tag which will be created later
-    in this guide
-  * Create a new tag using [git-extras](https://github.com/tj/git-extras/blob/main/Commands.md#git-release)
-    `git release` command
-    * For example: `git release v1.1.0.pre1`
-  * These should be the only changes in the PR
-  * Get the PR reviewed, approved and merged to main.
+On a branch (or fork) of ruby_git, create a PR containing changes to (1) bump the
+version number and (2) update the CHANGELOG.md, and (3) tag the release.
+
+  * Bump the version number
+    * Version number is in lib/ruby_git/version.rb
+    * Follow [Semantic Versioning](https://semver.org) guidelines
+    * `bundle exec bump --no-commit patch` # backwards compatible bug fixes
+    * `bundle exec bump --no-commit minor` # backwards compatible new functionality
+    * `bundle exec bump --no-commit major` # incompatible API changes
+    
+  * Update CHANGELOG.md
+    * `bundle exec rake changelog`
+
+  * Stage the changes to be committed
+    * `git add lib/ruby_git/version.rb CHANGELOG.md`
+
+  * Commit, tag, and push changes to the repository
+    * ```git release `ruby -I lib -r ruby_git -e 'puts RubyGit::VERSION'` ```
+
+  * Create a PR with these changes, have it reviewed and approved, and merged to main.
 
 ## Create a GitHub release
 
@@ -30,14 +38,8 @@ select `Draft a new release`
 
   * Select the tag corresponding to the version being released `v1.1.0.pre1`
   * The Target should be `main`
-  * For the release description, use the output of [changelog-rs](https://github.com/perlun/changelog-rs)
-    * Since the release has not been created yet, you will need to supply
-      `changeling-rs` with the current release tag and the tag the new release
-      is being created from
-    * For example: `changelog-rs . v1.0.0 v1.1.0.pre1`
-    * Copy the output, omitting the tag header `## v1.1.0.pre1` and paste into
-      the release description
-    * The release description can be edited later if needed
+  * For the release description, copy the relevant section from the CHANGELOG.md
+    * The release description can be edited later.
   * Select the appropriate value for `This is a pre-release`
     * Since `v1.1.0.pre1` is a pre-release, check `This is a pre-release`
 

data/Rakefile

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-task default: %i[spec bundle:audit rubocop yardstick verify_measurements yard build]
+task default: %i[spec bundle:audit rubocop yardstick:audit yardstick:coverage yard build]
 
 # Bundler Audit
 
@@ -20,13 +20,7 @@ require 'bump/tasks'
 
 require 'rspec/core/rake_task'
 
-RSpec::Core::RakeTask.new do |t|
-  t.rspec_opts = %w[
-    --require spec_helper.rb
-    --color
-    --format documentation
-  ]
-end
+RSpec::Core::RakeTask.new
 
 CLEAN << 'coverage'
 CLEAN << '.rspec_status'
@@ -55,14 +49,30 @@ end
 CLEAN << '.yardoc'
 CLEAN << 'doc'
 
-# yardstick
+# Yardstick
+
+desc 'Run yardstick to show missing YARD doc elements'
+task :'yardstick:audit' do
+  sh "yardstick 'lib/**/*.rb'"
+end
+
+# Yardstick coverage
 
 require 'yardstick/rake/verify'
-Yardstick::Rake::Verify.new do |verify|
+
+Yardstick::Rake::Verify.new(:'yardstick:coverage') do |verify|
   verify.threshold = 100
 end
 
-desc 'Run yardstick to check yard docs'
-task :yardstick do
-  sh "yardstick 'lib/**/*.rb'"
+# Changelog
+
+require 'github_changelog_generator/task'
+
+GitHubChangelogGenerator::RakeTask.new :changelog do |config|
+  config.header = '# Change Log'
+  config.user = 'jcouball'
+  config.project = 'ruby_git'
+  config.future_release = "v#{RubyGit::VERSION}"
+  config.release_url = 'https://github.com/jcouball/ruby_git/releases/tag/%s'
+  config.author = true
 end

data/lib/ruby_git.rb

@@ -1,7 +1,27 @@
 # frozen_string_literal: true
 
 require 'ruby_git/version'
+require 'ruby_git/file_helpers'
+require 'ruby_git/git_binary'
 
+# RubyGit is an object-oriented wrapper for the `git` command line tool for
+# working with Worktrees and Repositories. It tries to make more sense out
+# of the Git command line.
+#
+# @api public
+#
 module RubyGit
-  class Error < StandardError; end
+  # Return information about the git binary used by this library
+  #
+  # Use this object to set the path to the git binary to use or to see the
+  # path being used.
+  #
+  # @example Setting the git binary path
+  #    RubyGit.git.path = '/usr/local/bin/git'
+  #
+  # @return [RubyGit::GitBinary]
+  #
+  def self.git
+    (@git ||= RubyGit::GitBinary.new)
+  end
 end

data/lib/ruby_git/file_helpers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyGit
+  # A namespace for several file utility methods that I wish were part of FileUtils.
+  #
+  # @api public
+  #
+  module FileHelpers
+    # Cross platform way to find an executable file within a list of paths
+    #
+    # Works for both Linux/Unix and Windows.
+    #
+    # @example Searching over the PATH for a command
+    #   path = FileUtils.which('git')
+    #
+    # @example Overriding the default PATH
+    #   path = FileUtils.which('git', ['/usr/bin', '/usr/local/bin'])
+    #
+    # @param [String] cmd The basename of the executable file to search for
+    # @param [Array<String>] paths The list of directories to search for basename in
+    # @param [Array<String>] exts The list of extensions that indicate that a file is executable
+    #
+    # `exts` is for Windows. Other platforms should accept the default.
+    #
+    # @return [Pathname,nil] The path to the first executable file found on the path or
+    #   nil an executable file was not found.
+    #
+    def self.which(
+      cmd,
+      paths: ENV['PATH'].split(File::PATH_SEPARATOR),
+      exts: (ENV['PATHEXT']&.split(';') || [''])
+    )
+      raise 'PATH is not set' unless ENV.keys.include?('PATH')
+
+      paths
+        .product(exts)
+        .map { |path, ext| Pathname.new(File.join(path, "#{cmd}#{ext}")) }
+        .reject { |path| path.directory? || !path.executable? }
+        .find { |exe_path| !exe_path.directory? && exe_path.executable? }
+    end
+  end
+end

data/lib/ruby_git/git_binary.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyGit
+  # Sets and tracks the path to a git executable and reports the version
+  #
+  # @api public
+  #
+  class GitBinary
+    # Return a new GitBinary object
+    #
+    # @example
+    #   GitBinary.new
+    #
+    def initialize
+      @path = nil
+    end
+
+    # Sets the path to the git binary
+    #
+    # The given path must point to an executable file or a RuntimeError is raised.
+    #
+    # @example Setting the path to the git binary
+    #   git.path = '/usr/local/bin/git'
+    #
+    # @param [String] path the path to a git executable
+    #
+    # @return [Pathname]
+    #
+    # @raise [RuntimeError] A RuntimeError is raised when the path does not refer
+    #   to an existing executable file.
+    #
+    def path=(path)
+      new_path = Pathname.new(path)
+      raise "'#{new_path}' does not exist." unless new_path.exist?
+      raise "'#{new_path}' is not a file." unless new_path.file?
+      raise "'#{new_path}' is not executable." unless new_path.executable?
+
+      @path = new_path
+    end
+
+    # Retrieve the path to the git binary
+    #
+    # @example Get the git found on the PATH
+    #   git = RubyGit::GitBinary.new
+    #   path = git.path
+    #
+    # @return [Pathname] the path to the git binary
+    #
+    # @raise [RuntimeError] if path was not set via `path=` and either PATH is not set
+    #   or git was not found on the path.
+    #
+    def path
+      @path || (@path = self.class.default_path)
+    end
+
+    # Get the default path to to a git binary by searching the PATH
+    #
+    # @example Find the pathname to `super_git`
+    #   git = RubyGit::GitBinary.new
+    #   git.path = git.default_path(basename: 'super_git')
+    #
+    # @param [String] basename The basename of the git command
+    #
+    # @return [Pathname] the path to the git binary found in the path
+    #
+    # @raise [RuntimeError] if either PATH is not set or an executable file
+    #   `basename` was not found on the path.
+    #
+    def self.default_path(basename: 'git')
+      RubyGit::FileHelpers.which(basename) || raise("Could not find '#{basename}' in the PATH.")
+    end
+
+    # The version of git referred to by the path
+    #
+    # @example for version 2.28.0
+    #   git = RubyGit::GitBinary.new
+    #   puts git.version #=> [2,28,0]
+    #
+    # @return [Array<Integer>] an array of integers representing the version.
+    #
+    # @raise [RuntimeError] if path was not set via `path=` and either PATH is not set
+    #   or git was not found on the path.
+    #
+    def version
+      output = `#{path} --version`
+      version = output[/\d+\.\d+(\.\d+)+/]
+      version.split('.').collect(&:to_i)
+    end
+  end
+end

data/lib/ruby_git/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module RubyGit
-  VERSION = '0.1.1'
+  # The ruby_git gem version
+  #
+  VERSION = '0.1.2'
 end

data/ruby_git.gemspec

@@ -18,7 +18,12 @@ Gem::Specification.new do |spec|
   DESCRIPTION
   spec.homepage = 'https://github.com/pages/jcouball/ruby_git/'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
-  spec.requirements = ['git 2.18.0 or later']
+  spec.requirements = [
+    'Git 2.18.0 or later',
+    'Ruby 2.6 or later',
+    'Only MRI Ruby and JRuby are officially supported.',
+    'Mac, Linux, Unix, and Windows platforms are supported'
+  ]
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
@@ -37,6 +42,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bump', '~> 0.9'
   spec.add_development_dependency 'bundler-audit', '~> 0.7'
+  spec.add_development_dependency 'github_changelog_generator', '~> 1.15'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'redcarpet', '~> 3.5'
   spec.add_development_dependency 'rspec', '~> 3.9'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_git
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-18 00:00:00.000000000 Z
+date: 2020-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: github_changelog_generator
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -148,6 +162,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
 - ".yardopts"
@@ -156,6 +171,7 @@ files:
 - Gemfile
 - ISSUE_TEMPLATE.md
 - LICENSE.md
+- MAINTAINERS.md
 - PULL_REQUEST_TEMPLATE.md
 - README.md
 - RELEASING.md
@@ -163,6 +179,8 @@ files:
 - bin/console
 - bin/setup
 - lib/ruby_git.rb
+- lib/ruby_git/file_helpers.rb
+- lib/ruby_git/git_binary.rb
 - lib/ruby_git/version.rb
 - pre-commit
 - ruby_git.gemspec
@@ -189,7 +207,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- git 2.18.0 or later
+- Git 2.18.0 or later
+- Ruby 2.6 or later
+- Only MRI Ruby and JRuby are officially supported.
+- Mac, Linux, Unix, and Windows platforms are supported
 rubygems_version: 3.1.2
 signing_key:
 specification_version: 4