ruby_git 0.1.3 → 0.3.0

data/lib/ruby_git.rb

@@ -1,27 +1,167 @@
 # frozen_string_literal: true
 
-require 'ruby_git/version'
-require 'ruby_git/file_helpers'
-require 'ruby_git/git_binary'
+require_relative 'ruby_git/command_line'
+require_relative 'ruby_git/encoding_normalizer'
+require_relative 'ruby_git/errors'
+require_relative 'ruby_git/repository'
+require_relative 'ruby_git/status'
+require_relative 'ruby_git/version'
+require_relative 'ruby_git/worktree'
 
-# 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.
+require 'logger'
+
+# The RubyGit module provides a Ruby API that is an object-oriented wrapper around
+# the `git` command line. It is intended to make automating both simple and complex Git
+# interactions easier. To accomplish this, it ties each action you can do with `git` to
+# the type of object that action operates on.
+#
+# There are three main objects in RubyGit:
+# * {Worktree}: The directory tree of actual checked
+#   out files. The working tree normally contains the contents of the HEAD commit's
+#   tree, plus any local changes that you have made but not yet committed.
+# * Index: The index is used as a staging area between your
+#   working tree and your repository. You can use the index to build up a set of changes
+#   that you want to commit together. When you create a commit, what is committed is what is
+#   currently in the index, not what is in your working directory.
+# * Repository: The repository stores the files in a project,
+#   their history, and other meta data like commit information, tags, and branches.
 #
 # @api public
 #
 module RubyGit
-  # Return information about the git binary used by this library
+  @logger = Logger.new(nil)
+
+  class << self
+    # The logger used by the RubyGit gem (Logger.new(nil) by default)
+    #
+    # @example Using the logger
+    #   RubyGit.logger.debug('Debug message')
+    #
+    # @example Setting the logger
+    #   require 'logger'
+    #   require 'stringio'
+    #   log_device = StringIO.new
+    #   RubyGit.logger = Logger.new(log_device, level: Logger::DEBUG)
+    #   RubyGit.logger.debug('Debug message')
+    #   log_device.string.include?('Debug message')
+    #    => true
+    #
+    # @return [Logger] the logger used by the RubyGit gem
+    #
+    attr_accessor :logger
+  end
+
+  @binary_path = 'git'
+
+  class << self
+    # The path to the git binary used by the RubyGit gem
+    #
+    # * If the path is a command name, the command is search for in the PATH.
+    #
+    # * If the path is a relative path, it relative to the current directory (not
+    #   recommended as this will change as the current directory is changed).
+    #
+    # * If the path is an absolute path, it is used as is.
+    #
+    # @example
+    #   RubyGit.binary_path
+    #    => "git"
+    #
+    # @return [String]
+    #
+    attr_accessor :binary_path
+  end
+
+  # Create an empty Git repository under the root working tree `path`
+  #
+  # If the repository already exists, it will not be overwritten.
+  #
+  # @see https://git-scm.com/docs/git-init git-init
+  #
+  # @example
+  #   worktree = Worktree.init(worktree_path)
+  #
+  # @param [String] worktree_path the root path of a worktree
+  #
+  # @raise [RubyGit::Error] if worktree_path is not a directory
+  #
+  # @return [RubyGit::Worktree] the worktree whose root is at `path`
+  #
+  def self.init(worktree_path)
+    RubyGit::Worktree.init(worktree_path)
+  end
+
+  # Open an existing Git working tree that contains worktree_path
+  #
+  # @see https://git-scm.com/docs/git-open git-open
+  #
+  # @example
+  #   worktree = Worktree.open(worktree_path)
+  #
+  # @param [String] worktree_path the root path of a worktree
+  #
+  # @raise [RubyGit::Error] if `worktree_path` does not exist, is not a directory, or is not within
+  #   a Git worktree.
+  #
+  # @return [RubyGit::Worktree] the worktree that contains `worktree_path`
+  #
+  def self.open(worktree_path)
+    RubyGit::Worktree.open(worktree_path)
+  end
+
+  # Copy the remote repository and checkout the default branch
+  #
+  # Clones the repository referred to by `repository_url` into a newly created
+  # directory, creates remote-tracking branches for each branch in the cloned repository,
+  # and checks out the default branch in the worktree whose root directory is `to_path`.
+  #
+  # @see https://git-scm.com/docs/git-clone git-clone
+  #
+  # @example Using default for Worktree path
+  #   FileUtils.pwd
+  #    => "/Users/jsmith"
+  #   worktree = Worktree.clone('https://github.com/main-branch/ruby_git.git')
+  #   worktree.path
+  #    => "/Users/jsmith/ruby_git"
+  #
+  # @example Using a specified worktree_path
+  #   FileUtils.pwd
+  #    => "/Users/jsmith"
+  #   worktree_path = '/tmp/project'
+  #   worktree = Worktree.clone('https://github.com/main-branch/ruby_git.git', to_path: worktree_path)
+  #   worktree.path
+  #    => "/tmp/project"
+  #
+  # @param [String] repository_url a reference to a Git repository
+  #
+  # @param [String] to_path where to put the checked out working tree once the repository is cloned
+  #
+  # `to_path` will be created if it does not exist.  An error is raised if `to_path` exists and
+  # not an empty directory.
+  #
+  # @raise [RubyGit::Error] if (1) `repository_url` is not valid or does not point to a valid repository OR
+  #   (2) `to_path` is not an empty directory.
+  #
+  # @return [RubyGit::Worktree] the working tree checked out from the cloned repository
+  #
+  def self.clone(repository_url, to_path: '')
+    RubyGit::Worktree.clone(repository_url, to_path:)
+  end
+
+  # The version of git referred to by the path
   #
-  # Use this object to set the path to the git binary to use or to see the
-  # path being used.
+  # @example for version 2.28.0
+  #   RubyGit.binary_version #=> [2, 28, 0]
   #
-  # @example Setting the git binary path
-  #    RubyGit.git.path = '/usr/local/bin/git'
+  # @return [Array<Integer>] an array of integers representing the version.
   #
-  # @return [RubyGit::GitBinary]
+  # @raise [RuntimeError] if path was not set via `path=` and either PATH is not set
+  #   or git was not found on the path.
   #
-  def self.git
-    (@git ||= RubyGit::GitBinary.new)
+  def self.binary_version
+    command = %w[version]
+    options = { out: StringIO.new, err: StringIO.new }
+    version_string = RubyGit::CommandLine.run(*command, **options).stdout[/\d+\.\d+(\.\d+)+/]
+    version_string.split('.').collect(&:to_i)
   end
 end

data/package.json

@@ -0,0 +1,11 @@
+{
+  "devDependencies": {
+    "@commitlint/cli": "^19.5.0",
+    "@commitlint/config-conventional": "^19.5.0",
+    "husky": "^9.1.0"
+  },
+  "scripts": {
+    "postinstall": "husky",
+    "prepare": "husky"
+  }
+}

data/ruby_git.gemspec

@@ -9,27 +9,28 @@ Gem::Specification.new do |spec|
   spec.email         = ['jcouball@yahoo.com']
   spec.license       = 'MIT'
 
-  spec.summary       = 'A Ruby library to work with Git Worktrees and Respositories'
+  spec.summary       = 'A Ruby library to work with Git Respositories'
   spec.description   = <<~DESCRIPTION
     THIS PROJECT IS A WORK IN PROGRESS AND IS NOT USEFUL IN ITS CURRENT STATE
 
-    An object-oriented interface to working with Git Worktrees and Repositories that
+    An object-oriented interface to working with Git Repositories that
     tries to make sense out of the Git command line.
   DESCRIPTION
-  spec.homepage = 'https://github.com/jcouball/ruby_git/'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.1.0')
   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'
+    'Platform: Mac, Linux, or Windows',
+    'Ruby: MRI 3.1 or later, TruffleRuby 24 or later, or JRuby 9.4 or later',
+    'Git 2.28.0 or later'
   ]
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
+  # Project links
+  spec.homepage = "https://github.com/main-branch/#{spec.name}"
   spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/jcouball/ruby_git/'
-  spec.metadata['changelog_uri'] = 'https://github.com/jcouball/ruby_git/blob/main/CHANGELOG.md'
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}"
+  spec.metadata['changelog_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}/file/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -40,14 +41,25 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  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'
-  spec.add_development_dependency 'rubocop', '~> 0.91'
-  spec.add_development_dependency 'simplecov', '0.17.1'
-  spec.add_development_dependency 'yard', '~> 0.9'
-  spec.add_development_dependency 'yardstick', '~> 0.9'
+  spec.add_development_dependency 'bundler-audit', '~> 0.9'
+  spec.add_development_dependency 'command_line_boss', '~> 0.2'
+  spec.add_development_dependency 'create_github_release', '~> 2.1'
+  spec.add_development_dependency 'main_branch_shared_rubocop_config', '~> 0.1'
+  spec.add_development_dependency 'rake', '~> 13.2'
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.74'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'simplecov-lcov', '~> 0.8'
+  spec.add_development_dependency 'simplecov-rspec', '~> 0.4'
+
+  unless RUBY_PLATFORM == 'java'
+    spec.add_development_dependency 'redcarpet', '~> 3.6'
+    spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
+    spec.add_development_dependency 'yardstick', '~> 0.9'
+  end
+
+  spec.add_dependency 'process_executer', '~> 3.0'
+  spec.add_dependency 'rchardet', '~> 1.9'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

metadata

@@ -1,17 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: ruby_git
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - James Couball
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-24 00:00:00.000000000 Z
+date: 2025-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bump
+  name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -25,103 +24,145 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.9'
 - !ruby/object:Gem::Dependency
-  name: bundler-audit
+  name: command_line_boss
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
-  name: github_changelog_generator
+  name: create_github_release
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: main_branch_shared_rubocop_config
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '0.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
-  name: redcarpet
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.5'
+        version: '13.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.5'
+        version: '13.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.91'
+        version: '1.74'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.91'
+        version: '1.74'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: simplecov-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.17.1
+        version: '0.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.17.1
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -129,6 +170,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.28
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -136,6 +180,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.28
 - !ruby/object:Gem::Dependency
   name: yardstick
   requirement: !ruby/object:Gem::Requirement
@@ -150,10 +197,38 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: process_executer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rchardet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
 description: |
   THIS PROJECT IS A WORK IN PROGRESS AND IS NOT USEFUL IN ITS CURRENT STATE
 
-  An object-oriented interface to working with Git Worktrees and Repositories that
+  An object-oriented interface to working with Git Repositories that
   tries to make sense out of the Git command line.
 email:
 - jcouball@yahoo.com
@@ -161,38 +236,66 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".commitlintrc.yml"
+- ".github/CODEOWNERS"
+- ".github/ISSUE_TEMPLATE.md"
+- ".github/PULL_REQUEST_TEMPLATE.md"
+- ".github/workflows/continuous_integration.yml"
+- ".github/workflows/enforce_conventional_commits.yml"
+- ".github/workflows/experimental_ruby_builds.yml"
 - ".gitignore"
+- ".husky/commit-msg"
+- ".markdownlint.yml"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
 - ".yardopts"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - Gemfile
-- ISSUE_TEMPLATE.md
-- LICENSE.md
-- MAINTAINERS.md
-- PULL_REQUEST_TEMPLATE.md
+- LICENSE.txt
+- PLAN.md
 - README.md
 - RELEASING.md
 - Rakefile
+- RubyGit Class Diagram.svg
+- bin/command-line-test
 - bin/console
 - bin/setup
 - lib/ruby_git.rb
-- lib/ruby_git/file_helpers.rb
-- lib/ruby_git/git_binary.rb
+- lib/ruby_git/command_line.rb
+- lib/ruby_git/command_line/options.rb
+- lib/ruby_git/command_line/result.rb
+- lib/ruby_git/command_line/runner.rb
+- lib/ruby_git/encoding_normalizer.rb
+- lib/ruby_git/errors.rb
+- lib/ruby_git/repository.rb
+- lib/ruby_git/status.rb
+- lib/ruby_git/status/branch.rb
+- lib/ruby_git/status/entry.rb
+- lib/ruby_git/status/ignored_entry.rb
+- lib/ruby_git/status/ordinary_entry.rb
+- lib/ruby_git/status/parser.rb
+- lib/ruby_git/status/renamed_entry.rb
+- lib/ruby_git/status/report.rb
+- lib/ruby_git/status/stash.rb
+- lib/ruby_git/status/submodule_status.rb
+- lib/ruby_git/status/unmerged_entry.rb
+- lib/ruby_git/status/untracked_entry.rb
 - lib/ruby_git/version.rb
+- lib/ruby_git/worktree.rb
+- package.json
 - pre-commit
 - ruby_git.gemspec
-homepage: https://github.com/jcouball/ruby_git/
+homepage: https://github.com/main-branch/ruby_git
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/jcouball/ruby_git/
-  source_code_uri: https://github.com/jcouball/ruby_git/
-  changelog_uri: https://github.com/jcouball/ruby_git/blob/main/CHANGELOG.md
-post_install_message:
+  homepage_uri: https://github.com/main-branch/ruby_git
+  source_code_uri: https://github.com/main-branch/ruby_git
+  documentation_uri: https://rubydoc.info/gems/ruby_git/0.3.0
+  changelog_uri: https://rubydoc.info/gems/ruby_git/0.3.0/file/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -200,19 +303,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 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
-rubygems_version: 3.1.2
-signing_key:
+- 'Platform: Mac, Linux, or Windows'
+- 'Ruby: MRI 3.1 or later, TruffleRuby 24 or later, or JRuby 9.4 or later'
+- Git 2.28.0 or later
+rubygems_version: 3.6.2
 specification_version: 4
-summary: A Ruby library to work with Git Worktrees and Respositories
+summary: A Ruby library to work with Git Respositories
 test_files: []

data/.travis.yml

@@ -1,13 +0,0 @@
----
-language: ruby
-cache: bundler
-
-rvm:
-  - 2.6
-  - 2.7
-  - ruby-head
-
-matrix:
-  allow_failures:
-    - rvm: ruby-head
-  fast_finish: true

data/MAINTAINERS.md

@@ -1,8 +0,0 @@
-# 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)