Set and retrieve the path to the git binary used by this library

Author: James Couball

README.md

@@ -1,11 +1,11 @@
-# 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
+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. 
 
 ## Installation
@@ -26,6 +26,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

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

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

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 is not 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

lib/ruby_git/version.rb

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