git 1.19.1 → 2.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f12803468275850ae680a4df2719890e8f84de95258f30dc898f817c7155d44
-  data.tar.gz: d24540a708538775d2ff1af495f04e7f42a297aaf790d0fe7b65ad71fe402550
+  metadata.gz: 23b5fa33a9a0cb112334c8b243abd6b388984d5f63aa2ee57f83e67d66e68f4b
+  data.tar.gz: 292e0d1c9aa4ce4671206abcdb1a547ab606090ecd7b8f2d182def4721347c03
 SHA512:
-  metadata.gz: 15a09f75d84fb1ff7547403eb36c7342bee11fc1a23cf86e5eae224a2494da0e0bc60bf288c04924c87bdf6736f156f4d98f0468cf815d03b3291509ab234e8d
-  data.tar.gz: 7fe2633018ec2e38805b987271cc033d023b1a32b429cf2f75e88d1ac1c86c913689fc46806ea49c38fce66005215b05fc700ca3adc925afd0b3dcd3fefdc091
+  metadata.gz: 2332e16fc52d5ff5fd67cea38a1e4196bb98c06256746e81d13b0572ac78957743559eb27b8de752ba8c960e72f912cb5077fce625b6233ed6e63e1c2ef67890
+  data.tar.gz: bf769b8943941cec7efa01bae6152302023045d01a69c6aaddf9c04f8815eb18828a2e81b8133d0c7ab873235f08acfecce528d3e7f8659fb032baa73e44c6a1

data/.github/workflows/continuous_integration.yml

@@ -2,39 +2,43 @@ name: CI
 
 on:
   push:
-    branches: [master]
+    branches: [master,v1]
   pull_request:
-    branches: [master]
+    branches: [master,v1]
   workflow_dispatch:
 
 jobs:
-  continuous_integration_build:
-    continue-on-error: true
+  build:
+    name: Ruby ${{ matrix.ruby }} on ${{ matrix.operating-system }}
+    runs-on: ${{ matrix.operating-system }}
+    continue-on-error: ${{ matrix.experimental == 'Yes' }}
+    env: { JAVA_OPTS: -Djdk.io.File.enableADS=true }
+
     strategy:
       fail-fast: false
       matrix:
-        ruby: [2.7, 3.0, 3.1, 3.2]
+        # Only the latest versions of JRuby and TruffleRuby are tested
+        ruby: ["3.0", "3.1", "3.2", "3.3", "truffleruby-24.0.0", "jruby-9.4.5.0"]
         operating-system: [ubuntu-latest]
+        experimental: [No]
         include:
-          - ruby: head
+          - # Building against head version of Ruby is considered experimental
+            ruby: head
             operating-system: ubuntu-latest
-          - ruby: truffleruby-head
-            operating-system: ubuntu-latest
-          - ruby: 2.7
-            operating-system: windows-latest
-          - ruby: jruby-head
-            operating-system: windows-latest
+            experimental: Yes
 
-    name: Ruby ${{ matrix.ruby }} on ${{ matrix.operating-system }}
-
-    runs-on: ${{ matrix.operating-system }}
+          - # Only test with minimal Ruby version on Windows
+            ruby: 3.0
+            operating-system: windows-latest
 
-    env:
-      JAVA_OPTS: -Djdk.io.File.enableADS=true
+          - # Since JRuby on Windows is known to not work, consider this experimental
+            ruby: jruby-9.4.5.0
+            operating-system: windows-latest
+            experimental: Yes
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1

data/CHANGELOG.md

@@ -5,6 +5,25 @@
 
 # Change Log
 
+## v2.0.0.pre2 (2024-02-24)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.0.0.pre1..v2.0.0.pre2)
+
+Changes since v2.0.0.pre1:
+
+* 023017b Add a timeout for git commands (#692)
+* 8286ceb Refactor the Error heriarchy (#693)
+
+## v2.0.0.pre1 (2024-01-15)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v1.19.1..v2.0.0.pre1)
+
+Changes since v1.19.1:
+
+* 7585c39 Change how the git CLI subprocess is executed (#684)
+* f93e042 Update instructions for releasing a new version of the git gem (#686)
+* f48930d Update minimum required version of Ruby and Git (#685)
+
 ## v1.19.1 (2024-01-13)
 
 [Full Changelog](https://github.com/ruby-git/ruby-git/compare/v1.19.0..v1.19.1)

data/README.md

@@ -11,12 +11,32 @@
 [![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)
 
+* [Summary](#summary)
+* [v2.0.0 pre-release](#v200-pre-release)
+* [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)
+
+## Summary
+
 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.
 
+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)
+
+Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
+
 ## v2.0.0 pre-release
 
 git 2.0.0 is available as a pre-release version for testing! Please give it a try.
@@ -32,7 +52,7 @@ The changes coming in this major release include:
 * 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
+  See [PR #684](https://github.com/ruby-git/ruby-git/pull/684) for more details
   on the motivation for this implementation.
 
 The tentative plan is to release `2.0.0` near the end of March 2024 depending on
@@ -41,36 +61,19 @@ the feedback received during the pre-release period.
 The `master` branch will be used for `2.x` development. If needed, fixes for `1.x`
 version will be done on the `v1` branch.
 
-## Homepage
-
-The project source code is at:
-
-http://github.com/ruby-git/ruby-git
-
-## Documentation
-
-Detailed documentation can be found at:
-
-https://rubydoc.info/gems/git/Git.html
-
-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)
-
-Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
-
 ## Install
 
-You can install Ruby/Git like this:
+Install the gem and add to the application's Gemfile by executing:
 
-```
-sudo gem install git
+```shell
+bundle add git
 ```
 
-## Code Status
+If bundler is not being used to manage dependencies, install the gem by executing:
 
+```shell
+gem install git
+```
 
 ## Major Objects
 
@@ -99,17 +102,119 @@ Pass the `--all` option to `git log` as follows:
 
  **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.
+This gem raises custom errors that derive from `Git::Error`. These errors are
+arranged in the following class heirarchy:
+
+Error heirarchy:
+
+```text
+Error
+└── CommandLineError
+    ├── FailedError
+    └── SignaledError
+        └── TimeoutError
+```
 
-Ruby < 1.9 will require rubygems to be loaded.
+Other standard errors may also be raised like `ArgumentError`. Each method should
+document the errors it may raise.
+
+Description of each Error class:
+
+* `Error`: This catch-all error serves as the base class for other custom errors in this
+  gem. Errors of this class are raised when no more approriate specific error to
+  raise.
+* `CommandLineError`: This error is raised when there's a problem executing the git
+  command line. This gem will raise a more specific error depending on how the
+  command line failed.
+* `FailedError`: This error is raised when the git command line exits with a non-zero
+  status code that is not expected by the git gem.
+* `SignaledError`: This error is raised when the git command line is terminated as a
+  result of receiving a signal. This could happen if the process is forcibly
+  terminated or if there is a serious system error.
+* `TimeoutError`: This is a specific type of `SignaledError` that is raised when the
+  git command line operation times out and is killed via the SIGKILL signal. This
+  happens if the operation takes longer than the timeout duration configured in
+  `Git.config.timeout` or via the `:timeout` parameter given in git methods that
+  support this parameter.
+
+`Git::GitExecuteError` remains as an alias for `Git::Error`. It is considered
+deprecated as of git-2.0.0.
+
+Here is an example of catching errors when using the git gem:
 
 ```ruby
-require 'rubygems'
+begin
+  timeout_duration = 0.001 # seconds
+  repo = Git.clone('https://github.com/ruby-git/ruby-git', 'ruby-git-temp', timeout: timeout_duration)
+rescue Git::TimeoutError => e # Catch the more specific error first!
+  puts "Git clone took too long and timed out #{e}"
+rescue Git::Error => e
+  puts "Received the following error: #{e}"
 ```
 
+## Specifying And Handling Timeouts
+
+The timeout feature was added in git gem version `2.0.0`.
+
+A timeout for git 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, a `Git::TimeoutError` is raised.
+
+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, it 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::SignaledError` will be raised:
+
+```ruby
+begin
+  Git.clone(repo_url, timeout: 10)
+rescue Git::TimeoutError => e
+  result = e.result
+  result.class #=> Git::CommandLineResult
+  result.status #=> #<Process::Status: pid 62173 SIGKILL (signal 9)>
+  result.status.timeout? #=> true
+  result.git_cmd # The git command ran as an array of strings
+  result.stdout # The command's output to stdout until it was terminated
+  result.stderr # The command's output to stderr until it was terminated
+end
+```
+
+## Examples
+
+Here are a bunch of examples of how to use the Ruby/Git package.
+
 Require the 'git' gem.
+
 ```ruby
 require 'git'
 ```
@@ -276,11 +381,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')
@@ -422,6 +527,14 @@ 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 and Windows
+* The latest version of Truffle Ruby on Linus
+
 ## License
 
 licensed under MIT License Copyright (c) 2008  Scott Chacon. See LICENSE for further details.

data/RELEASING.md

@@ -7,64 +7,79 @@
 
 Releasing a new version of the `git` gem requires these steps:
 
-- [How to release a new git.gem](#how-to-release-a-new-gitgem)
-  - [Install Prerequisites](#install-prerequisites)
-  - [Prepare the Release](#prepare-the-release)
-  - [Review and Merge the Release](#review-and-merge-the-release)
-  - [Build and Release the Gem](#build-and-release-the-gem)
-
-These instructions use an example where:
-
-- The default branch is `master`
-- The current release version is `1.5.0`
-- You want to create a new *minor* release, `1.6.0`
+* [Install Prerequisites](#install-prerequisites)
+* [Determine the SemVer release type](#determine-the-semver-release-type)
+* [Create the release](#create-the-release)
+* [Review the CHANGELOG and release PR](#review-the-changelog-and-release-pr)
+* [Manually merge the release PR](#manually-merge-the-release-pr)
+* [Publish the git gem to RubyGems.org](#publish-the-git-gem-to-rubygemsorg)
 
 ## Install Prerequisites
 
 The following tools need to be installed in order to create the release:
 
-- [git](https://git-scm.com) is used to interact with the local and remote repositories
-- [gh](https://cli.github.com) is used to create the release and PR in GitHub
-- [Docker](https://www.docker.com) is used to run the script to create the release notes
+* [create_githhub_release](https://github.com/main-branch/create_github_release) is used to create the release
+* [git](https://git-scm.com) is used by `create-github-release` to interact with the local and remote repositories
+* [gh](https://cli.github.com) is used by `create-github-release` to create the release and PR in GitHub
 
-On a Mac, these tools can be installed using [brew](https://brew.sh):
+On a Mac, these tools can be installed using [gem](https://guides.rubygems.org/rubygems-basics/) and [brew](https://brew.sh):
 
 ```shell
+$ gem install create_github_release
+...
 $ brew install git
 ...
 $ brew install gh
 ...
-$ brew install --cask docker
-...
 $
 ```
 
-## Prepare the Release
+## Determine the SemVer release type
 
-Bump the version, create release notes, tag the release and create a GitHub release and PR which can be used to review the release.
+Determine the SemVer version increment that should be applied for the new release:
 
-Steps:
+* `major`: when the release includes incompatible API or functional changes.
+* `minor`: when the release adds functionality in a backward-compatible manner
+* `patch`: when the release includes small user-facing changes that are
+  backward-compatible and do not introduce new functionality.
 
-- Check out the code with `git clone https://github.com/ruby-git/ruby-git ruby-git-v1.6.0 && cd ruby-git-v1.6.0`
-- Install development dependencies using bundle `bundle install`
-- Based upon the nature of the changes, decide on the type of release: `major`, `minor`, or `patch` (in this example we will use `minor`)
-- Run the release script `bundle exec create-github-release minor`
+## Create the release
 
-## Review and Merge the Release
+Create the release using the `create-github-release` command. If the release type
+is `major`, the command is:
 
-Have the release PR approved and merge the changes into the `master` branch.
+```shell
+create-github-release major
+```
 
-**IMPORTANT** DO NOT merge to the `master` branch using the GitHub UI. Instead use the instructions below.
+Follow the directions given by the `create-github-release` command to finish the
+release. Where the instructions given by the command differ than the instructions
+below, follow the instructions given by the command.
 
-Steps:
+## Review the CHANGELOG and release PR
 
-- Get the release PR reviewed and approved in GitHub
-- Merge the changes with the command `git checkout master && git merge --ff-only v1.6.0 && git push`
+The `create-github-release` command will output a link to the CHANGELOG and the PR
+it created for the release. Review the CHANGELOG and have someone review and approve
+the release PR.
 
-## Build and Release the Gem
+## Manually merge the release PR
 
-Build the gem and publish it to [rubygems.org](https://rubygems.org/gems/git)
+It is important to manually merge the PR so a separate merge commit can be avoided.
+Use the commands output by the `create-github-release` which will looks like this
+if you are creating a 2.0.0 release:
 
-Steps:
+```shell
+git checkout master
+git merge --ff-only release-v2.0.0
+git push
+```
+
+This will automatically close the release PR.
+
+## Publish the git gem to RubyGems.org
 
-- Build and release the gem using rake `bundle exec rake release`
+Finally, publish the git gem to RubyGems.org using the following command:
+
+```shell
+rake release:rubygem_push
+```

data/git.gemspec

@@ -24,22 +24,20 @@ 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 'addressable', '~> 2.8'
+  s.add_runtime_dependency 'process_executer', '~> 1.1'
   s.add_runtime_dependency 'rchardet', '~> 1.8'
 
-  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 'rake', '~> 13.1'
+  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