ruby_git 0.2.0 → 0.3.1

data/lib/ruby_git/status/unmerged_entry.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require_relative 'entry'
+
+module RubyGit
+  module Status
+    # Represents an unmerged file in git status
+    #
+    # @api public
+    class UnmergedEntry < Entry
+      # @attribute [r] conflict_type
+      #
+      # The type of merge conflict
+      #
+      # @example
+      #   entry.conflict_type #=> :both_deleted
+      #
+      # @see RubyGit::Status::UnmergedEntry::CONFLICT_TYPES
+      #
+      # @return [Symbol]
+      #
+      # @api public
+      attr_reader :conflict_type
+
+      # @attribute [r] submodule_status
+      #
+      # The submodule status if the entry is a submodule or nil
+      #
+      # @example
+      #   entry.submodule #=> 'N...'
+      #
+      # @return [SubmoduleStatus, nil]
+      #
+      # @api public
+      attr_reader :submodule_status
+
+      # @attribute [r] base_mode
+      #
+      # The mode of the file in the base
+      #
+      # @example
+      #   entry.base_mode #=> 0o100644
+      #
+      # @return [Integer]
+      #
+      # @api public
+      attr_reader :base_mode
+
+      # @attribute [r] our_mode
+      #
+      # The mode of the file in our branch
+      #
+      # @example
+      #   entry.our_mode #=> 0o100644
+      #
+      # @return [Integer]
+      #
+      # @api public
+      attr_reader :our_mode
+
+      # @attribute [r] their_mode
+      #
+      # The mode of the file in their branch
+      #
+      # @example
+      #  entry.their_mode #=> 0o100644
+      #
+      # @return [Integer]
+      #
+      # @api public
+      attr_reader :their_mode
+
+      # @attribute [r] worktree_mode
+      #
+      # The mode of the file in the worktree
+      #
+      # @example
+      #   entry.worktree_mode #=> 0o100644
+      #
+      # @return [Integer]
+      #
+      # @api public
+      attr_reader :worktree_mode
+
+      # @attribute [r] base_sha
+      #
+      # The SHA of the file in the base
+      #
+      # @example
+      #   entry.base_sha #=> 'd670460b4b4aece5915caf5c68d12f560a9fe3e4'
+      #
+      # @return [String]
+      #
+      # @api public
+      attr_reader :base_sha
+
+      # @attribute [r] our_sha
+      #
+      # The SHA of the file in our branch
+      #
+      # @example
+      #   entry.our_sha #=> 'd670460b4b4aece5915caf5c68d12f560a9fe3e4'
+      #
+      # @return [String]
+      #
+      # @api public
+      attr_reader :our_sha
+
+      # @attribute [r] their_sha
+      #
+      # The SHA of the file in their branch
+      #
+      # @example
+      #   entry.their_sha #=> 'd670460b4b4aece5915caf5c68d12f560a9fe3e4'
+      #
+      # @return [String]
+      #
+      # @api public
+      attr_reader :their_sha
+
+      # @attribute [r] path
+      #
+      # The path of the file
+      #
+      # @example
+      #   entry.path #=> 'lib/example.rb'
+      #
+      # @return [String]
+      #
+      # @api public
+      attr_reader :path
+
+      # Parse an unmerged change line of git status output
+      #
+      # The line is expected to be in porcelain v2 format with NUL terminators.
+      #
+      # The format is as follows:
+      # u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+      #
+      # @example
+      #   line = 'uU N... 100644 100644 100644 100644 d670460b4b4aece5915caf5c68d12f560a9fe3e4 ' \
+      #     'd670460b4b4aece5915caf5c68d12f560a9fe3e4 d670460b4b4aece5915caf5c68d12f560a9fe3e4 lib/example.rb'
+      #   UnmergedEntry.parse(line) #=> #<RubyGit::Status::UnmergedEntry:0x00000001046bd488 ...>
+      #
+      # @param line [String] line from git status
+      #
+      # @return [RubyGit::Status::UnmergedEntry] parsed entry
+      #
+      def self.parse(line) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        tokens = line.split(' ', 11)
+
+        new(
+          conflict_type: conflict_code_to_type(tokens[1]),
+          submodule_status: SubmoduleStatus.parse(tokens[2]),
+          base_mode: Integer(tokens[3], 8),
+          our_mode: Integer(tokens[4], 8),
+          their_mode: Integer(tokens[5], 8),
+          worktree_mode: Integer(tokens[6], 8),
+          base_sha: tokens[7],
+          our_sha: tokens[8],
+          their_sha: tokens[9],
+          path: tokens[10]
+        )
+      end
+
+      # Maps the change code to a conflict type symbol
+      CONFLICT_TYPES = {
+        'DD' => :both_deleted,
+        'AU' => :added_by_us,
+        'UD' => :deleted_by_them,
+        'UA' => :added_by_them,
+        'DU' => :deleted_by_us,
+        'AA' => :both_added,
+        'UU' => :both_modified
+      }.freeze
+
+      # Convert conflict code to a symbol
+      #
+      # @example
+      #   UnmergedEntry.conflict_code_to_type('DD') #=> :both_deleted
+      #
+      # @param code [String] conflict code
+      # @return [Symbol] conflict type as symbol
+      #
+      def self.conflict_code_to_type(code)
+        CONFLICT_TYPES[code] || :unknown
+      end
+
+      # Initialize a new unmerged entry
+      #
+      # @example
+      #   UnmergedEntry.new(
+      #     conflict_type: :both_deleted,
+      #     submodule_status: nil,
+      #     base_mode: 0o100644,
+      #     our_mode: 0o100644,
+      #     their_mode: 0o100644,
+      #     worktree_mode: 0o100644,
+      #     base_sha: 'd670460b4b4aece5915caf5c68d12f560a9fe3e4',
+      #     our_sha: 'd670460b4b4aece5915caf5c68d12f560a9fe3e4',
+      #     their_sha: 'd670460b4b4aece5915caf5c68d12f560a9fe3e4',
+      #     path: 'lib/example.rb'
+      #   )
+      #
+      # @param conflict_type [Symbol] type of merge conflict
+      # @param submodule_status [SubmoduleStatus, nil] submodule status if applicable
+      # @param base_mode [Integer] mode of the file in the base
+      # @param our_mode [Integer] mode of the file in our branch
+      # @param their_mode [Integer] mode of the file in their branch
+      # @param worktree_mode [Integer] mode of the file in the worktree
+      # @param base_sha [String] SHA of the file in the base
+      # @param our_sha [String] SHA of the file in our branch
+      # @param their_sha [String] SHA of the file in their branch
+      # @param path [String] file path
+      #
+      def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        conflict_type:,
+        submodule_status:,
+        base_mode:, our_mode:, their_mode:, worktree_mode:,
+        base_sha:, our_sha:, their_sha:,
+        path:
+      )
+        super(path)
+        @conflict_type = conflict_type
+        @submodule_status = submodule_status
+        @base_mode = base_mode
+        @our_mode = our_mode
+        @their_mode = their_mode
+        @worktree_mode = worktree_mode
+        @base_sha = base_sha
+        @our_sha = our_sha
+        @their_sha = their_sha
+        @path = path
+      end
+
+      # Does the entry represent a merge conflict?
+      #
+      # * Merge conflicts are not considered untracked, staged or unstaged
+      #
+      # @example
+      #   entry.conflict? #=> false
+      #
+      # @return [Boolean]
+      #
+      def unmerged? = true
+    end
+  end
+end

data/lib/ruby_git/status/untracked_entry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'entry'
+
+module RubyGit
+  module Status
+    # Represents an untracked file in git status
+    #
+    # @api public
+    class UntrackedEntry < Entry
+      # Parse a git status line to create an untracked entry
+      #
+      # @example
+      #   UntrackedEntry.parse('?? lib/example.rb') #=> #<RubyGit::Status::UntrackedEntry:0x00000001046bd488 ...>
+      #
+      # @param line [String] line from git status
+      # @return [RubyGit::Status::UntrackedEntry] parsed entry
+      #
+      def self.parse(line)
+        tokens = line.split(' ', 2)
+        new(path: tokens[1])
+      end
+
+      # Initialize with the path
+      #
+      # @example
+      #   UntrackedEntry.new(path: 'file.txt')
+      #
+      # @param path [String] the path of the untracked file
+      #
+      def initialize(path:)
+        super(path)
+      end
+
+      # Is the entry an untracked file?
+      # @example
+      #   entry.ignored? #=> false
+      # @return [Boolean]
+      def untracked? = true
+
+      # Does the entry have unstaged changes in the worktree?
+      #
+      # * An entry can have both staged and unstaged changes
+      # * All untracked entries are considered unstaged
+      #
+      # @example
+      #   entry.ignored? #=> false
+      # @return [Boolean]
+      def unstaged? = true
+    end
+  end
+end

data/lib/ruby_git/status.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'status/branch'
+require_relative 'status/entry'
+require_relative 'status/ignored_entry'
+require_relative 'status/ordinary_entry'
+require_relative 'status/parser'
+require_relative 'status/renamed_entry'
+require_relative 'status/report'
+require_relative 'status/stash'
+require_relative 'status/submodule_status'
+require_relative 'status/unmerged_entry'
+require_relative 'status/untracked_entry'
+
+module RubyGit
+  # The working tree status
+  module Status
+    # Parse output of `git status` and return a structured report
+    #
+    # @example
+    #   output = `git status -u --porcelain=v2 --renames --branch --show-stash -z`
+    #   status = RubyGit::Status.parse(output)
+    #   status.branch.name #=> 'main'
+    #
+    # @param status_output [String] the raw output from git status command
+    # @return [RubyGit::Status::Report] a structured representation of git status
+    #
+    # @api public
+    def self.parse(status_output)
+      Parser.parse(status_output)
+    end
+  end
+end

data/lib/ruby_git/version.rb

@@ -3,5 +3,5 @@
 module RubyGit
   # The ruby_git gem version
   #
-  VERSION = '0.2.0'
+  VERSION = '0.3.1'
 end

data/lib/ruby_git/worktree.rb

@@ -1,15 +1,13 @@
 # frozen_string_literal: true
 
-require 'open3'
-
 module RubyGit
-  # The Worktree is a directory tree consisting of the checked out files that
+  # The working tree is a directory tree consisting of the checked out files that
   # you are currently working on.
   #
   # Create a new Worktree using {.init}, {.clone}, or {.open}.
   #
   class Worktree
-    # The root path of the worktree
+    # The root path of the working tree
     #
     # @example
     #   worktree_path = '/Users/James/myproject'
@@ -21,7 +19,7 @@ module RubyGit
     #
     attr_reader :path
 
-    # Create an empty Git repository under the root worktree `path`
+    # Create an empty Git repository under the root working tree `path`
     #
     # If the repository already exists, it will not be overwritten.
     #
@@ -30,34 +28,35 @@ module RubyGit
     # @example
     #   worktree = Worktree.init(worktree_path)
     #
-    # @param [String] worktree_path the root path of a worktree
+    # @param [String] worktree_path the root path of a Git working tree
     #
     # @raise [RubyGit::Error] if worktree_path is not a directory
     #
-    # @return [RubyGit::Worktree] the worktree whose root is at `path`
+    # @return [RubyGit::Worktree] the working tree whose root is at `path`
     #
     def self.init(worktree_path)
       raise RubyGit::Error, "Path '#{worktree_path}' not valid." unless File.directory?(worktree_path)
 
-      command = [RubyGit.git.path.to_s, 'init']
-      _out, err, status = Open3.capture3(*command, chdir: worktree_path)
-      raise RubyGit::Error, err unless status.success?
+      command = ['init']
+      options = { chdir: worktree_path, out: StringIO.new, err: StringIO.new }
+      RubyGit::CommandLine.run(*command, **options)
 
-      Worktree.new(worktree_path)
+      new(worktree_path)
     end
 
-    # Open an existing Git worktree that contains worktree_path
+    # Open an existing Git working tree that contains worktree_path
     #
     # @see https://git-scm.com/docs/git-open git-open
     #
     # @example
     #   worktree = Worktree.open(worktree_path)
     #
-    # @param [String] worktree_path the root path of a worktree
+    # @param [String] worktree_path the root path of a Git working tree
     #
-    # @raise [RubyGit::Error] if `worktree_path` does not exist, is not a directory, or is not within a Git worktree.
+    # @raise [RubyGit::Error] if `worktree_path` does not exist, is not a directory, or is not within
+    #   a Git working tree.
     #
-    # @return [RubyGit::Worktree] the worktree that contains `worktree_path`
+    # @return [RubyGit::Worktree] the Git working tree that contains `worktree_path`
     #
     def self.open(worktree_path)
       new(worktree_path)
@@ -67,7 +66,7 @@ module RubyGit
     #
     # Clones the repository referred to by `repository_url` into a newly created
     # directory, creates remote-tracking branches for each branch in the cloned repository,
-    # and checks out the default branch in the worktree whose root directory is `to_path`.
+    # and checks out the default branch in the Git working tree whose root directory is `to_path`.
     #
     # @see https://git-scm.com/docs/git-clone git-clone
     #
@@ -76,7 +75,7 @@ module RubyGit
     #    => "/Users/jsmith"
     #   worktree = Worktree.clone('https://github.com/main-branch/ruby_git.git')
     #   worktree.path
-    #     => "/Users/jsmith/ruby_git"
+    #    => "/Users/jsmith/ruby_git"
     #
     # @example Using a specified worktree_path
     #   FileUtils.pwd
@@ -84,52 +83,195 @@ module RubyGit
     #   worktree_path = '/tmp/project'
     #   worktree = Worktree.clone('https://github.com/main-branch/ruby_git.git', to_path: worktree_path)
     #   worktree.path
-    #     => "/tmp/project"
+    #    => "/tmp/project"
     #
     # @param [String] repository_url a reference to a Git repository
     #
-    # @param [String] to_path where to put the checked out worktree once the repository is cloned
+    # @param [String] to_path where to put the checked out Git working tree once the repository is cloned
     #
     # `to_path` will be created if it does not exist.  An error is raised if `to_path` exists and
     # not an empty directory.
     #
-    # @raise [RubyGit::Error] if (1) `repository_url` is not valid or does not point to a valid repository OR
+    # @raise [RubyGit::FailedError] if (1) `repository_url` is not valid or does not point to a valid repository OR
     #   (2) `to_path` is not an empty directory.
     #
-    # @return [RubyGit::Worktree] the worktree checked out from the cloned repository
+    # @return [RubyGit::Worktree] the Git working tree checked out from the cloned repository
+    #
+    def self.clone(repository_url, to_path: nil)
+      command = ['clone', '--', repository_url]
+      command << to_path if to_path
+      options = { out: StringIO.new, err: StringIO.new }
+      clone_output = RubyGit::CommandLine.run(*command, **options).stderr
+      new(cloned_to(clone_output))
+    end
+
+    # Get path of the cloned worktree from `git clone` stderr output
+    #
+    # @param clone_output [String] the stderr output of the `git clone` command
+    #
+    # @return [String] the path of the cloned worktree
     #
-    def self.clone(repository_url, to_path: '')
-      command = [RubyGit.git.path.to_s, 'clone', '--', repository_url, to_path]
-      _out, err, status = Open3.capture3(*command)
-      raise RubyGit::Error, err unless status.success?
+    # @api private
+    def self.cloned_to(clone_output)
+      clone_output.match(/Cloning into ['"](.+)['"]\.\.\./)[1]
+    end
 
-      new(to_path)
+    # Show the working tree and index status
+    #
+    # @example worktree = Worktree.open(worktree_path) worktree.status #=>
+    #   #<RubyGit::Status::Report ...>
+    #
+    # @param path_specs [Array<String>] paths to limit the status to
+    #   (default is all paths)
+    #
+    #   See [git-glossary
+    #   pathspec](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec).
+    #
+    # @param untracked_files [:all, :normal, :no] Defines how untracked files will be
+    # handled
+    #
+    #   See [git-staus
+    #   --untracked-files](https://git-scm.com/docs/git-status#Documentation/git-status.txt---untracked-filesltmodegt).
+    #
+    # @param ignored [:traditional, :matching, :no] Defines how ignored files will be
+    # handled, :no to not include ignored files
+    #
+    #   See [git-staus
+    #   --ignored](https://git-scm.com/docs/git-status#Documentation/git-status.txt---ignoredltmodegt).
+    #
+    # @param ignore_submodules [:all, :dirty, :untracked, :none] Default is :all
+    #
+    #   See [git-staus
+    #   --ignore-submodules](https://git-scm.com/docs/git-status#Documentation/git-status.txt---ignore-submodulesltwhengt).
+    #
+    # @return [RubyGit::Status::Report] the status of the working tree
+    #
+    def status(*path_specs, untracked_files: :all, ignored: :no, ignore_submodules: :all)
+      command = %w[status --porcelain=v2 --branch --show-stash --ahead-behind --renames -z]
+      command << "--untracked-files=#{untracked_files}"
+      command << "--ignored=#{ignored}"
+      command << "--ignore-submodules=#{ignore_submodules}"
+      command << '--' unless path_specs.empty?
+      command.concat(path_specs)
+      options = { out: StringIO.new, err: StringIO.new }
+      status_output = run(*command, **options).stdout
+      RubyGit::Status.parse(status_output)
+    end
+
+    # Add changed files to the index to stage for the next commit
+    #
+    # @example
+    #   worktree = Worktree.open(worktree_path)
+    #   worktree.add('file1.txt', 'file2.txt')
+    #   worktree.add('.')
+    #   worktree.add(all: true)
+    #
+    # @param pathspecs [Array<String>] paths to add to the index
+    # @param all [Boolean] adds, updates, and removes index entries to match the working tree (entire repo)
+    # @param force [Boolean] add files even if they are ignored
+    # @param refresh [Boolean] only refresh each files stat information in the index
+    # @param update [Boolean] add all updated and deleted files to the index but does not add any files
+    #
+    # @see https://git-scm.com/docs/git-add git-add
+    #
+    # @return [RubyGit::CommandLineResult] the result of the git add command
+    #
+    # @raise [ArgumentError] if any of the options are not valid
+    #
+    def add(*pathspecs, all: false, force: false, refresh: false, update: false) # rubocop:disable Metrics/MethodLength
+      validate_boolean_option(name: :all, value: all)
+      validate_boolean_option(name: :force, value: force)
+      validate_boolean_option(name: :refresh, value: refresh)
+      validate_boolean_option(name: :update, value: update)
+
+      command = %w[add]
+      command << '--all' if all
+      command << '--force' if force
+      command << '--update' if update
+      command << '--refresh' if refresh
+      command << '--' unless pathspecs.empty?
+      command.concat(pathspecs)
+
+      options = { out: StringIO.new, err: StringIO.new }
+
+      run(*command, **options)
+    end
+
+    # Return the repository associated with the worktree
+    #
+    # @example
+    #   worktree = Worktree.open(worktree_path)
+    #   worktree.repository #=> #<RubyGit::Repository ...>
+    #
+    # @return [RubyGit::Repository] the repository associated with the worktree
+    #
+    def repository
+      @repository ||= begin
+        command = %w[rev-parse --git-dir]
+        options = { chdir: path, chomp: true, out: StringIO.new, err: StringIO.new }
+        # rev-parse path might be relative to the worktree, thus the need to expand it
+        git_dir = File.realpath(RubyGit::CommandLine.run(*command, **options).stdout, path)
+        Repository.new(git_dir)
+      end
     end
 
     private
 
     # Create a Worktree object
+    #
+    # @param worktree_path [String] a path anywhere in the worktree
+    #
     # @api private
+    #
     def initialize(worktree_path)
       raise RubyGit::Error, "Path '#{worktree_path}' not valid." unless File.directory?(worktree_path)
 
       @path = root_path(worktree_path)
+      RubyGit.logger.debug("Created #{inspect}")
     end
 
-    # Find the root path of a worktree containing `path`
+    # Find the root path of a Git working tree containing `path`
     #
-    # @raise [RubyGit::Error] if the path is not in a worktree
+    # @raise [RubyGit::FailedError] if the path is not in a Git working tree
     #
-    # @return [String] the root path of the worktree containing `path`
+    # @return [String] the root path of the Git working tree containing `path`
     #
     # @api private
     #
     def root_path(worktree_path)
-      command = [RubyGit.git.path.to_s, 'rev-parse', '--show-toplevel']
-      out, err, status = Open3.capture3(*command, chdir: worktree_path)
-      raise RubyGit::Error, err unless status.success?
+      command = %w[rev-parse --show-toplevel]
+      options = { chdir: worktree_path, chomp: true, out: StringIO.new, err: StringIO.new }
+      File.realpath(RubyGit::CommandLine.run(*command, **options).stdout)
+    end
+
+    # Run a Git command in this worktree
+    #
+    # Passes the repository path and worktree path to RubyGit::CommandLine.run
+    #
+    # @param command [Array<String>] the git command to run
+    # @param options [Hash] options to pass to RubyGit::CommandLine.run
+    #
+    # @return [RubyGit::CommandLineResult] the result of the git command
+    #
+    # @api private
+    #
+    def run(*command, **options)
+      RubyGit::CommandLine.run(*command, repository_path: repository.path, worktree_path: path, **options)
+    end
+
+    # Raise an error if an option is not a Boolean (or optionally nil) value
+    # @param name [String] the name of the option
+    # @param value [Object] the value of the option
+    # @param nullable [Boolean] whether the option can be nil (default is false)
+    # @return [void]
+    # @raise [ArgumentError] if the option is not a Boolean (or optionally nil) value
+    # @api private
+    def validate_boolean_option(name:, value:, nullable: false)
+      return if nullable && value.nil?
+
+      return if [true, false].include?(value)
 
-      out.chomp
+      raise ArgumentError, "The '#{name}:' option must be a Boolean value but was #{value.inspect}"
     end
   end
 end