From 737c4bb16074f60a8887d8ce73f01993a6ffce95 Mon Sep 17 00:00:00 2001
From: Bill Franklin <b.franklin@outlook.com>
Date: Mon, 12 Aug 2024 11:06:29 +0100
Subject: [PATCH 01/10] ls-tree optional recursion into subtrees

---
 README.md                   |  3 +++
 lib/git/base.rb             |  4 ++--
 lib/git/lib.rb              |  9 +++++++--
 tests/units/test_ls_tree.rb | 15 +++++++++++++++
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 841bcfcd..cfed3aec 100644
--- a/README.md
+++ b/README.md
@@ -236,6 +236,9 @@ g.index.writable?
 g.repo
 g.dir
 
+# 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
diff --git a/lib/git/base.rb b/lib/git/base.rb
index 4a04a7ec..27de57de 100644
--- a/lib/git/base.rb
+++ b/lib/git/base.rb
@@ -642,8 +642,8 @@ def revparse(objectish)
       self.lib.revparse(objectish)
     end
 
-    def ls_tree(objectish)
-      self.lib.ls_tree(objectish)
+    def ls_tree(objectish, opts = {})
+      self.lib.ls_tree(objectish, opts)
     end
 
     def cat_file(objectish)
diff --git a/lib/git/lib.rb b/lib/git/lib.rb
index 1eefc70e..8f4e89bb 100644
--- a/lib/git/lib.rb
+++ b/lib/git/lib.rb
@@ -374,10 +374,15 @@ def object_contents(sha, &block)
       end
     end
 
-    def ls_tree(sha)
+    def ls_tree(sha, opts = {})
       data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
 
-      command_lines('ls-tree', sha).each do |line|
+      ls_tree_opts = []
+      ls_tree_opts << '-r' if opts[:recursive]
+      # path must be last arg
+      ls_tree_opts << opts[:path] if opts[:path]
+
+      command_lines('ls-tree', sha, *ls_tree_opts).each do |line|
         (info, filenm) = line.split("\t")
         (mode, type, sha) = info.split
         data[type][filenm] = {:mode => mode, :sha => sha}
diff --git a/tests/units/test_ls_tree.rb b/tests/units/test_ls_tree.rb
index 222af233..19d487a4 100644
--- a/tests/units/test_ls_tree.rb
+++ b/tests/units/test_ls_tree.rb
@@ -13,11 +13,26 @@ def test_ls_tree_with_submodules
       repo.add('README.md')
       repo.commit('Add README.md')
 
+      Dir.mkdir("repo/subdir")
+      File.write('repo/subdir/file.md', 'Content in subdir')
+      repo.add('subdir/file.md')
+      repo.commit('Add subdir/file.md')
+
+      # ls_tree
+      default_tree = assert_nothing_raised { repo.ls_tree('HEAD') }
+      assert_equal(default_tree.dig("blob").keys.sort, ["README.md"])
+      assert_equal(default_tree.dig("tree").keys.sort, ["subdir"])
+      # ls_tree with recursion into sub-trees
+      recursive_tree = assert_nothing_raised { repo.ls_tree('HEAD', recursive: true) }
+      assert_equal(recursive_tree.dig("blob").keys.sort, ["README.md", "subdir/file.md"])
+      assert_equal(recursive_tree.dig("tree").keys.sort, [])
+
       Dir.chdir('repo') do
         assert_child_process_success { `git -c protocol.file.allow=always submodule add ../submodule submodule 2>&1` }
         assert_child_process_success { `git commit -am "Add submodule" 2>&1` }
       end
 
+
       expected_submodule_sha = submodule.object('HEAD').sha
 
       # Make sure the ls_tree command can handle submodules (which show up as a commit object in the tree)

From a08f89b7de5edfbbb73dd37a20891852577ae043 Mon Sep 17 00:00:00 2001
From: Bill Franklin <b.franklin@outlook.com>
Date: Mon, 12 Aug 2024 11:27:42 +0100
Subject: [PATCH 02/10] Update README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cfed3aec..3152688a 100644
--- a/README.md
+++ b/README.md
@@ -237,7 +237,7 @@ g.repo
 g.dir
 
 # ls-tree with recursion into subtrees (list files)
-g.ls_tree("head", recursive: true)
+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

From 00c4939d0f622e8e5cc234b07ddcb6ae00fd5de1 Mon Sep 17 00:00:00 2001
From: James Couball <jcouball@yahoo.com>
Date: Fri, 23 Aug 2024 16:44:35 -0700
Subject: [PATCH 03/10] Verify that the commit(s) passed to git diff do not
 resemble a command-line option

---
 lib/git/lib.rb           | 21 +++++++++++++++++++++
 tests/units/test_diff.rb | 20 ++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/lib/git/lib.rb b/lib/git/lib.rb
index 8f4e89bb..e7bcb3e2 100644
--- a/lib/git/lib.rb
+++ b/lib/git/lib.rb
@@ -526,7 +526,24 @@ def grep(string, opts = {})
       hsh
     end
 
+    # Validate that the given arguments cannot be mistaken for a command-line option
+    #
+    # @param arg_name [String] the name of the arguments to mention in the error message
+    # @param args [Array<String, nil>] the arguments to validate
+    #
+    # @raise [ArgumentError] if any of the parameters are a string starting with a hyphen
+    # @return [void]
+    #
+    def validate_no_options(arg_name, *args)
+      invalid_args = args.select { |arg| arg&.start_with?('-') }
+      if invalid_args.any?
+        raise ArgumentError, "Invalid #{arg_name}: '#{invalid_args.join("', '")}'"
+      end
+    end
+
     def diff_full(obj1 = 'HEAD', obj2 = nil, opts = {})
+      validate_no_options('commit or commit range', obj1, obj2)
+
       diff_opts = ['-p']
       diff_opts << obj1
       diff_opts << obj2 if obj2.is_a?(String)
@@ -536,6 +553,8 @@ def diff_full(obj1 = 'HEAD', obj2 = nil, opts = {})
     end
 
     def diff_stats(obj1 = 'HEAD', obj2 = nil, opts = {})
+      validate_no_options('commit or commit range', obj1, obj2)
+
       diff_opts = ['--numstat']
       diff_opts << obj1
       diff_opts << obj2 if obj2.is_a?(String)
@@ -556,6 +575,8 @@ def diff_stats(obj1 = 'HEAD', obj2 = nil, opts = {})
     end
 
     def diff_name_status(reference1 = nil, reference2 = nil, opts = {})
+      validate_no_options('commit or commit range', reference1, reference2)
+
       opts_arr = ['--name-status']
       opts_arr << reference1 if reference1
       opts_arr << reference2 if reference2
diff --git a/tests/units/test_diff.rb b/tests/units/test_diff.rb
index d640146d..89a476a9 100644
--- a/tests/units/test_diff.rb
+++ b/tests/units/test_diff.rb
@@ -118,5 +118,25 @@ def test_diff_each
     assert_equal(160, files['scott/newfile'].patch.size)
   end
 
+  def test_diff_patch_with_bad_commit
+    assert_raise(ArgumentError) do
+      @git.diff('-s').patch
+    end
 
+    assert_raise(ArgumentError) do
+      @git.diff('gitsearch1', '-s').patch
+    end
+  end
+
+  def test_diff_name_status_with_bad_commit
+    assert_raise(ArgumentError) do
+      @git.diff('-s').name_status
+    end
+  end
+
+  def test_diff_stats_with_bad_commit
+    assert_raise(ArgumentError) do
+      @git.diff('-s').stats
+    end
+  end
 end

From dc46edea6384907fd948b5274dbebd08bd5e7acb Mon Sep 17 00:00:00 2001
From: James Couball <jcouball@yahoo.com>
Date: Sat, 24 Aug 2024 15:22:27 -0700
Subject: [PATCH 04/10] Verify that the commit-ish passed to git describe does
 not resemble a command-line option

---
 lib/git/lib.rb               | 54 ++++++++++++++++++++----------------
 tests/units/test_describe.rb |  5 ++++
 2 files changed, 35 insertions(+), 24 deletions(-)

diff --git a/lib/git/lib.rb b/lib/git/lib.rb
index e7bcb3e2..059d259e 100644
--- a/lib/git/lib.rb
+++ b/lib/git/lib.rb
@@ -169,27 +169,33 @@ def repository_default_branch(repository)
 
     ## READ COMMANDS ##
 
+    # Finds most recent tag that is reachable from a commit
     #
-    # Returns most recent tag that is reachable from a commit
+    # @see https://git-scm.com/docs/git-describe git-describe
     #
-    # accepts options:
-    #  :all
-    #  :tags
-    #  :contains
-    #  :debug
-    #  :exact_match
-    #  :dirty
-    #  :abbrev
-    #  :candidates
-    #  :long
-    #  :always
-    #  :math
-    #
-    #  @param [String|NilClass] committish target commit sha or object name
-    #  @param [{Symbol=>Object}] opts the given options
-    #  @return [String] the tag name
-    #
-    def describe(committish=nil, opts={})
+    # @param commit_ish [String, nil] target commit sha or object name
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :all [Boolean]
+    # @option opts :tags [Boolean]
+    # @option opts :contains [Boolean]
+    # @option opts :debug [Boolean]
+    # @option opts :long [Boolean]
+    # @option opts :always [Boolean]
+    # @option opts :exact_match [Boolean]
+    # @option opts :dirty [true, String]
+    # @option opts :abbrev [String]
+    # @option opts :candidates [String]
+    # @option opts :match [String]
+    #
+    # @return [String] the tag name
+    #
+    # @raise [ArgumentError] if the commit_ish is a string starting with a hyphen
+    # 
+    def describe(commit_ish = nil, opts = {})
+      assert_args_are_not_options('commit-ish object', commit_ish)
+
       arr_opts = []
 
       arr_opts << '--all' if opts[:all]
@@ -207,7 +213,7 @@ def describe(committish=nil, opts={})
       arr_opts << "--candidates=#{opts[:candidates]}" if opts[:candidates]
       arr_opts << "--match=#{opts[:match]}" if opts[:match]
 
-      arr_opts << committish if committish
+      arr_opts << commit_ish if commit_ish
 
       return command('describe', *arr_opts)
     end
@@ -534,7 +540,7 @@ def grep(string, opts = {})
     # @raise [ArgumentError] if any of the parameters are a string starting with a hyphen
     # @return [void]
     #
-    def validate_no_options(arg_name, *args)
+    def assert_args_are_not_options(arg_name, *args)
       invalid_args = args.select { |arg| arg&.start_with?('-') }
       if invalid_args.any?
         raise ArgumentError, "Invalid #{arg_name}: '#{invalid_args.join("', '")}'"
@@ -542,7 +548,7 @@ def validate_no_options(arg_name, *args)
     end
 
     def diff_full(obj1 = 'HEAD', obj2 = nil, opts = {})
-      validate_no_options('commit or commit range', obj1, obj2)
+      assert_args_are_not_options('commit or commit range', obj1, obj2)
 
       diff_opts = ['-p']
       diff_opts << obj1
@@ -553,7 +559,7 @@ def diff_full(obj1 = 'HEAD', obj2 = nil, opts = {})
     end
 
     def diff_stats(obj1 = 'HEAD', obj2 = nil, opts = {})
-      validate_no_options('commit or commit range', obj1, obj2)
+      assert_args_are_not_options('commit or commit range', obj1, obj2)
 
       diff_opts = ['--numstat']
       diff_opts << obj1
@@ -575,7 +581,7 @@ def diff_stats(obj1 = 'HEAD', obj2 = nil, opts = {})
     end
 
     def diff_name_status(reference1 = nil, reference2 = nil, opts = {})
-      validate_no_options('commit or commit range', reference1, reference2)
+      assert_args_are_not_options('commit or commit range', reference1, reference2)
 
       opts_arr = ['--name-status']
       opts_arr << reference1 if reference1
diff --git a/tests/units/test_describe.rb b/tests/units/test_describe.rb
index 2d0e2012..967fc753 100644
--- a/tests/units/test_describe.rb
+++ b/tests/units/test_describe.rb
@@ -13,4 +13,9 @@ def test_describe
     assert_equal(@git.describe(nil, {:tags => true}), 'grep_colon_numbers')
   end
 
+  def test_describe_with_invalid_commitish
+    assert_raise ArgumentError do
+      @git.describe('--all')
+    end
+  end
 end

From 9b9b31e704c0b85ffdd8d2af2ded85170a5af87d Mon Sep 17 00:00:00 2001
From: James Couball <jcouball@yahoo.com>
Date: Sat, 24 Aug 2024 17:08:56 -0700
Subject: [PATCH 05/10] Verify that the revision-range passed to git log does
 not resemble a command-line option

---
 lib/git/lib.rb          | 76 +++++++++++++++++++++++++++++++++++++++--
 tests/units/test_lib.rb | 28 +++++++++++++++
 2 files changed, 101 insertions(+), 3 deletions(-)

diff --git a/lib/git/lib.rb b/lib/git/lib.rb
index 059d259e..84eda5a1 100644
--- a/lib/git/lib.rb
+++ b/lib/git/lib.rb
@@ -192,7 +192,7 @@ def repository_default_branch(repository)
     # @return [String] the tag name
     #
     # @raise [ArgumentError] if the commit_ish is a string starting with a hyphen
-    # 
+    #
     def describe(commit_ish = nil, opts = {})
       assert_args_are_not_options('commit-ish object', commit_ish)
 
@@ -218,7 +218,37 @@ def describe(commit_ish = nil, opts = {})
       return command('describe', *arr_opts)
     end
 
-    def log_commits(opts={})
+    # Return the commits that are within the given revision range
+    #
+    # @see https://git-scm.com/docs/git-log git-log
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :count [Integer] the maximum number of commits to return (maps to max-count)
+    # @option opts :all [Boolean]
+    # @option opts :cherry [Boolean]
+    # @option opts :since [String]
+    # @option opts :until [String]
+    # @option opts :grep [String]
+    # @option opts :author [String]
+    # @option opts :between [Array<String>] an array of two commit-ish strings to specify a revision range
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :object [String] the revision range for the git log command
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :path_limiter [Array<String>, String] only include commits that impact files from the specified paths
+    #
+    # @return [Array<String>] the log output
+    #
+    # @raise [ArgumentError] if the resulting revision range is a string starting with a hyphen
+    #
+    def log_commits(opts = {})
+      assert_args_are_not_options('between', opts[:between]&.first)
+      assert_args_are_not_options('object', opts[:object])
+
       arr_opts = log_common_options(opts)
 
       arr_opts << '--pretty=oneline'
@@ -228,7 +258,47 @@ def log_commits(opts={})
       command_lines('log', *arr_opts).map { |l| l.split.first }
     end
 
-    def full_log_commits(opts={})
+    # Return the commits that are within the given revision range
+    #
+    # @see https://git-scm.com/docs/git-log git-log
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :count [Integer] the maximum number of commits to return (maps to max-count)
+    # @option opts :all [Boolean]
+    # @option opts :cherry [Boolean]
+    # @option opts :since [String]
+    # @option opts :until [String]
+    # @option opts :grep [String]
+    # @option opts :author [String]
+    # @option opts :between [Array<String>] an array of two commit-ish strings to specify a revision range
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :object [String] the revision range for the git log command
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :path_limiter [Array<String>, String] only include commits that impact files from the specified paths
+    # @option opts :skip [Integer]
+    #
+    # @return [Array<Hash>] the log output parsed into an array of hashs for each commit
+    #
+    #   Each hash contains the following keys:
+    #   * 'sha' [String] the commit sha
+    #   * 'author' [String] the author of the commit
+    #   * 'message' [String] the commit message
+    #   * 'parent' [Array<String>] the commit shas of the parent commits
+    #   * 'tree' [String] the tree sha
+    #   * 'author' [String] the author of the commit and timestamp of when the changes were created
+    #   * 'committer' [String] the committer of the commit and timestamp of when the commit was applied
+    #
+    # @raise [ArgumentError] if the revision range (specified with :between or :object) is a string starting with a hyphen
+    #
+    def full_log_commits(opts = {})
+      assert_args_are_not_options('between', opts[:between]&.first)
+      assert_args_are_not_options('object', opts[:object])
+
       arr_opts = log_common_options(opts)
 
       arr_opts << '--pretty=raw'
diff --git a/tests/units/test_lib.rb b/tests/units/test_lib.rb
index a2bb067e..be049c7b 100644
--- a/tests/units/test_lib.rb
+++ b/tests/units/test_lib.rb
@@ -123,6 +123,34 @@ def test_log_commits
     assert_equal(20, a.size)
   end
 
+  def test_log_commits_invalid_between
+    # between can not start with a hyphen
+    assert_raise ArgumentError do
+      @lib.log_commits :count => 20, :between => ['-v2.5', 'v2.6']
+    end
+  end
+
+  def test_log_commits_invalid_object
+    # :object can not start with a hyphen
+    assert_raise ArgumentError do
+      @lib.log_commits :count => 20, :object => '--all'
+    end
+  end
+
+  def test_full_log_commits_invalid_between
+    # between can not start with a hyphen
+    assert_raise ArgumentError do
+      @lib.full_log_commits :count => 20, :between => ['-v2.5', 'v2.6']
+    end
+  end
+
+  def test_full_log_commits_invalid_object
+    # :object can not start with a hyphen
+    assert_raise ArgumentError do
+      @lib.full_log_commits :count => 20, :object => '--all'
+    end
+  end
+
   def test_git_ssh_from_environment_is_passed_to_binary
     saved_binary_path = Git::Base.config.binary_path
     saved_git_ssh = Git::Base.config.git_ssh

From 02964423a6ee0f573ae9facf48836b4bcd0075c4 Mon Sep 17 00:00:00 2001
From: James Couball <jcouball@yahoo.com>
Date: Sun, 25 Aug 2024 10:12:45 -0700
Subject: [PATCH 06/10] Refactor Git::Lib#rev_parse

---
 README.md                  |  2 +-
 lib/git/base.rb            | 13 ++++++++-----
 lib/git/lib.rb             | 33 ++++++++++++++++++++++++---------
 lib/git/object.rb          |  2 +-
 tests/units/test_branch.rb |  4 ++--
 tests/units/test_lib.rb    | 26 ++++++++++++++++++++++----
 tests/units/test_object.rb |  4 ++--
 7 files changed, 60 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 3152688a..c3f788ca 100644
--- a/README.md
+++ b/README.md
@@ -277,7 +277,7 @@ 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
diff --git a/lib/git/base.rb b/lib/git/base.rb
index 27de57de..ae909dcc 100644
--- a/lib/git/base.rb
+++ b/lib/git/base.rb
@@ -634,14 +634,17 @@ def with_temp_working &blk
     # runs git rev-parse to convert the objectish to a full sha
     #
     # @example
-    #   git.revparse("HEAD^^")
-    #   git.revparse('v2.4^{tree}')
-    #   git.revparse('v2.4:/doc/index.html')
+    #   git.rev_parse("HEAD^^")
+    #   git.rev_parse('v2.4^{tree}')
+    #   git.rev_parse('v2.4:/doc/index.html')
     #
-    def revparse(objectish)
-      self.lib.revparse(objectish)
+    def rev_parse(objectish)
+      self.lib.rev_parse(objectish)
     end
 
+    # For backwards compatibility
+    alias revparse rev_parse
+
     def ls_tree(objectish, opts = {})
       self.lib.ls_tree(objectish, opts)
     end
diff --git a/lib/git/lib.rb b/lib/git/lib.rb
index 84eda5a1..4f607e4f 100644
--- a/lib/git/lib.rb
+++ b/lib/git/lib.rb
@@ -311,17 +311,32 @@ def full_log_commits(opts = {})
       process_commit_log_data(full_log)
     end
 
-    def revparse(string)
-      return string if string =~ /^[A-Fa-f0-9]{40}$/  # passing in a sha - just no-op it
-      rev = ['head', 'remotes', 'tags'].map do |d|
-        File.join(@git_dir, 'refs', d, string)
-      end.find do |path|
-        File.file?(path)
-      end
-      return File.read(rev).chomp if rev
-      command('rev-parse', string)
+    # Verify and resolve a Git revision to its full SHA
+    #
+    # @see https://git-scm.com/docs/git-rev-parse git-rev-parse
+    # @see https://git-scm.com/docs/git-rev-parse#_specifying_revisions Valid ways to specify revisions
+    # @see https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem Ref disambiguation rules
+    #
+    # @example
+    #   lib.rev_parse('HEAD') # => '9b9b31e704c0b85ffdd8d2af2ded85170a5af87d'
+    #   lib.rev_parse('9b9b31e') # => '9b9b31e704c0b85ffdd8d2af2ded85170a5af87d'
+    #
+    # @param revision [String] the revision to resolve
+    #
+    # @return [String] the full commit hash
+    #
+    # @raise [Git::FailedError] if the revision cannot be resolved
+    # @raise [ArgumentError] if the revision is a string starting with a hyphen
+    #
+    def rev_parse(revision)
+      assert_args_are_not_options('rev', revision)
+
+      command('rev-parse', revision)
     end
 
+    # For backwards compatibility with the old method name
+    alias :revparse :rev_parse
+
     def namerev(string)
       command('name-rev', string).split[1]
     end
diff --git a/lib/git/object.rb b/lib/git/object.rb
index 1ffc1013..083640b6 100644
--- a/lib/git/object.rb
+++ b/lib/git/object.rb
@@ -23,7 +23,7 @@ def initialize(base, objectish)
       end
 
       def sha
-        @sha ||= @base.lib.revparse(@objectish)
+        @sha ||= @base.lib.rev_parse(@objectish)
       end
 
       def size
diff --git a/tests/units/test_branch.rb b/tests/units/test_branch.rb
index 08707b63..2256f4cb 100644
--- a/tests/units/test_branch.rb
+++ b/tests/units/test_branch.rb
@@ -160,11 +160,11 @@ def test_branch_update_ref
       File.write('foo','rev 2')
       git.add('foo')
       git.commit('rev 2')
-      git.branch('testing').update_ref(git.revparse('HEAD'))
+      git.branch('testing').update_ref(git.rev_parse('HEAD'))
 
       # Expect the call to Branch#update_ref to pass the full ref name for the
       # of the testing branch to Lib#update_ref
-      assert_equal(git.revparse('HEAD'), git.revparse('refs/heads/testing'))
+      assert_equal(git.rev_parse('HEAD'), git.rev_parse('refs/heads/testing'))
     end
   end
 end
diff --git a/tests/units/test_lib.rb b/tests/units/test_lib.rb
index be049c7b..c8e035ad 100644
--- a/tests/units/test_lib.rb
+++ b/tests/units/test_lib.rb
@@ -174,10 +174,28 @@ def test_git_ssh_from_environment_is_passed_to_binary
     Git::Base.config.git_ssh = saved_git_ssh
   end
 
-  def test_revparse
-    assert_equal('1cc8667014381e2788a94777532a788307f38d26', @lib.revparse('1cc8667014381')) # commit
-    assert_equal('94c827875e2cadb8bc8d4cdd900f19aa9e8634c7', @lib.revparse('1cc8667014381^{tree}')) #tree
-    assert_equal('ba492c62b6227d7f3507b4dcc6e6d5f13790eabf', @lib.revparse('v2.5:example.txt')) #blob
+  def test_rev_parse_commit
+    assert_equal('1cc8667014381e2788a94777532a788307f38d26', @lib.rev_parse('1cc8667014381')) # commit
+  end
+
+  def test_rev_parse_tree
+    assert_equal('94c827875e2cadb8bc8d4cdd900f19aa9e8634c7', @lib.rev_parse('1cc8667014381^{tree}')) #tree
+  end
+
+  def test_rev_parse_blob
+    assert_equal('ba492c62b6227d7f3507b4dcc6e6d5f13790eabf', @lib.rev_parse('v2.5:example.txt')) #blob
+  end
+
+  def test_rev_parse_with_bad_revision
+    assert_raise(ArgumentError) do
+      @lib.rev_parse('--all')
+    end
+  end
+
+  def test_rev_parse_with_unknown_revision
+    assert_raise(Git::FailedError) do
+      @lib.rev_parse('NOTFOUND')
+    end
   end
 
   def test_object_type
diff --git a/tests/units/test_object.rb b/tests/units/test_object.rb
index 784e81bf..3f31b390 100644
--- a/tests/units/test_object.rb
+++ b/tests/units/test_object.rb
@@ -120,8 +120,8 @@ def test_blob_contents
     assert(block_called)
   end
 
-  def test_revparse
-    sha = @git.revparse('v2.6:example.txt')
+  def test_rev_parse
+    sha = @git.rev_parse('v2.6:example.txt')
     assert_equal('1f09f2edb9c0d9275d15960771b363ca6940fbe3', sha)
   end
 

From d4f66ab3beff28f65c3fe60f9f77f646c483ba89 Mon Sep 17 00:00:00 2001
From: James Couball <jcouball@yahoo.com>
Date: Sun, 25 Aug 2024 11:12:16 -0700
Subject: [PATCH 07/10] Sanitize non-option arguments passed to `git name-rev`

---
 lib/git/lib.rb          | 16 ++++++++++++++--
 lib/git/object.rb       |  2 +-
 tests/units/test_lib.rb | 10 ++++++++++
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/lib/git/lib.rb b/lib/git/lib.rb
index 4f607e4f..1742130e 100644
--- a/lib/git/lib.rb
+++ b/lib/git/lib.rb
@@ -337,10 +337,22 @@ def rev_parse(revision)
     # For backwards compatibility with the old method name
     alias :revparse :rev_parse
 
-    def namerev(string)
-      command('name-rev', string).split[1]
+    # Find the first symbolic name for given commit_ish
+    #
+    # @param commit_ish [String] the commit_ish to find the symbolic name of
+    #
+    # @return [String, nil] the first symbolic name or nil if the commit_ish isn't found
+    #
+    # @raise [ArgumentError] if the commit_ish is a string starting with a hyphen
+    #
+    def name_rev(commit_ish)
+      assert_args_are_not_options('commit_ish', commit_ish)
+
+      command('name-rev', commit_ish).split[1]
     end
 
+    alias :namerev :name_rev
+
     def object_type(sha)
       command('cat-file', '-t', sha)
     end
diff --git a/lib/git/object.rb b/lib/git/object.rb
index 083640b6..6c4aada9 100644
--- a/lib/git/object.rb
+++ b/lib/git/object.rb
@@ -175,7 +175,7 @@ def message
       end
 
       def name
-        @base.lib.namerev(sha)
+        @base.lib.name_rev(sha)
       end
 
       def gtree
diff --git a/tests/units/test_lib.rb b/tests/units/test_lib.rb
index c8e035ad..38694980 100644
--- a/tests/units/test_lib.rb
+++ b/tests/units/test_lib.rb
@@ -198,6 +198,16 @@ def test_rev_parse_with_unknown_revision
     end
   end
 
+  def test_name_rev
+    assert_equal('tags/v2.5~5', @lib.name_rev('00ea60e'))
+  end
+
+  def test_name_rev_with_invalid_commit_ish
+    assert_raise(ArgumentError) do
+      @lib.name_rev('-1cc8667014381')
+    end
+  end
+
   def test_object_type
     assert_equal('commit', @lib.object_type('1cc8667014381')) # commit
     assert_equal('tree', @lib.object_type('1cc8667014381^{tree}')) #tree

From 2d6157c95332b8e3907094d1229713720ff5029d Mon Sep 17 00:00:00 2001
From: James Couball <jcouball@yahoo.com>
Date: Sun, 25 Aug 2024 15:53:51 -0700
Subject: [PATCH 08/10] Document this gem's (aspirational) design philosophy

---
 CONTRIBUTING.md | 195 +++++++++++++++++++++++++++++++++---------------
 1 file changed, 135 insertions(+), 60 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 636f9c4b..082a8853 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,116 +3,191 @@
 # @title How To Contribute
 -->
 
-# Contributing to ruby-git
-
-Thank you for your interest in contributing to the ruby-git project.
-
-This document gives the guidelines for contributing to the ruby-git project.
-These guidelines may not fit every situation.  When contributing use your best
-judgement.
-
-Propose changes to these guidelines with a pull request.
+* [How to contribute](#how-to-contribute)
+* [How to report an issue or request a feature](#how-to-report-an-issue-or-request-a-feature)
+* [How to submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
+  * [Commit your changes to a fork of `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git)
+  * [Create a pull request](#create-a-pull-request)
+  * [Get your pull request reviewed](#get-your-pull-request-reviewed)
+* [Design philosophy](#design-philosophy)
+  * [Direct mapping to git commands](#direct-mapping-to-git-commands)
+  * [Parameter naming](#parameter-naming)
+  * [Output processing](#output-processing)
+* [Coding standards](#coding-standards)
+  * [1 PR = 1 Commit](#1-pr--1-commit)
+  * [Unit tests](#unit-tests)
+  * [Continuous integration](#continuous-integration)
+  * [Documentation](#documentation)
+* [Licensing](#licensing)
+
+
+# Contributing to the git gem
+
+Thank you for your interest in contributing to the `ruby-git` project.
+
+This document provides guidelines for contributing to the `ruby-git` project. While
+these guidelines may not cover every situation, we encourage you to use your best
+judgment when contributing.
+
+If you have suggestions for improving these guidelines, please propose changes via a
+pull request.
 
 ## How to contribute
 
-You can contribute in two ways:
+You can contribute in the following ways:
 
-1. [Report an issue or make a feature request](#how-to-report-an-issue-or-make-a-feature-request)
-2. [Submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
+1. [Report an issue or request a
+   feature](#how-to-report-an-issue-or-request-a-feature)
+2. [Submit a code or documentation
+   change](#how-to-submit-a-code-or-documentation-change)
 
-## How to report an issue or make a feature request
+## How to report an issue or request a feature
 
-ruby-git utilizes [GitHub Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues)
+`ruby-git` utilizes [GitHub
+Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues)
 for issue tracking and feature requests.
 
-Report an issue or feature request by [creating a ruby-git Github issue](https://github.com/ruby-git/ruby-git/issues/new).
-Fill in the template to describe the issue or feature request the best you can.
+To report an issue or request a feature, please [create a `ruby-git` GitHub
+issue](https://github.com/ruby-git/ruby-git/issues/new). Fill in the template as
+thoroughly as possible to describe the issue or feature request.
 
 ## How to submit a code or documentation change
 
-There is three step process for code or documentation changes:
+There is a three-step process for submitting code or documentation changes:
 
-1. [Commit your changes to a fork of ruby-git](#commit-changes-to-a-fork-of-ruby-git)
+1. [Commit your changes to a fork of
+   `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git)
 2. [Create a pull request](#create-a-pull-request)
 3. [Get your pull request reviewed](#get-your-pull-request-reviewed)
 
-### Commit changes to a fork of ruby-git
+### Commit your changes to a fork of `ruby-git`
 
-Make your changes in a fork of the ruby-git repository.
+Make your changes in a fork of the `ruby-git` repository.
 
 ### Create a pull request
 
-See [this article](https://help.github.com/articles/about-pull-requests/) if you
-are not familiar with GitHub Pull Requests.
+If you are not familiar with GitHub Pull Requests, please refer to [this
+article](https://help.github.com/articles/about-pull-requests/).
 
 Follow the instructions in the pull request template.
 
 ### Get your pull request reviewed
 
-Code review takes place in a GitHub pull request using the [the Github pull request review feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews).
+Code review takes place in a GitHub pull request using the [GitHub pull request
+review
+feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews).
 
 Once your pull request is ready for review, request a review from at least one
-[maintainer](MAINTAINERS.md) and any number of other contributors.
+[maintainer](MAINTAINERS.md) and any other contributors you deem necessary.
+
+During the review process, you may need to make additional commits, which should be
+squashed. Additionally, you may need to rebase your branch to the latest `master`
+branch if other changes have been merged.
+
+At least one approval from a project maintainer is required before your pull request
+can be merged. The maintainer is responsible for ensuring that the pull request meets
+[the project's coding standards](#coding-standards).
+
+## Design philosophy
+
+*Note: As of v2.x of the `git` gem, this design philosophy is aspirational. Future
+versions may include interface changes to fully align with these principles.*
+
+The `git` gem is designed as a lightweight wrapper around the `git` command-line
+tool, providing Ruby developers with a simple and intuitive interface for
+programmatically interacting with Git.
+
+This gem adheres to the "principle of least surprise," ensuring that it does not
+introduce unnecessary abstraction layers or modify Git's core functionality. Instead,
+the gem maintains a close alignment with the existing `git` command-line interface,
+avoiding extensions or alterations that could lead to unexpected behaviors.
+
+By following this philosophy, the `git` gem allows users to leverage their existing
+knowledge of Git while benefiting from the expressiveness and power of Ruby's syntax
+and paradigms.
+
+### Direct mapping to git commands
 
-During the review process, you may need to make additional commits which would
-need to be squashed.  It may also be necessary to rebase to master again if other
-changes are merged before your PR.
+Git commands are implemented within the `Git::Base` class, with each method directly
+corresponding to a `git` command. When a `Git::Base` object is instantiated via
+`Git.open`, `Git.clone`, or `Git.init`, the user can invoke these methods to interact
+with the underlying Git repository.
 
-At least one approval is required from a project maintainer before your pull
-request can be merged.  The maintainer is responsible for ensuring that the pull
-request meets [the project's coding standards](#coding-standards).
+For example, the `git add` command is implemented as `Git::Base#add`, and the `git
+ls-files` command is implemented as `Git::Base#ls_files`.
+
+When a single Git command serves multiple distinct purposes, method names within the
+`Git::Base` class should use the `git` command name as a prefix, followed by a
+descriptive suffix to indicate the specific function.
+
+For instance, `#ls_files_untracked` and `#ls_files_staged` could be used to execute
+the `git ls-files` command and return untracked and staged files, respectively.
+
+To enhance usability, aliases may be introduced to provide more user-friendly method
+names where appropriate.
+
+### Parameter naming
+
+Parameters within the `git` gem methods are named after their corresponding long
+command-line options, ensuring familiarity and ease of use for developers already
+accustomed to Git. Note that not all Git command options are supported.
+
+### Output processing
+
+The `git` gem translates the output of many Git commands into Ruby objects, making it
+easier to work with programmatically.
+
+These Ruby objects often include methods that allow for further Git operations where
+useful, providing additional functionality while staying true to the underlying Git
+behavior.
 
 ## Coding standards
 
-In order to ensure high quality, all pull requests must meet these requirements:
+To ensure high-quality contributions, all pull requests must meet the following
+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 a single 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
+* 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`:
+While working on specific features, you can run individual test files or a group of
+tests using `bin/test`:
 
-    # run a single file (from tests/units):
-    $ bin/test test_object
+```bash
+# run a single file (from tests/units):
+$ bin/test test_object
 
-    # run multiple files:
-    $ bin/test test_object test_archive
+# run multiple files:
+$ bin/test test_object test_archive
 
-    # run all unit tests:
-    $ bin/test
+# run all unit tests:
+$ 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)
+New and updated public methods must include [YARD](https://yardoc.org/) documentation.
+
+New and updated public-facing features should be documented in the project's [README.md](README.md).
 
 ## Licensing
 
-ruby-git uses [the MIT license](https://choosealicense.com/licenses/mit/) as
-declared in the [LICENSE](LICENSE) file.
+`ruby-git` uses [the MIT license](https://choosealicense.com/licenses/mit/) as 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.
+Licensing is critical to open-source projects as it ensures the software remains available under the terms desired by the author.
\ No newline at end of file

From 7292f2c79de7c38961025386ceda76fe390f67d7 Mon Sep 17 00:00:00 2001
From: James Couball <jcouball@yahoo.com>
Date: Mon, 26 Aug 2024 15:32:35 -0700
Subject: [PATCH 09/10] Omit the test for signed commit data on Windows

---
 tests/test_helper.rb               |  2 +-
 tests/units/test_signed_commits.rb | 11 +++++++++--
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/tests/test_helper.rb b/tests/test_helper.rb
index f5b08ee3..7be31378 100644
--- a/tests/test_helper.rb
+++ b/tests/test_helper.rb
@@ -45,7 +45,7 @@ def in_temp_repo(clone_name)
   def create_temp_repo(clone_name)
     clone_path = File.join(TEST_FIXTURES, clone_name)
     filename = 'git_test' + Time.now.to_i.to_s + rand(300).to_s.rjust(3, '0')
-    path = File.expand_path(File.join("/tmp/", filename))
+    path = File.expand_path(File.join(Dir.tmpdir, filename))
     FileUtils.mkdir_p(path)
     @tmp_path = File.realpath(path)
     FileUtils.cp_r(clone_path, @tmp_path)
diff --git a/tests/units/test_signed_commits.rb b/tests/units/test_signed_commits.rb
index d1c4d858..871b92a5 100644
--- a/tests/units/test_signed_commits.rb
+++ b/tests/units/test_signed_commits.rb
@@ -13,15 +13,22 @@ class TestSignedCommits < Test::Unit::TestCase
   def in_repo_with_signing_config(&block)
     in_temp_dir do |path|
       `git init`
-      `ssh-keygen -t dsa -N "" -C "test key" -f .git/test-key`
+      ssh_key_file = File.expand_path(File.join('.git', 'test-key'))
+      `ssh-keygen -t dsa -N "" -C "test key" -f "#{ssh_key_file}"`
       `git config --local gpg.format ssh`
-      `git config --local user.signingkey .git/test-key`
+      `git config --local user.signingkey #{ssh_key_file}.pub`
+
+      raise "ERROR: No .git/test-key file" unless File.exist?("#{ssh_key_file}.pub")
 
       yield
     end
   end
 
   def test_commit_data
+    # Signed commits should work on windows, but this test is omitted until the setup
+    # on windows can be figured out
+    omit('Omit testing of signed commits on Windows') if windows_platform?
+
     in_repo_with_signing_config do
       create_file('README.md', '# My Project')
       `git add README.md`

From 3b8de25f046c9e7952b0c181307ac1ba8c91448d Mon Sep 17 00:00:00 2001
From: James Couball <jcouball@yahoo.com>
Date: Mon, 26 Aug 2024 15:53:17 -0700
Subject: [PATCH 10/10] Release v2.2.0

Signed-off-by: James Couball <jcouball@yahoo.com>
---
 CHANGELOG.md       | 16 ++++++++++++++++
 lib/git/version.rb |  2 +-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f7d9bcae..f9120219 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,22 @@
 
 # Change Log
 
+## v2.2.0 (2024-08-26)
+
+[Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.1.1..v2.2.0)
+
+Changes since v2.1.1:
+
+* 7292f2c Omit the test for signed commit data on Windows
+* 2d6157c Document this gem's (aspirational) design philosophy
+* d4f66ab Sanitize non-option arguments passed to `git name-rev`
+* 0296442 Refactor Git::Lib#rev_parse
+* 9b9b31e Verify that the revision-range passed to git log does not resemble a command-line option
+* dc46ede Verify that the commit-ish passed to git describe does not resemble a command-line option
+* 00c4939 Verify that the commit(s) passed to git diff do not resemble a command-line option
+* a08f89b Update README
+* 737c4bb ls-tree optional recursion into subtrees
+
 ## v2.1.1 (2024-06-01)
 
 [Full Changelog](https://github.com/ruby-git/ruby-git/compare/v2.1.0..v2.1.1)
diff --git a/lib/git/version.rb b/lib/git/version.rb
index f970509b..15f996be 100644
--- a/lib/git/version.rb
+++ b/lib/git/version.rb
@@ -1,5 +1,5 @@
 module Git
   # The current gem version
   # @return [String] the current gem version.
-  VERSION='2.1.1'
+  VERSION='2.2.0'
 end