ai/opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 重构命令和技能文档体系，规范化文档格式和内容组织

Browse Source
This commit is contained in:
voson
2026-01-13 10:25:18 +08:00
parent 5a05d5ab53
commit f31f198407
19 changed files with 1055 additions and 2342 deletions
Download Patch File Download Diff File Expand all files Collapse all files

326
command/git-add.md
View File

@@ -2,169 +2,64 @@
description: Stage changes with automatic filtering of sensitive files
---
# git-add
Intelligently stage changes while automatically filtering security-sensitive files.
## What It Does
Please perform the following:
- 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
1. **Detect all unstaged changes:**
- Modified files (M)
- Deleted files (D)
- Untracked files (??) - **重要：第一次就显示并提供选项**
## Quick Start
2. **Filter sensitive files** - Automatically exclude:
- `.env*` - Environment files
- `*.key`, `*.pem`, `*.p8` - Private keys
- `.aws/*`, `.gcloud/*`, `.ssh/*` - Cloud/SSH credentials
- `credentials.json`, `secrets.json` - Credential files
- `node_modules/`, `vendor/`, `.venv/` - Dependencies
- `dist/`, `build/`, `.next/` - Build artifacts
- `.DS_Store`, `Thumbs.db` - System files
Use this command when you want to safely stage changes without accidentally committing sensitive information.
3. **Categorize files:**
- **已跟踪的修改/删除** (tracked modified/deleted)
- **未跟踪的安全文件** (untracked safe files)
- **敏感文件** (sensitive files - filtered)
## 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
4. **Display preview in Chinese:**
```
=== 将要暂存的文件 (N) ===
M [tracked modified files]
D [tracked deleted files]
Categories:
- Modified files (M)
- Deleted files (D)
- Untracked files (??) - **重要：第一次就显示并提供选项**
=== 未跟踪的文件 (N) ===
?? [untracked safe 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)
=== 敏感文件已过滤 (N) ===
⚠ [sensitive files with reasons]
=== 操作选项 ===
- 输入 "y" 或 "yes" 暂存已修改/已删除的文件（不包括未跟踪文件）
- 输入 "all" 暂存所有文件（包括未跟踪文件，但排除敏感文件）
- 输入 "with-untracked" 或 "u" 暂存所有文件（包括未跟踪文件）
- 输入 "force" 强制暂存所有文件（包括敏感文件，谨慎使用）
- 输入 "all" 或 "u" 暂存所有安全文件（包括未跟踪文件）✓ 推荐
- 输入 "force" 强制暂存所有文件（包括敏感文件）⚠️ 谨慎使用
- 输入 "no" 或 "cancel" 取消操作
- 输入文件路径 暂存特定文件
```
### 4. User Confirmation
5. **Wait for 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:
6. **Execute staging based on user choice:**
- `y/yes`: Stage tracked modified/deleted only
- `all/u`: Stage all safe files (including untracked)
- `force`: Show warning, require "confirm" input, then stage everything
- `no/cancel`: Abort
- File path: Stage specific file(s)
7. **Display result in Chinese:**
```
✓ 暂存成功
已暂存 3 个文件：
M src/index.js
M src/utils.js
A command/git-add.md
已暂存 N 个文件：
[列出已暂存的文件]
敏感文件已过滤并排除，保护了你的凭证信息。
@@ -173,149 +68,4 @@ Show success message in Chinese:
- 运行 /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
**重要：第一次运行就显示所有选项，包括未跟踪文件的处理方式，不需要用户多次运行命令。**