git 1.15.0 → 1.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a3877a2258c4835e6adc9ad9844f89eeaf340bf1ad7a47937178fc4abe4bfae
-  data.tar.gz: 4bc93c337d92610aa46c7265fb03cfff12ca62d23fcfe67488e5ffaf0dd171cb
+  metadata.gz: dcca4b91f56e1bf6b99c471f918fbe4b1ed6d56b0058021e345514676e153223
+  data.tar.gz: 9f4386702fca4248c3a7a07400c6ff3e52fa7898f0e16bbcb3b90bf945fde1da
 SHA512:
-  metadata.gz: 89caa1ce17512244548e72fcac709390c8017601e7699d6355939d613c8cba973c5309c733d4071d5db356d93f9fe37b42e3ca48862e759c00fdbf85b55eb51f
-  data.tar.gz: fff185e87d3925baed674a81b3501dba49a9e9c8af1e1f99fdb27645c83a5a22e820001ab46a49a71e703b0dcb741d5a6aa8baeddf2dd4c39fa6199443a8190e
+  metadata.gz: 4d943759fc15a56baee49734b4628cf1b5651416c13842077a9bfe979df1bdc05afbe114af904b2161ef84be090207f9691a80a704efe2d8a3a14bb4c80df8f6
+  data.tar.gz: 8feccfa435ec2f3d95a52ec0fd3920b5a956b2dc3cbcddfbc63c48052ddf64686ba1ef849f0b96307e573134d0e818c6d5bfaae8f3dad877a6f74a516806754a

data/CHANGELOG.md

@@ -5,6 +5,31 @@
 
 # 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)
+
+Changes since v1.15.0:
+
+* 536d Fix parsing when in detached HEAD state in Git::Lib#branches_all (#641)
+* 5c68 Fix parsing of symbolic refs in `Git::Lib#branches_all` (#640)
+* 7d88 Remote#branch and #merge should default to current branch instead of "master" (#639)
+* 3dda0 `#branch` name should default to current branch instead of `master` (#638)
+* d33d #checkout without args should do same as `git checkout` with no args (#637)
+* 0c90 #push without args should do same as `git push` with no args (#636)
+* 2b19 Make it easier to run test files from the command line (#635)
+
 ## v1.15.0 (2023-03-01)
 
 [Full Changelog](https://github.com/ruby-git/ruby-git/compare/v1.14.0..v1.15.0)

data/CONTRIBUTING.md

@@ -84,11 +84,11 @@ In order to ensure high quality, all pull requests must meet these requirements:
 While working on specific features you can run individual test files or
 a group of tests using `bin/test`:
 
-    # run a single file:
-    $ bin/test tests/units/test_object.rb
+    # run a single file (from tests/units):
+    $ bin/test test_object
 
     # run multiple files:
-    $ bin/test tests/units/test_object.rb tests/units/test_archive.rb
+    $ bin/test test_object test_archive
 
     # run all unit tests:
     $ bin/test

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/factory.rb

@@ -3,9 +3,8 @@ module Git
   class Base
 
     module Factory
-
       # @return [Git::Branch] an object for branch_name
-      def branch(branch_name = 'master')
+      def branch(branch_name = self.current_branch)
         Git::Branch.new(self, branch_name)
       end
 
@@ -93,7 +92,6 @@ module Git
         shas = self.lib.merge_base(*args)
         shas.map { |sha| gcommit(sha) }
       end
-
     end
 
   end

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.
@@ -350,8 +355,8 @@ module Git
     end
 
     # checks out a branch as the new git working directory
-    def checkout(branch = 'master', opts = {})
-      self.lib.checkout(branch, opts)
+    def checkout(*args, **options)
+      self.lib.checkout(*args, **options)
     end
 
     # checks out an old version of a file
@@ -369,16 +374,26 @@ 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
     #
-    #  @git.config('remote.remote-name.push', 'refs/heads/master:refs/heads/master')
+    # @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
     #
-    def push(remote = 'origin', branch = 'master', opts = {})
-      # Small hack to keep backwards compatibility with the 'push(remote, branch, tags)' method signature.
-      opts = {:tags => opts} if [true, false].include?(opts)
-
-      self.lib.push(remote, branch, opts)
+    #   @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]
+    #
+    #   @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)
     end
 
     # merges one or more branches into the current working branch

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")
@@ -347,13 +365,42 @@ module Git
       command('symbolic-ref', 'HEAD', "refs/heads/#{branch_name}")
     end
 
+    BRANCH_LINE_REGEXP = /
+      ^
+        # Prefix indicates if this branch is checked out. The prefix is one of:
+        (?:
+          (?<current>\*[[:blank:]]) |  # Current branch (checked out in the current worktree)
+          (?<worktree>\+[[:blank:]]) | # Branch checked out in a different worktree
+          [[:blank:]]{2}               # Branch not checked out
+        )
+
+        # The branch's full refname
+        (?:
+          (?<not_a_branch>\(not[[:blank:]]a[[:blank:]]branch\)) |
+          (?:\(HEAD[[:blank:]]detached[[:blank:]]at[[:blank:]](?<detached_ref>[^\)]+)\)) |
+          (?<refname>[^[[:blank:]]]+)
+        )
+
+        # Optional symref
+        # If this ref is a symbolic reference, this is the ref referenced
+        (?:
+          [[:blank:]]->[[:blank:]](?<symref>.*)
+        )?
+      $
+    /x
+
     def branches_all
-      arr = []
-      command_lines('branch', '-a').each do |b|
-        current = (b[0, 2] == '* ')
-        arr << [b.gsub('* ', '').strip, current]
-      end
-      arr
+      command_lines('branch', '-a').map do |line|
+        match_data = line.match(BRANCH_LINE_REGEXP)
+        raise GitExecuteError, 'Unexpected branch line format' unless match_data
+        next nil if match_data[:not_a_branch] || match_data[:detached_ref]
+        [
+          match_data[:refname],
+          !match_data[:current].nil?,
+          !match_data[:worktree].nil?,
+          match_data[:symref]
+        ]
+      end.compact
     end
 
     def worktrees_all
@@ -772,11 +819,16 @@ module Git
     #
     # @param [String] branch
     # @param [Hash] opts
-    def checkout(branch, opts = {})
+    def checkout(branch = nil, opts = {})
+      if branch.is_a?(Hash) && opts == {}
+        opts = branch
+        branch = nil
+      end
+
       arr_opts = []
       arr_opts << '-b' if opts[:new_branch] || opts[:b]
       arr_opts << '--force' if opts[:force] || opts[:f]
-      arr_opts << branch
+      arr_opts << branch if branch
       arr_opts << opts[:start_point] if opts[:start_point] && arr_opts.include?('-b')
 
       command('checkout', *arr_opts)
@@ -908,20 +960,37 @@ module Git
       command('fetch', *arr_opts)
     end
 
-    def push(remote, branch = 'master', opts = {})
+    def push(remote = nil, branch = nil, opts = nil)
+      if opts.nil? && branch.instance_of?(Hash)
+        opts = branch
+        branch = nil
+      end
+
+      if opts.nil? && remote.instance_of?(Hash)
+        opts = remote
+        remote = nil
+      end
+
+      opts ||= {}
+
       # Small hack to keep backwards compatibility with the 'push(remote, branch, tags)' method signature.
       opts = {:tags => opts} if [true, false].include?(opts)
 
+      raise ArgumentError, "You must specify a remote if a branch is specified" if remote.nil? && !branch.nil?
+
       arr_opts = []
       arr_opts << '--mirror'  if opts[:mirror]
       arr_opts << '--delete'  if opts[:delete]
       arr_opts << '--force'  if opts[:force] || opts[:f]
-      arr_opts << remote
+      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
 
       if opts[:mirror]
-          command('push', *arr_opts)
+          command('push', *arr_opts_with_branch)
       else
-          command('push', *arr_opts, branch)
+          command('push', *arr_opts_with_branch)
           command('push', '--tags', *arr_opts) if opts[:tags]
       end
     end

data/lib/git/remote.rb

@@ -1,8 +1,8 @@
 module Git
   class Remote < Path
-    
+
     attr_accessor :name, :url, :fetch_opts
-    
+
     def initialize(base, name)
       @base = base
       config = @base.lib.config_remote(name)
@@ -10,27 +10,29 @@ module Git
       @url = config['url']
       @fetch_opts = config['fetch']
     end
-    
+
     def fetch(opts={})
       @base.fetch(@name, opts)
     end
-    
+
     # merge this remote locally
-    def merge(branch = 'master')
-      @base.merge("#{@name}/#{branch}")
+    def merge(branch = @base.current_branch)
+      remote_tracking_branch = "#{@name}/#{branch}"
+      @base.merge(remote_tracking_branch)
     end
-    
-    def branch(branch = 'master')
-      Git::Branch.new(@base, "#{@name}/#{branch}")
+
+    def branch(branch = @base.current_branch)
+      remote_tracking_branch = "#{@name}/#{branch}"
+      Git::Branch.new(@base, remote_tracking_branch)
     end
-    
+
     def remove
-      @base.lib.remote_remove(@name)     
+      @base.lib.remote_remove(@name)
     end
-    
+
     def to_s
       @name
     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='1.15.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.15.0
+  version: 1.17.0
 platform: ruby
 authors:
 - Scott Chacon and others
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-01 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