catchup

Catchup

目标

快速了解当前分支中的所有变更，提供提交、变更文件和关键修改的智能摘要。本命令针对“重启工作流”进行了优化：运行 /clear 后，使用 /catchup 快速了解进展，无需逐个阅读文件。

输入

• $ARGUMENTS（可选）：用于比较的基分支名称
  • 如果未提供：自动检测 main、master 或 develop
  • 示例：/catchup、/catchup main、/catchup develop

流程

1. 验证 Git 仓库

检查当前目录是否为 Git 仓库：

git rev-parse --git-dir

如果检查失败，告知用户此命令需要在 Git 仓库中运行，然后退出。

2. 检测当前分支和基分支

# Get current branch
CURRENT_BRANCH=$(git branch --show-current)

# If no argument provided, auto-detect base branch
if [ -z "$ARGUMENTS" ]; then
  # Try to find default branch from remote
  DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')

  # Fallback: check if main or master exists
  if [ -z "$DEFAULT_BRANCH" ]; then
    if git show-ref --verify --quiet refs/heads/main; then
      DEFAULT_BRANCH="main"
    elif git show-ref --verify --quiet refs/heads/master; then
      DEFAULT_BRANCH="master"
    elif git show-ref --verify --quiet refs/heads/develop; then
      DEFAULT_BRANCH="develop"
    else
      echo "Could not auto-detect base branch. Please specify: /catchup <base-branch>"
      exit 1
    fi
  fi
  BASE_BRANCH="$DEFAULT_BRANCH"
else
  BASE_BRANCH="$ARGUMENTS"
fi

验证基分支是否存在：

if ! git show-ref --verify --quiet refs/heads/$BASE_BRANCH; then
  echo "Error: Base branch '$BASE_BRANCH' does not exist"
  exit 1
fi

3. 检查变更

确定是否存在任何变更：

# Get commit count ahead
COMMITS_AHEAD=$(git rev-list --count $BASE_BRANCH..HEAD)

# Get changed files count
CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD | wc -l)

如果两项结果均为零：

No changes detected between $CURRENT_BRANCH and $BASE_BRANCH.
Branches are in sync.

正常退出。

4. 收集分支信息

收集完整的分支上下文：

# Commit history (one-line format)
git log --oneline $BASE_BRANCH..HEAD

# Changed files with status
git diff --name-status $BASE_BRANCH...HEAD

# Diff stats (lines added/removed per file)
git diff --stat $BASE_BRANCH...HEAD

# Get uncommitted changes if any
git status --porcelain

5. 整理并呈现摘要

按以下结构呈现信息：

# Branch Catchup: {CURRENT_BRANCH}

## Overview
- **Current Branch**: {CURRENT_BRANCH}
- **Base Branch**: {BASE_BRANCH}
- **Commits Ahead**: {COMMITS_AHEAD}
- **Files Changed**: {total} ({added} added, {modified} modified, {deleted} deleted)
- **Uncommitted Changes**: {Yes/No} ({count} files)

## Commit History

{List commits with hash and message}

## Changed Files by Status

### Added Files
{List of added files}

### Modified Files
{List of modified files with diff stats}

### Deleted Files
{List of deleted files}

## Diff Statistics

{Output from git diff --stat showing lines changed per file}

## Uncommitted Changes
{If any exist, show git status output}

## File Organization

{Group files by directory/component for easier understanding}
Example:
- **Backend (src/)**: 5 files
- **Frontend (ui/)**: 3 files
- **Tests (tests/)**: 2 files
- **Docs (docs/)**: 1 file

## Key Insights

{Analyze commit messages and file changes to provide context}
- Main focus: {infer from commit messages}
- Components affected: {list major areas}
- Potential breaking changes: {flag if file names suggest}

## Next Steps

To see detailed changes in a specific file:
- Read the file directly
- Or git diff: `git diff {BASE_BRANCH}...HEAD -- path/to/file.py`

To resume work:
- Review uncommitted changes if any
- Review any outstanding task list
- Continue implementation

6. 智能读取文件（可选）

仅在以下情况下读取文件内容：

• 变更文件很少（≤3 个）
• 用户明确要求提供更多细节
• 从差异统计信息中无法明确看出文件变更

否则，相信摘要已提供足够的上下文。目标是提高效率——阅读 20 个以上的文件会违背“快速了解进展”的初衷。

错误处理

不在 Git 仓库中

Error: This command requires a git repository.
Current directory is not a git repository.

基分支无效

Error: Base branch '{BASE_BRANCH}' does not exist.
Available branches: {list branches}

Usage: /catchup [base-branch-name]

HEAD 处于分离状态

Warning: You are in a detached HEAD state.
Current commit: {hash}
Cannot determine current branch name.

You may want to create a branch first:
git checkout -b my-branch-name

尚无提交

This appears to be a new repository with no commits.
Cannot compare branches without commit history.

输出指南

• 简洁明了：先显示摘要，用户需要时再提供详情
• 条理清晰：将相关文件分组
• 便于采取行动：根据当前状态建议后续步骤
• 准确无误：仔细解析 Git 输出并处理边缘情况

使用示例

# Basic usage - auto-detect base branch
/catchup

# Compare to specific branch
/catchup develop

# Compare to main explicitly
/catchup main

# After /clear to understand current state
/clear
/catchup  # "What have I been working on?"

与其他命令集成

此命令可与以下命令配合使用：

• /clear - 清除状态，然后使用 /catchup 了解当前内容
• /handoff - 运行 /catchup 后，使用 /handoff 记录工作
• /create-pr - 运行 /catchup 后，在创建 PR 前检查变更
• /check-ci - 运行 /catchup 后，确保测试通过

最终说明

1. 为便于阅读，将输出控制在 1000 行以内
2. 如果差异规模很大（>50 个文件），仅显示统计摘要
3. 聚焦提交和高层次变更，而非逐行差异
4. 让用户能在 30 秒内快速了解分支状态
5. 提供可直接复制到文件读取操作中的文件路径