git 2.2.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfdec3b45e4e9b00ce87e37026c6b8fe81c306fdc7c127f01e1e682a8655986c
-  data.tar.gz: 3273f3eb91ab29af0143f1c5e0e5548bbc4e4575bc0a2a8ad4c6faa7cca3252b
+  metadata.gz: b62df99d178044fd3fe000a27475819f27bcede65dd96bbc884e1a9eb766df86
+  data.tar.gz: 37330af1ce4f2b8f0ea372cbb36fe32991ab93f5243dbe91589a045f7c5073cf
 SHA512:
-  metadata.gz: 137c05e180c79fc9b3e2810c1fb67a7a9304c365bf7ea445788cbf392c4e0bfadc04d91871e5f1aaf93db8c457b08b55487043abeff0e6a986fc1f812712ffe4
-  data.tar.gz: 8e7c483a7d5b8699cc48f523678e2d5b586b51fd900ca3a9f5ca3535d3fe9ce3275e449345783de6f5b2656f620dc81225595b17a7881946319c867b089f6d22
+  metadata.gz: 6a10a88c4cc04970184c9f5e1eda87dfc4778366498a867931be7196de1a0d882b5d9a7c552249d384ad46e7e1dee2c1077aff1d3ea31e5b53254dbe099e781b
+  data.tar.gz: 76d10cc88dfd8150daaf6f53f1af46077345fa35a64b71c8f6276e388503f1f15fee173dca322ae49c7fb511ebe5d44dc43dd84b15a9a234e2b06aea627e7032

data/CHANGELOG.md

@@ -5,6 +5,30 @@
 
 # Change Log
 
+## v2.3.1 (2024-10-23)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.3.0..v2.3.1)
+
+Changes since v2.3.0:
+
+* e236007 test: allow bin/test-in-docker to accept the test file(s) to run on command line
+* f4747e1 test: rename bin/tests to bin/test-in-docker
+* 51f781c test: remove duplicate test from test_stashes.rb
+* 2e79dbe Fixed "unbranched" stash message support:
+* da6fa6e Conatinerised the test suite with Docker:
+* 2e23d47 Update instructions for building a specific version of Git
+* 70565e3 Add Git.binary_version to return the version of the git command line
+
+## 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)

data/CONTRIBUTING.md

@@ -3,6 +3,9 @@
 # @title How To Contribute
 -->
 
+# Contributing to the git gem
+
+* [Summary](#summary)
 * [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)
@@ -18,10 +21,14 @@
   * [Unit tests](#unit-tests)
   * [Continuous integration](#continuous-integration)
   * [Documentation](#documentation)
+* [Building a specific version of the Git command-line](#building-a-specific-version-of-the-git-command-line)
+  * [Install pre-requisites](#install-pre-requisites)
+  * [Obtain Git source code](#obtain-git-source-code)
+  * [Build git](#build-git)
+  * [Use the new Git version](#use-the-new-git-version)
 * [Licensing](#licensing)
 
-
-# Contributing to the git gem
+## Summary
 
 Thank you for your interest in contributing to the `ruby-git` project.
 
@@ -172,22 +179,100 @@ $ bin/test test_object test_archive
 
 # run all unit tests:
 $ bin/test
+
+# run unit tests with a different version of the git command line:
+$ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers 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.
+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).
+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 include [YARD](https://yardoc.org/) documentation.
+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).
+
+## Building a specific version of the Git command-line
+
+To test with a specific version of the Git command-line, you may need to build that
+version from source code. The following instructions are adapted from Atlassian’s
+[How to install Git](https://www.atlassian.com/git/tutorials/install-git) page for
+building Git on macOS.
+
+### Install pre-requisites
+
+Prerequisites only need to be installed if they are not already present.
+
+From your terminal, install Xcode’s Command Line Tools:
+
+```shell
+xcode-select --install
+```
+
+Install [Homebrew](http://brew.sh/) by following the instructions on the Homebrew
+page.
+
+Using Homebrew, install OpenSSL:
+
+```shell
+brew install openssl
+```
+
+### Obtain Git source code
+
+Download and extract the source tarball for the desired Git version from [this source
+code mirror](https://mirrors.edge.kernel.org/pub/software/scm/git/).
+
+### Build git
+
+From your terminal, change to the root directory of the extracted source code and run
+the build with following command:
+
+```shell
+NO_GETTEXT=1 make CFLAGS="-I/usr/local/opt/openssl/include" LDFLAGS="-L/usr/local/opt/openssl/lib"
+```
+
+The build script will place the newly compiled Git executables in the `bin-wrappers`
+directory (e.g., `bin-wrappers/git`).
+
+### Use the new Git version
+
+To configure programs that use the Git gem to utilize the newly built version, do the
+following:
+
+```ruby
+require 'git'
+
+# Set the binary path
+Git.configure { |c| c.binary_path = '/Users/james/Downloads/git-2.30.2/bin-wrappers/git' }
+
+# Validate the version (if desired)
+assert_equal([2, 30, 2], Git.binary_version)
+```
+
+Tests can be run using the newly built Git version as follows:
+
+```shell
+GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
+```
 
-New and updated public-facing features should be documented in the project's [README.md](README.md).
+Note: `GIT_PATH` refers to the directory containing the `git` executable.
 
 ## 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 critical to open-source projects as it ensures the software remains available under the terms desired by the author.
+Licensing is critical to open-source projects as it ensures the software remains
+available under the terms desired by the author.

data/lib/git/base.rb

@@ -36,6 +36,20 @@ module Git
       @@config ||= Config.new
     end
 
+    def self.binary_version(binary_path)
+      git_cmd = "#{binary_path} -c core.quotePath=true -c color.ui=false version 2>&1"
+      result, status = Open3.capture2(git_cmd)
+      result = result.chomp
+
+      if status.success?
+        version = result[/\d+(\.\d+)+/]
+        version_parts = version.split('.').collect { |i| i.to_i }
+        version_parts.fill(0, version_parts.length...3)
+      else
+        raise RuntimeError, "Failed to get git version: #{status}\n#{result}"
+      end
+    end
+
     # (see Git.init)
     def self.init(directory = '.', options = {})
       normalize_paths(options, default_working_directory: directory, default_repository: directory, bare: options[:bare])
@@ -650,10 +664,17 @@ module Git
     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

@@ -353,21 +353,105 @@ module Git
 
     alias :namerev :name_rev
 
-    def object_type(sha)
-      command('cat-file', '-t', sha)
+    # 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
+
+    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
 
-    def object_size(sha)
-      command('cat-file', '-s', sha).to_i
+    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
 
-    # 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_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,
@@ -402,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 }
 
@@ -461,22 +583,6 @@ 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, opts = {})
       data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
 
@@ -591,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="")
@@ -982,8 +1134,10 @@ module Git
       if File.exist?(filename)
         File.open(filename) do |f|
           f.each_with_index do |line, i|
-            m = line.match(/:(.*)$/)
-            arr << [i, m[1].strip]
+            _, msg = line.split("\t")
+            # NOTE this logic may be removed/changed in 3.x
+            m = msg.match(/^[^:]+:(.*)$/)
+            arr << [i, (m ? m[1] : msg).strip]
           end
         end
       end

data/lib/git/object.rb

@@ -27,7 +27,7 @@ module Git
       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
 
@@ -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.2.0'
+  VERSION='2.3.1'
 end

data/lib/git.rb

@@ -381,4 +381,15 @@ module Git
   def self.open(working_dir, options = {})
     Base.open(working_dir, options)
   end
+
+  # Return the version of the git binary
+  #
+  # @example
+  #  Git.binary_version # => [2, 46, 0]
+  #
+  # @return [Array<Integer>] the version of the git binary
+  #
+  def self.binary_version(binary_path = Git::Base.config.binary_path)
+    Base.binary_version(binary_path)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.1
 platform: ruby
 authors:
 - Scott Chacon and others
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-26 00:00:00.000000000 Z
+date: 2024-10-23 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.2.0/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/2.2.0
+  changelog_uri: https://rubydoc.info/gems/git/2.3.1/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/2.3.1
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -261,7 +261,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - git 2.28.0 or greater
-rubygems_version: 3.5.9
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: An API to create, read, and manipulate Git repositories