Git 交互式提交助手 V2.6 - 完整使用手册¶

写在最前面请详细阅读¶

许可与声明¶

本脚本为开源工具，可自由修改和分发。使用时请遵循以下原则：

✅ 个人和商业项目均可免费使用
✅ 可根据需求自由修改
✅ 建议保留原作者信息
❌ 不提供任何形式的担保
❌ 使用者需自行承担风险

注意！！！如果新建了项目文件夹该脚本不支持一键提交，需要自行手动操作

点击跳转到项目脚本程序源码

最新版 项目进一步修改3.0版本源码项目脚本程序源码2.0版

不想复制粘贴，源码一次性下载路径我的Github仓库

📚 目录¶

简介
系统要求
安装与配置
快速上手
详细功能说明
高级用法
常见问题
故障排查
最佳实践
配置参考

简介¶

这是什么？¶

这是一个 PowerShell 交互式 Git 提交脚本，专门解决以下痛点：

❌ 工作区有 20+ 个文件改动，想分批提交但操作繁琐
❌ 手动 git add 每个文件容易出错
❌ 怕误提交敏感文件（.env、密钥等）
❌ 怕漏掉某些文件没提交
❌ 不确定当前仓库状态是否安全

核心功能¶

✅ 分批提交 - 从文件列表中按编号选择，一次提交一组 ✅ 智能检测 - 自动检查仓库状态、识别风险 ✅ 遗漏提醒 - 实时统计已提交/剩余文件数 ✅ 安全防护 - 敏感文件警告、大文件提醒、主分支保护 ✅ 可视化强 - 彩色输出、状态图标、进度统计 ✅ 容错性好 - 中文路径、空格路径、特殊字符全支持

系统要求¶

必需条件¶

项目	要求	检查方法
操作系统	Windows 10/11	-
PowerShell	5.1 或 7.x	`$PSVersionTable.PSVersion`
Git	2.20+	`git --version`
权限	执行策略允许脚本运行	见下文

安装与配置¶

步骤 1: 下载脚本¶

将脚本保存为 interactive-commit.ps1：

PowerShell

# 保存到常用位置，例如
C:\Scripts\interactive-commit.ps1
# 或项目目录
E:\MyProject\tools\interactive-commit.ps1

⚠️ 重要: 文件必须以 UTF-8 with BOM 编码保存，否则中文会乱码

如何设置编码？

VS Code: 右下角点击编码 → 选择 "UTF-8 with BOM" → 保存
Notepad++: 编码 → 转为 UTF-8 BOM 编码

步骤 2: 设置执行策略¶

PowerShell 默认禁止运行脚本，需要修改策略：

PowerShell

# 方案 1: 仅当前用户允许（推荐）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 方案 2: 临时允许（一次性）
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

验证是否生效：

PowerShell

Get-ExecutionPolicy -List

步骤 3: 配置脚本参数¶

打开脚本，修改顶部的 $Config 变量：

PowerShell

$Config = @{
    # 是否保护主分支（main/master）
    ProtectMainBranch    = $true

    # 敏感文件模式（支持通配符）
    SensitivePatterns    = @(
        ".env",           # 环境变量文件
        "*.key",          # 密钥文件
        "id_rsa",         # SSH 私钥
        "secrets.*",      # secrets.yaml 等
        "*credentials*",  # 包含 credentials 的文件
        "config.prod*"    # 生产配置
    )

    # 大文件阈值（MB）
    LargeFileThresholdMB = 50

    # 备用仓库路径（可选）
    TargetRepoPath       = "E:\pycharm\MyWeb\data-analytics-notes"
}

步骤 4: 测试运行¶

PowerShell

# 进入任意 Git 仓库
cd E:\MyProject

# 运行脚本
.\interactive-commit.ps1

快速上手¶

基础工作流¶

Text Only

1. 运行脚本
   ↓
2. 确认仓库信息（分支、文件数）
   ↓
3. 从列表中选择文件（输入编号）
   ↓
4. 输入 Commit Message
   ↓
5. 重复 3-4 直到文件处理完毕
   ↓
6. 输入 q 进入推送阶段
   ↓
7. 确认推送 → 完成！

示例场景¶

假设你有 10 个文件改动，想分 3 批提交：

PowerShell

PS E:\MyProject> .\interactive-commit.ps1

# 启动信息
[08:00:28] 正在初始化...
[08:00:28] 仓库根目录: E:/MyProject
[08:00:28] 当前分支: feature/new-api
[08:00:28] 检测到 10 个待处理文件

# ========== 第一批：修复 bug ==========
----------------------------------------
待处理变更 (共 10 项)：
 [1] M  src/api/user.js
 [2] M  src/api/auth.js
 [3] ?? tests/user.test.js
 [4] M  README.md
 [5] ?? .env
 ...

指令: [数字]选择 | [a]全选 | [r]刷新 | [q]完成并推送 | [x]强制退出
请输入: 1 2 3

[08:01:05] 正在暂存 3 个文件...
  ✓ src/api/user.js
  ✓ src/api/auth.js
  ✓ tests/user.test.js

Commit Message (留空取消本次提交): fix: 修复用户登录 bug

[08:01:30] ✓ Commit 成功！

# ========== 第二批：更新文档 ==========
----------------------------------------
待处理变更 (共 7 项)：
 [1] M  README.md
 [2] ?? docs/api.md
 [3] ?? .env
 ...

请输入: 1 2

Commit Message: docs: 更新 API 文档

[08:02:10] ✓ Commit 成功！

# ========== 剩余文件提醒 ==========
╔════════════════════════════════════════╗
║  ⚠️  注意：还有 5 个文件未提交！
║  📊 统计：初始 10 个 → 已提交 5 个 → 剩余 5 个
╚════════════════════════════════════════╝

请输入: q

# ========== 遗漏检查 ==========
⚠️  警告：还有 5 个文件未提交！
这些文件将不会被推送到远程仓库。

剩余文件：
  • .env
  • config.prod.json
  ...

确认要结束提交阶段吗？(输入 YES 确认，其他任意键返回)
> YES

# ========== 推送阶段 ==========
[08:03:00] 有 2 个本地提交待推送。

准备推送到远程仓库...
确认推送? (y/n): y

[08:03:05] 正在推送...
[08:03:10] ✓ 推送成功！

📊 本次会话统计：
  • 初始文件数：10
  • 已提交文件：5
  • 遗漏文件数：5

已提交的文件列表：
  • src/api/user.js
  • src/api/auth.js
  • tests/user.test.js
  • README.md
  • docs/api.md

按任意键退出...

详细功能说明¶

1. 启动检查¶

脚本启动时会自动执行以下检查：

1.1 仓库检测¶

PowerShell

[08:00:28] 正在初始化...
[08:00:28] 仓库根目录: E:/MyProject

✅ 自动查找 .git 目录
✅ 支持在子目录中运行
❌ 如果不在仓库内，脚本会终止

1.2 Git 状态检测¶

检查是否有未完成的操作：

状态	说明	脚本行为
`MERGE_HEAD`	正在合并	🛑 阻止运行
`CHERRY_PICK_HEAD`	正在 cherry-pick	🛑 阻止运行
`REVERT_HEAD`	正在 revert	🛑 阻止运行
`rebase-apply`	正在 rebase	🛑 阻止运行
`rebase-merge`	正在 rebase	🛑 阻止运行

如果检测到锁：

Text Only

[08:00:28] 严重警告：检测到 Git 正在进行复杂操作 (MERGE_HEAD)。
[脚本错误] 请先解决 Git 状态锁问题。

如何解决？

PowerShell

# 查看状态
git status

# 完成或中止当前操作
git merge --abort      # 中止合并
git rebase --abort     # 中止 rebase
git cherry-pick --abort # 中止 cherry-pick

1.3 主分支保护¶

如果当前在 main 或 master 分支：

PowerShell

[08:00:28] 当前分支: main
[08:00:28] !!! 警告：当前处于主分支 'main' !!!
确定要继续操作吗？(输入 YES 继续): _

必须输入 YES（大写）才能继续
其他任何输入都会退出脚本
目的: 防止误在主分支提交，建议使用 feature 分支

如何关闭？

PowerShell

# 修改脚本配置
$Config = @{
    ProtectMainBranch = $false  # 改为 false
    ...
}

2. 文件列表显示¶

2.1 状态标识¶

脚本会给不同状态的文件加上颜色：

状态码	含义	颜色	示例
`M`	已修改	🟡 黄色	`[1] M src/index.js`
`A`	已暂存（新增）	🟢 绿色	`[2] A src/new.js`
`??`	未跟踪（新文件）	🟢 绿色	`[3] ?? README.md`
`D`	已删除	🔴 红色	`[4] D old.txt`
`R`	重命名	🟣 紫色	`[5] R old.js -> new.js`

2.2 特殊路径处理¶

脚本能正确处理：

PowerShell

# ✅ 中文路径
[1] ?? 9 months study/银行家算法.md

# ✅ 带空格的路径
[2] M  "My Documents/file name.txt"

# ✅ 重命名
[3] R  old name.md -> new name.md

3. 交互指令¶

3.1 选择文件¶

单选：

PowerShell

请输入: 3
# 只选择第 3 个文件

多选（空格分隔）：

PowerShell

请输入: 1 3 5 7
# 选择 1、3、5、7 号文件

多选（逗号分隔）：

PowerShell

请输入: 1,3,5,7
# 同样选择 1、3、5、7

混合分隔：

PowerShell

请输入: 1, 3  5, 7
# 脚本会自动解析

3.2 特殊指令¶

指令	功能	使用场景
`a`	全选	想一次提交所有文件
`r`	刷新列表	外部修改了文件，需要更新
`q`	完成并推送	已完成提交，进入推送阶段
`x`	强制退出	紧急退出，不推送

示例：

PowerShell

# 全选所有文件
请输入: a
[08:01:05] 已选择全部 10 个文件

# 刷新（如果你在另一个窗口修改了代码）
请输入: r
[08:01:10] 正在刷新文件列表...

# 完成提交，准备推送
请输入: q
[08:01:15] 结束提交阶段，进入推送...

# 紧急退出（不推送）
请输入: x
[08:01:20] 已强制退出，未执行推送。

4. 暂存过程¶

4.1 目录检测¶

脚本会自动跳过目录：

PowerShell

[08:01:05] 正在暂存 5 个文件...
  处理: src/
[08:01:06] 跳过目录: src/
  ✓ src/index.js
  ✓ src/api.js

4.2 敏感文件警告¶

如果选择了敏感文件：

PowerShell

  处理: .env
!!! 敏感文件: .env !!!
确认暂存? (y/n): _

输入 y 继续暂存
输入 n 跳过该文件

触发模式（可配置）：

PowerShell

$Config.SensitivePatterns = @(
    ".env",
    "*.key",
    "id_rsa",
    "secrets.*",
    "*credentials*",
    "config.prod*"
)

4.3 大文件提醒¶

文件超过阈值时：

PowerShell

  处理: video.mp4
[08:01:10] 大文件警告: video.mp4 (156.78 MB)
  ✓ video.mp4

只提醒，不阻止
默认阈值：50 MB
可通过 $Config.LargeFileThresholdMB 修改

4.4 暂存确认¶

暂存成功后显示当前状态：

PowerShell

当前暂存区状态:
A  src/index.js
A  src/api.js
M  README.md
?? .env

绿色的 A/M = 已暂存
红色的 ?? = 未暂存

5. Commit 操作¶

5.1 输入 Message¶

PowerShell

Commit Message (留空取消本次提交): _

规范建议：

Text Only

feat: 添加用户登录功能
fix: 修复购物车计算错误
docs: 更新 API 文档
style: 格式化代码
refactor: 重构支付模块
test: 添加单元测试
chore: 更新依赖版本

5.2 空 Message 取消¶

PowerShell

Commit Message (留空取消本次提交): 

[08:01:30] 已取消提交。
[08:01:30] 正在撤销暂存...

自动执行 git reset HEAD
文件回到未暂存状态
不会丢失改动

5.3 Commit 成功¶

PowerShell

[main e560189] feat: 添加用户登录
 3 files changed, 256 insertions(+)
 create mode 100644 src/login.js
[08:01:35] ✓ Commit 成功！

6. 遗漏检测系统 ⭐¶

这是脚本的核心亮点功能！

6.1 实时统计¶

每轮提交后，如果还有剩余文件：

PowerShell

╔════════════════════════════════════════════════════════════╗
║  ⚠️  注意：还有 3 个文件未提交！
║  📊 统计：初始 10 个 → 已提交 7 个 → 剩余 3 个
║  💡 建议：输入 [r] 刷新列表，确认是否还有文件需要处理
╚════════════════════════════════════════════════════════════╝

6.2 退出二次确认¶

输入 q 时，如果有剩余文件：

PowerShell

⚠️  警告：还有 3 个文件未提交！
这些文件将不会被推送到远程仓库。

剩余文件：
  • config.prod.json
  • .env
  • backup.sql

确认要结束提交阶段吗？(输入 YES 确认，其他任意键返回)
> _

输入 YES → 确认退出，进入推送
其他输入 → 返回文件选择，继续处理

6.3 推送前最终检查¶

即使你确认退出，推送前还会再次检查：

PowerShell

╔════════════════════════════════════════╗
║  ❌ 发现遗漏文件！
║  以下 3 个文件未被提交：
╠════════════════════════════════════════╣
║    • config.prod.json
║    • .env
║    • backup.sql
╠════════════════════════════════════════╣
║  建议返回处理 (输入 n 返回)
╚════════════════════════════════════════╝

仍然继续推送？(y/n): _

输入 y → 推送（但遗漏文件不会被推送）
输入 n → 退出脚本，可重新运行处理

7. 推送阶段¶

7.1 状态检测¶

脚本会智能判断推送情况：

情况	说明	脚本行为
无 upstream	分支首次推送	`git push -u origin <branch>`
落后远端	本地旧于远端	⚠️ 建议先 pull，不推送
领先远端	有新提交待推	✅ 可以推送
已同步	无需推送	ℹ️ 提示已同步

7.2 推送示例¶

场景 1：正常推送

PowerShell

[08:03:00] 有 2 个本地提交待推送。

准备推送到远程仓库...
确认推送? (y/n): y

[08:03:05] 正在推送...
Enumerating objects: 10, done.
Counting objects: 100% (10/10), done.
...
To https://github.com/user/repo.git
   abc1234..def5678  feature -> feature
[08:03:10] ✓ 推送成功！

场景 2：首次推送

PowerShell

[08:03:00] 当前分支无上游分支，需要首次推送。
[08:03:00] 将设置上游分支为: origin/feature-new

确认推送? (y/n): y

[08:03:05] 正在推送...
# 自动执行: git push -u origin feature-new

场景 3：落后远端

PowerShell

[08:03:00] ⚠ 本地落后远端 3 个提交，建议先执行 'git pull'。

# 不会提示推送，需要先同步

8. 最终统计¶

推送完成后，显示会话汇总：

PowerShell

========================================
📊 本次会话统计：
  • 初始文件数：10
  • 已提交文件：7
  • 遗漏文件数：3

已提交的文件列表：
  • src/api/user.js
  • src/api/auth.js
  • tests/user.test.js
  • README.md
  • docs/api.md
  • src/utils/helper.js
  • package.json

⚠️  提醒：有 3 个文件未提交

按任意键退出...

高级用法¶

1. 快捷方式配置¶

方法 1：添加到 PATH

PowerShell

# 将脚本目录加入 PATH
$env:PATH += ";C:\Scripts"

# 现在可以在任何位置运行
cd E:\MyProject
interactive-commit.ps1

方法 2：PowerShell 别名

PowerShell

# 添加到 PowerShell 配置文件
notepad $PROFILE

# 添加这行
Set-Alias gic "C:\Scripts\interactive-commit.ps1"

# 重新加载配置
. $PROFILE

# 使用别名
gic

方法 3：右键菜单（Windows）

PowerShell

# 创建 .reg 文件添加右键菜单
Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\Directory\Background\shell\GitCommit]
@="Git 交互提交"

[HKEY_CLASSES_ROOT\Directory\Background\shell\GitCommit\command]
@="powershell.exe -NoExit -File \"C:\\Scripts\\interactive-commit.ps1\""

2. 批量操作技巧¶

技巧 1：按文件类型分批¶

PowerShell

# 第一批：提交所有 .js 文件（假设是 1-5 号）
请输入: 1 2 3 4 5
Commit Message: feat: 更新 JavaScript 模块

# 第二批：提交所有 .md 文件（6-8 号）
请输入: 6 7 8
Commit Message: docs: 更新文档

# 第三批：提交配置文件（9-10 号）
请输入: 9 10
Commit Message: chore: 更新配置

技巧 2：使用刷新功能¶

PowerShell

# 场景：你想修改某个文件后再提交

请输入: 1 2 3   # 先提交前 3 个
Commit Message: fix: 修复 bug

# 此时你在编辑器中修改了第 4 个文件

请输入: r        # 刷新列表
# 列表会更新，确保第 4 个文件的最新状态

请输入: 4        # 提交修改后的文件

技巧 3：分阶段提交¶

PowerShell

# 阶段 1：核心功能
选择: 1-10
Message: feat: 实现核心功能模块

# 阶段 2：测试
选择: 11-15
Message: test: 添加单元测试

# 阶段 3：文档
选择: 16-20
Message: docs: 完善使用文档

# 阶段 4：样式调整
选择: 21-25
Message: style: 优化代码格式

3. 自定义配置模板¶

根据不同项目需求，创建配置变体：

模板 1：敏感项目（严格模式）

PowerShell

$Config = @{
    ProtectMainBranch    = $true
    SensitivePatterns    = @(
        ".env*",
        "*.key",
        "*.pem",
        "*.p12",
        "id_rsa*",
        "secrets*",
        "*password*",
        "*token*",
        "*.pfx",
        "config.prod*",
        "database.json"
    )
    LargeFileThresholdMB = 20  # 更严格
    TargetRepoPath       = ""
}

模板 2：开源项目（宽松模式）

PowerShell

$Config = @{
    ProtectMainBranch    = $false  # 允许主分支提交
    SensitivePatterns    = @(
        ".env"  # 仅基本保护
    )
    LargeFileThresholdMB = 100  # 允许大文件
    TargetRepoPath       = ""
}

模板 3：多媒体项目

PowerShell

$Config = @{
    ProtectMainBranch    = $true
    SensitivePatterns    = @(".env")
    LargeFileThresholdMB = 500  # 视频/图片项目
    TargetRepoPath       = ""
}

4. 团队协作规范¶

规范 1：Commit Message 规范¶

建议团队统一使用以下格式：

Text Only

<type>(<scope>): <subject>

<body>

<footer>

示例：

Text Only

feat(auth): 添加双因素认证

- 实现 TOTP 验证
- 添加备用验证码
- 更新用户设置页面

Closes #123

Type 类型：

feat: 新功能
fix: 修复 bug
docs: 文档
style: 格式（不影响代码）
refactor: 重构
perf: 性能优化
test: 测试
chore: 构建/工具

规范 2：分支命名¶

Text Only

feature/user-authentication
bugfix/login-error
hotfix/security-patch
release/v1.2.0

规范 3：提交频率¶

✅ 推荐: 每个逻辑功能一个 commit
✅ 推荐: 每天至少推送一次
❌ 避免: 一个 commit 包含无关改动
❌ 避免: 提交信息模糊（如 "update"）

常见问题¶

Q1: 脚本无法运行，提示"无法加载"？¶

原因: 执行策略限制

解决:

PowerShell

# 临时允许
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

# 永久允许（当前用户）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q2: 中文文件名显示乱码或无法选择？¶

原因: 文件编码不是 UTF-8 with BOM

解决:

用 VS Code 打开脚本
右下角点击编码（如 "UTF-8"）
选择 "Save with Encoding"
选择 "UTF-8 with BOM"
重新运行脚本

Q3: 提示"路径中具有非法字符"？¶

原因: PowerShell 版本过旧或路径特殊字符

解决:

PowerShell

# 检查 PowerShell 版本
$PSVersionTable.PSVersion

# 如果是 5.1，升级到 7.x
winget install Microsoft.PowerShell

Q4: 文件消失了，明明有变更但列表不显示？¶

原因: Git 忽略规则或文件在 .gitignore 中

检查:

PowerShell

# 查看完整状态
git status --ignored

# 检查特定文件
git check-ignore -v <文件路径>

# 强制添加（如果确实需要）
git add -f <文件路径>

Q5: 推送失败，提示"权限拒绝"？¶

可能原因:

GitHub token 过期
SSH 密钥未配置
仓库无写权限

解决:

PowerShell

# 检查远程 URL
git remote -v

# HTTPS 方式：更新 token
git remote set-url origin https://<token>@github.com/user/repo.git

# SSH 方式：检查密钥
ssh -T git@github.com

Q6: 如何撤销刚才的提交？¶

场景 1：还没推送

PowerShell

# 撤销最近一次 commit，保留改动
git reset --soft HEAD~1

# 撤销 commit 和暂存，保留改动
git reset HEAD~1

# 完全撤销（危险！）
git reset --hard HEAD~1

场景 2：已经推送

PowerShell

# 创建反向提交
git revert HEAD

# 强制覆盖（团队慎用！）
git push -f origin <branch>

Q7: 脚本运行很慢？¶

可能原因:

文件数量太多（500+ 个）
仓库体积太大
网络问题

优化:

PowerShell

# 查看仓库大小
git count-objects -vH

# 清理不需要的文件
git clean -fd

# 忽略大型文件夹（添加到 .gitignore）
node_modules/
.venv/
dist/

Q8: 想跳过敏感文件检查？¶

临时跳过: 在脚本运行时，看到警告直接输入 y

永久跳过:

PowerShell

# 修改配置
$Config = @{
    SensitivePatterns = @()  # 清空规则
}

Q9: 如何处理重命名文件？¶

脚本会自动检测重命名（显示为 R old -> new），选择后会正确提交：

PowerShell

[5] R  src/old-name.js -> src/new-name.js

# 选择时只需输入编号
请输入: 5

# Git 会自动处理重命名

注意: Git 通过相似度检测重命名，至少 50% 相同

Q10: 能否同时运行多个脚本实例？¶

不推荐！ 可能导致：

暂存区冲突
Commit 混乱
推送冲突

如果必须: 在不同分支、不同仓库中运行

故障排查¶

排查流程¶

Text Only

1. 检查 PowerShell 版本
   ↓
2. 检查 Git 版本和配置
   ↓
3. 检查文件编码（UTF-8 with BOM）
   ↓
4. 检查执行策略
   ↓
5. 查看详细错误信息
   ↓
6. 尝试手动执行 Git 命令

诊断命令¶

PowerShell

# 1. 系统信息
$PSVersionTable
git --version
Get-ExecutionPolicy -List

# 2. 仓库状态
git status
git branch -vv
git remote -v

# 3. 脚本文件检查
Get-Content .\interactive-commit.ps1 -Encoding UTF8 | Select-Object -First 5

# 4. 测试 Git 命令
git status --porcelain=v1
git rev-parse --show-toplevel

# 5. 权限检查
Test-Path .git -PathType Container
(Get-Item .git).Attributes

最佳实践¶

1. 提交前检查清单¶

2. 分批提交策略¶

按功能分批:

Text Only

第 1 批: 核心逻辑实现
第 2 批: 错误处理
第 3 批: 单元测试
第 4 批: 文档更新

按文件类型分批:

Text Only

第 1 批: 后端代码 (*.js, *.py)
第 2 批: 前端代码 (*.vue, *.css)
第 3 批: 配置文件 (*.json, *.yaml)
第 4 批: 文档 (*.md)

3. Commit Message 最佳实践¶

好的示例:

Text Only

✅ feat(auth): 添加 JWT 认证中间件
✅ fix(api): 修复用户查询空指针异常
✅ docs: 更新 API 文档 v2.0
✅ refactor(db): 优化数据库连接池配置

不好的示例:

Text Only

❌ update
❌ fix bug
❌ 改了一些东西
❌ asjdlkajsdlkj

4. 分支管理建议¶

Text Only

main (生产)
  ├── develop (开发)
  │    ├── feature/user-login
  │    ├── feature/payment
  │    └── feature/notification
  ├── hotfix/security-patch
  └── release/v1.2.0

工作流:

从 develop 创建 feature 分支
开发完成后用脚本分批提交
推送到远程
创建 Pull Request
Code Review 后合并

5. 团队协作规范¶

规范 1: 提交频率

每完成一个小功能就提交
每天至少推送一次
下班前确保代码已推送

规范 2: 分支命名

Text Only

feature/<功能名>     # 新功能
bugfix/<bug描述>     # bug 修复
hotfix/<紧急修复>    # 生产热修复
release/<版本号>     # 发布分支

规范 3: Code Review

提交前自查代码
保持提交粒度适中
及时响应 Review 意见

配置参考¶

完整配置说明¶

PowerShell

$Config = @{
    # ============ 分支保护 ============
    # 是否保护主分支（防止误提交到 main/master）
    # true: 需要输入 YES 确认
    # false: 直接允许
    ProtectMainBranch = $true

    # ============ 敏感文件规则 ============
    # 支持通配符匹配（*, ?）
    # 匹配时会高亮警告并要求二次确认
    SensitivePatterns = @(
        ".env",           # 环境变量
        ".env.*",         # .env.local, .env.production
        "*.key",          # 密钥文件
        "*.pem",          # SSL 证书
        "id_rsa",         # SSH 私钥
        "id_rsa.*",       # id_rsa.pub 等
        "secrets.*",      # secrets.yaml, secrets.json
        "*credentials*",  # credentials.txt, aws-credentials
        "*password*",     # password.txt, passwords.json
        "*token*",        # api-token.txt, tokens.json
        "config.prod*",   # config.production.js
        "*.pfx",          # Windows 证书
        "*.p12"           # iOS 证书
    )

    # ============ 大文件阈值 ============
    # 单位：MB
    # 超过此大小会警告（但不阻止）
    LargeFileThresholdMB = 50

    # ============ 备用仓库路径 ============
    # 如果当前目录找不到仓库，尝试此路径
    # 留空 "" 表示不使用备用路径
    TargetRepoPath = ""

    # 或指定具体路径：
    # TargetRepoPath = "E:\Projects\MyRepo"
}

按项目类型推荐配置¶

Web 前端项目:

PowerShell

$Config = @{
    ProtectMainBranch = $true
    SensitivePatterns = @(".env*", "*.key", "*token*")
    LargeFileThresholdMB = 10  # 前端资源不应太大
    TargetRepoPath = ""
}

后端 API 项目:

PowerShell

$Config = @{
    ProtectMainBranch = $true
    SensitivePatterns = @(
        ".env*",
        "database.*",
        "*credentials*",
        "config.prod*"
    )
    LargeFileThresholdMB = 50
    TargetRepoPath = ""
}

数据科学项目:

PowerShell

$Config = @{
    ProtectMainBranch = $false  # 经常需要在 main 提交
    SensitivePatterns = @(".env", "*.key")
    LargeFileThresholdMB = 500  # 允许大型数据集
    TargetRepoPath = ""
}

进阶技巧¶

1. 集成到 IDE¶

VS Code 集成:

安装 "Tasks" 扩展
创建 .vscode/tasks.json:

JSON

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Git 交互提交",
      "type": "shell",
      "command": "powershell",
      "args": [
        "-File",
        "C:\\Scripts\\interactive-commit.ps1"
      ],
      "problemMatcher": [],
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated"
      }
    }
  ]
}

按 Ctrl+Shift+P → "Tasks: Run Task" → 选择任务

2. 自动化脚本链¶

PowerShell

# pre-commit.ps1 - 提交前自动检查
.\lint-check.ps1          # 代码格式检查
.\run-tests.ps1           # 运行测试
.\interactive-commit.ps1  # 交互式提交

3. 日志记录¶

在脚本末尾添加日志功能：

PowerShell

# 记录每次运行
$logFile = "commit-history.log"
$logEntry = @"
==========
Time: $(Get-Date)
Branch: $currentBranch
Files Committed: $($Global:CommittedFiles.Count)
Files: $($Global:CommittedFiles -join ", ")
==========
"@
Add-Content -Path $logFile -Value $logEntry

更新日志¶

V2.6 (当前版本)¶

✨ 修复单文件显示问题
✨ 增强路径引号处理
✨ 修复字符转义语法错误
✨ 改进错误处理机制

V2.5¶

✨ 修复中文路径解析
✨ 增加文件遗漏检测
✨ 改进路径处理逻辑

V2.4¶

✨ 彻底修复中文文件名
✨ 增加遗漏检测警告
✨ 改进数组处理

V2.3¶

✨ 修复退出逻辑
✨ 改进文件解析
✨ 增加手动退出确认

支持与反馈¶

获取帮助¶

查看内置帮助:

PowerShell

Get-Help .\interactive-commit.ps1 -Full

调试模式:

PowerShell

# 查看详细输出
$VerbosePreference = "Continue"
.\interactive-commit.ps1

错误诊断:

PowerShell

# 捕获完整错误
.\interactive-commit.ps1 2>&1 | Tee-Object -FilePath error.log

附录¶

A. Git 状态码对照表¶

状态	含义	XY 格式
`??`	未跟踪	`??`
`A`	已暂存（新增）	`A`
`M`	工作区修改	`M`
`M`	暂存区修改	`M`
`MM`	暂存+工作区都修改	`MM`
`D`	已删除（暂存）	`D`
`D`	工作区删除	`D`
`R`	重命名	`R`
`C`	复制	`C`
`U`	未合并	`UU`

B. 快捷键参考¶

操作	按键
退出当前输入	`Ctrl+C`
清空输入	`Esc`
历史命令	`↑` / `↓`
粘贴	`右键` 或 `Ctrl+V`

C. 相关资源¶

许可与声明¶

本脚本为开源工具，可自由修改和分发。使用时请遵循以下原则：

✅ 个人和商业项目均可免费使用
✅ 可根据需求自由修改
✅ 建议保留原作者信息
❌ 不提供任何形式的担保
❌ 使用者需自行承担风险

文档版本: 1.0 最后更新: 2025年12月

💡 提示: 按 Ctrl+F 搜索关键词快速定位问题解决方案！

一、项目解决的痛点¶

在真实开发里，最容易翻车的场景之一就是：一次改动太多文件，提交又不想“一锅端”。

比如你今天同时改了：业务代码、测试、文档、配置、临时文件……git status 一看几十个变更。接下来会出现一堆常见痛点：

分批提交很麻烦：需要反复 git add <file>，文件多时操作机械且耗时
容易误提交敏感信息：.env、token、密钥、生产配置一不小心就进仓库（甚至被 push 上远端）
容易漏提交：提交完以为“都好了”，结果还有文件没 commit，push 后才发现改动没上去
分支风险：人在 main/master 上没注意就直接 commit，后续 PR/回滚都更麻烦
仓库状态不安全：merge/rebase 过程中误操作提交，会把历史搞乱，排查成本极高

这个脚本的价值就是把这些风险和重复劳动“流程化”：交互式选文件 → 分批 commit → 漏项提醒 → 推送前二次检查 → 关键风险拦截/警告，让提交这件事更可控、更安全。

注：本项目借助AI工具完成¶

项目完整提示词如下：

1.1项目AI完整提示词¶

Text Only

## PowerShell 交互式分批提交 GitHub 提示词（完整规格）

你是一个资深 DevOps/Windows 自动化工程师。请用 **PowerShell（ps1）** 编写一个 **交互式 Git 提交脚本**，用于把本地多文件改动按用户选择分批提交，并最终推送到 GitHub。脚本必须稳健、可读、可维护，并对常见风险做防护。

### 1. 运行环境与约束

- 运行环境：Windows PowerShell 5.1 或 PowerShell 7+
- 假设用户已安装 Git，并且 `git` 命令在 PATH 中
- **禁止**依赖第三方 PowerShell 模块（仅用系统自带能力 + git 命令）
- 脚本默认在当前目录运行，但必须能自动定位仓库根目录（或至少提示用户进入仓库后再运行）

------

### 2. 启动前检查（必须）

脚本启动后必须执行以下检查，任何一项失败都要停止并给出可读提示：

1. **是否在 git 仓库内**

- 使用 `git rev-parse --is-inside-work-tree`

1. **检测是否存在未完成的 git 操作**

- rebase/merge/cherry-pick 等进行中应直接阻止脚本继续
- 检测方法（任选其一）：
  - 检查 `.git` 下相关文件：`MERGE_HEAD` / `CHERRY_PICK_HEAD` / `rebase-apply` / `rebase-merge`
  - 或 git 命令检测状态（但不要解析人类输出）

1. **显示当前分支、远端信息**

- 显示 `git branch --show-current`
- 显示 `git remote -v`

1. **主分支保护（可配置）**

- 若当前分支为 `main` 或 `master`，默认给出强提醒：
  - 允许继续，但必须二次确认（输入 YES 才能继续），以防误在主分支上直接提交
- 支持通过脚本顶部变量配置是否允许主分支直接提交

------

### 3. 获取变更文件列表（必须用机器可解析输出）

- 不能解析普通 `git status` 的人类文本输出
- 必须使用以下之一：
  - `git status --porcelain=v1 -z`（优先推荐，能处理空格/中文路径）
- 文件列表需包含：
  - 未跟踪（??）
  - 已修改（M）
  - 新增（A）
  - 删除（D）
  - 重命名（R）——如出现重命名，需以“新路径”为提交对象，并在展示时提示 old -> new

------

### 4. 交互式显示与选择（核心功能）

1. 将所有待处理变更按编号打印，例如：

- `[1] M docs/index.md`
- `[2] ?? src/new file.txt`
- `[3] D old/removed.md`
- `[4] R old/name.md -> new/name.md`

1. 提示用户输入要提交的编号（支持多选）

- 格式：`1 2 5`（空格分隔）
- 对非法编号、重复编号、空输入要有提示并重新输入
- 提供特殊指令：
  - `q` 退出脚本（不做 push）
  - `r` 刷新文件列表
  - `a` 选择全部（可选但建议）

1. **目录处理要求**

- 如果用户选择项中包含“目录路径”（PathType=Container）：
  - 必须忽略该项
  - 输出提醒：“检测到目录 xxx，已忽略；目录请自行单独提交”
- 说明：即便 `git status` 多数情况下返回文件路径，也要考虑用户输入可能包含目录、子模块、或路径异常

------

### 5. 暂存行为（必须）

- 对用户本轮选择的每个路径执行暂存操作
- 必须能正确处理删除/重命名/新增等情况，建议用：
  - `git add -A -- <path>`
- 暂存后必须打印一次状态确认：
  - `git status`（可读输出即可），并突出显示 staged 状态

------

### 6. Commit 行为（必须）

- 暂存确认后，提示用户输入 commit message
- commit message 不能为空；为空则取消本轮 commit（但要提示暂存区可能已变化）
- 支持“一次提交多个文件使用同一个 commit message”
- commit 执行：
  - `git commit -m "<message>"`
- commit 成功后必须输出：
  - 本次 commit 的简要信息（hash、标题）
  - 本次 commit 包含哪些文件（例如 `git show --name-only --oneline -1`）

------

### 7. 循环机制（必须）

- 完成一次 commit 后，自动回到“文件列表展示与选择”步骤
- 直到：
  - 工作区无可提交变更（脚本提示 Done 并进入 push 阶段），或
  - 用户输入 `q` 退出

------

### 8. Push 行为（必须且要安全）

- 不要写死 `git push origin main`，因为用户可能在 feature 分支上
- 默认推送策略：
  1. 获取当前分支名 `branch`
  2. 如果该分支尚未设置 upstream，则使用：
     - `git push -u origin <branch>`
  3. 若已设置 upstream，则：
     - `git push`
- 仅当当前分支就是 `main`（或用户明确选择“推 main”）时，才允许 `git push origin main`
- push 前必须二次确认（y/n）

------

### 9. 日志与结果输出（必须）

- 每轮操作都要有明确提示（正在做什么、用什么命令、结果如何）
- 脚本最后必须：
  - 执行并打印 `git status` 最终状态
  - 输出一句总结：
    - `xxx路径/xxx文件已提交`（列出本次脚本会话中提交过的文件清单，去重排序）
  - 若未 push，也要明确提示“本次未推送到远端”

------

### 10. 错误处理（必须）

- 每条 git 命令都要检查退出码
- 任意关键步骤失败（add/commit/push）必须：
  - 打印 stderr
  - 停止后续步骤（不要继续执行下一步）
- 对可能导致仓库混乱的场景要停止并提示：
  - merge/rebase 进行中
  - 没有任何变更
  - 用户输入无效

------

### 11. 安全防护（强烈建议实现）

1. **敏感文件检测**

- 若用户选择的文件匹配以下模式，输出高亮警告并要求再次确认才能继续暂存：
  - `.env`、`*.key`、`id_rsa`、`secrets.*`、`credentials*`、`config.prod*`
- 只警告不自动阻止（可配置）

1. **大文件提醒**

- 若文件大小超过阈值（例如 50MB），警告可能 push 失败或不适合进 git

------

### 12. 交互体验要求（建议）

- 输出要清晰、分段、尽量少噪音
- 对每一步给用户明确下一步操作提示
- 允许 `Ctrl+C` 安全中断（提示可能产生的暂存影响）

------

### 13. 交付形式

- 输出一个 `.ps1` 文件内容
- 脚本开头写明：
  - 使用方法（如何运行、是否需要执行策略）
  - 可配置参数（是否允许 main 提交、敏感文件规则、大小阈值、是否自动 push）

------

## 主要风险点

- 推送写死 main 会误推/推不出去（必须改为推当前分支）
- 分批按文件提交可能把一个功能拆成多个 commit，历史可读性差（需要提醒“同一逻辑尽量同一次提交”）
- 删除/重命名如果只用 `git add file` 可能暂存不完整（用 `git add -A -- path`）
- 解析普通 `git status` 会被空格/中文路径/重命名格式坑（必须用 `--porcelain -z`）
- rebase/merge 进行中提交会让仓库更乱（必须阻止）

1.2 脚本完整文件¶

PowerShell

<#
.SYNOPSIS
    交互式 Git 分批提交助手 (V2.6 - 稳定运行版)
    修复内容：
    1. 修复单文件显示问题
    2. 修复路径引号处理
    3. 修复字符转义语法错误
    注意：请务必将此文件保存为 "UTF-8 with BOM" 编码格式
#>

# -----------------------------------------------------------------------------
# 0. 配置与初始化
# -----------------------------------------------------------------------------

$OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

$Config = @{
    ProtectMainBranch    = $true
    SensitivePatterns    = @(".env", "*.key", "id_rsa", "secrets.*", "*credentials*", "config.prod*")
    LargeFileThresholdMB = 50
    TargetRepoPath       = "这里改成你的git本地仓库"
}

$Global:CommittedFiles = @()
$Global:InitialFileCount = 0

# -----------------------------------------------------------------------------
# 1. 辅助函数
# -----------------------------------------------------------------------------

function Write-Log {
    param([string]$Message, [string]$Level = "Info", [switch]$NoNewLine)
    $color = "Cyan"
    switch ($Level) {
        "Success" { $color = "Green" }
        "Warn"    { $color = "Yellow" }
        "Error"   { $color = "Red" }
    }
    $timeStr = (Get-Date -Format "HH:mm:ss")
    Write-Host "[$timeStr] $Message" -ForegroundColor $color -NoNewline:$NoNewLine
}

function Get-GitRoot {
    $root = git rev-parse --show-toplevel 2>$null
    if ($LASTEXITCODE -eq 0 -and $root) { return $root }

    if (Test-Path $Config.TargetRepoPath) {
        Push-Location $Config.TargetRepoPath
        try {
            $root = git rev-parse --show-toplevel 2>$null
            if ($LASTEXITCODE -eq 0 -and $root) { return $root }
        } finally {
            Pop-Location
        }
    }
    return $null
}

function Check-GitState {
    $gitDir = git rev-parse --git-dir 2>$null
    if (-not $gitDir) { return $true }

    $blockers = @("MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "rebase-apply", "rebase-merge", "BISECT_LOG")
    foreach ($item in $blockers) {
        $lockPath = Join-Path $gitDir $item
        if (Test-Path $lockPath) {
            Write-Log "严重警告：检测到 Git 正在进行复杂操作 ($item)。" "Error"
            return $false
        }
    }
    return $true
}

function Parse-GitStatus {
    $rawLines = git -c core.quotepath=false status --porcelain=v1 2>$null

    # 强制转换为数组
    if ($rawLines -is [string]) {
        $rawLines = @($rawLines)
    }

    if (-not $rawLines -or $rawLines.Count -eq 0) { 
        return @() 
    }

    $results = [System.Collections.ArrayList]@()
    $index = 1

    foreach ($line in $rawLines) {
        if ([string]::IsNullOrWhiteSpace($line) -or $line.Length -lt 3) { 
            continue 
        }

        try {
            $status = $line.Substring(0, 2)
            $rest   = $line.Substring(3).Trim()

            if ([string]::IsNullOrWhiteSpace($rest)) { continue }

            # 移除 Git 添加的路径引号
            if ($rest.StartsWith('"') -and $rest.EndsWith('"') -and $rest.Length -gt 1) {
                $rest = $rest.Substring(1, $rest.Length - 2)
            }

            $obj = [PSCustomObject]@{
                Index   = $index
                Status  = $status
                Path    = ""
                OldPath = $null
                Display = ""
                RawLine = $line
            }

            # 处理重命名
            if ($status -match "^R") {
                if ($rest -match '^(.+?)\s+->\s+(.+)$') {
                    $oldPath = $matches[1].Trim()
                    $newPath = $matches[2].Trim()

                    # 分别去除引号
                    if ($oldPath.StartsWith('"') -and $oldPath.EndsWith('"')) {
                        $oldPath = $oldPath.Substring(1, $oldPath.Length - 2)
                    }
                    if ($newPath.StartsWith('"') -and $newPath.EndsWith('"')) {
                        $newPath = $newPath.Substring(1, $newPath.Length - 2)
                    }

                    $obj.OldPath = $oldPath
                    $obj.Path    = $newPath
                    $obj.Display = "$status $oldPath -> $newPath"
                } else {
                    $obj.Path = $rest
                    $obj.Display = "$status $rest"
                }
            } else {
                $obj.Path = $rest
                $obj.Display = "$status $rest"
            }

            [void]$results.Add($obj)
            $index++

        } catch {
            Write-Host "警告：无法解析行: $line" -ForegroundColor Yellow
            continue
        }
    }

    return $results.ToArray()
}

function Get-SafeCount {
    param($Collection)
    if ($null -eq $Collection) { return 0 }
    if ($Collection -is [array]) { return $Collection.Count }
    if ($Collection -is [System.Collections.ICollection]) { return $Collection.Count }
    return 1
}

function Show-RemainingFilesWarning {
    param([int]$Remaining, [int]$Total, [int]$Committed)

    if ($Remaining -gt 0) {
        Write-Host ""
        Write-Host "╔════════════════════════════════════════════════════════════╗" -ForegroundColor Yellow
        Write-Host "║  ⚠️  注意：还有 $Remaining 个文件未提交！" -ForegroundColor Yellow
        Write-Host "║  📊 统计：初始 $Total 个 → 已提交 $Committed 个 → 剩余 $Remaining 个" -ForegroundColor Yellow
        Write-Host "║  💡 建议：输入 [r] 刷新列表，确认是否还有文件需要处理" -ForegroundColor Yellow
        Write-Host "╚════════════════════════════════════════════════════════════╝" -ForegroundColor Yellow
        Write-Host ""
    }
}

function Get-SafeFullPath {
    param([string]$RepoRoot, [string]$RelativePath)

    try {
        # 使用字符串拼接，避免 Join-Path 的问题
        $sep = [System.IO.Path]::DirectorySeparatorChar
        $cleanRoot = $RepoRoot.TrimEnd(@('\', '/'))
        $cleanRel = $RelativePath.TrimStart(@('\', '/'))
        return "$cleanRoot$sep$cleanRel"
    } catch {
        return $RelativePath
    }
}

# -----------------------------------------------------------------------------
# 2. 主逻辑
# -----------------------------------------------------------------------------

try {
    Write-Log "正在初始化..."
    if (-not (Get-Command git -ErrorAction SilentlyContinue)) { 
        throw "未找到 git 命令。" 
    }

    $repoRoot = Get-GitRoot
    if (-not $repoRoot) { 
        throw "未找到有效的 Git 仓库。" 
    }

    Set-Location $repoRoot
    Write-Log "仓库根目录: $repoRoot" "Success"

    if (-not (Check-GitState)) { 
        throw "请先解决 Git 状态锁问题。" 
    }

    $currentBranch = git branch --show-current
    if (-not $currentBranch) { 
        $currentBranch = "DETACHED_HEAD" 
    }
    Write-Log "当前分支: $currentBranch" "Info"

    if ($Config.ProtectMainBranch -and ($currentBranch -in "main", "master")) {
        Write-Log "!!! 警告：当前处于主分支 '$currentBranch' !!!" "Warn"
        $confirm = Read-Host "确定要继续操作吗？(输入 YES 继续)"
        if ($confirm -ne "YES") { 
            Write-Log "已取消。" "Info"
            exit 0 
        }
    }

    # 记录初始文件数
    $initialChanges = Parse-GitStatus
    $Global:InitialFileCount = Get-SafeCount $initialChanges
    Write-Log "检测到 $Global:InitialFileCount 个待处理文件" "Info"

    $doLoop = $true
    while ($doLoop) {
        Write-Host "`n----------------------------------------" -ForegroundColor Gray

        $changes = Parse-GitStatus
        $remainingCount = Get-SafeCount $changes

        if ($remainingCount -eq 0) {
            Write-Log "✓ 工作区干净，所有文件已处理完毕！" "Success"
            break
        }

        # 显示文件列表
        Write-Host "待处理变更 (共 $remainingCount 项)：" -ForegroundColor Cyan

        foreach ($change in $changes) {
            $color = "White"
            if ($change.Status -like "M*") { $color = "Yellow" }
            elseif ($change.Status -like "A*" -or $change.Status -like "??") { $color = "Green" }
            elseif ($change.Status -like "D*") { $color = "Red" }
            elseif ($change.Status -like "R*") { $color = "Magenta" }

            Write-Host " [$($change.Index)] $($change.Display)" -ForegroundColor $color
        }

        # 显示警告
        $committedCount = Get-SafeCount $Global:CommittedFiles
        if ($remainingCount -gt 0 -and $committedCount -gt 0) {
            Show-RemainingFilesWarning -Remaining $remainingCount -Total $Global:InitialFileCount -Committed $committedCount
        }

        Write-Host "`n指令: [数字]选择 | [a]全选 | [r]刷新 | [q]完成并推送 | [x]强制退出" -ForegroundColor White
        $inputStr = Read-Host "请输入"

        # 处理指令
        if ($inputStr -eq 'q') { 
            if ($remainingCount -gt 0) {
                Write-Host "`n⚠️  警告：还有 $remainingCount 个文件未提交！" -ForegroundColor Yellow
                Write-Host "这些文件将不会被推送到远程仓库。" -ForegroundColor Yellow
                Write-Host ""
                Write-Host "剩余文件：" -ForegroundColor Yellow
                foreach ($c in $changes) {
                    Write-Host "  • $($c.Path)" -ForegroundColor Yellow
                }
                Write-Host ""
                $confirmQuit = Read-Host "确认要结束提交阶段吗？(输入 YES 确认，其他任意键返回)"
                if ($confirmQuit -ne "YES") {
                    Write-Log "已取消，继续处理文件..." "Info"
                    continue
                }
            }
            Write-Log "结束提交阶段，进入推送..." "Info"
            break 
        }

        if ($inputStr -eq 'x') { 
            Write-Log "已强制退出，未执行推送。" "Warn"
            exit 0 
        }

        if ($inputStr -eq 'r') { 
            Write-Log "正在刷新文件列表..." "Info"
            continue 
        }

        # 选择文件
        $selectedFiles = @()
        if ($inputStr -eq 'a') {
            $selectedFiles = $changes
            $selectCount = Get-SafeCount $selectedFiles
            Write-Log "已选择全部 $selectCount 个文件" "Info"
        } else {
            $indices = $inputStr -split "[,\s]+" | Where-Object { $_ -match "^\d+$" }
            foreach ($idx in $indices) {
                $item = $changes | Where-Object { $_.Index -eq [int]$idx }
                if ($item) { $selectedFiles += $item }
            }
        }

        $selectedCount = Get-SafeCount $selectedFiles
        if ($selectedCount -eq 0) { 
            Write-Log "未选择任何文件。" "Warn"
            continue 
        }

        Write-Log "正在暂存 $selectedCount 个文件..."
        $stagedFilesThisRound = @()

        foreach ($file in $selectedFiles) {
            $targetPath = $file.Path

            Write-Host "  处理: $targetPath" -ForegroundColor Gray

            # 使用安全路径
            $fullPath = Get-SafeFullPath -RepoRoot $repoRoot -RelativePath $targetPath

            # 目录检查
            try {
                if (Test-Path -LiteralPath $fullPath -PathType Container -ErrorAction SilentlyContinue) {
                    Write-Log "跳过目录: $targetPath" "Warn"
                    continue
                }
            } catch {
                # 忽略路径检查错误
            }

            # 敏感文件检查
            $isSensitive = $false
            foreach ($p in $Config.SensitivePatterns) {
                $fileName = Split-Path $targetPath -Leaf
                if ($targetPath -like $p -or $fileName -like $p) {
                    $isSensitive = $true
                    break
                }
            }
            if ($isSensitive) {
                Write-Host "!!! 敏感文件: $targetPath !!!" -ForegroundColor Red
                if ((Read-Host "确认暂存? (y/n)") -ne 'y') { 
                    continue 
                }
            }

            # 大文件检查
            try {
                if ((Test-Path -LiteralPath $fullPath -ErrorAction SilentlyContinue) -and $file.Status -notlike "D*") {
                    $fileInfo = Get-Item -LiteralPath $fullPath -ErrorAction SilentlyContinue
                    if ($fileInfo -and $fileInfo.Length) {
                        $sizeMB = $fileInfo.Length / 1MB
                        if ($sizeMB -gt $Config.LargeFileThresholdMB) {
                            $sizeStr = "{0:N2} MB" -f $sizeMB
                            Write-Log "大文件警告: $targetPath ($sizeStr)" "Warn"
                        }
                    }
                }
            } catch {
                # 忽略大小检查错误
            }

            # 执行 git add
            $err = & git add -v -- $targetPath 2>&1
            if ($LASTEXITCODE -eq 0) {
                $stagedFilesThisRound += $file
                Write-Host "  ✓ $targetPath" -ForegroundColor Green
            } else {
                Write-Log "暂存失败: $targetPath" "Error"
                Write-Host "  Git 错误: $err" -ForegroundColor Red
            }
        }

        $stagedCount = Get-SafeCount $stagedFilesThisRound
        if ($stagedCount -eq 0) { 
            Write-Log "本轮没有成功暂存任何文件。" "Warn"
            continue 
        }

        Write-Host "`n当前暂存区状态:" -ForegroundColor Green
        git status --short

        $msg = Read-Host "`nCommit Message (留空取消本次提交)"
        if ([string]::IsNullOrWhiteSpace($msg)) { 
            Write-Log "已取消提交。" "Warn"
            Write-Log "正在撤销暂存..." "Info"
            git reset HEAD
            continue 
        }

        & git commit -m "$msg"
        if ($LASTEXITCODE -eq 0) {
            Write-Log "✓ Commit 成功！" "Success"
            foreach ($f in $stagedFilesThisRound) {
                if ($f.Path -notin $Global:CommittedFiles) { 
                    $Global:CommittedFiles += $f.Path 
                }
            }
        } else {
            Write-Log "Commit 失败，请检查错误信息。" "Error"
        }
    }

    # ========== 推送阶段 ==========
    Write-Host "`n========================================"
    Write-Host "进入推送阶段..." -ForegroundColor Cyan
    Write-Host "========================================"

    # 最后检查遗漏文件
    $finalCheck = Parse-GitStatus
    $finalCount = Get-SafeCount $finalCheck

    if ($finalCount -gt 0) {
        Write-Host ""
        Write-Host "╔════════════════════════════════════════╗" -ForegroundColor Red
        Write-Host "║  ❌ 发现遗漏文件！" -ForegroundColor Red
        Write-Host "║  以下 $finalCount 个文件未被提交：" -ForegroundColor Red
        Write-Host "╠════════════════════════════════════════╣" -ForegroundColor Red
        foreach ($f in $finalCheck) {
            Write-Host "║    • $($f.Path)" -ForegroundColor Red
        }
        Write-Host "╠════════════════════════════════════════╣" -ForegroundColor Red
        Write-Host "║  建议返回处理 (输入 n 返回)" -ForegroundColor Red
        Write-Host "╚════════════════════════════════════════╝" -ForegroundColor Red
        Write-Host ""

        $continueWithMissing = Read-Host "仍然继续推送？(y/n)"
        if ($continueWithMissing -ne 'y') {
            Write-Log "已取消。请重新运行脚本处理遗漏文件。" "Warn"
            exit 0
        }
    }

    $upstream = git rev-parse --abbrev-ref --symbolic-full-name "@{u}" 2>$null
    $shouldPush = $false

    if ($LASTEXITCODE -ne 0) {
        Write-Log "当前分支无上游分支，需要首次推送。" "Warn"
        $shouldPush = $true
    } else {
        $counts = git rev-list --left-right --count "$upstream...HEAD" 2>$null
        if ($counts -match "(\d+)\s+(\d+)") {
            $behind = [int]$matches[1]
            $ahead  = [int]$matches[2]

            if ($behind -gt 0) { 
                Write-Log "⚠ 本地落后远端 $behind 个提交，建议先执行 'git pull'。" "Error" 
                $shouldPush = $false
            }
            elseif ($ahead -gt 0) { 
                Write-Log "有 $ahead 个本地提交待推送。" "Info"
                $shouldPush = $true 
            }
            else {
                Write-Log "本地与远端已同步，无需推送。" "Success"
                $shouldPush = $false
            }
        }
    }

    if ($shouldPush) {
        Write-Host "`n准备推送到远程仓库..." -ForegroundColor Yellow

        $pushArgs = @("push")
        if (-not $upstream) { 
            Write-Log "将设置上游分支为: origin/$currentBranch" "Info"
            $pushArgs += @("-u", "origin", $currentBranch)
        }

        $confirm = Read-Host "确认推送? (y/n)"
        if ($confirm -eq 'y') {
            Write-Log "正在推送..." "Info"
            & git @pushArgs

            if ($LASTEXITCODE -eq 0) {
                Write-Log "✓ 推送成功！" "Success"
            } else {
                Write-Log "✗ 推送失败，请检查网络或权限。" "Error"
            }
        } else {
            Write-Log "已取消推送。" "Warn"
        }
    }

    # 显示统计
    $committedCount = Get-SafeCount $Global:CommittedFiles
    $missedCount = $Global:InitialFileCount - $committedCount

    Write-Host "`n========================================" -ForegroundColor Gray
    Write-Host "📊 本次会话统计：" -ForegroundColor Cyan
    Write-Host "  • 初始文件数：$Global:InitialFileCount" -ForegroundColor White
    Write-Host "  • 已提交文件：$committedCount" -ForegroundColor Green
    Write-Host "  • 遗漏文件数：$missedCount" -ForegroundColor $(if ($missedCount -gt 0) { "Red" } else { "Green" })

    if ($committedCount -gt 0) {
        Write-Host "`n已提交的文件列表：" -ForegroundColor Cyan
        $Global:CommittedFiles | Sort-Object -Unique | ForEach-Object { 
            Write-Host "  • $_" -ForegroundColor White
        }
    }

    if ($missedCount -gt 0) {
        Write-Host "`n⚠️  提醒：有 $missedCount 个文件未提交" -ForegroundColor Yellow
    } else {
        Write-Host "`n✓ 所有文件都已成功处理！" -ForegroundColor Green
    }

} catch {
    Write-Host "`n[脚本错误] $_" -ForegroundColor Red
    Write-Host "错误位置: $($_.InvocationInfo.ScriptLineNumber) 行" -ForegroundColor Red
    Write-Host "堆栈信息: $($_.ScriptStackTrace)" -ForegroundColor Red
}

Write-Host "`n按任意键退出..." -ForegroundColor Gray
$null = $Host.UI.RawUI.ReadKey("NoEcho,IncludeKeyDown")

项目进一步修改3.0版本源码¶

PowerShell

<#
.SYNOPSIS
    交互式 Git 分批提交助手 (V3.0 - 全面优化版)
    优化内容：
    1. 移除硬编码路径，支持 -RepoPath 参数
    2. 使用 Push-Location/Pop-Location 恢复工作目录
    3. 使用脚本作用域变量和 ArrayList 提升性能
    4. 支持目录递归展开（方案一）
    5. 支持范围选择输入（如 1-5, 1,3,5）
    6. 精确撤销暂存（只撤销本轮文件）
    7. 大文件处理增强（可选跳过 + LFS 建议）
    8. 修正遗漏文件计算逻辑
    注意：请务必将此文件保存为 "UTF-8 with BOM" 编码格式
#>

param(
    [string]$RepoPath = ""
)

# -----------------------------------------------------------------------------
# 0. 配置与初始化
# -----------------------------------------------------------------------------

$OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

$Config = @{
    ProtectMainBranch    = $true
    SensitivePatterns    = @(".env", "*.key", "id_rsa", "secrets.*", "*credentials*", "config.prod*")
    LargeFileThresholdMB = 50
}

# 使用脚本作用域变量和高效的 List 类型
$script:CommittedFiles = [System.Collections.Generic.List[string]]::new()
$script:InitialFileCount = 0
$script:OriginalLocation = Get-Location

# -----------------------------------------------------------------------------
# 1. 辅助函数
# -----------------------------------------------------------------------------

function Write-Log {
    param([string]$Message, [string]$Level = "Info", [switch]$NoNewLine)
    $color = "Cyan"
    switch ($Level) {
        "Success" { $color = "Green" }
        "Warn"    { $color = "Yellow" }
        "Error"   { $color = "Red" }
    }
    $timeStr = (Get-Date -Format "HH:mm:ss")
    Write-Host "[$timeStr] $Message" -ForegroundColor $color -NoNewline:$NoNewLine
}

function Get-GitRoot {
    param([string]$TargetPath = "")

    # 首先尝试当前目录
    $root = git rev-parse --show-toplevel 2>$null
    if ($LASTEXITCODE -eq 0 -and $root) { return $root }

    # 如果指定了目标路径，尝试该路径
    if ($TargetPath -and (Test-Path $TargetPath)) {
        Push-Location $TargetPath
        try {
            $root = git rev-parse --show-toplevel 2>$null
            if ($LASTEXITCODE -eq 0 -and $root) { return $root }
        } finally {
            Pop-Location
        }
    }
    return $null
}

function Check-GitState {
    $gitDir = git rev-parse --git-dir 2>$null
    if (-not $gitDir) { return $true }

    $blockers = @("MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "rebase-apply", "rebase-merge", "BISECT_LOG")
    foreach ($item in $blockers) {
        $lockPath = Join-Path $gitDir $item
        if (Test-Path $lockPath) {
            Write-Log "严重警告：检测到 Git 正在进行复杂操作 ($item)。" "Error"
            return $false
        }
    }
    return $true
}

function Parse-GitStatus {
    $rawLines = git -c core.quotepath=false status --porcelain=v1 2>$null

    # 强制转换为数组
    if ($rawLines -is [string]) {
        $rawLines = @($rawLines)
    }

    if (-not $rawLines -or $rawLines.Count -eq 0) { 
        return @() 
    }

    $results = [System.Collections.ArrayList]@()
    $index = 1

    foreach ($line in $rawLines) {
        if ([string]::IsNullOrWhiteSpace($line) -or $line.Length -lt 3) { 
            continue 
        }

        try {
            $status = $line.Substring(0, 2)
            $rest   = $line.Substring(3).Trim()

            if ([string]::IsNullOrWhiteSpace($rest)) { continue }

            # 移除 Git 添加的路径引号
            if ($rest.StartsWith('"') -and $rest.EndsWith('"') -and $rest.Length -gt 1) {
                $rest = $rest.Substring(1, $rest.Length - 2)
            }

            $obj = [PSCustomObject]@{
                Index   = $index
                Status  = $status
                Path    = ""
                OldPath = $null
                Display = ""
                RawLine = $line
                IsDirectory = $false
            }

            # 处理重命名
            if ($status -match "^R") {
                if ($rest -match '^(.+?)\s+->\s+(.+)$') {
                    $oldPath = $matches[1].Trim()
                    $newPath = $matches[2].Trim()

                    # 分别去除引号
                    if ($oldPath.StartsWith('"') -and $oldPath.EndsWith('"')) {
                        $oldPath = $oldPath.Substring(1, $oldPath.Length - 2)
                    }
                    if ($newPath.StartsWith('"') -and $newPath.EndsWith('"')) {
                        $newPath = $newPath.Substring(1, $newPath.Length - 2)
                    }

                    $obj.OldPath = $oldPath
                    $obj.Path    = $newPath
                    $obj.Display = "$status $oldPath -> $newPath"
                } else {
                    $obj.Path = $rest
                    $obj.Display = "$status $rest"
                }
            } else {
                $obj.Path = $rest
                $obj.Display = "$status $rest"
            }

            [void]$results.Add($obj)
            $index++

        } catch {
            Write-Host "警告：无法解析行: $line" -ForegroundColor Yellow
            continue
        }
    }

    return $results.ToArray()
}

function Get-SafeCount {
    param($Collection)
    if ($null -eq $Collection) { return 0 }
    if ($Collection -is [array]) { return $Collection.Count }
    if ($Collection -is [System.Collections.ICollection]) { return $Collection.Count }
    return 1
}

function Show-RemainingFilesWarning {
    param([int]$Remaining, [int]$Total, [int]$Committed)

    if ($Remaining -gt 0) {
        Write-Host ""
        Write-Host "╔════════════════════════════════════════════════════════════╗" -ForegroundColor Yellow
        Write-Host "║  ⚠️  注意：还有 $Remaining 个文件未提交！" -ForegroundColor Yellow
        Write-Host "║  📊 统计：初始 $Total 个 → 已提交 $Committed 个 → 剩余 $Remaining 个" -ForegroundColor Yellow
        Write-Host "║  💡 建议：输入 [r] 刷新列表，确认是否还有文件需要处理" -ForegroundColor Yellow
        Write-Host "╚════════════════════════════════════════════════════════════╝" -ForegroundColor Yellow
        Write-Host ""
    }
}

function Get-SafeFullPath {
    param([string]$RepoRoot, [string]$RelativePath)

    try {
        # 使用字符串拼接，避免 Join-Path 的问题
        $sep = [System.IO.Path]::DirectorySeparatorChar
        $cleanRoot = $RepoRoot.TrimEnd(@('\', '/'))
        $cleanRel = $RelativePath.TrimStart(@('\', '/'))
        return "$cleanRoot$sep$cleanRel"
    } catch {
        return $RelativePath
    }
}

function Parse-InputIndices {
    param([string]$InputStr, [int]$MaxIndex)

    $indices = [System.Collections.Generic.List[int]]::new()

    foreach ($part in ($InputStr -split "[,\s]+")) {
        $part = $part.Trim()
        if ([string]::IsNullOrWhiteSpace($part)) { continue }

        # 支持范围格式: 1-5
        if ($part -match "^(\d+)-(\d+)$") {
            $start = [int]$matches[1]
            $end = [int]$matches[2]
            if ($start -le $end -and $start -ge 1 -and $end -le $MaxIndex) {
                foreach ($i in $start..$end) {
                    if (-not $indices.Contains($i)) {
                        $indices.Add($i)
                    }
                }
            }
        }
        # 单个数字
        elseif ($part -match "^\d+$") {
            $num = [int]$part
            if ($num -ge 1 -and $num -le $MaxIndex -and -not $indices.Contains($num)) {
                $indices.Add($num)
            }
        }
    }

    return ($indices | Sort-Object)
}

function Process-DirectoryFiles {
    param(
        [string]$TargetPath,
        [array]$AllChanges,
        [string]$RepoRoot
    )

    # 查找该目录下的所有待处理文件
    $normalizedTarget = $TargetPath.TrimEnd(@('\', '/'))
    $dirFiles = $AllChanges | Where-Object { 
        $normalizedPath = $_.Path.TrimEnd(@('\', '/'))
        ($normalizedPath.StartsWith("$normalizedTarget/")) -or 
        ($normalizedPath.StartsWith("$normalizedTarget\")) -or
        ($normalizedPath -eq $normalizedTarget)
    }

    return $dirFiles
}

# -----------------------------------------------------------------------------
# 2. 主逻辑
# -----------------------------------------------------------------------------

try {
    Write-Log "正在初始化..."
    if (-not (Get-Command git -ErrorAction SilentlyContinue)) { 
        throw "未找到 git 命令。" 
    }

    # 使用参数或当前目录获取 Git 仓库根目录
    $repoRoot = Get-GitRoot -TargetPath $RepoPath
    if (-not $repoRoot) { 
        throw "未找到有效的 Git 仓库。请在 Git 仓库目录中运行此脚本，或使用 -RepoPath 参数指定仓库路径。" 
    }

    # 使用 Push-Location 以便后续恢复
    Push-Location $repoRoot
    Write-Log "仓库根目录: $repoRoot" "Success"

    if (-not (Check-GitState)) { 
        throw "请先解决 Git 状态锁问题。" 
    }

    $currentBranch = git branch --show-current
    if (-not $currentBranch) { 
        $currentBranch = "DETACHED_HEAD" 
    }
    Write-Log "当前分支: $currentBranch" "Info"

    if ($Config.ProtectMainBranch -and ($currentBranch -in "main", "master")) {
        Write-Log "!!! 警告：当前处于主分支 '$currentBranch' !!!" "Warn"
        Write-Host "建议：在功能分支上进行开发，然后通过 PR 合并到主分支" -ForegroundColor Yellow
        $confirm = Read-Host "确定要继续操作吗？(输入 YES 继续，其他任意键取消)"
        if ($confirm -ne "YES") { 
            Write-Log "已取消。" "Info"
            exit 0 
        }
    }

    # 记录初始文件数
    $initialChanges = Parse-GitStatus
    $script:InitialFileCount = Get-SafeCount $initialChanges
    Write-Log "检测到 $script:InitialFileCount 个待处理文件" "Info"

    $doLoop = $true
    while ($doLoop) {
        Write-Host "`n----------------------------------------" -ForegroundColor Gray

        $changes = Parse-GitStatus
        $remainingCount = Get-SafeCount $changes

        if ($remainingCount -eq 0) {
            Write-Log "✓ 工作区干净，所有文件已处理完毕！" "Success"
            break
        }

        # 显示文件列表
        Write-Host "待处理变更 (共 $remainingCount 项)：" -ForegroundColor Cyan
        Write-Host "💡 提示：支持范围选择，如 1-5 或 1,3,5 或 1-3,7,9-10" -ForegroundColor Gray

        foreach ($change in $changes) {
            $color = "White"
            if ($change.Status -like "M*") { $color = "Yellow" }
            elseif ($change.Status -like "A*" -or $change.Status -like "??") { $color = "Green" }
            elseif ($change.Status -like "D*") { $color = "Red" }
            elseif ($change.Status -like "R*") { $color = "Magenta" }

            Write-Host " [$($change.Index)] $($change.Display)" -ForegroundColor $color
        }

        # 显示警告
        $committedCount = $script:CommittedFiles.Count
        if ($remainingCount -gt 0 -and $committedCount -gt 0) {
            Show-RemainingFilesWarning -Remaining $remainingCount -Total $script:InitialFileCount -Committed $committedCount
        }

        Write-Host "`n指令: [数字/范围]选择 | [a]全选 | [r]刷新 | [q]完成并推送 | [x]强制退出" -ForegroundColor White
        $inputStr = Read-Host "请输入"

        # 处理指令
        if ($inputStr -eq 'q') { 
            if ($remainingCount -gt 0) {
                Write-Host "`n⚠️  警告：还有 $remainingCount 个文件未提交！" -ForegroundColor Yellow
                Write-Host "这些文件将不会被推送到远程仓库。" -ForegroundColor Yellow
                Write-Host ""
                Write-Host "剩余文件：" -ForegroundColor Yellow
                foreach ($c in $changes) {
                    Write-Host "  • $($c.Path)" -ForegroundColor Yellow
                }
                Write-Host ""
                $confirmQuit = Read-Host "确认要结束提交阶段吗？(输入 YES 确认，其他任意键返回)"
                if ($confirmQuit -ne "YES") {
                    Write-Log "已取消，继续处理文件..." "Info"
                    continue
                }
            }
            Write-Log "结束提交阶段，进入推送..." "Info"
            break 
        }

        if ($inputStr -eq 'x') { 
            Write-Log "已强制退出，未执行推送。" "Warn"
            exit 0 
        }

        if ($inputStr -eq 'r') { 
            Write-Log "正在刷新文件列表..." "Info"
            continue 
        }

        # 选择文件
        $selectedFiles = [System.Collections.ArrayList]@()
        if ($inputStr -eq 'a') {
            foreach ($c in $changes) {
                [void]$selectedFiles.Add($c)
            }
            $selectCount = $selectedFiles.Count
            Write-Log "已选择全部 $selectCount 个文件" "Info"
        } else {
            $indices = Parse-InputIndices -InputStr $inputStr -MaxIndex $remainingCount
            foreach ($idx in $indices) {
                $item = $changes | Where-Object { $_.Index -eq $idx }
                if ($item) { 
                    [void]$selectedFiles.Add($item) 
                }
            }
        }

        $selectedCount = $selectedFiles.Count
        if ($selectedCount -eq 0) { 
            Write-Log "未选择任何有效文件。请输入有效的数字或范围。" "Warn"
            continue 
        }

        Write-Log "正在处理 $selectedCount 个选中项..."
        $stagedFilesThisRound = [System.Collections.ArrayList]@()

        foreach ($file in $selectedFiles) {
            $targetPath = $file.Path

            Write-Host "  处理: $targetPath" -ForegroundColor Gray

            # 使用安全路径
            $fullPath = Get-SafeFullPath -RepoRoot $repoRoot -RelativePath $targetPath

            # ========== 目录递归展开处理（方案一）==========
            try {
                if (Test-Path -LiteralPath $fullPath -PathType Container -ErrorAction SilentlyContinue) {
                    Write-Host "  📁 检测到目录: $targetPath" -ForegroundColor Yellow

                    # 查找目录下的所有待处理文件
                    $dirFiles = Process-DirectoryFiles -TargetPath $targetPath -AllChanges $changes -RepoRoot $repoRoot
                    $dirFileCount = Get-SafeCount $dirFiles

                    if ($dirFileCount -gt 0) {
                        Write-Host "     包含 $dirFileCount 个待处理文件：" -ForegroundColor Cyan

                        # 最多显示 10 个文件
                        $displayFiles = $dirFiles | Select-Object -First 10
                        foreach ($df in $displayFiles) {
                            Write-Host "       • $($df.Path)" -ForegroundColor Gray
                        }
                        if ($dirFileCount -gt 10) {
                            Write-Host "       ... 还有 $($dirFileCount - 10) 个文件" -ForegroundColor Gray
                        }

                        $confirmDir = Read-Host "     是否暂存该目录下的所有 $dirFileCount 个文件？(y/n)"
                        if ($confirmDir -eq 'y') {
                            foreach ($df in $dirFiles) {
                                $dfPath = $df.Path
                                $err = & git add -v -- $dfPath 2>&1
                                if ($LASTEXITCODE -eq 0) {
                                    [void]$stagedFilesThisRound.Add($df)
                                    Write-Host "       ✓ $dfPath" -ForegroundColor Green
                                } else {
                                    Write-Host "       ✗ $dfPath : $err" -ForegroundColor Red
                                }
                            }
                        } else {
                            Write-Log "已跳过目录: $targetPath" "Info"
                        }
                    } else {
                        Write-Log "空目录或无变更，跳过: $targetPath" "Warn"
                    }
                    continue
                }
            } catch {
                # 忽略路径检查错误，继续尝试作为文件处理
            }

            # 敏感文件检查
            $isSensitive = $false
            foreach ($p in $Config.SensitivePatterns) {
                $fileName = Split-Path $targetPath -Leaf
                if ($targetPath -like $p -or $fileName -like $p) {
                    $isSensitive = $true
                    break
                }
            }
            if ($isSensitive) {
                Write-Host "  !!! 敏感文件: $targetPath !!!" -ForegroundColor Red
                if ((Read-Host "  确认暂存? (y/n)") -ne 'y') { 
                    continue 
                }
            }

            # 大文件检查（增强版 - 可选跳过 + LFS 建议）
            try {
                if ((Test-Path -LiteralPath $fullPath -ErrorAction SilentlyContinue) -and $file.Status -notlike "D*") {
                    $fileInfo = Get-Item -LiteralPath $fullPath -ErrorAction SilentlyContinue
                    if ($fileInfo -and $fileInfo.Length) {
                        $sizeMB = $fileInfo.Length / 1MB
                        if ($sizeMB -gt $Config.LargeFileThresholdMB) {
                            $sizeStr = "{0:N2} MB" -f $sizeMB
                            Write-Host "  ⚠️  大文件警告: $targetPath ($sizeStr)" -ForegroundColor Yellow
                            Write-Host "     💡 建议：考虑使用 Git LFS 管理大文件 (git lfs track ""$($fileInfo.Extension)"")" -ForegroundColor Cyan
                            $skipLarge = Read-Host "     是否跳过此大文件？(y=跳过, n=继续添加)"
                            if ($skipLarge -eq 'y') {
                                Write-Log "已跳过大文件: $targetPath" "Info"
                                continue
                            }
                        }
                    }
                }
            } catch {
                # 忽略大小检查错误
            }

            # 执行 git add
            $err = & git add -v -- $targetPath 2>&1
            if ($LASTEXITCODE -eq 0) {
                [void]$stagedFilesThisRound.Add($file)
                Write-Host "  ✓ $targetPath" -ForegroundColor Green
            } else {
                Write-Log "暂存失败: $targetPath" "Error"
                Write-Host "  Git 错误: $err" -ForegroundColor Red
            }
        }

        $stagedCount = $stagedFilesThisRound.Count
        if ($stagedCount -eq 0) { 
            Write-Log "本轮没有成功暂存任何文件。" "Warn"
            continue 
        }

        Write-Host "`n当前暂存区状态:" -ForegroundColor Green
        git status --short

        $msg = Read-Host "`nCommit Message (留空取消本次提交)"
        if ([string]::IsNullOrWhiteSpace($msg)) { 
            Write-Log "已取消提交。" "Warn"
            Write-Log "正在撤销本轮暂存的 $stagedCount 个文件..." "Info"

            # 精确撤销：只撤销本轮暂存的文件
            foreach ($staged in $stagedFilesThisRound) {
                git reset HEAD -- $staged.Path 2>$null
            }
            Write-Log "已撤销 $stagedCount 个文件的暂存" "Info"
            continue 
        }

        & git commit -m "$msg"
        if ($LASTEXITCODE -eq 0) {
            Write-Log "✓ Commit 成功！" "Success"
            foreach ($f in $stagedFilesThisRound) {
                if (-not $script:CommittedFiles.Contains($f.Path)) { 
                    $script:CommittedFiles.Add($f.Path) 
                }
            }
        } else {
            Write-Log "Commit 失败，请检查错误信息。" "Error"
        }
    }

    # ========== 推送阶段 ==========
    Write-Host "`n========================================"
    Write-Host "进入推送阶段..." -ForegroundColor Cyan
    Write-Host "========================================"

    # 最后检查遗漏文件（使用实时检查）
    $finalCheck = Parse-GitStatus
    $finalCount = Get-SafeCount $finalCheck

    if ($finalCount -gt 0) {
        Write-Host ""
        Write-Host "╔════════════════════════════════════════╗" -ForegroundColor Red
        Write-Host "║  ❌ 发现遗漏文件！" -ForegroundColor Red
        Write-Host "║  以下 $finalCount 个文件未被提交：" -ForegroundColor Red
        Write-Host "╠════════════════════════════════════════╣" -ForegroundColor Red
        foreach ($f in $finalCheck) {
            Write-Host "║    • $($f.Path)" -ForegroundColor Red
        }
        Write-Host "╠════════════════════════════════════════╣" -ForegroundColor Red
        Write-Host "║  建议返回处理 (输入 n 返回)" -ForegroundColor Red
        Write-Host "╚════════════════════════════════════════╝" -ForegroundColor Red
        Write-Host ""

        $continueWithMissing = Read-Host "仍然继续推送？(y/n)"
        if ($continueWithMissing -ne 'y') {
            Write-Log "已取消。请重新运行脚本处理遗漏文件。" "Warn"
            exit 0
        }
    }

    $upstream = git rev-parse --abbrev-ref --symbolic-full-name "@{u}" 2>$null
    $shouldPush = $false

    if ($LASTEXITCODE -ne 0) {
        Write-Log "当前分支无上游分支，需要首次推送。" "Warn"
        $shouldPush = $true
    } else {
        $counts = git rev-list --left-right --count "$upstream...HEAD" 2>$null
        if ($counts -match "(\d+)\s+(\d+)") {
            $behind = [int]$matches[1]
            $ahead  = [int]$matches[2]

            if ($behind -gt 0) { 
                Write-Log "⚠ 本地落后远端 $behind 个提交，建议先执行 'git pull'。" "Error" 
                $shouldPush = $false
            }
            elseif ($ahead -gt 0) { 
                Write-Log "有 $ahead 个本地提交待推送。" "Info"
                $shouldPush = $true 
            }
            else {
                Write-Log "本地与远端已同步，无需推送。" "Success"
                $shouldPush = $false
            }
        }
    }

    if ($shouldPush) {
        Write-Host "`n准备推送到远程仓库..." -ForegroundColor Yellow

        $pushArgs = @("push")
        if (-not $upstream) { 
            Write-Log "将设置上游分支为: origin/$currentBranch" "Info"
            $pushArgs += @("-u", "origin", $currentBranch)
        }

        $confirm = Read-Host "确认推送? (y/n)"
        if ($confirm -eq 'y') {
            Write-Log "正在推送..." "Info"
            & git @pushArgs

            if ($LASTEXITCODE -eq 0) {
                Write-Log "✓ 推送成功！" "Success"
            } else {
                Write-Log "✗ 推送失败，请检查网络或权限。" "Error"
            }
        } else {
            Write-Log "已取消推送。" "Warn"
        }
    }

    # 显示统计（使用实时遗漏文件数）
    $committedCount = $script:CommittedFiles.Count
    $finalRemaining = Parse-GitStatus
    $missedCount = Get-SafeCount $finalRemaining

    Write-Host "`n========================================" -ForegroundColor Gray
    Write-Host "📊 本次会话统计：" -ForegroundColor Cyan
    Write-Host "  • 初始文件数：$script:InitialFileCount" -ForegroundColor White
    Write-Host "  • 已提交文件：$committedCount" -ForegroundColor Green
    Write-Host "  • 遗漏文件数：$missedCount" -ForegroundColor $(if ($missedCount -gt 0) { "Red" } else { "Green" })

    if ($committedCount -gt 0) {
        Write-Host "`n已提交的文件列表：" -ForegroundColor Cyan
        $script:CommittedFiles | Sort-Object -Unique | ForEach-Object { 
            Write-Host "  • $_" -ForegroundColor White
        }
    }

    if ($missedCount -gt 0) {
        Write-Host "`n⚠️  提醒：有 $missedCount 个文件未提交" -ForegroundColor Yellow
    } else {
        Write-Host "`n✓ 所有文件都已成功处理！" -ForegroundColor Green
    }

} catch {
    Write-Host "`n[脚本错误] $_" -ForegroundColor Red
    Write-Host "错误位置: $($_.InvocationInfo.ScriptLineNumber) 行" -ForegroundColor Red
    Write-Host "堆栈信息: $($_.ScriptStackTrace)" -ForegroundColor Red
} finally {
    # 恢复原始工作目录
    Pop-Location -ErrorAction SilentlyContinue
}

Write-Host "`n按任意键退出..." -ForegroundColor Gray
$null = $Host.UI.RawUI.ReadKey("NoEcho,IncludeKeyDown")

二、✅ 已完整实现的核心功能如下¶

1. 启动前检查 ✅ 完整实现¶

✅ Git 仓库检测（Get-GitRoot 函数）
✅ 未完成操作检测（Check-GitState - 检测 MERGE_HEAD、REBASE 等）
✅ 当前分支显示
✅ 主分支保护（需输入 YES 确认）
❌ 缺失：远端信息显示（git remote -v）

2. 变更文件列表 ✅ 已实现且增强¶

✅ 使用 --porcelain=v1（机器可解析）
✅ 使用 -c core.quotepath=false（处理中文）
✅ 支持所有状态（M/A/D/R/??）
✅ 增强：自动去除 Git 添加的路径引号
⚠️ 未完全使用 -z：虽然提到了，但实际用的是标准输出

3. 交互式选择 ✅ 完整实现且增强¶

✅ 编号显示（带颜色区分状态）
✅ 多选支持（空格/逗号分隔）
✅ 特殊指令：q/r/a
✅ 非法输入处理
✅ 目录忽略（带提示）
✅ 增强：x 强制退出（不推送）
✅ 增强：q 改为进入推送阶段而非直接退出

4. 暂存行为 ✅ 完整实现¶

✅ 使用 git add -v -- <path>
✅ 删除/重命名正确处理
✅ 状态确认（git status --short）
✅ 增强：逐文件显示暂存结果（✓ 标记）

5. Commit 行为 ✅ 完整实现且增强¶

✅ 提示输入 message
✅ 空 message 检测
✅ Commit 执行
⚠️ 未完全实现：未显示 git show --name-only
✅ 增强：取消时自动 git reset HEAD 撤销暂存

6. 循环机制 ✅ 完整实现¶

✅ 自动回到文件列表
✅ 工作区干净时自动进入推送
✅ 支持 q 手动退出

7. Push 行为 ✅ 完整实现¶

✅ 自动检测当前分支
✅ upstream 检测
✅ 无 upstream 时 -u origin <branch>
✅ 二次确认（y/n）
✅ 落后远端检测

8. 日志输出 ✅ 完整实现¶

✅ 每步操作都有提示
✅ 时间戳日志（Write-Log 函数）
✅ 最终文件清单

9. 错误处理 ✅ 完整实现¶

✅ 所有 Git 命令检查 $LASTEXITCODE
✅ Try-Catch 包裹
✅ 详细错误信息输出

10. 安全防护 ✅ 完整实现且增强¶

✅ 敏感文件检测（可配置模式）
✅ 大文件提醒（50MB 阈值）
✅ 二次确认机制

三、脚本的创新增强功能¶

1. 文件遗漏检测系统 ⭐⭐⭐¶

PowerShell

$Global:InitialFileCount = 0  # 记录初始文件数
$Global:CommittedFiles = @()  # 跟踪已提交文件

✨ 初始化时记录总文件数
✨ 每轮 Commit 后实时统计
✨ 黄色警告框提示剩余文件
✨ 推送前红色警告框检查遗漏
✨ 最终统计报告

2. 增强的路径处理 ⭐⭐¶

PowerShell

# 自动去除 Git 添加的引号
if ($rest.StartsWith('"') -and $rest.EndsWith('"')) {
    $rest = $rest.Substring(1, $rest.Length - 2)
}

✨ 解决中文文件名问题
✨ 处理带空格的路径
✨ 安全的路径拼接函数

3. 智能退出机制 ⭐⭐¶

✨ q = 完成提交并推送（智能）
✨ x = 强制退出不推送（紧急）
✨ 有剩余文件时需输入 YES 二次确认

4. 丰富的视觉反馈 ⭐¶

PowerShell

╔════════════════════════════════════════╗
║  ⚠️  注意：还有 1 个文件未提交！
║  📊 统计：初始 10 个 → 已提交 9 个 → 剩余 1 个
╚════════════════════════════════════════╝

✨ 彩色状态（M=黄/A=绿/D=红/R=紫）
✨ 时间戳日志
✨ Emoji 图标
✨ 边框警告

5. 健壮的数组处理 ⭐⭐¶

PowerShell

function Get-SafeCount {
    # 解决单文件时 .Count 返回空的问题
}

✨ 修复 PowerShell 单对象计数 bug
✨ 强制数组转换

6. 可配置性 ⭐¶

PowerShell

$Config = @{
    ProtectMainBranch    = $true
    SensitivePatterns    = @(...)
    LargeFileThresholdMB = 50
    TargetRepoPath       = "..."
}

✨ 集中配置管理
✨ 易于自定义

四、未实现或部分缺失的功能¶

1. 远端信息显示¶

PowerShell

# 建议补充
git remote -v

2. Commit 详情显示¶

PowerShell

# 建议补充
git show --name-only --oneline -1

3. 未使用 `-z` 参数¶

当前用标准输出，虽然已处理引号，但 -z 更可靠

4. Ctrl+C 中断提示¶

未实现优雅的中断处理

五、功能完成度评估¶

需求类别	完成度	说明
启动检查	90%	缺少 remote -v 显示
文件解析	95%	已超预期，路径处理完善
交互选择	100%	完整实现且增强
暂存行为	100%	完整实现
Commit	95%	缺少详细信息展示
循环机制	100%	完整实现
Push 行为	100%	完整实现
日志输出	100%	超预期（时间戳+统计）
错误处理	100%	全面覆盖
安全防护	100%	完整实现
遗漏检测	⭐ 新增	原需求未要求
路径引号	⭐ 新增	原需求未涉及
智能退出	⭐ 增强	原需求只要求 q 退出

六、脚本当前状态¶

✅ 优势¶

功能完整度 97% - 核心需求全部实现
用户体验优秀 - 视觉反馈丰富，操作直观
错误处理完善 - 大量 try-catch 和边界处理
创新功能 - 遗漏检测系统是亮点
代码质量高 - 函数化、注释清晰、可维护

⚠️ 需改进¶

添加 git remote -v 显示
添加 commit 详情（git show）
考虑使用 -z 参数提高健壮性

💡 建议补充¶

PowerShell

# 在启动检查阶段添加
Write-Host "`n远程仓库信息:" -ForegroundColor Cyan
git remote -v

# 在 Commit 成功后添加
Write-Host "`n本次提交详情:" -ForegroundColor Green
git show --name-only --oneline -1

七、总结¶

这个脚本超额完成了原始需求，不仅实现了所有核心功能（97%），还创新性地添加了：

文件遗漏检测与统计系统
增强的路径处理（中文/空格/引号）
智能退出机制
丰富的视觉反馈

可以直接投入生产使用，只需根据个人偏好补充 2-3 个小功能即可完美使用！

Git 交互式提交助手 V2.6 - 完整使用手册¶

写在最前面 请详细阅读¶

许可与声明¶

📚 目录¶

简介¶

这是什么？¶

核心功能¶

系统要求¶

必需条件¶

推荐配置¶

安装与配置¶

步骤 1: 下载脚本¶

步骤 2: 设置执行策略¶

步骤 3: 配置脚本参数¶

步骤 4: 测试运行¶

快速上手¶

基础工作流¶

示例场景¶

详细功能说明¶

1. 启动检查¶

1.1 仓库检测¶

1.2 Git 状态检测¶

1.3 主分支保护¶

2. 文件列表显示¶

2.1 状态标识¶

2.2 特殊路径处理¶

3. 交互指令¶

3.1 选择文件¶

3.2 特殊指令¶

4. 暂存过程¶

4.1 目录检测¶

4.2 敏感文件警告¶

4.3 大文件提醒¶

4.4 暂存确认¶

5. Commit 操作¶

5.1 输入 Message¶

5.2 空 Message 取消¶

5.3 Commit 成功¶

6. 遗漏检测系统 ⭐¶

6.1 实时统计¶

6.2 退出二次确认¶

6.3 推送前最终检查¶

7. 推送阶段¶

7.1 状态检测¶

7.2 推送示例¶

8. 最终统计¶

高级用法¶

1. 快捷方式配置¶

2. 批量操作技巧¶

技巧 1：按文件类型分批¶

技巧 2：使用刷新功能¶

技巧 3：分阶段提交¶

3. 自定义配置模板¶

4. 团队协作规范¶

规范 1：Commit Message 规范¶

规范 2：分支命名¶

规范 3：提交频率¶

常见问题¶

Q1: 脚本无法运行，提示"无法加载"？¶

Q2: 中文文件名显示乱码或无法选择？¶

Q3: 提示"路径中具有非法字符"？¶

Q4: 文件消失了，明明有变更但列表不显示？¶

Q5: 推送失败，提示"权限拒绝"？¶

Q6: 如何撤销刚才的提交？¶

Q7: 脚本运行很慢？¶

Q8: 想跳过敏感文件检查？¶

Q9: 如何处理重命名文件？¶

Q10: 能否同时运行多个脚本实例？¶

故障排查¶

排查流程¶

诊断命令¶

最佳实践¶

1. 提交前检查清单¶

2. 分批提交策略¶

3. Commit Message 最佳实践¶

4. 分支管理建议¶

5. 团队协作规范¶

配置参考¶

完整配置说明¶

按项目类型推荐配置¶

写在最前面请详细阅读¶

项目进一步修改3.0版本源码¶

3. 未使用 `-z` 参数¶

五、功能完成度评估¶

六、脚本当前状态¶

七、总结¶