git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/stash/create.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Stash
+      # Create a stash commit without storing it in refs/stash
+      #
+      # This is a plumbing command used to create a stash commit object without
+      # actually storing it in the stash reflog. It's useful for scripts that
+      # need to create stash commits programmatically.
+      #
+      # The command creates a stash commit and outputs its SHA, but does not
+      # update refs/stash. Use {Store} to store the commit in the stash reflog.
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      # @example Create a stash commit
+      #   Git::Commands::Stash::Create.new(execution_context).call
+      #
+      # @example Create a stash commit with a message
+      #   Git::Commands::Stash::Create.new(execution_context).call('WIP: my changes')
+      #
+      class Create < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'create'
+          operand :message
+        end
+
+        # @!method call(*, **)
+        #
+        #   Create a stash commit
+        #
+        #   @overload call()
+        #
+        #     Create a stash commit without a message
+        #
+        #   @overload call(message)
+        #
+        #     Create a stash commit with a message
+        #
+        #     @param message [String] optional message for the stash commit
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git stash create`
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/stash/drop.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Stash
+      # Remove a stash entry from the stash list
+      #
+      # Removes a single stash entry from the list of stash entries.
+      # If no stash reference is given, it removes the latest one.
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      # @example Drop the latest stash
+      #   Git::Commands::Stash::Drop.new(execution_context).call
+      #
+      # @example Drop a specific stash
+      #   Git::Commands::Stash::Drop.new(execution_context).call('stash@\\{2}')
+      #
+      class Drop < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'drop'
+          flag_option %i[quiet q]
+          operand :stash
+        end
+
+        # @!method call(*, **)
+        #
+        #   Drop a stash entry
+        #
+        #   @overload call(**options)
+        #
+        #     Drop the latest stash
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #       Alias: :q
+        #
+        #   @overload call(stash, **options)
+        #
+        #     Drop a specific stash
+        #
+        #     @param stash [String] stash reference (e.g., 'stash@\\{0}', '0')
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #       Alias: :q
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git stash drop`
+        #
+        #   @raise [Git::FailedError] if the stash does not exist
+      end
+    end
+  end
+end

data/lib/git/commands/stash/list.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+require 'git/parsers/stash'
+
+module Git
+  module Commands
+    module Stash
+      # List all stash entries
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      # @example List all stashes
+      #   Git::Commands::Stash::List.new(execution_context).call
+      #
+      class List < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'list'
+          literal "--format=#{Git::Parsers::Stash::STASH_FORMAT}"
+        end
+
+        # @!method call(*, **)
+        #
+        #   List all stash entries
+        #
+        #   @overload call()
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git stash list`
+      end
+    end
+  end
+end

data/lib/git/commands/stash/pop.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Stash
+      # Apply stashed changes and remove from stash list
+      #
+      # Like {Apply}, but removes the stash from the stash list after
+      # applying, unless there are conflicts.
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      # @example Pop the latest stash
+      #   Git::Commands::Stash::Pop.new(execution_context).call
+      #
+      # @example Pop a specific stash
+      #   Git::Commands::Stash::Pop.new(execution_context).call('stash@\\{2}')
+      #
+      # @example Pop and restore index state
+      #   Git::Commands::Stash::Pop.new(execution_context).call(index: true)
+      #
+      # @example Pop quietly
+      #   Git::Commands::Stash::Pop.new(execution_context).call(quiet: true)
+      #
+      class Pop < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'pop'
+          flag_option :index
+          flag_option %i[quiet q]
+          operand :stash
+        end
+
+        # @!method call(*, **)
+        #
+        #   Pop stashed changes
+        #
+        #   @overload call(**options)
+        #
+        #     Pop the latest stash
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :index (nil) restore the index state as well
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #       Alias: :q
+        #
+        #   @overload call(stash, **options)
+        #
+        #     Pop a specific stash
+        #
+        #     @param stash [String] stash reference (e.g., 'stash@\\{0}', '0')
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :index (nil) restore the index state as well
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #       Alias: :q
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git stash pop`
+        #
+        #   @raise [Git::FailedError] if the stash does not exist
+      end
+    end
+  end
+end

data/lib/git/commands/stash/push.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Stash
+      # Stash changes in the working directory
+      #
+      # Saves local modifications to a new stash entry and rolls them back
+      # to HEAD (in the working tree and index). The command takes
+      # various options to customize what gets stashed.
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      # @example Save all changes with a message
+      #   Git::Commands::Stash::Push.new(execution_context).call(message: 'WIP: feature work')
+      #
+      # @example Stash only specific files
+      #   Git::Commands::Stash::Push.new(execution_context).call('src/file.rb', message: 'Partial stash')
+      #
+      # @example Keep staged changes in index
+      #   Git::Commands::Stash::Push.new(execution_context).call(keep_index: true)
+      #
+      # @example Include untracked files
+      #   Git::Commands::Stash::Push.new(execution_context).call(include_untracked: true)
+      #
+      class Push < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'push'
+          flag_option %i[patch p]
+          flag_option %i[staged S]
+          flag_option %i[keep_index k], negatable: true
+          flag_option %i[quiet q]
+          flag_option %i[include_untracked u]
+          flag_option %i[all a]
+          value_option %i[message m]
+          value_option :pathspec_from_file, inline: true
+          flag_option :pathspec_file_nul
+          end_of_options
+          operand :pathspec, repeatable: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(*pathspec, **options)
+        #
+        #     Stash changes in the working directory
+        #
+        #     @param pathspec [Array<String>] optional paths to limit what gets stashed
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :patch (nil) interactively select hunks to stash
+        #
+        #       Alias: :p
+        #
+        #     @option options [Boolean, nil] :staged (nil) stash only staged changes
+        #
+        #       Alias: :S
+        #
+        #     @option options [Boolean, nil] :keep_index (nil) keep staged changes in the index (`--keep-index`)
+        #
+        #       Alias: :k
+        #
+        #     @option options [Boolean, nil] :no_keep_index (nil) do not preserve staged changes in the index
+        #       (`--no-keep-index`)
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #       Alias: :q
+        #
+        #     @option options [Boolean, nil] :include_untracked (nil) include untracked files in the stash
+        #
+        #       Alias: :u
+        #
+        #     @option options [Boolean, nil] :all (nil) include untracked and ignored files in the stash
+        #
+        #       Alias: :a
+        #
+        #     @option options [String] :message (nil) descriptive message for the stash
+        #
+        #       Alias: :m
+        #
+        #     @option options [String] :pathspec_from_file (nil) read pathspecs from the given file
+        #
+        #     @option options [Boolean, nil] :pathspec_file_nul (nil) pathspecs in the file are NUL-separated
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git stash push`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+      end
+    end
+  end
+end

data/lib/git/commands/stash/show.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Stash
+      # Show the changes recorded in a stash entry as a diff
+      #
+      # Shows the changes recorded in the stash entry as a diff between the
+      # stashed contents and the commit back when the stash entry was first
+      # created.
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      # @example Show numstat for the latest stash
+      #   Git::Commands::Stash::Show.new(ctx).call(numstat: true, shortstat: true)
+      #
+      # @example Show patch for a specific stash
+      #   Git::Commands::Stash::Show.new(ctx).call('stash@{2}', patch: true, numstat: true, shortstat: true)
+      #
+      # @example Show with directory statistics
+      #   Git::Commands::Stash::Show.new(ctx).call(numstat: true, shortstat: true, dirstat: true)
+      #   Git::Commands::Stash::Show.new(ctx).call(numstat: true, shortstat: true, dirstat: 'lines,cumulative')
+      #
+      class Show < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'show'
+
+          flag_option :patch
+          flag_option :numstat
+          flag_option :raw
+          flag_option :shortstat
+          value_option %i[unified U], inline: true
+
+          flag_option %i[include_untracked u], negatable: true
+          flag_option :only_untracked
+          flag_or_value_option %i[find_renames M], inline: true
+          flag_or_value_option %i[find_copies C], inline: true
+          flag_option :find_copies_harder
+          value_option :inter_hunk_context, inline: true
+          flag_or_value_option :dirstat, inline: true
+          operand :stash
+        end
+
+        # @!method call(*, **)
+        #
+        #   Show stash diff
+        #
+        #   @overload call(**options)
+        #
+        #     Show diff for the latest stash
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :patch (nil) include unified diff patches per file
+        #
+        #     @option options [Boolean, nil] :numstat (nil) include per-file insertion/deletion counts
+        #
+        #     @option options [Boolean, nil] :raw (nil) include per-file mode/SHA/status metadata
+        #
+        #     @option options [Boolean, nil] :shortstat (nil) include aggregate totals line
+        #
+        #     @option options [Integer, String] :unified (nil) generate diff with <n> lines of context
+        #
+        #       Alias: :U
+        #
+        #     @option options [Boolean, nil] :include_untracked (nil) include untracked files (`--include-untracked`)
+        #
+        #       Alias: :u
+        #
+        #     @option options [Boolean, nil] :no_include_untracked (nil) exclude untracked files
+        #       (`--no-include-untracked`)
+        #
+        #     @option options [Boolean, nil] :only_untracked (nil) show only untracked files
+        #
+        #     @option options [Boolean, Integer, nil] :find_renames (nil) detect renames; optionally pass a
+        #       similarity threshold (e.g., 50 for 50%). Alias: :M
+        #
+        #     @option options [Boolean, Integer, nil] :find_copies (nil) detect copies as well as renames;
+        #       optionally pass a threshold. Alias: :C
+        #
+        #     @option options [Boolean, nil] :find_copies_harder (nil) inspect all files as copy sources; expensive
+        #
+        #     @option options [Integer, String] :inter_hunk_context (nil) show context between diff hunks, up to
+        #       <n> lines, fusing hunks that are close to each other
+        #
+        #     @option options [Boolean, String, nil] :dirstat (nil) include directory statistics
+        #
+        #       Pass `true` for default, or a string like `'lines,cumulative'` for options.
+        #
+        #   @overload call(stash, **options)
+        #
+        #     Show diff for a specific stash
+        #
+        #     @param stash [String] stash reference (e.g., 'stash@\\{0}', '0')
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :patch (nil) include unified diff patches per file
+        #
+        #     @option options [Boolean, nil] :numstat (nil) include per-file insertion/deletion counts
+        #
+        #     @option options [Boolean, nil] :raw (nil) include per-file mode/SHA/status metadata
+        #
+        #     @option options [Boolean, nil] :shortstat (nil) include aggregate totals line
+        #
+        #     @option options [Integer, String] :unified (nil) generate diff with <n> lines of context
+        #
+        #       Alias: :U
+        #
+        #     @option options [Boolean, nil] :include_untracked (nil) include untracked files (`--include-untracked`)
+        #
+        #       Alias: :u
+        #
+        #     @option options [Boolean, nil] :no_include_untracked (nil) exclude untracked files
+        #       (`--no-include-untracked`)
+        #
+        #     @option options [Boolean, nil] :only_untracked (nil) show only untracked files
+        #
+        #     @option options [Boolean, Integer, nil] :find_renames (nil) detect renames; optionally pass a
+        #       similarity threshold (e.g., 50 for 50%). Alias: :M
+        #
+        #     @option options [Boolean, Integer, nil] :find_copies (nil) detect copies as well as renames;
+        #       optionally pass a threshold. Alias: :C
+        #
+        #     @option options [Boolean, nil] :find_copies_harder (nil) inspect all files as copy sources; expensive
+        #
+        #     @option options [Integer, String] :inter_hunk_context (nil) show context between diff hunks, up to
+        #       <n> lines, fusing hunks that are close to each other
+        #
+        #     @option options [Boolean, String, nil] :dirstat (nil) include directory statistics
+        #
+        #       Pass `true` for default, or a string like `'lines,cumulative'` for options.
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git stash show`
+        #
+        #   @raise [Git::FailedError] if git returns a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/stash/store.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Stash
+      # Store a commit in the stash reflog
+      #
+      # This is a plumbing command used to store a given stash commit (created
+      # by `git stash create`) in the stash reflog, updating refs/stash.
+      #
+      # This command is typically used after {Create} to actually record
+      # the stash in the reflog.
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      # @example Store a stash commit
+      #   Git::Commands::Stash::Store.new(execution_context).call('abc123def456')
+      #
+      # @example Store with a custom message
+      #   Git::Commands::Stash::Store.new(execution_context).call('abc123def456', message: 'WIP: feature')
+      #
+      class Store < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'store'
+          value_option %i[message m]
+          flag_option %i[quiet q]
+          operand :commit, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   Store a commit in the stash reflog
+        #
+        #   @overload call(commit, **options)
+        #
+        #     @param commit [String] the commit SHA to store in the stash (required)
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :message (nil) description for the reflog entry
+        #
+        #       Alias: :m
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress output
+        #
+        #       Alias: :q
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git stash store`
+        #
+        #     @raise [Git::FailedError] if the commit is not a valid stash commit
+      end
+    end
+  end
+end

data/lib/git/commands/stash.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'stash/apply'
+require_relative 'stash/branch'
+require_relative 'stash/clear'
+require_relative 'stash/create'
+require_relative 'stash/drop'
+require_relative 'stash/list'
+require_relative 'stash/pop'
+require_relative 'stash/push'
+require_relative 'stash/show'
+require_relative 'stash/store'
+
+module Git
+  module Commands
+    # Commands for stashing working directory changes via `git stash`
+    #
+    # This module contains command classes split by stash operation:
+    #
+    # - {Stash::Push} — save changes to a new stash entry
+    # - {Stash::Pop} — apply the top stash and remove it from the stash list
+    # - {Stash::Apply} — apply a stash without removing it
+    # - {Stash::Drop} — remove a single stash entry
+    # - {Stash::Clear} — remove all stash entries
+    # - {Stash::List} — list stash entries
+    # - {Stash::Show} — show changes recorded in a stash entry
+    # - {Stash::Branch} — create a new branch from a stash entry
+    # - {Stash::Create} — create a stash object without storing it
+    # - {Stash::Store} — store a stash object created with `create`
+    #
+    # @api private
+    #
+    # @see https://git-scm.com/docs/git-stash git-stash documentation
+    #
+    module Stash
+    end
+  end
+end