Skip to content

PUSH_SCRIPT_GUIDE.md

Latest commit

 

History

History
389 lines (279 loc) · 7.14 KB

PUSH_SCRIPT_GUIDE.md

File metadata and controls

389 lines (279 loc) · 7.14 KB

📦 Push.bat 脚本使用指南

版本：v0.0.2
更新时间：2025-10-11
适用项目：Bit HCI

🎯 概述

push.bat 是 Bit HCI 项目的自动化推送脚本，用于简化 Git 工作流程，自动完成暂存、提交、拉取和推送操作。

✨ v0.0.2 新增功能

1. 增强的输出显示

  • ✅ 添加脚本版本和标题横幅
  • ✅ 更清晰的步骤提示信息
  • ✅ 彩色状态标识：[INFO]、[OK]、[WARN]、[ERROR]

2. 智能变更检测

  • ✅ 自动检测是否有文件变更
  • ✅ 如果没有变更，检查远程更新后直接退出
  • ✅ 显示将要暂存的文件列表

3. 自定义提交消息

  • ✅ 支持命令行参数指定提交消息
  • ✅ 如果未指定，自动生成时间戳格式的提交消息

4. 文件统计

  • ✅ 显示变更的文件数量
  • ✅ 在最终摘要中显示统计信息

5. 改进的错误处理

  • ✅ 每个错误都有详细的说明和建议
  • ✅ 冲突处理提示
  • ✅ 常见问题的解决方案提示

6. PROGRESS.md 同步

  • ✅ 自动同步 docs/PROGRESS.md 到 README.md
  • ✅ 同步失败不影响后续流程

7. 完成摘要

  • ✅ 显示操作摘要（文件数、分支、远程URL）
  • ✅ 显示最后一次提交信息
  • ✅ 提供后续操作建议

📖 使用方法

基本用法

# 推送到默认分支（main）
push.bat

# 推送到指定分支
push.bat dev

# 推送并指定提交消息（必须用引号）
push.bat main "feat: add new feature"

参数说明

push.bat [branch] [commit_message]
参数 说明 默认值 示例
branch 目标分支名称 main dev, feature/xxx
commit_message 自定义提交消息 chore(repo): sync on [timestamp] "docs: update README"

🔄 执行流程

脚本按照以下顺序执行：

  1. 环境检查

    • 检查 Git 是否安装
    • 验证是否在 Git 仓库中
    • 切换到目标分支（如需要）

  2. 状态检查

    • 显示当前仓库状态
    • 检测是否有文件变更
    • 如无变更，检查远程更新

  3. 文档同步

    • 将 docs/PROGRESS.md 同步到 README.md
    • 确保项目文档一致性

  4. 暂存变更

    • 显示将要暂存的文件
    • 执行 git add -A
    • 统计变更文件数量

  5. 提交变更

    • 生成或使用自定义提交消息
    • 提交所有暂存的变更
    • 显示提交结果

  6. 拉取更新

    • 显示远程仓库 URL
    • 使用 rebase 方式拉取最新代码
    • 处理可能的冲突

  7. 推送代码

    • 推送到远程仓库
    • 自动设置上游分支（如需要）
    • 显示推送结果

  8. 完成总结

    • 显示操作摘要
    • 显示最后提交信息
    • 提供后续建议

📊 输出示例

成功执行示例

========================================
  Bit HCI Push Script v0.0.2
========================================

[INFO] Using branch: main
[INFO] Current repository status:

## main...origin/main
 M README.md
 M compiler/README.md
?? new_file.md

[INFO] Syncing PROGRESS.md to README.md...
[OK] PROGRESS.md synced successfully.

[INFO] Files to be staged:
 M README.md
 M compiler/README.md
?? new_file.md

[INFO] Staging all changes...
[INFO] Found 3 file(s) with changes.
[INFO] Commit message: chore(repo): sync on 2025-10-11_19-30-00
[OK] Changes committed successfully.

[INFO] Remote URL: git@github.com:CestlavieBitOS/Bit-HCI.git

[INFO] Pulling latest changes with rebase...
[OK] Pull completed successfully.

[INFO] Pushing to origin/main...

========================================
[OK] Sync completed successfully!
========================================

[INFO] Summary:
  - Files changed: 3
  - Branch: main
  - Remote: git@github.com:CestlavieBitOS/Bit-HCI.git

[INFO] Next steps:
  - Check your remote repository
  - Review the commit in the history

[INFO] Last commit:
4f12bbc (HEAD -> main, origin/main) chore(repo): sync on 2025-10-11_19-30-00

无变更示例

========================================
  Bit HCI Push Script v0.0.2
========================================

[INFO] Using branch: main
[INFO] Current repository status:

## main...origin/main

[INFO] No changes detected in working directory.
[INFO] Checking remote for updates...
[INFO] Everything is up to date.

⚠️ 常见问题

1. 推送失败

错误信息：

[ERROR] Push failed.

可能原因：

  • 网络连接问题
  • SSH 密钥未配置
  • 没有推送权限

解决方案：

# 检查远程连接
git remote -v

# 测试 SSH 连接
ssh -T git@github.com

# 检查权限
git push --dry-run

2. Rebase 冲突

错误信息：

[ERROR] Pull with rebase failed.
[INFO] This usually means there are conflicts.

解决方案：

# 解决冲突后继续
git rebase --continue

# 或者放弃 rebase
git rebase --abort

# 然后重新运行脚本
push.bat

3. 文档同步失败

错误信息：

[WARN] Failed to sync PROGRESS.md, continuing anyway...

可能原因：

  • docs/PROGRESS.md 文件不存在
  • PowerShell 执行失败

解决方案：

  • 检查文件是否存在
  • 手动同步后继续推送

🔧 高级用法

批处理多个操作

# 连续推送到多个分支
push.bat main "Update main"
git checkout dev
push.bat dev "Merge from main"

结合其他 Git 命令

# 推送前查看差异
git diff
push.bat

# 推送后查看日志
push.bat
git log --oneline -5

脚本集成

# 在其他脚本中调用
call push.bat main "Automated update"
if %errorlevel% neq 0 (
    echo Push failed, aborting...
    exit /b 1
)

🛠️ 自定义修改

修改默认分支

在脚本中找到：

if "%BRANCH%"=="" set BRANCH=main

修改为：

if "%BRANCH%"=="" set BRANCH=dev

修改提交消息格式

在脚本中找到：

set "MSG=chore(repo): sync on !NOW!"

修改为你喜欢的格式：

set "MSG=Auto sync: !NOW!"

禁用 PROGRESS.md 同步

注释掉或删除以下部分：

REM echo [INFO] Syncing PROGRESS.md to README.md...
REM powershell -NoProfile -Command "..."

📝 最佳实践

1. 推送前检查

# 查看状态
git status

# 查看差异
git diff

# 运行脚本
push.bat

2. 有意义的提交消息

# 使用语义化提交消息
push.bat main "feat: add user authentication"
push.bat main "fix: resolve memory leak"
push.bat main "docs: update API documentation"
push.bat main "chore: update dependencies"

3. 定期同步

# 每天工作结束前推送
push.bat

# 完成功能后立即推送
push.bat main "feat: complete login module"

🔒 安全建议

  1. 不要在提交消息中包含敏感信息
  2. 定期检查 .gitignore 文件
  3. 使用 SSH 密钥而非密码
  4. 推送前检查要提交的文件

📚 相关文档

维护者：Bit Project 团队
最后更新：2025-10-11
脚本版本：v0.0.2