git 1.19.1 → 2.1.1

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,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 '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 '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.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

data/lib/git/base.rb

@@ -1,17 +1,16 @@
-require 'git/base/factory'
 require 'logger'
 require 'open3'
 
 module Git
-  # Git::Base is the main public interface for interacting with Git commands.
+  # The main public interface for interacting with Git commands
   #
   # Instead of creating a Git::Base directly, obtain a Git::Base instance by
   # calling one of the follow {Git} class methods: {Git.open}, {Git.init},
   # {Git.clone}, or {Git.bare}.
   #
+  # @api public
+  #
   class Base
-    include Git::Base::Factory
-
     # (see Git.bare)
     def self.bare(git_dir, options = {})
       normalize_paths(options, default_repository: git_dir, bare: true)
@@ -122,6 +121,62 @@ module Git
       @index = options[:index] ? Git::Index.new(options[:index], false) : nil
     end
 
+    # Update the index from the current worktree to prepare the for the next commit
+    #
+    # @example
+    #   lib.add('path/to/file')
+    #   lib.add(['path/to/file1','path/to/file2'])
+    #   lib.add(all: true)
+    #
+    # @param [String, Array<String>] paths a file or files to be added to the repository (relative to the worktree root)
+    # @param [Hash] options
+    #
+    # @option options [Boolean] :all Add, modify, and remove index entries to match the worktree
+    # @option options [Boolean] :force Allow adding otherwise ignored files
+    #
+    def add(paths = '.', **options)
+      self.lib.add(paths, options)
+    end
+
+    # adds a new remote to this repository
+    # url can be a git url or a Git::Base object if it's a local reference
+    #
+    #  @git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git')
+    #  @git.fetch('scotts_git')
+    #  @git.merge('scotts_git/master')
+    #
+    # Options:
+    #   :fetch => true
+    #   :track => <branch_name>
+    def add_remote(name, url, opts = {})
+      url = url.repo.path if url.is_a?(Git::Base)
+      self.lib.remote_add(name, url, opts)
+      Git::Remote.new(self, name)
+    end
+
+    # Create a new git tag
+    #
+    # @example
+    #   repo.add_tag('tag_name', object_reference)
+    #   repo.add_tag('tag_name', object_reference, {:options => 'here'})
+    #   repo.add_tag('tag_name', {:options => 'here'})
+    #
+    # @param [String] name The name of the tag to add
+    # @param [Hash] options Opstions to pass to `git tag`.
+    #   See [git-tag](https://git-scm.com/docs/git-tag) for more details.
+    # @option options [boolean] :annotate Make an unsigned, annotated tag object
+    # @option options [boolean] :a An alias for the `:annotate` option
+    # @option options [boolean] :d Delete existing tag with the given names.
+    # @option options [boolean] :f Replace an existing tag with the given name (instead of failing)
+    # @option options [String] :message Use the given tag message
+    # @option options [String] :m An alias for the `:message` option
+    # @option options [boolean] :s Make a GPG-signed tag.
+    #
+    def add_tag(name, *options)
+      self.lib.tag(name, *options)
+      self.tag(name)
+    end
+
     # changes current working directory for a block
     # to the git working directory
     #
@@ -254,27 +309,11 @@ module Git
       self.object('HEAD').grep(string, path_limiter, opts)
     end
 
-    # updates the repository index using the working directory content
-    #
-    # @example
-    #   git.add
-    #   git.add('path/to/file')
-    #   git.add(['path/to/file1','path/to/file2'])
-    #   git.add(:all => true)
+    # List the files in the worktree that are ignored by git
+    # @return [Array<String>] the list of ignored files relative to teh root of the worktree
     #
-    # options:
-    #   :all => true
-    #
-    # @param [String,Array] paths files paths to be added (optional, default='.')
-    # @param [Hash] options
-    # @option options [boolean] :all
-    #   Update the index not only where the working tree has a file matching
-    #   <pathspec> but also where the index already has an entry.
-    #   See [the --all option to git-add](https://git-scm.com/docs/git-add#Documentation/git-add.txt--A)
-    #   for more details.
-    #
-    def add(paths = '.', **options)
-      self.lib.add(paths, options)
+    def ignored_files
+      self.lib.ignored_files
     end
 
     # removes file(s) from the git repository
@@ -409,14 +448,27 @@ module Git
       self.lib.conflicts(&block)
     end
 
-    # pulls the given branch from the given remote into the current branch
+    # Pulls the given branch from the given remote into the current branch
+    #
+    # @param remote [String] the remote repository to pull from
+    # @param branch [String] the branch to pull from
+    # @param opts [Hash] options to pass to the pull command
     #
-    #  @git.pull                          # pulls from origin/master
-    #  @git.pull('upstream')              # pulls from upstream/master
-    #  @git.pull('upstream', 'develope')  # pulls from upstream/develop
+    # @option opts [Boolean] :allow_unrelated_histories (false) Merges histories of two projects that started their
+    #   lives independently
+    # @example pulls from origin/master
+    #   @git.pull
+    # @example pulls from upstream/master
+    #   @git.pull('upstream')
+    # @example pulls from upstream/develop
+    #   @git.pull('upstream', 'develop')
     #
-    def pull(remote = nil, branch = nil)
-      self.lib.pull(remote, branch)
+    # @return [Void]
+    #
+    # @raise [Git::FailedError] if the pull fails
+    # @raise [ArgumentError] if a branch is given without a remote
+    def pull(remote = nil, branch = nil, opts = {})
+      self.lib.pull(remote, branch, opts)
     end
 
     # returns an array of Git:Remote objects
@@ -424,22 +476,6 @@ module Git
       self.lib.remotes.map { |r| Git::Remote.new(self, r) }
     end
 
-    # adds a new remote to this repository
-    # url can be a git url or a Git::Base object if it's a local reference
-    #
-    #  @git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git')
-    #  @git.fetch('scotts_git')
-    #  @git.merge('scotts_git/master')
-    #
-    # Options:
-    #   :fetch => true
-    #   :track => <branch_name>
-    def add_remote(name, url, opts = {})
-      url = url.repo.path if url.is_a?(Git::Base)
-      self.lib.remote_add(name, url, opts)
-      Git::Remote.new(self, name)
-    end
-
     # sets the url for a remote
     # url can be a git url or a Git::Base object if it's a local reference
     #
@@ -463,7 +499,7 @@ module Git
       self.lib.tags.map { |r| tag(r) }
     end
 
-    # Creates a new git tag (Git::Tag)
+    # Create a new git tag
     #
     # @example
     #   repo.add_tag('tag_name', object_reference)
@@ -619,6 +655,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