kk-git 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e2ef1f50e051f8167139fae0478f01da4a0cae6ea6401a73cdf67765ad13936
-  data.tar.gz: 71d53513506ebff53f091a7d10c9ab41e0e6b3b60e393d783061aa2f19072288
+  metadata.gz: 6db1717b25840058e422b1b8955fb33222666cffdb8692e366e76821b93ea6a9
+  data.tar.gz: 3f2c67d3187d973923bc26b49fbc3d2e2bc5fe83b47738bc86d1ca97999ecdff
 SHA512:
-  metadata.gz: c25c845bb90eae62b73feff52b0a0043e20004b20bec670460fa90ba6bb09e53fa468986c960305787a311622b30947eda805c1dc9395e7294a3bca663d877b5
-  data.tar.gz: 0534a91d78bef3ddbd34f85cdc5f7e9392a68d771a2c940a1d435151fe28910b925164c8277e08e2addfa5faf085af0fe27a0375e4900a1ea2f5468e8dd4f966
+  metadata.gz: 53560be756360a59510ad02eb3888936b9a63cb9285c5386c765c3173bc320bdbe41ebc8c9c2d984ff511729b556279061d5369ed448050b8642ec64eea99687
+  data.tar.gz: 414075a7880e76253a3ba7fda59a93731121ce4979c86ee1ba0629c42c4e899bdae70e3ddd99fdb0252f770c6c16a5690fee805dbbefec17177d3f9caf2b2595

data/exe/kk-git

@@ -10,104 +10,174 @@ rescue LoadError
   require_relative '../lib/kk/git'
 end
 
-options = {
-  mode: :staged,
-  format: :text,
-  include_body: true,
-  repo_dir: '.',
-  type: nil,
-  scope: nil,
-  subject: nil,
-  detect_breaking: true
-}
-
-parser = OptionParser.new do |opts|
-  opts.banner = "Usage:\n" \
-                "  kk-git --version\n" \
-                "  kk-git commit-message [options]\n\n" \
-                "根据当前 Git repo 变更生成 Conventional Commit 信息。"
-
-  opts.on('--repo DIR', '指定 repo 目录（默认当前目录）') { |v| options[:repo_dir] = v }
-
-  opts.on('--staged', '仅基于暂存区变更（默认）') { options[:mode] = :staged }
-  opts.on('--worktree', '仅基于工作区变更（含 untracked）') { options[:mode] = :worktree }
-  opts.on('--all', '合并暂存区与工作区变更') { options[:mode] = :all }
-
-  opts.on('--[no-]body', '多文件时输出/不输出 body（默认输出）') { |v| options[:include_body] = v }
-
-  opts.on('--type TYPE', '覆盖自动推断的 type（如 feat/fix/docs）') { |v| options[:type] = v }
-  opts.on('--scope SCOPE', '覆盖自动推断的 scope') { |v| options[:scope] = v }
-  opts.on('--subject SUBJECT', '覆盖自动推断的 subject') { |v| options[:subject] = v }
-  opts.on('--[no-]detect-breaking', '是否检测 BREAKING 标记（默认检测）') { |v| options[:detect_breaking] = v }
-
-  opts.on('--format FORMAT', '输出格式：text/json（默认 text）') do |v|
-    options[:format] = v.to_s.downcase.to_sym
+def to_utf8(str)
+  return nil if str.nil?
+
+  s = str.to_s.dup
+  s.force_encoding(Encoding::UTF_8)
+  s.scrub('�')
+end
+
+def run_commit_message!(argv)
+  options = {
+    mode: :staged,
+    format: :text,
+    include_body: true,
+    repo_dir: '.',
+    type: nil,
+    scope: nil,
+    subject: nil,
+    detect_breaking: true
+  }
+
+  parser = OptionParser.new do |opts|
+    opts.banner = 'Usage: kk-git commit-message [options]'
+    opts.on('--repo DIR', 'Git repo directory (default: current dir)') { |v| options[:repo_dir] = v }
+    opts.on('--staged', 'Use staged changes only (default)') { options[:mode] = :staged }
+    opts.on('--worktree', 'Use working-tree changes only (includes untracked)') { options[:mode] = :worktree }
+    opts.on('--all', 'Combine staged + working-tree changes') { options[:mode] = :all }
+    opts.on('--[no-]body', 'Include body for multi-file changes (default: yes)') { |v| options[:include_body] = v }
+    opts.on('--type TYPE', 'Override inferred type') { |v| options[:type] = v }
+    opts.on('--scope SCOPE', 'Override inferred scope') { |v| options[:scope] = v }
+    opts.on('--subject SUBJECT', 'Override inferred subject') { |v| options[:subject] = v }
+    opts.on('--[no-]detect-breaking', 'Detect BREAKING markers (default: yes)') { |v| options[:detect_breaking] = v }
+    opts.on('--format FORMAT', 'Output format: text/json (default: text)') { |v| options[:format] = v.to_s.downcase.to_sym }
+    opts.on('-h', '--help', 'Show help') { puts opts; exit 0 }
+  end
+  parser.parse!(argv)
+
+  options[:type] = to_utf8(options[:type])
+  options[:scope] = to_utf8(options[:scope])
+  options[:subject] = to_utf8(options[:subject])
+
+  result =
+    if options[:format] == :json
+      KKGit::CommitMessage.generate_hash(
+        repo_dir: options[:repo_dir],
+        mode: options[:mode],
+        include_body: options[:include_body],
+        type_override: options[:type],
+        scope_override: options[:scope],
+        subject_override: options[:subject],
+        detect_breaking: options[:detect_breaking]
+      )
+    else
+      KKGit::CommitMessage.generate(
+        repo_dir: options[:repo_dir],
+        mode: options[:mode],
+        include_body: options[:include_body],
+        type_override: options[:type],
+        scope_override: options[:scope],
+        subject_override: options[:subject],
+        detect_breaking: options[:detect_breaking]
+      )
+    end
+
+  if result.nil? || (result.is_a?(Hash) && result[:empty])
+    exit 1
   end
 
-  opts.on('-h', '--help', '显示帮助') do
-    puts opts
-    exit 0
+  puts(options[:format] == :json ? JSON.pretty_generate(result) : result)
+end
+
+def run_status!(argv)
+  options = { format: :text }
+  parser = OptionParser.new do |opts|
+    opts.banner = 'Usage: kk-git status [options]'
+    opts.on('--format FORMAT', 'Output format: text/json (default: text)') { |v| options[:format] = v.to_s.downcase.to_sym }
+    opts.on('-h', '--help', 'Show help') { puts opts; exit 0 }
   end
+  parser.parse!(argv)
 
-  opts.on('-v', '--version', '显示版本号') do
-    puts KKGit::VERSION
-    exit 0
+  hash = KKGit::GitOps.status_hash
+  if options[:format] == :json
+    puts JSON.pretty_generate(hash)
+  else
+    puts "Branch: #{hash[:branch]} (#{hash[:remote]})"
+    puts "Working tree: #{hash[:clean] ? 'clean' : 'dirty'}"
+    puts "Ahead: #{hash[:ahead]}, Behind: #{hash[:behind]}"
+    puts "Upstream: #{hash[:upstream_configured] ? 'configured' : 'not set'}"
+    puts 'Detached HEAD: yes' if hash[:detached]
   end
 end
 
-# 支持 `kk-git --version` 这种无子命令形式
-if ['--version', '-v'].include?(ARGV[0])
-  puts KKGit::VERSION
-  exit 0
-end
+def run_sync!(argv)
+  parser = OptionParser.new do |opts|
+    opts.banner = 'Usage: kk-git sync [options]'
+    opts.on('-h', '--help', 'Show help') { puts opts; exit 0 }
+  end
+  parser.parse!(argv)
 
-subcommand = ARGV.shift
-if subcommand != 'commit-message'
-  warn "未知命令: #{subcommand}\n\n#{parser}"
-  exit 2
+  remote = KKGit::GitOps.remote
+  branch = KKGit::GitOps.branch
+  s = KKGit::GitOps.status(remote: remote, branch: branch)
+
+  if s.needs_sync?
+    KKGit::GitOps.sync_with_remote!(remote, branch)
+  else
+    puts 'Already in sync with remote'
+  end
 end
 
-parser.parse!(ARGV)
+def run_push!(argv)
+  parser = OptionParser.new do |opts|
+    opts.banner = 'Usage: kk-git push [options]'
+    opts.on('-h', '--help', 'Show help') { puts opts; exit 0 }
+  end
+  parser.parse!(argv)
 
-def to_utf8(str)
-  return nil if str.nil?
-  s = str.to_s.dup
-  # ARGV 在不同 locale 下可能被标记为 ASCII-8BIT/US-ASCII，但字节本身通常是 UTF-8。
-  # 这里优先按 UTF-8 解释字节，并对非法序列做 scrub。
-  s.force_encoding(Encoding::UTF_8)
-  s.scrub('�')
+  KKGit::GitOps.auto_commit_push!
 end
 
-options[:type] = to_utf8(options[:type])
-options[:scope] = to_utf8(options[:scope])
-options[:subject] = to_utf8(options[:subject])
-
-result =
-  if options[:format] == :json
-    KKGit::CommitMessage.generate_hash(
-      repo_dir: options[:repo_dir],
-      mode: options[:mode],
-      include_body: options[:include_body],
-      type_override: options[:type],
-      scope_override: options[:scope],
-      subject_override: options[:subject],
-      detect_breaking: options[:detect_breaking]
-    )
-  else
-    KKGit::CommitMessage.generate(
-      repo_dir: options[:repo_dir],
-      mode: options[:mode],
-      include_body: options[:include_body],
-      type_override: options[:type],
-      scope_override: options[:scope],
-      subject_override: options[:subject],
-      detect_breaking: options[:detect_breaking]
-    )
-  end
+def main_help
+  <<~HELP
+    Usage:
+      kk-git --version
+      kk-git commit-message [options]
+      kk-git status [options]
+      kk-git sync [options]
+      kk-git push [options]
+
+    Git helper: generate Conventional Commits messages and automate sync.
+
+    Environment variables (push/sync):
+      KK_GIT_REMOTE       remote name (default: origin)
+      KK_GIT_BRANCH       branch name (default: current branch)
+      KK_GIT_PULL_ARGS    extra args for git pull (default: --ff-only)
+      KK_GIT_ADD_PATHS    paths for git add (default: .)
+      KK_GIT_DRY_RUN=1    print commands without executing
+      KK_GIT_SKIP_PULL=1  skip pull step
+      KK_GIT_SKIP_PUSH=1  skip push step
+      KK_GIT_AMEND=1      amend last commit instead of creating new one
+
+    Run `kk-git <command> --help` for command-specific options.
+  HELP
+end
 
-if result.nil? || (result.is_a?(Hash) && result[:empty])
-  exit 1
+if ['--version', '-v'].include?(ARGV[0])
+  puts KKGit::VERSION
+  exit 0
 end
 
-puts(options[:format] == :json ? JSON.pretty_generate(result) : result)
+if ['--help', '-h'].include?(ARGV[0]) && ARGV.length == 1
+  puts main_help
+  exit 0
+end
 
+subcommand = ARGV.shift
+case subcommand
+when 'commit-message'
+  run_commit_message!(ARGV)
+when 'status'
+  run_status!(ARGV)
+when 'sync'
+  run_sync!(ARGV)
+when 'push'
+  run_push!(ARGV)
+when nil
+  warn "Missing command.\n\n#{main_help}"
+  exit 2
+else
+  warn "Unknown command: #{subcommand}\n\n#{main_help}"
+  exit 2
+end

data/lib/kk/git/commit_message.rb

@@ -4,13 +4,13 @@ require 'json'
 require 'open3'
 
 module KKGit
-  # 根据当前 repo 的变更生成 Conventional Commits 信息。
+  # Generate Conventional Commits messages from git changes.
   #
-  # - 支持暂存区（staged）和工作区（working tree）变更
-  # - 支持识别 untracked 文件
-  # - 输出格式："<type>(<scope>): <subject>\n\n<body>"
+  # - Supports staged and working-tree changes
+  # - Supports untracked files
+  # - Output format: "<type>(<scope>): <subject>\n\n<body>"
   class CommitMessage
-    # 变更条目（支持 rename/copy 的 old/new）
+    # Change entry (supports rename/copy old/new paths)
     Change = Struct.new(:status, :path, :old_path, :source, keyword_init: true)
 
     TYPE_PRIORITY = {
@@ -25,19 +25,19 @@ module KKGit
       'chore' => 9
     }.freeze
 
-    # 生成 commit message。
+    # Generate a commit message.
     #
-    # @param repo_dir [String] Git 仓库目录（默认当前目录）
-    # @param mode [Symbol] :staged（仅暂存区）/:worktree（仅工作区）/:all（两者合并）
-    # @param include_body [Boolean] 多文件时是否输出 body（文件列表）
-    # @param fallback_scope [String] 无法推断 scope 时的默认值
-    # @param type_override [String, nil] 强制指定 type（如 feat/fix/docs）
-    # @param scope_override [String, nil] 强制指定 scope
-    # @param subject_override [String, nil] 强制指定 subject
-    # @param detect_breaking [Boolean] 是否从 diff 中检测 BREAKING 标记并生成 "type(scope)!:"（默认 true）
-    # @param max_diff_bytes [Integer] diff 检测的最大字节数（防止超大仓库导致变慢）
+    # @param repo_dir [String] git repo directory (default: current dir)
+    # @param mode [Symbol] :staged / :worktree / :all
+    # @param include_body [Boolean] include body for multi-file changes
+    # @param fallback_scope [String] scope used when inference can't decide
+    # @param type_override [String, nil] force type (feat/fix/docs/...)
+    # @param scope_override [String, nil] force scope
+    # @param subject_override [String, nil] force subject
+    # @param detect_breaking [Boolean] detect "BREAKING" markers and emit "type(scope)!:" (default: true)
+    # @param max_diff_bytes [Integer] cap diff size for breaking detection
     #
-    # @return [String, nil] 无变更时返回 nil
+    # @return [String, nil] returns nil when there are no changes
     def self.generate(
       repo_dir: '.',
       mode: :staged,
@@ -69,7 +69,7 @@ module KKGit
       message
     end
 
-    # 生成结构化信息（便于脚本/CI 消费）。
+    # Generate structured data (useful for scripts/CI).
     #
     # @return [Hash]
     def self.generate_hash(
@@ -169,7 +169,7 @@ module KKGit
     end
 
     def self.normalize_and_dedup(changes)
-      # key 维度：new_path；同一路径可能在 staged + worktree 都出现
+      # Keyed by new_path; same path can show up in staged + worktree.
       dedup = {}
       changes.each do |c|
         next if c.path.nil? || c.path.strip.empty?
@@ -181,10 +181,10 @@ module KKGit
           next
         end
 
-        # 优先级：
-        # - staged 覆盖 worktree（更贴近即将提交的内容）
-        # - rename/copy 优先于普通修改
-        # - A(新增) 优先于 M
+        # Priority:
+        # - staged wins over worktree (closer to what will be committed)
+        # - rename/copy wins over plain modifications
+        # - A(add) wins over M(modify)
         priority = change_priority(c)
         existing_priority = change_priority(existing)
         dedup[key] = c if priority < existing_priority
@@ -212,16 +212,16 @@ module KKGit
 
     def self.run_git(args, repo_dir:)
       stdout, stderr, status = Open3.capture3('git', *args, chdir: repo_dir)
-      # Open3 返回的 stdout/stderr 可能是 ASCII-8BIT（BINARY），统一转为 UTF-8 避免拼接时报编码错误。
+      # Open3 stdout/stderr may be ASCII-8BIT (BINARY). Normalize to UTF-8 to avoid concat errors.
       stdout = stdout.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: '�')
       stderr = stderr.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: '�')
 
-      raise "git #{args.join(' ')} 失败: #{stderr.strip}" unless status.success?
+      raise "git #{args.join(' ')} failed: #{stderr.strip}" unless status.success?
 
       stdout
     end
 
-    # 推断 type/scope/subject（含 breaking 检测）
+    # Infer type/scope/subject (with optional breaking detection)
     #
     # @return [Hash] {:type,:scope,:subject,:breaking}
     def self.infer(changes:, repo_dir:, mode:, detect_breaking:, max_diff_bytes:, fallback_scope:)
@@ -243,14 +243,14 @@ module KKGit
       return fallback_scope if uniq.empty?
       return uniq.first if uniq.length == 1
 
-      # 多 scope 的时候，尽量选 repo；否则 fallback
+      # When multiple scopes exist, prefer "repo"; otherwise fallback.
       return 'repo' if uniq.include?('repo')
 
       fallback_scope
     end
 
     def self.infer_scope(paths, fallback_scope:)
-      # 工具/脚本类变更：尽量统一 scope 为 tools
+      # Tooling/script/build changes: prefer a stable scope
       if paths.any? && paths.all? { |p| tooling_path?(p) || doc_path?(p) || ci_path?(p) }
         return 'tools'
       end
@@ -261,7 +261,7 @@ module KKGit
       return uniq.first if uniq.length == 1
       return 'repo' if uniq.include?('repo')
 
-      # 多个顶层目录：统一落到 repo（避免 scope 过长/不稳定）
+      # Multiple top-level dirs: use repo to keep scope stable/short.
       'repo'
     end
 
@@ -277,7 +277,7 @@ module KKGit
     def self.infer_type(changes)
       paths = changes.map(&:path)
 
-      # 快速类别判断
+      # Fast paths
       only_docs = paths.all? { |p| doc_path?(p) }
       return 'docs' if only_docs
 
@@ -290,12 +290,12 @@ module KKGit
       only_deps = paths.all? { |p| deps_path?(p) }
       return 'chore' if only_deps
 
-      # 工具/脚本/构建相关：倾向 chore（即便新增代码文件）
+      # Tooling/script/build related: prefer chore (even if code is added)
       if paths.any? && paths.all? { |p| tooling_path?(p) || doc_path?(p) || ci_path?(p) || deps_path?(p) }
         return 'chore'
       end
 
-      # 代码变更的启发式：新增更偏 feat；否则若命中 fix 关键词则 fix；否则 refactor/chore
+      # Heuristics for code changes
       has_code = paths.any? { |p| code_path?(p) }
       has_new_code = changes.any? { |c| c.status == 'A' && code_path?(c.path) }
       has_fix_keyword = paths.any? { |p| p.match?(/fix|bug|error|issue/i) }
@@ -305,7 +305,7 @@ module KKGit
       return 'fix' if has_code && has_fix_keyword
       return 'refactor' if has_code && has_delete
 
-      # 混合场景：按优先级聚合
+      # Mixed: aggregate by priority
       types = changes.map { |c| type_by_path(c.path) }
       pick_main_type(types)
     end
@@ -321,7 +321,7 @@ module KKGit
 
       return 'chore' unless code_path?(path)
 
-      # 默认：代码修改更接近 fix（更保守）；新增则在 infer_type 中处理为 feat
+      # Default: treat code changes as fix (conservative). Adds are handled as feat by infer_type.
       'fix'
     end
 
@@ -409,11 +409,11 @@ module KKGit
         c = changes.first
         action =
           case c.status
-          when 'A' then '新增'
-          when 'D' then '删除'
-          when 'R' then '重命名'
-          when 'C' then '复制'
-          else '更新'
+          when 'A' then 'Add'
+          when 'D' then 'Remove'
+          when 'R' then 'Rename'
+          when 'C' then 'Copy'
+          else 'Update'
           end
 
         if %w[R C].include?(c.status) && c.old_path
@@ -424,21 +424,21 @@ module KKGit
 
       label =
         case scope
-        when 'repo' then '项目'
-        when 'tools' then '工具'
+        when 'repo' then 'project'
+        when 'tools' then 'tools'
         else scope
         end
 
       case type
-      when 'feat' then "添加#{label}功能"
-      when 'fix' then "修复#{label}问题"
-      when 'docs' then "更新#{label}文档"
-      when 'refactor' then "重构#{label}代码"
-      when 'style' then "调整#{label}代码格式"
-      when 'perf' then "优化#{label}性能"
-      when 'test' then "更新#{label}测试"
-      when 'ci' then "更新#{label}CI配置"
-      else "维护#{label}"
+      when 'feat' then "Add #{label} features"
+      when 'fix' then "Fix #{label} issues"
+      when 'docs' then "Update #{label} docs"
+      when 'refactor' then "Refactor #{label}"
+      when 'style' then "Format #{label}"
+      when 'perf' then "Improve #{label} performance"
+      when 'test' then "Update #{label} tests"
+      when 'ci' then "Update #{label} CI"
+      else "Update #{label}"
       end
     end
 
@@ -458,12 +458,12 @@ module KKGit
       end
 
       lines = []
-      append_group(lines, '新增', groups['A'])
-      append_group(lines, '修改', groups['M'])
-      append_group(lines, '删除', groups['D'])
-      append_group(lines, '重命名', groups['R'])
-      append_group(lines, '复制', groups['C'])
-      append_group(lines, '其他', groups['?'])
+      append_group(lines, 'Added', groups['A'])
+      append_group(lines, 'Changed', groups['M'])
+      append_group(lines, 'Removed', groups['D'])
+      append_group(lines, 'Renamed', groups['R'])
+      append_group(lines, 'Copied', groups['C'])
+      append_group(lines, 'Other', groups['?'])
       lines.join("\n")
     end
 

data/lib/kk/git/git_ops.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'tempfile'
+
+module KKGit
+  # Git 仓库操作：供 Rake task 与 CLI 复用。
+  module GitOps
+    class Error < StandardError; end
+
+    # 仓库同步状态快照
+    Status = Struct.new(
+      :branch, :remote, :clean, :ahead, :behind,
+      :upstream_configured, :detached,
+      keyword_init: true
+    ) do
+      # 是否需要与远端同步（有未推送 commit 或落后远端）
+      def needs_sync?
+        ahead.positive? || behind.positive?
+      end
+
+      def unpushed?
+        ahead.positive?
+      end
+
+      def behind_remote?
+        behind.positive?
+      end
+    end
+
+    class << self
+      # @return [Boolean] KK_GIT_DRY_RUN=1 时只打印命令不执行
+      def dry_run?
+        ENV['KK_GIT_DRY_RUN'] == '1'
+      end
+
+      def skip_pull?
+        ENV['KK_GIT_SKIP_PULL'] == '1'
+      end
+
+      def skip_push?
+        ENV['KK_GIT_SKIP_PUSH'] == '1'
+      end
+
+      def amend?
+        ENV['KK_GIT_AMEND'] == '1'
+      end
+
+      def remote
+        ENV.fetch('KK_GIT_REMOTE', 'origin')
+      end
+
+      # @param explicit [String, nil] KK_GIT_BRANCH 或显式传入
+      def branch(explicit: ENV['KK_GIT_BRANCH'])
+        explicit.to_s.strip.empty? ? current_branch : explicit.to_s.strip
+      end
+
+      # git add 路径，默认 `.`；可用 KK_GIT_ADD_PATHS 指定多个路径（空格分隔）
+      def add_paths
+        ENV.fetch('KK_GIT_ADD_PATHS', '.').split(/\s+/).reject(&:empty?)
+      end
+
+      # 会修改仓库状态的 git 子命令；dry-run 时跳过这些命令
+      MUTATING_GIT_COMMANDS = %w[add commit push pull merge rebase checkout reset cherry-pick revert].freeze
+
+      def run_cmd(*cmd, chdir: nil)
+        if dry_run? && mutating_git_command?(cmd)
+          label = chdir ? "(cd #{chdir} && #{cmd.join(' ')})" : cmd.join(' ')
+          puts "[dry-run] #{label}"
+          return ['', '', true]
+        end
+
+        stdout, stderr, status =
+          if chdir
+            Open3.capture3(*cmd, chdir: chdir)
+          else
+            Open3.capture3(*cmd)
+          end
+        [stdout.to_s, stderr.to_s, status.success?]
+      end
+
+      def mutating_git_command?(cmd)
+        cmd[0] == 'git' && MUTATING_GIT_COMMANDS.include?(cmd[1])
+      end
+
+      def ensure_ok!(ok, title, stdout: nil, stderr: nil)
+        return if ok
+
+        msg = +"#{title} failed"
+        msg << "\n#{stderr}" unless stderr.to_s.strip.empty?
+        msg << "\n#{stdout}" unless stdout.to_s.strip.empty?
+        raise Error, msg
+      end
+
+      def in_git_repo?
+        _, _, ok = run_cmd('git', 'rev-parse', '--git-dir')
+        ok
+      end
+
+      def ensure_in_repo!
+        raise Error, 'Not a git repository' unless in_git_repo?
+      end
+
+      def current_branch
+        out, err, ok = run_cmd('git', 'rev-parse', '--abbrev-ref', 'HEAD')
+        ensure_ok!(ok, 'Get current branch', stdout: out, stderr: err)
+        out.strip
+      end
+
+      def detached_head?
+        current_branch == 'HEAD'
+      end
+
+      def ensure_not_detached!
+        raise Error, 'Cannot push from detached HEAD' if detached_head?
+      end
+
+      def working_tree_clean?
+        out, err, ok = run_cmd('git', 'status', '--porcelain')
+        ensure_ok!(ok, 'Check git status', stdout: out, stderr: err)
+        out.strip.empty?
+      end
+
+      def upstream_configured?
+        _, _, ok = run_cmd('git', 'rev-parse', '--abbrev-ref', '@{u}')
+        ok
+      end
+
+      # 相对 upstream / remote/branch 领先的 commit 数
+      def ahead_count(remote, branch)
+        out, _err, ok = run_cmd('git', 'rev-list', '--count', '@{u}..HEAD')
+        return out.strip.to_i if ok
+
+        out, _err, ok = run_cmd('git', 'rev-list', '--count', "#{remote}/#{branch}..HEAD")
+        return out.strip.to_i if ok
+
+        0
+      end
+
+      # 相对 upstream / remote/branch 落后的 commit 数
+      def behind_count(remote, branch)
+        out, _err, ok = run_cmd('git', 'rev-list', '--count', 'HEAD..@{u}')
+        return out.strip.to_i if ok
+
+        out, _err, ok = run_cmd('git', 'rev-list', '--count', "HEAD..#{remote}/#{branch}")
+        return out.strip.to_i if ok
+
+        0
+      end
+
+      def unpushed_commits?(remote, branch)
+        ahead_count(remote, branch).positive?
+      end
+
+      # @return [Status]
+      def status(remote: nil, branch: nil)
+        ensure_in_repo!
+        remote ||= self.remote
+        branch ||= self.branch
+
+        Status.new(
+          branch: branch,
+          remote: remote,
+          clean: working_tree_clean?,
+          ahead: ahead_count(remote, branch),
+          behind: behind_count(remote, branch),
+          upstream_configured: upstream_configured?,
+          detached: detached_head?
+        )
+      end
+
+      def status_hash(remote: nil, branch: nil)
+        s = status(remote: remote, branch: branch)
+        {
+          branch: s.branch,
+          remote: s.remote,
+          clean: s.clean,
+          ahead: s.ahead,
+          behind: s.behind,
+          upstream_configured: s.upstream_configured,
+          detached: s.detached,
+          needs_sync: s.needs_sync?
+        }
+      end
+
+      def pull_remote!(remote, branch)
+        return if skip_pull?
+
+        pull_args = ENV.fetch('KK_GIT_PULL_ARGS', '--ff-only').split
+        out, err, ok = run_cmd('git', 'pull', remote, branch, *pull_args)
+        ensure_ok!(ok, 'git pull', stdout: out, stderr: err)
+      end
+
+      def push_remote!(remote, branch)
+        return if skip_push?
+
+        ensure_not_detached! unless dry_run?
+
+        if upstream_configured?
+          out, err, ok = run_cmd('git', 'push', remote, branch)
+        else
+          out, err, ok = run_cmd('git', 'push', '-u', remote, branch)
+        end
+        ensure_ok!(ok, 'git push', stdout: out, stderr: err)
+      end
+
+      def sync_with_remote!(remote, branch)
+        pull_remote!(remote, branch)
+        push_remote!(remote, branch)
+        puts "Synced: #{remote} #{branch}" unless dry_run?
+      end
+
+      def add_all!
+        paths = add_paths
+        out, err, ok = run_cmd('git', 'add', *paths)
+        ensure_ok!(ok, 'git add', stdout: out, stderr: err)
+      end
+
+      # @return [Boolean] commit 是否成功
+      def commit_with_message!(message)
+        commit_args = amend? ? %w[commit --amend -F] : %w[commit -F]
+
+        Tempfile.create('commit_message') do |f|
+          f.write(message)
+          f.flush
+          out, err, ok = run_cmd('git', *commit_args, f.path)
+          if ok
+            true
+          elsif err.include?('nothing to commit') || out.include?('nothing to commit')
+            puts 'No staged changes to commit'
+            false
+          else
+            ensure_ok!(ok, 'git commit', stdout: out, stderr: err)
+            false
+          end
+        end
+      end
+
+      # 自动 add → commit → pull → push 主流程
+      #
+      # @return [Symbol] :synced | :committed_and_synced | :noop
+      def auto_commit_push!(commit_message_generator: nil)
+        ensure_in_repo!
+        remote_name = remote
+        branch_name = branch
+
+        if working_tree_clean?
+          if status(remote: remote_name, branch: branch_name).needs_sync?
+            sync_with_remote!(remote_name, branch_name)
+            return :synced
+          end
+
+          puts 'No changes to commit or push'
+          return :noop
+        end
+
+        add_all!
+
+        message =
+          if commit_message_generator
+            commit_message_generator.call
+          else
+            KKGit::CommitMessage.generate(mode: :all)
+          end
+        message = message.to_s.strip
+        message = "chore(repo): update project files\n\n#{Time.now}" if message.empty?
+
+        committed = commit_with_message!(message)
+        if committed || unpushed_commits?(remote_name, branch_name)
+          sync_with_remote!(remote_name, branch_name)
+          return committed ? :committed_and_synced : :synced
+        end
+
+        :noop
+      end
+    end
+  end
+end

data/lib/kk/git/rake_tasks.rb

@@ -1,113 +1,72 @@
 # frozen_string_literal: true
 
 require 'rake'
-require 'kk/git'
-require 'open3'
-require 'tempfile'
+require_relative '../git'
 
 module KKGit
-  # Rake 集成：在任意项目的 Rakefile 中 `require 'kk/git/rake_tasks'` 即可注册任务。
+  # Rake integration: `require 'kk/git/rake_tasks'` to register tasks.
   #
-  # 说明：
-  # - 这些任务**不会 exit/abort**，以便在其它 task 中被 invoke。
-  # - 会把生成结果写入 `ENV['KK_GIT_COMMIT_MESSAGE']`，方便上层 task 复用。
+  # Notes:
+  # - These tasks do NOT exit/abort so they can be invoked by other tasks.
+  # - The generated message is stored in `ENV['KK_GIT_COMMIT_MESSAGE']`.
   module RakeTasks
-    def self.run_cmd(*cmd)
-      stdout, stderr, status = Open3.capture3(*cmd)
-      [stdout.to_s, stderr.to_s, status.success?]
-    end
-
-    def self.ensure_ok!(ok, title, stdout: nil, stderr: nil)
-      return if ok
-
-      msg = +"#{title} 失败"
-      msg << "\n#{stderr}" unless stderr.to_s.strip.empty?
-      msg << "\n#{stdout}" unless stdout.to_s.strip.empty?
-      raise msg
-    end
-
-    def self.current_branch
-      out, err, ok = run_cmd('git', 'rev-parse', '--abbrev-ref', 'HEAD')
-      ensure_ok!(ok, '获取当前分支', stdout: out, stderr: err)
-      out.strip
-    end
-
-    def self.working_tree_clean?
-      out, err, ok = run_cmd('git', 'status', '--porcelain')
-      ensure_ok!(ok, '检查 git 状态', stdout: out, stderr: err)
-      out.strip.empty?
-    end
-
     def self.install!
       extend Rake::DSL
 
       namespace :git do
-        desc '根据暂存区变更生成 commit message（Conventional Commits）'
+        desc 'Show branch sync status (ahead/behind/clean)'
+        task :status do
+          s = KKGit::GitOps.status
+          puts "Branch: #{s.branch} (#{s.remote})"
+          puts "Working tree: #{s.clean ? 'clean' : 'dirty'}"
+          puts "Ahead: #{s.ahead}, Behind: #{s.behind}"
+          puts "Upstream: #{s.upstream_configured ? 'configured' : 'not set'}"
+          puts 'Detached HEAD: yes' if s.detached
+        end
+
+        desc 'Pull and push without committing (sync unpushed or behind commits)'
+        task :sync do
+          remote = KKGit::GitOps.remote
+          branch = KKGit::GitOps.branch
+          s = KKGit::GitOps.status(remote: remote, branch: branch)
+
+          if s.needs_sync?
+            KKGit::GitOps.sync_with_remote!(remote, branch)
+          else
+            puts 'Already in sync with remote'
+          end
+        end
+
+        desc 'Generate commit message from staged changes (Conventional Commits)'
         task :commit_message do
           msg = KKGit::CommitMessage.generate(mode: :staged)
           ENV['KK_GIT_COMMIT_MESSAGE'] = msg.to_s
           puts msg if msg
         end
 
-        desc '根据工作区变更生成 commit message（含 untracked）'
+        desc 'Generate commit message from working-tree changes (includes untracked)'
         task :commit_message_worktree do
           msg = KKGit::CommitMessage.generate(mode: :worktree)
           ENV['KK_GIT_COMMIT_MESSAGE'] = msg.to_s
           puts msg if msg
         end
 
-        desc '合并暂存区+工作区变更生成 commit message'
+        desc 'Generate commit message from staged + working-tree changes'
         task :auto_commit do
           msg = KKGit::CommitMessage.generate(mode: :all)
           ENV['KK_GIT_COMMIT_MESSAGE'] = msg.to_s
           puts msg if msg
         end
 
-        desc '自动 add/commit/pull/push（基于 git:auto_commit）'
+        desc 'Auto add/commit/pull/push (uses git:auto_commit)'
         task :auto_commit_push do
-          if working_tree_clean?
-            puts '没有变更需要提交'
-            next
+          generator = lambda do
+            Rake::Task['git:auto_commit'].reenable
+            Rake::Task['git:auto_commit'].invoke
+            ENV['KK_GIT_COMMIT_MESSAGE'].to_s
           end
 
-          remote = ENV.fetch('KK_GIT_REMOTE', 'origin')
-          branch = ENV.fetch('KK_GIT_BRANCH', current_branch)
-
-          # 1) add
-          out, err, ok = run_cmd('git', 'add', '.')
-          ensure_ok!(ok, 'git add', stdout: out, stderr: err)
-
-          # 2) 生成 commit message（允许重复 invoke）
-          Rake::Task['git:auto_commit'].reenable
-          Rake::Task['git:auto_commit'].invoke
-          commit_message = ENV['KK_GIT_COMMIT_MESSAGE'].to_s.strip
-          commit_message = "chore(repo): 更新项目文件\n\n#{Time.now}" if commit_message.empty?
-
-          # 3) commit（用临时文件避免转义问题）
-          Tempfile.create('commit_message') do |f|
-            f.write(commit_message)
-            f.flush
-            out, err, ok = run_cmd('git', 'commit', '-F', f.path)
-            # 没有 staged 变更时 git commit 会失败；这里给出更友好的提示
-            unless ok
-              if err.include?('nothing to commit') || out.include?('nothing to commit')
-                puts '没有暂存变更需要提交'
-                next
-              end
-            end
-            ensure_ok!(ok, 'git commit', stdout: out, stderr: err)
-          end
-
-          # 4) pull（默认使用 --ff-only，避免非交互环境进入合并流程）
-          pull_args = ENV.fetch('KK_GIT_PULL_ARGS', '--ff-only').split
-          out, err, ok = run_cmd('git', 'pull', *pull_args)
-          ensure_ok!(ok, 'git pull', stdout: out, stderr: err)
-
-          # 5) push
-          out, err, ok = run_cmd('git', 'push', remote, branch)
-          ensure_ok!(ok, 'git push', stdout: out, stderr: err)
-
-          puts "✅ 已推送: #{remote} #{branch}"
+          KKGit::GitOps.auto_commit_push!(commit_message_generator: generator)
         end
       end
     end
@@ -115,4 +74,3 @@ module KKGit
 end
 
 KKGit::RakeTasks.install!
-

data/lib/kk/git/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module KKGit
-  VERSION = '0.1.6'
+  VERSION = '0.2.0'
 end
 

data/lib/kk/git.rb

@@ -2,6 +2,7 @@
 
 require_relative 'git/version'
 require_relative 'git/commit_message'
+require_relative 'git/git_ops'
 
 module KKGit
 end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: kk-git
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - kk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-24 00:00:00.000000000 Z
+date: 2026-06-19 00:00:00.000000000 Z
 dependencies: []
-description: 根据当前 Git repo 的变更（暂存/工作区）自动生成 Conventional Commits 格式的 commit message，便于
-  Rake/脚本调用。
+description: Generate Conventional Commits commit messages from current git changes
+  (staged/worktree), designed for Rake/script usage.
 email:
 - ''
 executables:
@@ -22,6 +22,7 @@ files:
 - exe/kk-git
 - lib/kk/git.rb
 - lib/kk/git/commit_message.rb
+- lib/kk/git/git_ops.rb
 - lib/kk/git/rake_tasks.rb
 - lib/kk/git/version.rb
 homepage: ''
@@ -47,5 +48,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Git 辅助工具：自动生成 Conventional Commit 信息
+summary: 'Git helper: generate Conventional Commits messages'
 test_files: []