---
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

```bash
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:

```bash
# 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 (无未跟踪文件)
```bash
/git-add
# 显示：3 个已修改文件
# 提示：是否确认暂存? (y/no)
# 输入 "y" 暂存所有已修改文件
```

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

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

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

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

## Implementation Guide

### 关键实现要点

**1. 文件分类逻辑**
```bash
# 获取所有状态
git status --porcelain

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

**2. 选项显示逻辑**
```python
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. 执行逻辑**
```bash
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