git 2.0.0.pre3 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bd064fe363a807e4c9a77eaf61810f6fc41323ad1b60a57eb0379460f26e91c
-  data.tar.gz: 890bb2663ba5e3cc9b12f3dae403a019e3b7eb0ffb95ad2fdf5989073d53e807
+  metadata.gz: 7c7aebf8b61eb75a0d3e587fae03711b1d9cec89c7fb69462bda24c069daeaa4
+  data.tar.gz: f73bd8a6e030209305ffbcc1bae372cd6820745569142ddd7239b366ef78d322
 SHA512:
-  metadata.gz: bbd732fb4061c1b68500860218eb14248adc48d4e4ff77d9b2c19cd13de5cb54c9c1bf313949131c91c7e3a25b24d8d105abb485571e06b25415875a67ce4f94
-  data.tar.gz: 6bf02024406485e4150cc76073d859446e490a659e6a17dad1f0f04c9d0084bcb063ccbc12dc839baa1b20094e2a2dcaf800c744560c49eab29264b588d154fb
+  metadata.gz: 32c0e605d3ee280c19cf863f5b9a5fc9437171b9facbbee074b2ddca096c4cae3f08ddf42cb6cad7a91512824f40cd51940e1846c1f1a3e5bb7f4e7ee52e154b
+  data.tar.gz: 528bf8926dbf6b76681b8333ca3d797b1e28854921f6abcd5b2fd9a13c6861c25e6ad75462efb818c1c74de0980c96974a423ad2a19aaf87d5b27e3e2ffca8cf

data/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+Review our [guidelines for contributing](https://github.com/ruby-git/ruby-git/blob/master/CONTRIBUTING.md) to this repository. A good start is to:
+
+* Write tests for your changes
+* Run `rake` before pushing
+* Include / update docs in the README.md and in YARD documentation
+
+# Description
+

data/.github/workflows/continuous_integration.yml

@@ -22,20 +22,10 @@ jobs:
         operating-system: [ubuntu-latest]
         experimental: [No]
         include:
-          - # Building against head version of Ruby is considered experimental
-            ruby: head
-            operating-system: ubuntu-latest
-            experimental: Yes
-
           - # Only test with minimal Ruby version on Windows
             ruby: 3.0
             operating-system: windows-latest
 
-          - # 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@v4

data/.github/workflows/experimental_continuous_integration.yml

@@ -0,0 +1,43 @@
+name: CI Experimental
+
+on:
+  push:
+    branches: [master,v1]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Ruby ${{ matrix.ruby }} on ${{ matrix.operating-system }}
+    runs-on: ${{ matrix.operating-system }}
+    continue-on-error: true
+    env: { JAVA_OPTS: -Djdk.io.File.enableADS=true }
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - # Building against head version of Ruby is considered experimental
+            ruby: head
+            operating-system: ubuntu-latest
+            experimental: Yes
+
+          - # Since JRuby on Windows is known to not work, consider this experimental
+            ruby: jruby-head
+            operating-system: windows-latest
+            experimental: Yes
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
+      - name: Run Build
+        run: bundle exec rake default
+
+      - name: Test Gem
+        run: bundle exec rake test:gem

data/CHANGELOG.md

@@ -5,6 +5,44 @@
 
 # Change Log
 
+## v2.0.1 (2024-05-21)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.0.0..v2.0.1)
+
+Changes since v2.0.0:
+
+* da435b1 Document and add tests for Git::Status
+* c8a77db Fix Git::Base#status on an empty repo
+* 712fdad Fix Git::Status#untracked when run from worktree subdir
+* 6a59bc8 Remove the Git::Base::Factory module
+
+## v2.0.0 (2024-05-10)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.0.0.pre4..v2.0.0)
+
+Changes since v2.0.0.pre4:
+
+* 1afc4c6 Update 2.x release line description
+* ed52420 Make the pull request template more concise
+* 299ae6b Remove stale bot integration
+* efb724b Remove the DCO requirement for commits
+
+## v2.0.0.pre4 (2024-05-10)
+
+[Full Changelog](https://jcouball@github.com/ruby-git/ruby-git/compare/v2.0.0.pre3..v2.0.0.pre4)
+
+Changes since v2.0.0.pre3:
+
+* 56783e7 Update create_github_release dependency so pre-releases can be made
+* 8566929 Add dependency on create_github_release gem used for releasing the git gem
+* 7376d76 Refactor errors that are raised by this gem
+* 7e99b17 Update documentation for new timeout functionality
+* 705e983 Move experimental builds to a separate workflow that only runs when pushed to master
+* e056d64 Build with jruby-head on Windows until jruby/jruby#7515 is fixed
+* ec7c257 Remove unneeded scripts to create a new release
+* d9570ab Move issue and pull request templates to the .github directory
+* e4d6a77 Show log(x).since combination in README
+
 ## v2.0.0.pre3 (2024-03-15)
 
 [Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.0.0.pre2..v2.0.0.pre3)

data/CONTRIBUTING.md

@@ -40,10 +40,6 @@ There is three step process for code or documentation changes:
 
 Make your changes in a fork of the ruby-git repository.
 
-Each commit must include a [DCO sign-off](#developer-certificate-of-origin-dco)
-by adding the line `Signed-off-by: Name <email>` to the end of the commit
-message.
-
 ### Create a pull request
 
 See [this article](https://help.github.com/articles/about-pull-requests/) if you
@@ -71,15 +67,18 @@ request meets [the project's coding standards](#coding-standards).
 In order to ensure high quality, all pull requests must meet these requirements:
 
 ### 1 PR = 1 Commit
-  * All commits for a PR must be squashed into one commit
-  * To avoid an extra merge commit, the PR must be able to be merged as [a fast forward merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
-  * The easiest way to ensure a fast forward merge is to rebase your local branch
-    to the ruby-git master branch
+
+* All commits for a PR must be squashed into one commit
+* To avoid an extra merge commit, the PR must be able to be merged as [a fast forward
+  merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
+* The easiest way to ensure a fast forward merge is to rebase your local branch to
+ the ruby-git master branch
 
 ### Unit tests
-  * All changes must be accompanied by new or modified unit tests
-  * The entire test suite must pass when `bundle exec rake default` is run from the
-    project's local working copy.
+
+* All changes must be accompanied by new or modified unit tests
+* The entire test suite must pass when `bundle exec rake default` is run from the
+  project's local working copy.
 
 While working on specific features you can run individual test files or
 a group of tests using `bin/test`:
@@ -94,20 +93,21 @@ a group of tests using `bin/test`:
     $ 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.
-  * 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).
+
+* 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).
 
 ### Documentation
-  * New and updated public methods must have [YARD](https://yardoc.org/)
-    documentation added to them
-  * New and updated public facing features should be documented in the project's
-    [README.md](README.md)
 
-### Licensing sign-off
-  * Each commit must contain [the DCO sign-off](#developer-certificate-of-origin-dco)
-    in the form:  `Signed-off-by: Name <email>`
+* New and updated public methods must have [YARD](https://yardoc.org/) documentation
+  added to them
+* New and updated public facing features should be documented in the project's
+  [README.md](README.md)
 
 ## Licensing
 
@@ -116,48 +116,3 @@ declared in the [LICENSE](LICENSE) file.
 
 Licensing is very important to open source projects. It helps ensure the
 software continues to be available under the terms that the author desired.
-
-### Developer Certificate of Origin (DCO)
-
-This project requires that authors have permission to submit their contributions
-under the MIT license. To make a good faith effort to ensure this, ruby-git
-requires the [Developer Certificate of Origin (DCO)](https://elinux.org/Developer_Certificate_Of_Origin)
-process be followed.
-
-This process requires that each commit include a `Signed-off-by` line that
-indicates the author accepts the DCO.  Here is an example DCO sign-off line:
-
-```
-Signed-off-by: John Doe <john.doe@hisdomain.com>
-```
-
-The full text of the DCO version 1.1 is below or at <http://developercertificate.org/>.
-
-```
-Developer's Certificate of Origin 1.1
-
-By making a contribution to this project, I certify that:
-
-(a) The contribution was created in whole or in part by me and I
-    have the right to submit it under the open source license
-    indicated in the file; or
-
-(b) The contribution is based upon previous work that, to the
-    best of my knowledge, is covered under an appropriate open
-    source license and I have the right under that license to
-    submit that work with modifications, whether created in whole
-    or in part by me, under the same open source license (unless
-    I am permitted to submit under a different license), as
-    Indicated in the file; or
-
-(c) The contribution was provided directly to me by some other
-    person who certified (a), (b) or (c) and I have not modified
-    it.
-
-(d) I understand and agree that this project and the contribution
-    are public and that a record of the contribution (including
-    all personal information I submit with it, including my
-    sign-off) is maintained indefinitely and may be redistributed
-    consistent with this project or the open source license(s)
-    involved.
-```

data/README.md

@@ -12,7 +12,7 @@
 [![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)
+* [v2.x Release](#v2x-release)
 * [Install](#install)
 * [Major Objects](#major-objects)
 * [Errors Raised By This Gem](#errors-raised-by-this-gem)
@@ -23,11 +23,8 @@
 
 ## 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.
+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:
 
@@ -37,15 +34,19 @@ Get started by obtaining a repository object by:
 
 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
+## v2.x Release
 
-git 2.0.0 is available as a pre-release version for testing! Please give it a try.
+git 2.0.0 has recently been released. Please give it a try.
+
+**If you have problems with the 2.x release, open an issue and use the 1.x version
+instead.** We will do our best to fix your issues in a timely fashion.
 
 **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.**
 
-The changes coming in this major release include:
+The changes in this major release include:
 
+* Added a dependency on the activesupport gem to use the deprecation functionality
 * 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)
@@ -55,9 +56,6 @@ The changes coming in this major release include:
   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
-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.
 
@@ -69,12 +67,24 @@ Install the gem and add to the application's Gemfile by executing:
 bundle add git
 ```
 
+to install version 1.x:
+
+```shell
+bundle add git --version "~> 1.19"
+```
+
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```shell
 gem install git
 ```
 
+to install version 1.x:
+
+```shell
+gem install git --version "~> 1.19"
+```
+
 ## Major Objects
 
 **Git::Base** - The object returned from a `Git.open` or `Git.clone`. Most major actions are called from this object.
@@ -104,76 +114,45 @@ Pass the `--all` option to `git log` as follows:
 
 ## Errors Raised By This Gem
 
-This gem raises custom errors that derive from `Git::Error`. These errors are
-arranged in the following class heirarchy:
-
-Error heirarchy:
+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.
 
-```text
-Error
-└── CommandLineError
-    ├── FailedError
-    └── SignaledError
-        └── TimeoutError
-```
-
-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:
+It is recommended to rescue `Git::Error` to catch any runtime error raised by
+this gem unless you need more specific error handling.
 
 ```ruby
 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}"
+  # some git operation
 rescue Git::Error => e
-  puts "Received the following 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 operations can be set either globally or for specific method calls
-that accept a `:timeout` parameter.
+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, a `Git::TimeoutError` is raised.
+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, 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.
+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:
 
@@ -193,19 +172,20 @@ 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:
+If the command takes too long, a `Git::TimeoutError` 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
+  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
 ```
 
@@ -244,9 +224,12 @@ 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')
+# 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')
@@ -532,9 +515,15 @@ end
 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 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/git.gemspec

@@ -27,10 +27,12 @@ Gem::Specification.new do |s|
   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 'process_executer', '~> 1.1'
   s.add_runtime_dependency 'rchardet', '~> 1.8'
 
+  s.add_development_dependency 'create_github_release', '~> 1.4'
   s.add_development_dependency 'minitar', '~> 0.9'
   s.add_development_dependency 'mocha', '~> 2.1'
   s.add_development_dependency 'rake', '~> 13.1'

data/lib/git/base.rb

@@ -1,4 +1,3 @@
-require 'git/base/factory'
 require 'logger'
 require 'open3'
 
@@ -10,8 +9,6 @@ module Git
   # {Git.clone}, or {Git.bare}.
   #
   class Base
-    include Git::Base::Factory
-
     # (see Git.bare)
     def self.bare(git_dir, options = {})
       normalize_paths(options, default_repository: git_dir, bare: true)
@@ -632,6 +629,96 @@ module Git
       self.lib.branch_current
     end
 
+    # @return [Git::Branch] an object for branch_name
+    def branch(branch_name = self.current_branch)
+      Git::Branch.new(self, branch_name)
+    end
+
+    # @return [Git::Branches] a collection of all the branches in the repository.
+    #   Each branch is represented as a {Git::Branch}.
+    def branches
+      Git::Branches.new(self)
+    end
+
+    # returns a Git::Worktree object for dir, commitish
+    def worktree(dir, commitish = nil)
+      Git::Worktree.new(self, dir, commitish)
+    end
+
+    # returns a Git::worktrees object of all the Git::Worktrees
+    # objects for this repo
+    def worktrees
+      Git::Worktrees.new(self)
+    end
+
+    # @return [Git::Object::Commit] a commit object
+    def commit_tree(tree = nil, opts = {})
+      Git::Object::Commit.new(self, self.lib.commit_tree(tree, opts))
+    end
+
+    # @return [Git::Diff] a Git::Diff object
+    def diff(objectish = 'HEAD', obj2 = nil)
+      Git::Diff.new(self, objectish, obj2)
+    end
+
+    # @return [Git::Object] a Git object
+    def gblob(objectish)
+      Git::Object.new(self, objectish, 'blob')
+    end
+
+    # @return [Git::Object] a Git object
+    def gcommit(objectish)
+      Git::Object.new(self, objectish, 'commit')
+    end
+
+    # @return [Git::Object] a Git object
+    def gtree(objectish)
+      Git::Object.new(self, objectish, 'tree')
+    end
+
+    # @return [Git::Log] a log with the specified number of commits
+    def log(count = 30)
+      Git::Log.new(self, count)
+    end
+
+    # returns a Git::Object of the appropriate type
+    # you can also call @git.gtree('tree'), but that's
+    # just for readability.  If you call @git.gtree('HEAD') it will
+    # still return a Git::Object::Commit object.
+    #
+    # object calls a method that will run a rev-parse
+    # on the objectish and determine the type of the object and return
+    # an appropriate object for that type
+    #
+    # @return [Git::Object] an instance of the appropriate type of Git::Object
+    def object(objectish)
+      Git::Object.new(self, objectish)
+    end
+
+    # @return [Git::Remote] a remote of the specified name
+    def remote(remote_name = 'origin')
+      Git::Remote.new(self, remote_name)
+    end
+
+    # @return [Git::Status] a status object
+    def status
+      Git::Status.new(self)
+    end
+
+    # @return [Git::Object::Tag] a tag object
+    def tag(tag_name)
+      Git::Object.new(self, tag_name, 'tag', true)
+    end
+
+    # Find as good common ancestors as possible for a merge
+    # example: g.merge_base('master', 'some_branch', 'some_sha', octopus: true)
+    #
+    # @return [Array<Git::Object::Commit>] a collection of common ancestors
+    def merge_base(*args)
+      shas = self.lib.merge_base(*args)
+      shas.map { |sha| gcommit(sha) }
+    end
+
     private
 
     # Normalize options before they are sent to Git::Base.new