git 2.1.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b171ab737c87e925d5752b52f2f05bdd2361592624d88b8db8db380dde051019
-  data.tar.gz: d7b3b7cdaba4996288c4c0e8fffe7819da6c0933ade68ca810d9fb3519d5cda0
+  metadata.gz: 1e24e434e4639e6c31133234cee6d96708baf23d212c2f78cf4b94159810b090
+  data.tar.gz: 9fc37b011ac0cb0e87a0ee50b7993e751a7075a7496d6feb41431d2f3612e823
 SHA512:
-  metadata.gz: '08dd5a4ea7b07230642e2dd87fca85ea634890f4700b77a996b3ff4443fc62d3c11a230c082c4d5b2c45c6c7d6916d9b98ce7362676e72d1a4bdd6f0fe2043e6'
-  data.tar.gz: 568111f5579b6b1728974dbfa12dc4d742f3715e951645dbed9a54d91399492157b77659b2e956ee995c142c8dbb01f3ee07357fb4db2a9c2bd0e1870e83dc79
+  metadata.gz: 232624614200233e3f2ed308a4e73580345fef5be0a98e64f35992ecb222fa96c4163399b2f08afbfcdf69cd3b2f8f6c57c309fe9122f18a56e9bc31f827b301
+  data.tar.gz: 4ae699244e5ff9f679795279b8dbfeebe35ce8c9bfb7e5d9a18552b77b3d86b630f50bd9fedb4eec4f697269cfec6c90f72adfa2edeada25258ab457f3b5dad8

data/CHANGELOG.md

@@ -5,6 +5,32 @@
 
 # Change Log
 
+## v2.3.0 (2024-09-01)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.2.0..v2.3.0)
+
+Changes since v2.2.0:
+
+* f8bc987 Fix windows CI build error
+* 471f5a8 Sanatize object ref sent to cat-file command
+* 604a9a2 Make Git::Base#branch work when HEAD is detached
+
+## v2.2.0 (2024-08-26)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.1.1..v2.2.0)
+
+Changes since v2.1.1:
+
+* 7292f2c Omit the test for signed commit data on Windows
+* 2d6157c Document this gem's (aspirational) design philosophy
+* d4f66ab Sanitize non-option arguments passed to `git name-rev`
+* 0296442 Refactor Git::Lib#rev_parse
+* 9b9b31e Verify that the revision-range passed to git log does not resemble a command-line option
+* dc46ede Verify that the commit-ish passed to git describe does not resemble a command-line option
+* 00c4939 Verify that the commit(s) passed to git diff do not resemble a command-line option
+* a08f89b Update README
+* 737c4bb ls-tree optional recursion into subtrees
+
 ## v2.1.1 (2024-06-01)
 
 [Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.1.0..v2.1.1)

data/CONTRIBUTING.md

@@ -3,116 +3,191 @@
 # @title How To Contribute
 -->
 
-# Contributing to ruby-git
-
-Thank you for your interest in contributing to the ruby-git project.
-
-This document gives the guidelines for contributing to the ruby-git project.
-These guidelines may not fit every situation.  When contributing use your best
-judgement.
-
-Propose changes to these guidelines with a pull request.
+* [How to contribute](#how-to-contribute)
+* [How to report an issue or request a feature](#how-to-report-an-issue-or-request-a-feature)
+* [How to submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
+  * [Commit your changes to a fork of `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git)
+  * [Create a pull request](#create-a-pull-request)
+  * [Get your pull request reviewed](#get-your-pull-request-reviewed)
+* [Design philosophy](#design-philosophy)
+  * [Direct mapping to git commands](#direct-mapping-to-git-commands)
+  * [Parameter naming](#parameter-naming)
+  * [Output processing](#output-processing)
+* [Coding standards](#coding-standards)
+  * [1 PR = 1 Commit](#1-pr--1-commit)
+  * [Unit tests](#unit-tests)
+  * [Continuous integration](#continuous-integration)
+  * [Documentation](#documentation)
+* [Licensing](#licensing)
+
+
+# Contributing to the git gem
+
+Thank you for your interest in contributing to the `ruby-git` project.
+
+This document provides guidelines for contributing to the `ruby-git` project. While
+these guidelines may not cover every situation, we encourage you to use your best
+judgment when contributing.
+
+If you have suggestions for improving these guidelines, please propose changes via a
+pull request.
 
 ## How to contribute
 
-You can contribute in two ways:
+You can contribute in the following ways:
 
-1. [Report an issue or make a feature request](#how-to-report-an-issue-or-make-a-feature-request)
-2. [Submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
+1. [Report an issue or request a
+   feature](#how-to-report-an-issue-or-request-a-feature)
+2. [Submit a code or documentation
+   change](#how-to-submit-a-code-or-documentation-change)
 
-## How to report an issue or make a feature request
+## How to report an issue or request a feature
 
-ruby-git utilizes [GitHub Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues)
+`ruby-git` utilizes [GitHub
+Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues)
 for issue tracking and feature requests.
 
-Report an issue or feature request by [creating a ruby-git Github issue](https://github.com/ruby-git/ruby-git/issues/new).
-Fill in the template to describe the issue or feature request the best you can.
+To report an issue or request a feature, please [create a `ruby-git` GitHub
+issue](https://github.com/ruby-git/ruby-git/issues/new). Fill in the template as
+thoroughly as possible to describe the issue or feature request.
 
 ## How to submit a code or documentation change
 
-There is three step process for code or documentation changes:
+There is a three-step process for submitting code or documentation changes:
 
-1. [Commit your changes to a fork of ruby-git](#commit-changes-to-a-fork-of-ruby-git)
+1. [Commit your changes to a fork of
+   `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git)
 2. [Create a pull request](#create-a-pull-request)
 3. [Get your pull request reviewed](#get-your-pull-request-reviewed)
 
-### Commit changes to a fork of ruby-git
+### Commit your changes to a fork of `ruby-git`
 
-Make your changes in a fork of the ruby-git repository.
+Make your changes in a fork of the `ruby-git` repository.
 
 ### Create a pull request
 
-See [this article](https://help.github.com/articles/about-pull-requests/) if you
-are not familiar with GitHub Pull Requests.
+If you are not familiar with GitHub Pull Requests, please refer to [this
+article](https://help.github.com/articles/about-pull-requests/).
 
 Follow the instructions in the pull request template.
 
 ### Get your pull request reviewed
 
-Code review takes place in a GitHub pull request using the [the Github pull request review feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews).
+Code review takes place in a GitHub pull request using the [GitHub pull request
+review
+feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews).
 
 Once your pull request is ready for review, request a review from at least one
-[maintainer](MAINTAINERS.md) and any number of other contributors.
+[maintainer](MAINTAINERS.md) and any other contributors you deem necessary.
+
+During the review process, you may need to make additional commits, which should be
+squashed. Additionally, you may need to rebase your branch to the latest `master`
+branch if other changes have been merged.
+
+At least one approval from a project maintainer is required before your pull request
+can be merged. The maintainer is responsible for ensuring that the pull request meets
+[the project's coding standards](#coding-standards).
+
+## Design philosophy
+
+*Note: As of v2.x of the `git` gem, this design philosophy is aspirational. Future
+versions may include interface changes to fully align with these principles.*
+
+The `git` gem is designed as a lightweight wrapper around the `git` command-line
+tool, providing Ruby developers with a simple and intuitive interface for
+programmatically interacting with Git.
+
+This gem adheres to the "principle of least surprise," ensuring that it does not
+introduce unnecessary abstraction layers or modify Git's core functionality. Instead,
+the gem maintains a close alignment with the existing `git` command-line interface,
+avoiding extensions or alterations that could lead to unexpected behaviors.
+
+By following this philosophy, the `git` gem allows users to leverage their existing
+knowledge of Git while benefiting from the expressiveness and power of Ruby's syntax
+and paradigms.
+
+### Direct mapping to git commands
 
-During the review process, you may need to make additional commits which would
-need to be squashed.  It may also be necessary to rebase to master again if other
-changes are merged before your PR.
+Git commands are implemented within the `Git::Base` class, with each method directly
+corresponding to a `git` command. When a `Git::Base` object is instantiated via
+`Git.open`, `Git.clone`, or `Git.init`, the user can invoke these methods to interact
+with the underlying Git repository.
 
-At least one approval is required from a project maintainer before your pull
-request can be merged.  The maintainer is responsible for ensuring that the pull
-request meets [the project's coding standards](#coding-standards).
+For example, the `git add` command is implemented as `Git::Base#add`, and the `git
+ls-files` command is implemented as `Git::Base#ls_files`.
+
+When a single Git command serves multiple distinct purposes, method names within the
+`Git::Base` class should use the `git` command name as a prefix, followed by a
+descriptive suffix to indicate the specific function.
+
+For instance, `#ls_files_untracked` and `#ls_files_staged` could be used to execute
+the `git ls-files` command and return untracked and staged files, respectively.
+
+To enhance usability, aliases may be introduced to provide more user-friendly method
+names where appropriate.
+
+### Parameter naming
+
+Parameters within the `git` gem methods are named after their corresponding long
+command-line options, ensuring familiarity and ease of use for developers already
+accustomed to Git. Note that not all Git command options are supported.
+
+### Output processing
+
+The `git` gem translates the output of many Git commands into Ruby objects, making it
+easier to work with programmatically.
+
+These Ruby objects often include methods that allow for further Git operations where
+useful, providing additional functionality while staying true to the underlying Git
+behavior.
 
 ## Coding standards
 
-In order to ensure high quality, all pull requests must meet these requirements:
+To ensure high-quality contributions, all pull requests must meet the following
+requirements:
 
 ### 1 PR = 1 Commit
 
-* All commits for a PR must be squashed into one commit
-* To avoid an extra merge commit, the PR must be able to be merged as [a fast forward
-  merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
-* The easiest way to ensure a fast forward merge is to rebase your local branch to
- the ruby-git master branch
+* All commits for a PR must be squashed into a single commit.
+* To avoid an extra merge commit, the PR must be able to be merged as [a fast-forward
+  merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging).
+* The easiest way to ensure a fast-forward merge is to rebase your local branch to
+  the `ruby-git` master branch.
 
 ### Unit tests
 
-* All changes must be accompanied by new or modified unit tests
+* All changes must be accompanied by new or modified unit tests.
 * The entire test suite must pass when `bundle exec rake default` is run from the
   project's local working copy.
 
-While working on specific features you can run individual test files or
-a group of tests using `bin/test`:
+While working on specific features, you can run individual test files or a group of
+tests using `bin/test`:
 
-    # run a single file (from tests/units):
-    $ bin/test test_object
+```bash
+# run a single file (from tests/units):
+$ bin/test test_object
 
-    # run multiple files:
-    $ bin/test test_object test_archive
+# run multiple files:
+$ bin/test test_object test_archive
 
-    # run all unit tests:
-    $ bin/test
+# run all unit tests:
+$ bin/test
+```
 
 ### Continuous integration
 
-* All tests must pass in the project's [GitHub Continuous Integration
-  build](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) before the
-  pull request will be merged.
-* The [Continuous Integration
-  workflow](https://github.com/ruby-git/ruby-git/blob/master/.github/workflows/continuous_integration.yml)
-  runs both `bundle exec rake default` and `bundle exec rake test:gem` from the
-  project's [Rakefile](https://github.com/ruby-git/ruby-git/blob/master/Rakefile).
+All tests must pass in the project's [GitHub Continuous Integration build](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) before the pull request will be merged.
+
+The [Continuous Integration workflow](https://github.com/ruby-git/ruby-git/blob/master/.github/workflows/continuous_integration.yml) runs both `bundle exec rake default` and `bundle exec rake test:gem` from the project's [Rakefile](https://github.com/ruby-git/ruby-git/blob/master/Rakefile).
 
 ### Documentation
 
-* New and updated public methods must have [YARD](https://yardoc.org/) documentation
-  added to them
-* New and updated public facing features should be documented in the project's
-  [README.md](README.md)
+New and updated public methods must include [YARD](https://yardoc.org/) documentation.
+
+New and updated public-facing features should be documented in the project's [README.md](README.md).
 
 ## Licensing
 
-ruby-git uses [the MIT license](https://choosealicense.com/licenses/mit/) as
-declared in the [LICENSE](LICENSE) file.
+`ruby-git` uses [the MIT license](https://choosealicense.com/licenses/mit/) as declared in the [LICENSE](LICENSE) file.
 
-Licensing is very important to open source projects. It helps ensure the
-software continues to be available under the terms that the author desired.
+Licensing is critical to open-source projects as it ensures the software remains available under the terms desired by the author.

data/README.md

@@ -236,6 +236,9 @@ g.index.writable?
 g.repo
 g.dir
 
+# ls-tree with recursion into subtrees (list files)
+g.ls_tree("HEAD", recursive: true)
+
 # log - returns a Git::Log object, which is an Enumerator of Git::Commit objects
 # default configuration returns a max of 30 commits
 g.log
@@ -274,7 +277,7 @@ tree.blobs
 tree.subtrees
 tree.children # blobs and subtrees
 
-g.revparse('v2.5:Makefile')
+g.rev_parse('v2.0.0:README.md')
 
 g.branches # returns Git::Branch objects
 g.branches.local

data/lib/git/base.rb

@@ -634,23 +634,33 @@ module Git
     # runs git rev-parse to convert the objectish to a full sha
     #
     # @example
-    #   git.revparse("HEAD^^")
-    #   git.revparse('v2.4^{tree}')
-    #   git.revparse('v2.4:/doc/index.html')
+    #   git.rev_parse("HEAD^^")
+    #   git.rev_parse('v2.4^{tree}')
+    #   git.rev_parse('v2.4:/doc/index.html')
     #
-    def revparse(objectish)
-      self.lib.revparse(objectish)
+    def rev_parse(objectish)
+      self.lib.rev_parse(objectish)
     end
 
-    def ls_tree(objectish)
-      self.lib.ls_tree(objectish)
+    # For backwards compatibility
+    alias revparse rev_parse
+
+    def ls_tree(objectish, opts = {})
+      self.lib.ls_tree(objectish, opts)
     end
 
     def cat_file(objectish)
-      self.lib.object_contents(objectish)
+      self.lib.cat_file(objectish)
     end
 
-    # returns the name of the branch the working directory is currently on
+    # The name of the branch HEAD refers to or 'HEAD' if detached
+    #
+    # Returns one of the following:
+    #   * The branch name that HEAD refers to (even if it is an unborn branch)
+    #   * 'HEAD' if in a detached HEAD state
+    #
+    # @return [String] the name of the branch HEAD refers to or 'HEAD' if detached
+    #
     def current_branch
       self.lib.branch_current
     end

data/lib/git/lib.rb

@@ -169,27 +169,33 @@ module Git
 
     ## READ COMMANDS ##
 
+    # Finds most recent tag that is reachable from a commit
     #
-    # Returns most recent tag that is reachable from a commit
+    # @see https://git-scm.com/docs/git-describe git-describe
     #
-    # accepts options:
-    #  :all
-    #  :tags
-    #  :contains
-    #  :debug
-    #  :exact_match
-    #  :dirty
-    #  :abbrev
-    #  :candidates
-    #  :long
-    #  :always
-    #  :math
-    #
-    #  @param [String|NilClass] committish target commit sha or object name
-    #  @param [{Symbol=>Object}] opts the given options
-    #  @return [String] the tag name
-    #
-    def describe(committish=nil, opts={})
+    # @param commit_ish [String, nil] target commit sha or object name
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :all [Boolean]
+    # @option opts :tags [Boolean]
+    # @option opts :contains [Boolean]
+    # @option opts :debug [Boolean]
+    # @option opts :long [Boolean]
+    # @option opts :always [Boolean]
+    # @option opts :exact_match [Boolean]
+    # @option opts :dirty [true, String]
+    # @option opts :abbrev [String]
+    # @option opts :candidates [String]
+    # @option opts :match [String]
+    #
+    # @return [String] the tag name
+    #
+    # @raise [ArgumentError] if the commit_ish is a string starting with a hyphen
+    #
+    def describe(commit_ish = nil, opts = {})
+      assert_args_are_not_options('commit-ish object', commit_ish)
+
       arr_opts = []
 
       arr_opts << '--all' if opts[:all]
@@ -207,12 +213,42 @@ module Git
       arr_opts << "--candidates=#{opts[:candidates]}" if opts[:candidates]
       arr_opts << "--match=#{opts[:match]}" if opts[:match]
 
-      arr_opts << committish if committish
+      arr_opts << commit_ish if commit_ish
 
       return command('describe', *arr_opts)
     end
 
-    def log_commits(opts={})
+    # Return the commits that are within the given revision range
+    #
+    # @see https://git-scm.com/docs/git-log git-log
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :count [Integer] the maximum number of commits to return (maps to max-count)
+    # @option opts :all [Boolean]
+    # @option opts :cherry [Boolean]
+    # @option opts :since [String]
+    # @option opts :until [String]
+    # @option opts :grep [String]
+    # @option opts :author [String]
+    # @option opts :between [Array<String>] an array of two commit-ish strings to specify a revision range
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :object [String] the revision range for the git log command
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :path_limiter [Array<String>, String] only include commits that impact files from the specified paths
+    #
+    # @return [Array<String>] the log output
+    #
+    # @raise [ArgumentError] if the resulting revision range is a string starting with a hyphen
+    #
+    def log_commits(opts = {})
+      assert_args_are_not_options('between', opts[:between]&.first)
+      assert_args_are_not_options('object', opts[:object])
+
       arr_opts = log_common_options(opts)
 
       arr_opts << '--pretty=oneline'
@@ -222,7 +258,47 @@ module Git
       command_lines('log', *arr_opts).map { |l| l.split.first }
     end
 
-    def full_log_commits(opts={})
+    # Return the commits that are within the given revision range
+    #
+    # @see https://git-scm.com/docs/git-log git-log
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :count [Integer] the maximum number of commits to return (maps to max-count)
+    # @option opts :all [Boolean]
+    # @option opts :cherry [Boolean]
+    # @option opts :since [String]
+    # @option opts :until [String]
+    # @option opts :grep [String]
+    # @option opts :author [String]
+    # @option opts :between [Array<String>] an array of two commit-ish strings to specify a revision range
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :object [String] the revision range for the git log command
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :path_limiter [Array<String>, String] only include commits that impact files from the specified paths
+    # @option opts :skip [Integer]
+    #
+    # @return [Array<Hash>] the log output parsed into an array of hashs for each commit
+    #
+    #   Each hash contains the following keys:
+    #   * 'sha' [String] the commit sha
+    #   * 'author' [String] the author of the commit
+    #   * 'message' [String] the commit message
+    #   * 'parent' [Array<String>] the commit shas of the parent commits
+    #   * 'tree' [String] the tree sha
+    #   * 'author' [String] the author of the commit and timestamp of when the changes were created
+    #   * 'committer' [String] the committer of the commit and timestamp of when the commit was applied
+    #
+    # @raise [ArgumentError] if the revision range (specified with :between or :object) is a string starting with a hyphen
+    #
+    def full_log_commits(opts = {})
+      assert_args_are_not_options('between', opts[:between]&.first)
+      assert_args_are_not_options('object', opts[:object])
+
       arr_opts = log_common_options(opts)
 
       arr_opts << '--pretty=raw'
@@ -235,36 +311,147 @@ module Git
       process_commit_log_data(full_log)
     end
 
-    def revparse(string)
-      return string if string =~ /^[A-Fa-f0-9]{40}$/  # passing in a sha - just no-op it
-      rev = ['head', 'remotes', 'tags'].map do |d|
-        File.join(@git_dir, 'refs', d, string)
-      end.find do |path|
-        File.file?(path)
-      end
-      return File.read(rev).chomp if rev
-      command('rev-parse', string)
+    # Verify and resolve a Git revision to its full SHA
+    #
+    # @see https://git-scm.com/docs/git-rev-parse git-rev-parse
+    # @see https://git-scm.com/docs/git-rev-parse#_specifying_revisions Valid ways to specify revisions
+    # @see https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem Ref disambiguation rules
+    #
+    # @example
+    #   lib.rev_parse('HEAD') # => '9b9b31e704c0b85ffdd8d2af2ded85170a5af87d'
+    #   lib.rev_parse('9b9b31e') # => '9b9b31e704c0b85ffdd8d2af2ded85170a5af87d'
+    #
+    # @param revision [String] the revision to resolve
+    #
+    # @return [String] the full commit hash
+    #
+    # @raise [Git::FailedError] if the revision cannot be resolved
+    # @raise [ArgumentError] if the revision is a string starting with a hyphen
+    #
+    def rev_parse(revision)
+      assert_args_are_not_options('rev', revision)
+
+      command('rev-parse', revision)
     end
 
-    def namerev(string)
-      command('name-rev', string).split[1]
+    # For backwards compatibility with the old method name
+    alias :revparse :rev_parse
+
+    # Find the first symbolic name for given commit_ish
+    #
+    # @param commit_ish [String] the commit_ish to find the symbolic name of
+    #
+    # @return [String, nil] the first symbolic name or nil if the commit_ish isn't found
+    #
+    # @raise [ArgumentError] if the commit_ish is a string starting with a hyphen
+    #
+    def name_rev(commit_ish)
+      assert_args_are_not_options('commit_ish', commit_ish)
+
+      command('name-rev', commit_ish).split[1]
     end
 
-    def object_type(sha)
-      command('cat-file', '-t', sha)
+    alias :namerev :name_rev
+
+    # Output the contents or other properties of one or more objects.
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @example Get the contents of a file without a block
+    #   lib.cat_file_contents('README.md') # => "This is a README file\n"
+    #
+    # @example Get the contents of a file with a block
+    #  lib.cat_file_contents('README.md') { |f| f.read } # => "This is a README file\n"
+    #  
+    # @param object [String] the object whose contents to return
+    #
+    # @return [String] the object contents
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_contents(object, &block)
+      assert_args_are_not_options('object', object)
+
+      if block_given?
+        Tempfile.create do |file|
+          # If a block is given, write the output from the process to a temporary
+          # file and then yield the file to the block
+          #
+          command('cat-file', "-p", object, out: file, err: file)
+          file.rewind
+          yield file
+        end
+      else
+        # If a block is not given, return the file contents as a string
+        command('cat-file', '-p', object)
+      end
     end
 
-    def object_size(sha)
-      command('cat-file', '-s', sha).to_i
+    alias :object_contents :cat_file_contents
+
+    # Get the type for the given object
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @param object [String] the object to get the type
+    #
+    # @return [String] the object type
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_type(object)
+      assert_args_are_not_options('object', object)
+
+      command('cat-file', '-t', object)
     end
 
-    # returns useful array of raw commit object data
-    def commit_data(sha)
-      sha = sha.to_s
-      cdata = command_lines('cat-file', 'commit', sha)
-      process_commit_data(cdata, sha)
+    alias :object_type :cat_file_type
+
+    # Get the size for the given object
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @param object [String] the object to get the type
+    #
+    # @return [String] the object type
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_size(object)
+      assert_args_are_not_options('object', object)
+
+      command('cat-file', '-s', object).to_i
+    end
+
+    alias :object_size :cat_file_size
+
+    # Return a hash of commit data
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @param object [String] the object to get the type
+    #
+    # @return [Hash] commit data
+    #
+    # The returned commit data has the following keys:
+    #    * tree [String]
+    #    * parent [Array<String>]
+    #    * author [String] the author name, email, and commit timestamp
+    #    * committer [String] the committer name, email, and merge timestamp
+    #    * message [String] the commit message
+    #    * gpgsig [String] the public signing key of the commit (if signed)
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_commit(object)
+      assert_args_are_not_options('object', object)
+
+      cdata = command_lines('cat-file', 'commit', object)
+      process_commit_data(cdata, object)
     end
 
+    alias :commit_data :cat_file_commit
+
     def process_commit_data(data, sha)
       hsh = {
         'sha'    => sha,
@@ -299,12 +486,50 @@ module Git
       end
     end
 
-    def tag_data(name)
-      sha = sha.to_s
-      tdata = command_lines('cat-file', 'tag', name)
-      process_tag_data(tdata, name)
+    # Return a hash of annotated tag data
+    #
+    # Does not work with lightweight tags. List all annotated tags in your repository with the following command:
+    #
+    # ```sh
+    # git for-each-ref --format='%(refname:strip=2)' refs/tags | while read tag; do git cat-file tag $tag >/dev/null 2>&1 && echo $tag; done
+    # ```
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @param object [String] the tag to retrieve
+    #
+    # @return [Hash] tag data
+    #
+    #   Example tag data returned:
+    #   ```ruby
+    #   {
+    #     "name" => "annotated_tag",
+    #     "object" => "46abbf07e3c564c723c7c039a43ab3a39e5d02dd",
+    #     "type" => "commit",
+    #     "tag" => "annotated_tag",
+    #     "tagger" => "Scott Chacon <schacon@gmail.com> 1724799270 -0700",
+    #     "message" => "Creating an annotated tag\n"
+    #   }
+    #   ```
+    #
+    # The returned commit data has the following keys:
+    #   * object [String] the sha of the tag object
+    #   * type [String]
+    #   * tag [String] tag name
+    #   * tagger [String] the name and email of the user who created the tag and the timestamp of when the tag was created
+    #   * message [String] the tag message
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_tag(object)
+      assert_args_are_not_options('object', object)
+
+      tdata = command_lines('cat-file', 'tag', object)
+      process_tag_data(tdata, object)
     end
 
+    alias :tag_data :cat_file_tag
+
     def process_tag_data(data, name)
       hsh = { 'name' => name }
 
@@ -358,26 +583,15 @@ module Git
       return hsh_array
     end
 
-    def object_contents(sha, &block)
-      if block_given?
-        Tempfile.create do |file|
-          # If a block is given, write the output from the process to a temporary
-          # file and then yield the file to the block
-          #
-          command('cat-file', "-p", sha, out: file, err: file)
-          file.rewind
-          yield file
-        end
-      else
-        # If a block is not given, return stdout
-        command('cat-file', '-p', sha)
-      end
-    end
-
-    def ls_tree(sha)
+    def ls_tree(sha, opts = {})
       data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
 
-      command_lines('ls-tree', sha).each do |line|
+      ls_tree_opts = []
+      ls_tree_opts << '-r' if opts[:recursive]
+      # path must be last arg
+      ls_tree_opts << opts[:path] if opts[:path]
+
+      command_lines('ls-tree', sha, *ls_tree_opts).each do |line|
         (info, filenm) = line.split("\t")
         (mode, type, sha) = info.split
         data[type][filenm] = {:mode => mode, :sha => sha}
@@ -483,8 +697,54 @@ module Git
       files
     end
 
+    # The state and name of branch pointed to by `HEAD`
+    #
+    # HEAD can be in the following states:
+    #
+    # **:active**: `HEAD` points to a branch reference which in turn points to a
+    # commit representing the tip of that branch. This is the typical state when
+    # working on a branch.
+    #
+    # **:unborn**: `HEAD` points to a branch reference that does not yet exist
+    # because no commits have been made on that branch. This state occurs in two
+    # scenarios:
+    #
+    # * When a repository is newly initialized, and no commits have been made on the
+    #   initial branch.
+    # * When a new branch is created using `git checkout --orphan <branch>`, starting
+    #   a new branch with no history.
+    #
+    # **:detached**: `HEAD` points directly to a specific commit (identified by its
+    # SHA) rather than a branch reference. This state occurs when you check out a
+    # commit, a tag, or any state that is not directly associated with a branch. The
+    # branch name in this case is `HEAD`.
+    #
+    HeadState = Struct.new(:state, :name)
+
+    # The current branch state which is the state of `HEAD`
+    #
+    # @return [HeadState] the state and name of the current branch
+    #
+    def current_branch_state
+      branch_name = command('branch', '--show-current')
+      return HeadState.new(:detached, 'HEAD') if branch_name.empty?
+
+      state =
+        begin
+          command('rev-parse', '--verify', '--quiet', branch_name)
+          :active
+        rescue Git::FailedError => e
+          raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?
+
+          :unborn
+        end
+
+      return HeadState.new(state, branch_name)
+    end
+
     def branch_current
-      branches_all.select { |b| b[1] }.first[0] rescue nil
+      branch_name = command('branch', '--show-current')
+      branch_name.empty? ? 'HEAD' : branch_name
     end
 
     def branch_contains(commit, branch_name="")
@@ -521,7 +781,24 @@ module Git
       hsh
     end
 
+    # Validate that the given arguments cannot be mistaken for a command-line option
+    #
+    # @param arg_name [String] the name of the arguments to mention in the error message
+    # @param args [Array<String, nil>] the arguments to validate
+    #
+    # @raise [ArgumentError] if any of the parameters are a string starting with a hyphen
+    # @return [void]
+    #
+    def assert_args_are_not_options(arg_name, *args)
+      invalid_args = args.select { |arg| arg&.start_with?('-') }
+      if invalid_args.any?
+        raise ArgumentError, "Invalid #{arg_name}: '#{invalid_args.join("', '")}'"
+      end
+    end
+
     def diff_full(obj1 = 'HEAD', obj2 = nil, opts = {})
+      assert_args_are_not_options('commit or commit range', obj1, obj2)
+
       diff_opts = ['-p']
       diff_opts << obj1
       diff_opts << obj2 if obj2.is_a?(String)
@@ -531,6 +808,8 @@ module Git
     end
 
     def diff_stats(obj1 = 'HEAD', obj2 = nil, opts = {})
+      assert_args_are_not_options('commit or commit range', obj1, obj2)
+
       diff_opts = ['--numstat']
       diff_opts << obj1
       diff_opts << obj2 if obj2.is_a?(String)
@@ -551,6 +830,8 @@ module Git
     end
 
     def diff_name_status(reference1 = nil, reference2 = nil, opts = {})
+      assert_args_are_not_options('commit or commit range', reference1, reference2)
+
       opts_arr = ['--name-status']
       opts_arr << reference1 if reference1
       opts_arr << reference2 if reference2

data/lib/git/object.rb

@@ -23,11 +23,11 @@ module Git
       end
 
       def sha
-        @sha ||= @base.lib.revparse(@objectish)
+        @sha ||= @base.lib.rev_parse(@objectish)
       end
 
       def size
-        @size ||= @base.lib.object_size(@objectish)
+        @size ||= @base.lib.cat_file_size(@objectish)
       end
 
       # Get the object's contents.
@@ -38,9 +38,9 @@ module Git
       # Use this for large files so that they are not held in memory.
       def contents(&block)
         if block_given?
-          @base.lib.object_contents(@objectish, &block)
+          @base.lib.cat_file_contents(@objectish, &block)
         else
-          @contents ||= @base.lib.object_contents(@objectish)
+          @contents ||= @base.lib.cat_file_contents(@objectish)
         end
       end
 
@@ -175,7 +175,7 @@ module Git
       end
 
       def name
-        @base.lib.namerev(sha)
+        @base.lib.name_rev(sha)
       end
 
       def gtree
@@ -237,7 +237,7 @@ module Git
         def check_commit
           return if @tree
 
-          data = @base.lib.commit_data(@objectish)
+          data = @base.lib.cat_file_commit(@objectish)
           set_commit(data)
         end
 
@@ -254,7 +254,7 @@ module Git
       end
 
       def annotated?
-        @annotated ||= (@base.lib.object_type(self.name) == 'tag')
+        @annotated ||= (@base.lib.cat_file_type(self.name) == 'tag')
       end
 
       def message
@@ -279,7 +279,7 @@ module Git
         if !self.annotated?
           @message = @tagger = nil
         else
-          tdata = @base.lib.tag_data(@name)
+          tdata = @base.lib.cat_file_tag(@name)
           @message = tdata['message'].chomp
           @tagger = Git::Author.new(tdata['tagger'])
         end
@@ -300,7 +300,7 @@ module Git
         return Git::Object::Tag.new(base, sha, objectish)
       end
 
-      type ||= base.lib.object_type(objectish)
+      type ||= base.lib.cat_file_type(objectish)
       klass =
         case type
         when /blob/   then Blob

data/lib/git/version.rb

@@ -1,5 +1,5 @@
 module Git
   # The current gem version
   # @return [String] the current gem version.
-  VERSION='2.1.1'
+  VERSION='2.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.3.0
 platform: ruby
 authors:
 - Scott Chacon and others
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-01 00:00:00.000000000 Z
+date: 2024-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -243,8 +243,8 @@ licenses:
 metadata:
   homepage_uri: http://github.com/ruby-git/ruby-git
   source_code_uri: http://github.com/ruby-git/ruby-git
-  changelog_uri: https://rubydoc.info/gems/git/2.1.1/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/2.1.1
+  changelog_uri: https://rubydoc.info/gems/git/2.3.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/2.3.0
 post_install_message:
 rdoc_options: []
 require_paths: