# 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.
      #
      # @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')
      #
      # @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
      #
      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::CommandLine::Result] the result of calling `git stash create`
        #
        #   @raise [Git::FailedError] if git exits with a non-zero exit status
        #
        #   @api public
      end
    end
  end
end
