git 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf601afe6ddef5cc504f0a350bd9595feb76cc95822bd65716d6b5cecf2d324d
-  data.tar.gz: 5f334a391220774ab0fea9c789a87fe3a45d9de55e0745d87f59c0bc9a52e5a9
+  metadata.gz: bfdec3b45e4e9b00ce87e37026c6b8fe81c306fdc7c127f01e1e682a8655986c
+  data.tar.gz: 3273f3eb91ab29af0143f1c5e0e5548bbc4e4575bc0a2a8ad4c6faa7cca3252b
 SHA512:
-  metadata.gz: 20133b00f0f50ccc00dc1bd4bb88107911ff5f438e127b804270752c43029e2447b15a5212c701a24a49a6f98d7b12359cb3326924ea3dadf631408b316e626e
-  data.tar.gz: 11ca7ae94de18e0b3d4aad99d315c2b973a8e2521ee24a935e5236fdc91eace943074ad388889a09ef4d8e33e2a4b1355d2590fe16fe0a1eda05357e1a315290
+  metadata.gz: 137c05e180c79fc9b3e2810c1fb67a7a9304c365bf7ea445788cbf392c4e0bfadc04d91871e5f1aaf93db8c457b08b55487043abeff0e6a986fc1f812712ffe4
+  data.tar.gz: 8e7c483a7d5b8699cc48f523678e2d5b586b51fd900ca3a9f5ca3535d3fe9ce3275e449345783de6f5b2656f620dc81225595b17a7881946319c867b089f6d22

data/CHANGELOG.md

@@ -5,6 +5,36 @@
 
 # Change Log
 
+## 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)
+
+Changes since v2.1.0:
+
+* 6ce3d4d Handle ignored files with quoted (non-ASCII) filenames
+* dd8e8d4 Supply all of the _specific_ color options too
+* 749a72d Memoize all of the significant calls in Git::Status
+* 2bacccc When core.ignoreCase, check for untracked files case-insensitively
+* 7758ee4 When core.ignoreCase, check for deleted files case-insensitively
+* 993eb78 When core.ignoreCase, check for added files case-insensitively
+* d943bf4 When core.ignoreCase, check for changed files case-insensitively
+
 ## v2.1.0 (2024-05-31)
 
 [Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.0.1..v2.1.0)

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

@@ -309,6 +309,13 @@ module Git
       self.object('HEAD').grep(string, path_limiter, opts)
     end
 
+    # List the files in the worktree that are ignored by git
+    # @return [Array<String>] the list of ignored files relative to teh root of the worktree
+    #
+    def ignored_files
+      self.lib.ignored_files
+    end
+
     # removes file(s) from the git repository
     def rm(path = '.', opts = {})
       self.lib.rm(path, opts)
@@ -627,16 +634,19 @@ 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)

data/lib/git/escaped_path.rb

@@ -3,7 +3,7 @@
 module Git
   # Represents an escaped Git path string
   #
-  # Git commands that output paths (e.g. ls-files, diff), will escape usual
+  # Git commands that output paths (e.g. ls-files, diff), will escape unusual
   # characters in the path with backslashes in the same way C escapes control
   # characters (e.g. \t for TAB, \n for LF, \\ for backslash) or bytes with values
   # larger than 0x80 (e.g. octal \302\265 for "micro" in UTF-8).

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,21 +311,48 @@ 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
 
+    alias :namerev :name_rev
+
     def object_type(sha)
       command('cat-file', '-t', sha)
     end
@@ -374,10 +477,15 @@ module Git
       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}
@@ -521,7 +629,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 +656,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 +678,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
@@ -574,18 +703,52 @@ module Git
       diff_as_hash('diff-index', treeish)
     end
 
+    # List all files that are in the index
+    #
+    # @param location [String] the location to list the files from
+    #
+    # @return [Hash<String, Hash>] a hash of files in the index
+    #   * key: file [String] the file path
+    #   * value: file_info [Hash] the file information containing the following keys:
+    #     * :path [String] the file path
+    #     * :mode_index [String] the file mode
+    #     * :sha_index [String] the file sha
+    #     * :stage [String] the file stage
+    #
     def ls_files(location=nil)
       location ||= '.'
-      hsh = {}
-      command_lines('ls-files', '--stage', location).each do |line|
-        (info, file) = line.split("\t")
-        (mode, sha, stage) = info.split
-        if file.start_with?('"') && file.end_with?('"')
-          file = Git::EscapedPath.new(file[1..-2]).unescape
+      {}.tap do |files|
+        command_lines('ls-files', '--stage', location).each do |line|
+          (info, file) = line.split("\t")
+          (mode, sha, stage) = info.split
+          files[unescape_quoted_path(file)] = {
+            :path => file, :mode_index => mode, :sha_index => sha, :stage => stage
+          }
         end
-        hsh[file] = {:path => file, :mode_index => mode, :sha_index => sha, :stage => stage}
       end
-      hsh
+    end
+
+    # Unescape a path if it is quoted
+    #
+    # Git commands that output paths (e.g. ls-files, diff), will escape unusual
+    # characters.
+    #
+    # @example
+    #   lib.unescape_if_quoted('"quoted_file_\\342\\230\\240"') # => 'quoted_file_☠'
+    #   lib.unescape_if_quoted('unquoted_file')   # => 'unquoted_file'
+    #
+    # @param path [String] the path to unescape if quoted
+    #
+    # @return [String] the unescaped path if quoted otherwise the original path
+    #
+    # @api private
+    #
+    def unescape_quoted_path(path)
+      if path.start_with?('"') && path.end_with?('"')
+        Git::EscapedPath.new(path[1..-2]).unescape
+      else
+        path
+      end
     end
 
     def ls_remote(location=nil, opts={})
@@ -606,7 +769,7 @@ module Git
     end
 
     def ignored_files
-      command_lines('ls-files', '--others', '-i', '--exclude-standard')
+      command_lines('ls-files', '--others', '-i', '--exclude-standard').map { |f| unescape_quoted_path(f) }
     end
 
     def untracked_files
@@ -1223,6 +1386,14 @@ module Git
         global_opts << "--work-tree=#{@git_work_dir}" if !@git_work_dir.nil?
         global_opts << '-c' << 'core.quotePath=true'
         global_opts << '-c' << 'color.ui=false'
+        global_opts << '-c' << 'color.advice=false'
+        global_opts << '-c' << 'color.diff=false'
+        global_opts << '-c' << 'color.grep=false'
+        global_opts << '-c' << 'color.push=false'
+        global_opts << '-c' << 'color.remote=false'
+        global_opts << '-c' << 'color.showBranch=false'
+        global_opts << '-c' << 'color.status=false'
+        global_opts << '-c' << 'color.transport=false'
       end
     end
 

data/lib/git/object.rb

@@ -23,7 +23,7 @@ module Git
       end
 
       def sha
-        @sha ||= @base.lib.revparse(@objectish)
+        @sha ||= @base.lib.rev_parse(@objectish)
       end
 
       def size
@@ -175,7 +175,7 @@ module Git
       end
 
       def name
-        @base.lib.namerev(sha)
+        @base.lib.name_rev(sha)
       end
 
       def gtree

data/lib/git/status.rb

@@ -22,7 +22,7 @@ module Git
     #
     # @return [Enumerable]
     def changed
-      @files.select { |_k, f| f.type == 'M' }
+      @_changed ||= @files.select { |_k, f| f.type == 'M' }
     end
 
     #
@@ -34,7 +34,7 @@ module Git
     #     changed?('lib/git.rb')
     # @return [Boolean]
     def changed?(file)
-      changed.member?(file)
+      case_aware_include?(:changed, :lc_changed, file)
     end
 
     # Returns an Enumerable containing files that have been added.
@@ -42,7 +42,7 @@ module Git
     #
     # @return [Enumerable]
     def added
-      @files.select { |_k, f| f.type == 'A' }
+      @_added ||= @files.select { |_k, f| f.type == 'A' }
     end
 
     # Determines whether the given file has been added to the repository
@@ -54,7 +54,7 @@ module Git
     #     added?('lib/git.rb')
     # @return [Boolean]
     def added?(file)
-      added.member?(file)
+      case_aware_include?(:added, :lc_added, file)
     end
 
     #
@@ -63,7 +63,7 @@ module Git
     #
     # @return [Enumerable]
     def deleted
-      @files.select { |_k, f| f.type == 'D' }
+      @_deleted ||= @files.select { |_k, f| f.type == 'D' }
     end
 
     #
@@ -75,7 +75,7 @@ module Git
     #     deleted?('lib/git.rb')
     # @return [Boolean]
     def deleted?(file)
-      deleted.member?(file)
+      case_aware_include?(:deleted, :lc_deleted, file)
     end
 
     #
@@ -84,7 +84,7 @@ module Git
     #
     # @return [Enumerable]
     def untracked
-      @files.select { |_k, f| f.untracked }
+      @_untracked ||= @files.select { |_k, f| f.untracked }
     end
 
     #
@@ -96,7 +96,7 @@ module Git
     #     untracked?('lib/git.rb')
     # @return [Boolean]
     def untracked?(file)
-      untracked.member?(file)
+      case_aware_include?(:untracked, :lc_untracked, file)
     end
 
     def pretty
@@ -264,5 +264,43 @@ module Git
         end
       end
     end
+
+    # It's worth noting that (like git itself) this gem will not behave well if
+    # ignoreCase is set inconsistently with the file-system itself. For details:
+    # https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreignoreCase
+    def ignore_case?
+      return @_ignore_case if defined?(@_ignore_case)
+      @_ignore_case = @base.config('core.ignoreCase') == 'true'
+    rescue Git::FailedError
+      @_ignore_case = false
+    end
+
+    def downcase_keys(hash)
+      hash.map { |k, v| [k.downcase, v] }.to_h
+    end
+
+    def lc_changed
+      @_lc_changed ||= changed.transform_keys(&:downcase)
+    end
+
+    def lc_added
+      @_lc_added ||= added.transform_keys(&:downcase)
+    end
+
+    def lc_deleted
+      @_lc_deleted ||= deleted.transform_keys(&:downcase)
+    end
+
+    def lc_untracked
+      @_lc_untracked ||= untracked.transform_keys(&:downcase)
+    end
+
+    def case_aware_include?(cased_hash, downcased_hash, file)
+      if ignore_case?
+        send(downcased_hash).include?(file.downcase)
+      else
+        send(cased_hash).include?(file)
+      end
+    end
   end
 end

data/lib/git/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Scott Chacon and others
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-31 00:00:00.000000000 Z
+date: 2024-08-26 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.0/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/2.1.0
+  changelog_uri: https://rubydoc.info/gems/git/2.2.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/2.2.0
 post_install_message:
 rdoc_options: []
 require_paths: