opencode/command/git-add.md

description

description
Stage changes with automatic filtering of sensitive files

git-add

Intelligently stage changes while automatically filtering security-sensitive files.

What It Does

• Detects all unstaged changes
• Automatically excludes common sensitive files (credentials, secrets, etc.)
• Previews files that will be staged
• Asks for confirmation before staging
• Shows excluded sensitive files for awareness

Quick Start

Use this command when you want to safely stage changes without accidentally committing sensitive information.

Sensitive Files Filtered

Always excluded:

• .env* - Environment files
• *.key, *.pem, *.p8 - Private keys
• .aws/*, .gcloud/* - Cloud credentials
• .ssh/* - SSH keys
• credentials.json, secrets.json - Credential files
• package-lock.json, yarn.lock (optional, can override)
• node_modules/, vendor/, .venv/ - Dependencies
• dist/, build/, .next/ - Build artifacts
• .DS_Store, Thumbs.db - System files

Custom exclusions:

• Can be specified in project .gitignore or .secretsignore

Steps

1. Detect All Unstaged Changes

git status --porcelain
git diff --name-only

Categories:

• Modified files (M)
• Deleted files (D)
• Untracked files (??) - 重要：第一次就显示并提供选项

2. Filter Sensitive Files

Build exclusion list:

• Read .gitignore for patterns
• Read .secretsignore if exists (project-specific rules)
• Apply built-in security patterns
• Check for .env*, *.key, credentials.json, etc.

Separate files into:

• Modified/Deleted files (tracked): 已跟踪的修改和删除
• Untracked files (safe): 未跟踪但安全的新文件
• Sensitive files: 敏感文件（需要 force 才能暂存）

关键逻辑：

• 默认选项 (y): 只暂存已跟踪的修改/删除
• all/u 选项: 暂存所有安全文件（包括未跟踪）
• force 选项: 暂存所有文件（包括敏感）
• 一次性显示所有选项，不需要二次运行命令

3. Display Preview

Show clear summary in format:

=== 将要暂存的文件 (3) ===
M  src/index.js
M  src/utils.js
D  old-file.js

=== 未跟踪的文件 (2) ===
?? new-feature.js
?? tests/new-test.js

=== 敏感文件已过滤 (2) ===
⚠ .env.local (Environment file)
⚠ config/secrets.json (Credential file)

=== 操作选项 ===
- 输入 "y" 或 "yes" 暂存已修改/已删除的文件（不包括未跟踪文件）
- 输入 "all" 暂存所有文件（包括未跟踪文件，但排除敏感文件）
- 输入 "with-untracked" 或 "u" 暂存所有文件（包括未跟踪文件）
- 输入 "force" 强制暂存所有文件（包括敏感文件，谨慎使用）
- 输入 "no" 或 "cancel" 取消操作
- 输入文件路径 暂存特定文件

4. User Confirmation

Prompt user:

是否确认暂存上述文件? (y/all/u/no) 

Options:

• y or yes: Stage modified/deleted files only (exclude untracked)
• all or with-untracked or u: Stage all including untracked files (exclude sensitive)
• force: Stage everything including sensitive files (show warning)
• no or cancel: Abort
• File path: Stage only specific file(s)

智能提示：

• 如果没有未跟踪文件，只显示 y/no 选项
• 如果有未跟踪文件，显示 y/all/u/no 选项，并高亮推荐使用 "all" 或 "u"
• 如果有敏感文件，额外显示 force 选项并警告风险

5. Execute Staging

If user confirms:

# Option 1: Stage modified/deleted only (y)
git add <modified-file-1> <modified-file-2> ...

# Option 2: Stage all including untracked (all/u)
git add <all-safe-files-including-untracked>

# Option 3: Stage everything including sensitive (force)
git add .

Warning for "force" option:

⚠️  警告：你选择暂存所有文件，包括敏感文件！
请确认这是有意的，避免意外提交凭证或密钥。

已暂存的敏感文件：
- .env.local
- config/secrets.json

输入 "confirm" 继续，或 "cancel" 取消操作

Success message for "all/u" option:

✓ 已暂存所有文件（包括未跟踪文件）

已暂存 5 个文件：
  M  src/index.js
  M  src/utils.js
  D  old-file.js
  A  new-feature.js
  A  tests/new-test.js

敏感文件已自动过滤并排除。

6. Display Result

Show success message in Chinese:

✓ 暂存成功

已暂存 3 个文件：
  M  src/index.js
  M  src/utils.js
  A  command/git-add.md

敏感文件已过滤并排除，保护了你的凭证信息。

下一步：
- 运行 /git-commit 生成提交信息并提交
- 运行 /git-status 查看暂存区状态

Safety Features

Automatic Filters

Pattern	Why	Can Override
.env*	Environment variables	No
*.key, *.pem	Private keys	No
credentials.json	API credentials	No
secrets.json	Secrets	No
.aws/*, .gcloud/*	Cloud credentials	No
.ssh/*	SSH keys	No
package-lock.json	Lock files (optional)	Yes

Warnings

• Show count of filtered files
• List filtered file names for transparency
• Warn when using "all" option
• Explain why each sensitive file was excluded

Use Cases

• Stage changes safely before commit
• Prevent accidental credential leaks
• Review what will be committed before staging
• Follow security best practices

Related Commands

• /git-status - Check file changes before staging
• /git-commit - Commit staged files
• /git-push - Push commits to remote

Examples

Normal Usage (无未跟踪文件)

/git-add
# 显示：3 个已修改文件
# 提示：是否确认暂存? (y/no)
# 输入 "y" 暂存所有已修改文件

包含未跟踪文件的情况

/git-add
# 显示：
#   - 3 个已修改/已删除文件
#   - 2 个未跟踪文件
# 提示：是否确认暂存? (y/all/u/no)
# 输入 "y" 仅暂存已修改文件
# 输入 "all" 或 "u" 暂存所有文件（包括未跟踪）

强制暂存敏感文件

/git-add
# 显示：包含 2 个敏感文件
# 提示：是否确认暂存? (y/all/force/no)
# 输入 "force" 强制暂存所有文件
# ⚠️ 显示二次确认警告

暂存特定文件

/git-add
# 显示预览
# 输入文件路径：src/index.js
# 仅暂存指定的文件

取消操作

/git-add
# 显示预览
# 输入 "no" 或 "cancel"
# 操作中止

Implementation Guide

关键实现要点

1. 文件分类逻辑

# 获取所有状态
git status --porcelain

# 分类处理
tracked_modified=()    # M 状态
tracked_deleted=()     # D 状态
untracked_safe=()      # ?? 状态且非敏感
untracked_sensitive=() # ?? 状态且敏感
tracked_sensitive=()   # M/D 状态但匹配敏感规则

2. 选项显示逻辑

if has_untracked_files:
    if has_sensitive_files:
        prompt = "是否确认暂存? (y/all/force/no)"
        options = {
            "y": "仅暂存已跟踪的修改/删除",
            "all/u": "暂存所有安全文件（含未跟踪）",
            "force": "暂存所有文件（含敏感）⚠️",
            "no": "取消操作"
        }
    else:
        prompt = "是否确认暂存? (y/all/no)"
        options = {
            "y": "仅暂存已跟踪的修改/删除",
            "all/u": "暂存所有文件（含未跟踪）✓ 推荐",
            "no": "取消操作"
        }
else:
    prompt = "是否确认暂存? (y/no)"

3. 执行逻辑

case $choice in
    y|yes)
        git add "${tracked_modified[@]}" "${tracked_deleted[@]}"
        ;;
    all|u|with-untracked)
        git add "${tracked_modified[@]}" "${tracked_deleted[@]}" "${untracked_safe[@]}"
        ;;
    force)
        # 二次确认
        read -p "⚠️ 确认暂存敏感文件? (输入 confirm): " confirm
        if [[ "$confirm" == "confirm" ]]; then
            git add .
        fi
        ;;
esac

Notes

• This command prioritizes security over convenience
• Sensitive files must be explicitly forced to stage
• 重要：第一次运行就显示所有选项，不需要用户多次运行命令
• Untracked files are displayed upfront with clear options
• Use .secretsignore file for project-specific exclusion patterns
• Consider setting up git hooks for additional security