git 1.19.1 → 3.1.1

data/README.md

@@ -8,50 +8,49 @@
 [![Gem Version](https://badge.fury.io/rb/git.svg)](https://badge.fury.io/rb/git)
 [![Documentation](https://img.shields.io/badge/Documentation-Latest-green)](https://rubydoc.info/gems/git/)
 [![Change Log](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://rubydoc.info/gems/git/file/CHANGELOG.md)
-[![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)
+[![Build Status](https://github.com/ruby-git/ruby-git/workflows/CI/badge.svg?branch=main)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
 
-The [git gem](https://rubygems.org/gems/git) provides an API that can be used to
-create, read, and manipulate Git repositories by wrapping system calls to the `git`
-command line. 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.
+- [📢 Default Branch Rename 📢](#-default-branch-rename-)
+- [📢 We've Switched to Conventional Commits 📢](#-weve-switched-to-conventional-commits-)
+- [Summary](#summary)
+- [Install](#install)
+- [Major Objects](#major-objects)
+- [Errors Raised By This Gem](#errors-raised-by-this-gem)
+- [Specifying And Handling Timeouts](#specifying-and-handling-timeouts)
+- [Examples](#examples)
+- [Ruby version support policy](#ruby-version-support-policy)
+- [License](#license)
 
-## v2.0.0 pre-release
+## 📢 Default Branch Rename 📢
 
-git 2.0.0 is available as a pre-release version for testing! Please give it a try.
+On June 6th, 2025, the default branch was renamed from 'master' to 'main'.
 
-**JRuby on Windows is not yet supported by the 2.x release line. Users running JRuby
-on Windows should continue to use the 1.x release line.**
+Instructions for renaming your local or forked branch to match can be found in the
+gist [Default Branch Name
+Change](https://gist.github.com/jcouball/580a10e395f7fdfaaa4297bbe816cc7d).
 
-The changes coming in this major release include:
+## 📢 We've Switched to Conventional Commits 📢
 
-* Create a policy of supported Ruby versions to support only non-EOL Ruby versions
-* Create a policy of supported Git CLI versions (released 2020-12-25)
-* Update the required Ruby version to at least 3.0 (released 2020-07-27)
-* Update the required Git command line version to at least 2.28
-* Update how CLI commands are called to use the [process_executer](https://github.com/main-branch/process_executer)
-  gem which is built on top of [Kernel.spawn](https://ruby-doc.org/3.3.0/Kernel.html#method-i-spawn).
-  See [PR #617](https://github.com/ruby-git/ruby-git/pull/617) for more details
-  on the motivation for this implementation.
+To enhance our development workflow, enable automated changelog generation, and pave
+the way for Continuous Delivery, the `ruby-git` project has adopted the [Conventional
+Commits standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit
+messages.
 
-The tentative plan is to release `2.0.0` near the end of March 2024 depending on
-the feedback received during the pre-release period.
+Going forward, all commits to this repository **MUST** adhere to the Conventional
+Commits standard. Commits not adhering to this standard will cause the CI build to
+fail. PRs will not be merged if they include non-conventional commits.
 
-The `master` branch will be used for `2.x` development. If needed, fixes for `1.x`
-version will be done on the `v1` branch.
+A git pre-commit hook may be installed to validate your conventional commit messages
+before pushing them to GitHub by running `bin/setup` in the project root.
 
-## Homepage
+Read more about this change in the [Commit Message Guidelines section of
+CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines)
 
-The project source code is at:
+## Summary
 
-http://github.com/ruby-git/ruby-git
-
-## Documentation
-
-Detailed documentation can be found at:
-
-https://rubydoc.info/gems/git/Git.html
+The [git gem](https://rubygems.org/gems/git) provides a Ruby interface to the `git`
+command line.
 
 Get started by obtaining a repository object by:
 
@@ -63,14 +62,29 @@ Methods that can be called on a repository object are documented in [Git::Base](
 
 ## Install
 
-You can install Ruby/Git like this:
+Install the gem and add to the application's Gemfile by executing:
+
+```shell
+bundle add git
+```
+
+to install version 1.x:
 
+```shell
+bundle add git --version "~> 1.19"
 ```
-sudo gem install git
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```shell
+gem install git
 ```
 
-## Code Status
+to install version 1.x:
 
+```shell
+gem install git --version "~> 1.19"
+```
 
 ## Major Objects
 
@@ -88,28 +102,112 @@ directory, in the index and in the repository.  Similar to running 'git status'
 
 **Git::Remote**- A reference to a remote repository that is tracked by this repository.
 
-**Git::Log** - An Enumerable object that references all the `Git::Object::Commit` objects that encompass your log query, which can be constructed through methods on the `Git::Log object`,
-like:
+**Git::Log** - An Enumerable object that references all the `Git::Object::Commit`
+objects that encompass your log query, which can be constructed through methods on
+the `Git::Log object`, like:
 
- `@git.log(20).object("some_file").since("2 weeks ago").between('v2.6', 'v2.7').each { |commit| [block] }`
+```ruby
+git.log
+  .max_count(:all)
+  .object('README.md')
+  .since('10 years ago')
+  .between('v1.0.7', 'HEAD')
+  .map { |commit| commit.sha }
+```
 
-Pass the `--all` option to `git log` as follows:
+A maximum of 30 commits are returned if `max_count` is not called. To get all commits
+that match the log query, call `max_count(:all)`.
 
- `@git.log.all.each { |commit| [block] }`
+Note that `git.log.all` adds the `--all` option to the underlying `git log` command.
+This asks for the logs of all refs (basically all commits reachable by HEAD,
+branches, and tags). This does not control the maximum number of commits returned. To
+control how many commits are returned, you should call `max_count`.
 
- **Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`.
+**Git::Worktrees** - Enumerable object that holds `Git::Worktree objects`.
 
-## Examples
+## Errors Raised By This Gem
 
-Here are a bunch of examples of how to use the Ruby/Git package.
+The git gem will only raise an `ArgumentError` or an error that is a subclass of
+`Git::Error`. It does not explicitly raise any other types of errors.
 
-Ruby < 1.9 will require rubygems to be loaded.
+It is recommended to rescue `Git::Error` to catch any runtime error raised by
+this gem unless you need more specific error handling.
 
 ```ruby
-require 'rubygems'
+begin
+  # some git operation
+rescue Git::Error => e
+  puts "An error occurred: #{e.message}"
+end
 ```
 
+See [`Git::Error`](https://rubydoc.info/gems/git/Git/Error) for more information.
+
+## Specifying And Handling Timeouts
+
+The timeout feature was added in git gem version `2.0.0`.
+
+A timeout for git command line operations can be set either globally or for specific
+method calls that accept a `:timeout` parameter.
+
+The timeout value must be a real, non-negative `Numeric` value that specifies a
+number of seconds a `git` command will be given to complete before being sent a KILL
+signal. This library may hang if the `git` command does not terminate after receiving
+the KILL signal.
+
+When a command times out, it is killed by sending it the `SIGKILL` signal and a
+`Git::TimeoutError` is raised. This error derives from the `Git::SignaledError` and
+`Git::Error`.
+
+If the timeout value is `0` or `nil`, no timeout will be enforced.
+
+If a method accepts a `:timeout` parameter and a receives a non-nil value, the value
+of this parameter will override the global timeout value. In this context, a value of
+`nil` (which is usually the default) will use the global timeout value and a value of
+`0` will turn off timeout enforcement for that method call no matter what the global
+value is.
+
+To set a global timeout, use the `Git.config` object:
+
+```ruby
+Git.config.timeout = nil # a value of nil or 0 means no timeout is enforced
+Git.config.timeout = 1.5 # can be any real, non-negative Numeric interpreted as number of seconds
+```
+
+The global timeout can be overridden for a specific method if the method accepts a
+`:timeout` parameter:
+
+```ruby
+repo_url = 'https://github.com/ruby-git/ruby-git.git'
+Git.clone(repo_url) # Use the global timeout value
+Git.clone(repo_url, timeout: nil) # Also uses the global timeout value
+Git.clone(repo_url, timeout: 0) # Do not enforce a timeout
+Git.clone(repo_url, timeout: 10.5)  # Timeout after 10.5 seconds raising Git::SignaledError
+```
+
+If the command takes too long, a `Git::TimeoutError` will be raised:
+
+```ruby
+begin
+  Git.clone(repo_url, timeout: 10)
+rescue Git::TimeoutError => e
+  e.result.tap do |r|
+    r.class #=> Git::CommandLineResult
+    r.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
+    r.status.timeout? #=> true
+    r.git_cmd # The git command ran as an array of strings
+    r.stdout # The command's output to stdout until it was terminated
+    r.stderr # The command's output to stderr until it was terminated
+  end
+end
+```
+
+## Examples
+
+Here are a bunch of examples of how to use the Ruby/Git package.
+
 Require the 'git' gem.
+
 ```ruby
 require 'git'
 ```
@@ -139,9 +237,15 @@ g.index.writable?
 g.repo
 g.dir
 
-g.log   # returns a Git::Log object, which is an Enumerator of Git::Commit objects
-g.log(200)
-g.log.since('2 weeks ago')
+# 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
+g.log(200) # 200 most recent commits
+g.log.since('2 weeks ago') # default count of commits since 2 weeks ago.
+g.log(200).since('2 weeks ago') # commits since 2 weeks ago, limited to 200.
 g.log.between('v2.5', 'v2.6')
 g.log.each {|l| puts l.sha }
 g.gblob('v2.5:Makefile').log.since('2 weeks ago')
@@ -174,14 +278,14 @@ 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
 g.current_branch
 g.branches.remote
-g.branches[:master].gcommit
-g.branches['origin/master'].gcommit
+g.branches[:main].gcommit
+g.branches['origin/main'].gcommit
 
 g.grep('hello')  # implies HEAD
 g.blob('v2.5:Makefile').grep('hello')
@@ -238,7 +342,7 @@ Git.ls_remote('https://github.com/ruby-git/ruby-git.git') # returns a hash conta
 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'
+Git.default_branch('https://github.com/ruby-git/ruby-git') #=> 'main'
 ```
 
 And here are the operations that will need to write to your git repository.
@@ -276,11 +380,11 @@ g.add(:all=>true)                       # git add --all -- "."
 g.add('file_path')                      # git add -- "file_path"
 g.add(['file_path_1', 'file_path_2'])   # git add -- "file_path_1" "file_path_2"
 
-g.remove()									# git rm -f -- "."
-g.remove('file.txt')						# git rm -f -- "file.txt"
-g.remove(['file.txt', 'file2.txt'])		# git rm -f -- "file.txt" "file2.txt"
-g.remove('file.txt', :recursive => true) 	# git rm -f -r -- "file.txt"
-g.remove('file.txt', :cached => true)		# git rm -f --cached -- "file.txt"
+g.remove()                                # git rm -f -- "."
+g.remove('file.txt')                      # git rm -f -- "file.txt"
+g.remove(['file.txt', 'file2.txt'])       # git rm -f -- "file.txt" "file2.txt"
+g.remove('file.txt', :recursive => true)  # git rm -f -r -- "file.txt"
+g.remove('file.txt', :cached => true)     # git rm -f --cached -- "file.txt"
 
 g.commit('message')
 g.commit_all('message')
@@ -311,13 +415,13 @@ g.branch('new_branch') # creates new or fetches existing
 g.branch('new_branch').checkout
 g.branch('new_branch').delete
 g.branch('existing_branch').checkout
-g.branch('master').contains?('existing_branch')
+g.branch('main').contains?('existing_branch')
 
 # delete remote branch
 g.push('origin', 'remote_branch_name', force: true, delete: true)
 
 g.checkout('new_branch')
-g.checkout('new_branch', new_branch: true, start_point: 'master')
+g.checkout('new_branch', new_branch: true, start_point: 'main')
 g.checkout(g.branch('new_branch'))
 
 g.branch(name).merge(branch2)
@@ -327,7 +431,7 @@ g.branch(name).in_branch(message) { # add files }  # auto-commits
 g.merge('new_branch')
 g.merge('new_branch', 'merge commit message', no_ff: true)
 g.merge('origin/remote_branch')
-g.merge(g.branch('master'))
+g.merge(g.branch('main'))
 g.merge([branch1, branch2])
 
 g.merge_base('branch1', 'branch2')
@@ -422,6 +526,20 @@ g.with_temp_working(dir) do
 end
 ```
 
+## Ruby version support policy
+
+This gem will be expected to function correctly on:
+
+* All non-EOL versions of the MRI Ruby on Mac, Linux, and Windows
+* The latest version of JRuby on Linux
+* The latest version of Truffle Ruby on Linus
+
+It is this project's intent to support the latest version of JRuby on Windows
+once the following JRuby bug is fixed:
+
+jruby/jruby#7515
+
 ## License
 
-licensed under MIT License Copyright (c) 2008  Scott Chacon. See LICENSE for further details.
+Licensed under MIT License Copyright (c) 2008  Scott Chacon. See LICENSE for further
+details.

data/Rakefile

@@ -58,3 +58,10 @@ task :'test:gem' => :install do
 
   puts 'Gem Test Succeeded'
 end
+
+# Make it so that calling `rake release` just calls `rake release:rubygem_push` to
+# avoid creating and pushing a new tag.
+
+Rake::Task['release'].clear
+desc 'Customized release task to avoid creating a new tag'
+task release: 'release:rubygem_push'

data/git.gemspec

@@ -24,22 +24,22 @@ Gem::Specification.new do |s|
   s.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{s.name}/#{s.version}"
 
   s.require_paths = ['lib']
-  s.required_ruby_version = '>= 2.3'
-  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.required_ruby_version = '>= 3.0.0'
+  s.requirements = ['git 2.28.0 or greater']
 
+  s.add_runtime_dependency 'activesupport', '>= 5.0'
   s.add_runtime_dependency 'addressable', '~> 2.8'
-  s.add_runtime_dependency 'rchardet', '~> 1.8'
+  s.add_runtime_dependency 'process_executer', '~> 1.3'
+  s.add_runtime_dependency 'rchardet', '~> 1.9'
 
-  s.add_development_dependency 'bump', '~> 0.10'
-  s.add_development_dependency 'create_github_release', '~> 0.2'
-  s.add_development_dependency 'minitar', '~> 0.9'
-  s.add_development_dependency 'mocha', '~> 2.1'
-  s.add_development_dependency 'rake', '~> 13.0'
-  s.add_development_dependency 'test-unit', '~> 3.3'
+  s.add_development_dependency 'create_github_release', '~> 2.1'
+  s.add_development_dependency 'minitar', '~> 1.0'
+  s.add_development_dependency 'mocha', '~> 2.7'
+  s.add_development_dependency 'rake', '~> 13.2'
+  s.add_development_dependency 'test-unit', '~> 3.6'
 
   unless RUBY_PLATFORM == 'java'
-    s.add_development_dependency 'redcarpet', '~> 3.5'
+    s.add_development_dependency 'redcarpet', '~> 3.6'
     s.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
     s.add_development_dependency 'yardstick', '~> 0.9'
   end

data/lib/git/author.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Git
   class Author
     attr_accessor :name, :email, :date
-    
+
     def initialize(author_string)
       if m = /(.*?) <(.*?)> (\d+) (.*)/.match(author_string)
         @name = m[1]
@@ -9,6 +11,5 @@ module Git
         @date = Time.at(m[3].to_i)
       end
     end
-    
   end
 end