git 1.16.0 → 1.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06d2809c51685e3171199f0eb8bce4c02a7970d61d12fabbde7bf2ab3850a86b
-  data.tar.gz: 439eac61b04b8fcdafa739f7f6f27cfc89f00d557aac52aacd6f71762bc8281e
+  metadata.gz: dcca4b91f56e1bf6b99c471f918fbe4b1ed6d56b0058021e345514676e153223
+  data.tar.gz: 9f4386702fca4248c3a7a07400c6ff3e52fa7898f0e16bbcb3b90bf945fde1da
 SHA512:
-  metadata.gz: 57db3b512e1d30130f1ab8bf9f77a701591c4c05c8c9fe35e9d047329cc7fe08b6e17c93d276bcfbfcb3e5c92a8dcb48cc571d513a7a981d69989eac7daea957
-  data.tar.gz: ee2b51658bda3767a01729888c60b677d79d69b75fadb8659a6d56144e82f51e21da817f7f310b1af0be9baedda37923315adac10ad7a65be1624b6ecb0628fb
+  metadata.gz: 4d943759fc15a56baee49734b4628cf1b5651416c13842077a9bfe979df1bdc05afbe114af904b2161ef84be090207f9691a80a704efe2d8a3a14bb4c80df8f6
+  data.tar.gz: 8feccfa435ec2f3d95a52ec0fd3920b5a956b2dc3cbcddfbc63c48052ddf64686ba1ef849f0b96307e573134d0e818c6d5bfaae8f3dad877a6f74a516806754a

data/CHANGELOG.md

@@ -5,6 +5,17 @@
 
 # Change Log
 
+## v1.17.0 (2023-03-05)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v1.16.0..v1.17.0)
+
+Changes since v1.16.0:
+
+* 1311 Add deprecation mechanism (introduces runtime dependency on ActiveSupport) (#645)
+* 50b8 Add the push_option option for Git::Lib#push (#644)
+* a799 Make Git::Base#ls_tree handle commit objects (#643)
+* 6db3 Implememt Git.default_branch (#571)
+
 ## v1.16.0 (2023-03-03)
 
 [Full Changelog](https://github.com/ruby-git/ruby-git/compare/v1.15.0..v1.16.0)

data/README.md

@@ -3,47 +3,73 @@
 # @title README
 -->
 
-# The Git Gem
+# The `git` Gem
 
-The Git Gem provides an API that can be used to create, read, and manipulate
+[![Gem Version](https://badge.fury.io/rb/git.svg)](https://badge.fury.io/rb/git)
+[![Change Log](https://img.shields.io/badge/change%20log-Latest-green)](https://rubydoc.info/gems/git/file/CHANGELOG.md)
+[![Build Status](https://github.com/ruby-git/ruby-git/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/ruby-git/ruby-git/actions/workflows/continuous_integration.yml)
+[![Code Climate](https://codeclimate.com/github/ruby-git/ruby-git.png)](https://codeclimate.com/github/ruby-git/ruby-git)
+[![Source Code](https://img.shields.io/badge/source-GitHub-green)](https://github.com/ruby-git/ruby-git)
+[![Documentation](https://img.shields.io/badge/documentation-Latest-green)](https://rubydoc.info/gems/git)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ruby-git/ruby-git/blob/master/LICENSE)
+
+The git Gem provides an API that can be used to create, read, and manipulate
 Git repositories by wrapping system calls to the `git` binary. The API can be
 used for working with Git in complex interactions including branching and
 merging, object inspection and manipulation, history, patch generation and
 more.
 
-## Homepage
+## Basic Usage
 
-The project source code is at:
+Get started by obtaining a repository object by:
 
-http://github.com/ruby-git/ruby-git
+* Opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
+* Initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method)
+* Cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
 
-## Documentation
+Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
 
-Detailed documentation can be found at:
+## Install
 
-https://rubydoc.info/gems/git/Git.html
+You can install the `git` gem with the following command:
 
-Get started by obtaining a repository object by:
-
-* opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
-* initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method)
-* cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
+```shell
+gem install git
+```
 
-Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
+## Deprecation Warnings
 
-## Install
+Deprecation warnings are managed with the `Git.deprecation` attribute.
 
-You can install Ruby/Git like this:
+Use this object to define deprecations in the source code:
 
+```ruby
+Git.deprecation.deprecate_methods(Git::Branch, stashes: 'use Git::Base#stash_list instead')
 ```
-sudo gem install git
+
+The default action when using deprecated items (methods, classes, etc.) is to output
+a **DEPRECATION WARNING** to `$stderr` like the following:
+
+```text
+DEPRECATION WARNING: stashes is deprecated and will be removed from git 2.0.0 (use Git::Base.stash_list instead)
 ```
 
-## Code Status
+The action taken when a deprecated item is used is defined by setting the behavior
+on the deprecation object:
+
+```ruby
+# Log all deprecation warnings to $stderr (the default)
+Git.deprecation = :stderr
 
-* [![Build Status](https://github.com/ruby-git/ruby-git/workflows/CI/badge.svg?branch=master)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
-* [![Code Climate](https://codeclimate.com/github/ruby-git/ruby-git.png)](https://codeclimate.com/github/ruby-git/ruby-git)
-* [![Gem Version](https://badge.fury.io/rb/git.svg)](https://badge.fury.io/rb/git)
+# Raise an ActiveSupport::DeprecationException
+Git.deprecation = :raise
+
+# Do nothing
+Git.deprecation = :silence
+```
+
+See [ActiveSupport::Deprecation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
+for more details on how to use deprecations.
 
 ## Major Objects
 
@@ -197,6 +223,8 @@ g.show('v2.8', 'README.md')
 Git.ls_remote('https://github.com/ruby-git/ruby-git.git') # returns a hash containing the available references of the repo.
 Git.ls_remote('/path/to/local/repo')
 Git.ls_remote() # same as Git.ls_remote('.')
+
+Git.default_branch('https://github.com/ruby-git/ruby-git') #=> 'master'
 ```
 
 And here are the operations that will need to write to your git repository.

data/Rakefile

@@ -18,7 +18,7 @@ task :test do
 end
 default_tasks << :test
 
-unless RUBY_PLATFORM == 'java'
+unless RUBY_PLATFORM == 'java' || RUBY_ENGINE == 'truffleruby'
   #
   # YARD documentation for this project can NOT be built with JRuby.
   # This project uses the redcarpet gem which can not be installed on JRuby.

data/git.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to?(:required_rubygems_version=)
   s.requirements = ['git 1.6.0.0, or greater']
 
+  s.add_runtime_dependency 'activesupport', '>= 4.0.0'
   s.add_runtime_dependency 'addressable', '~> 2.8'
   s.add_runtime_dependency 'rchardet', '~> 1.8'
 

data/lib/git/base.rb

@@ -24,6 +24,11 @@ module Git
       new(new_options)
     end
 
+    # (see Git.default_branch)
+    def self.repository_default_branch(repository, options = {})
+      Git::Lib.new(nil, options[:log]).repository_default_branch(repository)
+    end
+
     # Returns (and initialize if needed) a Git::Config instance
     #
     # @return [Git::Config] the current config instance.
@@ -369,10 +374,23 @@ module Git
       self.lib.fetch(remote, opts)
     end
 
-    # pushes changes to a remote repository - easiest if this is a cloned repository,
-    # otherwise you may have to run something like this first to setup the push parameters:
+    # Push changes to a remote repository
+    #
+    # @overload push(remote = nil, branch = nil, options = {})
+    #   @param remote [String] the remote repository to push to
+    #   @param branch [String] the branch to push
+    #   @param options [Hash] options to pass to the push command
+    #
+    #   @option opts [Boolean] :mirror (false) Push all refs under refs/heads/, refs/tags/ and refs/remotes/
+    #   @option opts [Boolean] :delete (false) Delete refs that don't exist on the remote
+    #   @option opts [Boolean] :force (false) Force updates
+    #   @option opts [Boolean] :tags (false) Push all refs under refs/tags/
+    #   @option opts [Array, String] :push_options (nil) Push options to transmit
+    #
+    #   @return [Void]
     #
-    #  @git.config('remote.remote-name.push', 'refs/heads/master:refs/heads/master')
+    #   @raise [Git::FailedError] if the push fails
+    #   @raise [ArgumentError] if a branch is given without a remote
     #
     def push(*args, **options)
       self.lib.push(*args, **options)

data/lib/git/lib.rb

@@ -124,6 +124,24 @@ module Git
       base_opts
     end
 
+    # Returns the name of the default branch of the given repository
+    #
+    # @param repository [URI, Pathname, String] The (possibly remote) repository to clone from
+    #
+    # @return [String] the name of the default branch
+    #
+    def repository_default_branch(repository)
+      output = command('ls-remote', '--symref', '--', repository, 'HEAD')
+
+      match_data = output.match(%r{^ref: refs/remotes/origin/(?<default_branch>[^\t]+)\trefs/remotes/origin/HEAD$})
+      return match_data[:default_branch] if match_data
+
+      match_data = output.match(%r{^ref: refs/heads/(?<default_branch>[^\t]+)\tHEAD$})
+      return match_data[:default_branch] if match_data
+
+      raise 'Unable to determine the default branch'
+    end
+
     ## READ COMMANDS ##
 
     #
@@ -320,7 +338,7 @@ module Git
     end
 
     def ls_tree(sha)
-      data = {'blob' => {}, 'tree' => {}}
+      data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
 
       command_lines('ls-tree', sha).each do |line|
         (info, filenm) = line.split("\t")
@@ -964,6 +982,7 @@ module Git
       arr_opts << '--mirror'  if opts[:mirror]
       arr_opts << '--delete'  if opts[:delete]
       arr_opts << '--force'  if opts[:force] || opts[:f]
+      Array(opts[:push_option]).each { |o| arr_opts << '--push-option' << o } if opts[:push_option]
       arr_opts << remote if remote
       arr_opts_with_branch = arr_opts.dup
       arr_opts_with_branch << branch if branch

data/lib/git/version.rb

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

data/lib/git.rb

@@ -1,7 +1,32 @@
-# Add the directory containing this file to the start of the load path if it
-# isn't there already.
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+require 'active_support/deprecation'
+
+module Git
+  # An object used to manage deprecations
+  #
+  # A ActiveSupport::Deprecation object used to manage the deprecations scheduled
+  # to be removed in the next major release of the `git`` gem.
+  #
+  # @example Deprecate a method
+  #   Git.deprecation.deprecate_methods(Git::Branch, stashes: 'use Git::Base#stash_list instead')
+  #
+  # @example Set the deprecation behavior
+  #   # Log all deprecation warnings to $stderr (the default)
+  #   Git.deprecation.behavior = :stderr
+  #
+  #   # Raise an ActiveSupport::DeprecationException
+  #   Git.deprecation.behavior = :raise
+  #
+  #   # Do nothing
+  #   Git.deprecation.behavior = :raise
+  #
+  # @see https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html ActiveSupport::Deprecation
+  #
+  # @return [ActiveSupport::Deprecation]
+  #
+  def self.deprecation
+    @deprecation ||= ActiveSupport::Deprecation.new('2.0.0', 'git')
+  end
+end
 
 require 'git/author'
 require 'git/base'
@@ -175,6 +200,46 @@ module Git
     Base.clone(repository_url, directory, options)
   end
 
+  # Returns the name of the default branch of the given repository
+  #
+  # @example with a URI string
+  #   Git.default_branch('https://github.com/ruby-git/ruby-git') # => 'master'
+  #   Git.default_branch('https://github.com/rspec/rspec-core') # => 'main'
+  #
+  # @example with a URI object
+  #   repository_uri = URI('https://github.com/ruby-git/ruby-git')
+  #   Git.default_branch(repository_uri) # => 'master'
+  #
+  # @example with a local repository
+  #   Git.default_branch('.') # => 'master'
+  #
+  # @example with a local repository Pathname
+  #   repository_path = Pathname('.')
+  #   Git.default_branch(repository_path) # => 'master'
+  #
+  # @example with the logging option
+  #   logger = Logger.new(STDOUT, level: Logger::INFO)
+  #   Git.default_branch('.', log: logger) # => 'master'
+  #   I, [2022-04-13T16:01:33.221596 #18415]  INFO -- : git '-c' 'core.quotePath=true' '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD'  2>&1
+  #
+  # @param repository [URI, Pathname, String] The (possibly remote) repository to get the default branch name for
+  #
+  #   See [GIT URLS](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a)
+  #   for more information.
+  #
+  # @param [Hash] options The options for this command (see list of valid
+  #   options below)
+  #
+  # @option options [Logger] :log A logger to use for Git operations.  Git
+  #   commands are logged at the `:info` level.  Additional logging is done
+  #   at the `:debug` level.
+  #
+  # @return [String] the name of the default branch
+  #
+  def self.default_branch(repository, options = {})
+    Base.repository_default_branch(repository, options)
+  end
+
   # Export the current HEAD (or a branch, if <tt>options[:branch]</tt>
   # is specified) into the +name+ directory, then remove all traces of git from the
   # directory.

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 1.16.0
+  version: 1.17.0
 platform: ruby
 authors:
 - Scott Chacon and others
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-04 00:00:00.000000000 Z
+date: 2023-03-06 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
 - !ruby/object:Gem::Dependency
   name: addressable
   requirement: !ruby/object:Gem::Requirement