@zjex/git-workflow 0.4.2 → 0.4.3

package/docs/commands/amend-date.md

@@ -0,0 +1,425 @@
+# 修改提交时间
+
+修改指定 commit 的提交时间（Author Date 和 Committer Date）。
+
+## 命令
+
+```bash
+# 交互式选择 commit
+gw amend:date
+gw ad
+
+# 直接指定 commit hash
+gw ad a1b2c3d
+gw ad HEAD~2
+```
+
+## 使用方式
+
+### 方式 1: 交互式选择（推荐）
+
+不带参数运行，从最近 20 个 commit 中选择：
+
+```bash
+gw ad
+```
+
+### 方式 2: 指定 commit hash
+
+直接指定要修改的 commit：
+
+```bash
+# 使用短 hash
+gw ad a1b2c3d
+
+# 使用完整 hash
+gw ad a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
+
+# 使用相对引用
+gw ad HEAD      # 最新 commit
+gw ad HEAD~1    # 上一个 commit
+gw ad HEAD~2    # 上上个 commit
+```
+
+## 交互流程
+
+### 步骤 1: 选择 commit（如果未指定）
+
+```
+? 选择要修改时间的 commit:
+❯ a1b2c3d ✨ feat(auth): 添加用户登录功能 2026-01-19 14:30:00 +0800
+  d4e5f6g 🐛 fix(auth): 修复登录bug 2026-01-18 10:20:00 +0800
+  h7i8j9k 📝 docs: 更新文档 2026-01-17 16:45:00 +0800
+  ...
+```
+
+### 步骤 2: 显示当前信息
+
+```
+当前 commit 信息:
+  Hash:    a1b2c3d
+  Message: ✨ feat(auth): 添加用户登录功能
+  Date:    2026-01-19 14:30:00 +0800
+────────────────────────────────────────
+```
+
+### 步骤 3: 输入新日期
+
+```
+输入日期格式: YYYY-MM-DD (如: 2026-01-19)
+
+? 输入新的日期: 2026-01-15
+```
+
+**日期格式**: `YYYY-MM-DD`，时间默认为 `00:00:00`
+
+### 步骤 4: 确认修改
+
+```
+修改预览:
+  Commit:   a1b2c3d
+  旧时间:   2026-01-19 14:30:00 +0800
+  新时间:   2026-01-15 00:00:00
+  修改类型: Author + Committer (两者都修改)
+────────────────────────────────────────
+
+? 确认修改? (y/N)
+```
+
+## 使用场景
+
+### 场景 1: 修改最新 commit
+
+```bash
+gw ad HEAD
+# 或
+gw ad
+
+# 输入日期: 2026-01-15
+# 确认
+
+✔ 修改成功
+```
+
+**特点**: 使用 `git commit --amend`，不会改变 commit hash
+
+### 场景 2: 修改历史 commit
+
+```bash
+gw ad HEAD~3
+
+# 输入日期: 2026-01-10
+# 确认
+
+⚠️  警告: 修改非最新 commit 需要使用 rebase，可能会改变 commit hash
+   这会影响已推送到远程的 commit，请谨慎操作
+
+? 确认修改? (y/N) y
+
+正在执行 rebase...
+✔ 修改成功
+
+⚠️  注意: commit hash 已改变
+   如果已推送到远程，需要使用 force push:
+   git push --force-with-lease
+```
+
+**特点**: 使用 `git filter-branch`，会改变 commit hash
+
+### 场景 3: 批量修改多个 commit
+
+```bash
+# 修改第一个
+gw ad HEAD~2
+# 输入: 2026-01-10
+
+# 修改第二个
+gw ad HEAD~1
+# 输入: 2026-01-11
+
+# 修改最新的
+gw ad HEAD
+# 输入: 2026-01-12
+```
+
+## 注意事项
+
+### ⚠️ 修改历史 commit
+
+- **会改变 commit hash** - 所有后续 commit 的 hash 都会改变
+- **影响团队协作** - 如果已推送到远程，其他人需要重新拉取
+- **需要 force push** - 推送时必须使用 `--force-with-lease`
+
+### � Fo前rce Push
+
+修改已推送的 commit 后，需要强制推送：
+
+```bash
+# 推荐：更安全的 force push
+git push --force-with-lease
+
+# 或：强制推送（不推荐）
+git push --force
+```
+
+### 📅 时间格式
+
+- **输入格式**: `YYYY-MM-DD`（如 `2026-01-19`）
+- **存储格式**: `YYYY-MM-DD 00:00:00`（时间默认为 00:00:00）
+- **时区**: 使用系统当前时区
+
+### 🔄 修改范围
+
+默认同时修改：
+
+- **Author Date**: 代码编写时间
+- **Committer Date**: 代码提交时间
+
+## 示例
+
+### 示例 1: 修改最新 commit 为指定日期
+
+```bash
+$ gw ad HEAD
+输入新的日期: 2026-01-15
+确认修改? y
+
+✔ 修改成功
+```
+
+### 示例 2: 修改指定 hash 的 commit
+
+```bash
+$ gw ad a1b2c3d
+输入新的日期: 2026-01-10
+确认修改? y
+
+⚠️  警告: 修改非最新 commit 需要使用 rebase，可能会改变 commit hash
+正在执行 rebase...
+✔ 修改成功
+```
+
+### 示例 3: 交互式选择并修改
+
+```bash
+$ gw ad
+
+? 选择要修改时间的 commit:
+❯ a1b2c3d ✨ feat: 添加登录功能 2026-01-19 14:30:00
+  d4e5f6g 🐛 fix: 修复bug 2026-01-18 10:20:00
+
+输入新的日期: 2026-01-15
+确认修改? y
+
+✔ 修改成功
+```
+
+## 相关命令
+
+- `gw c` - 提交代码
+- `gw log` - 查看提交日志
+- `git log --format="%ai"` - 查看 Author Date
+- `git log --format="%ci"` - 查看 Committer Date
+
+## 技术细节
+
+### Author Date vs Committer Date
+
+Git 中每个 commit 都有两个时间戳：
+
+#### 📝 Author Date (作者时间)
+
+- **含义**: 代码实际编写的时间
+- **设置时机**: 第一次创建 commit 时
+- **保持不变**: 即使 rebase、cherry-pick 也会保留原始作者时间
+- **查看命令**: `git log --format="%ai"`
+
+**示例场景**:
+
+```bash
+# 2026-01-15 你写了代码并提交
+git commit -m "feat: 添加登录功能"
+# Author Date: 2026-01-15 10:00:00
+
+# 2026-01-20 你 rebase 了这个 commit
+git rebase -i HEAD~5
+# Author Date: 仍然是 2026-01-15 10:00:00 (不变)
+# Committer Date: 2026-01-20 14:30:00 (更新为 rebase 时间)
+```
+
+#### 📦 Committer Date (提交时间)
+
+- **含义**: 代码最后一次被提交到仓库的时间
+- **设置时机**: 每次 commit、amend、rebase、cherry-pick 时
+- **会更新**: 任何修改 commit 的操作都会更新这个时间
+- **查看命令**: `git log --format="%ci"`
+
+**示例场景**:
+
+```bash
+# 原始提交
+git commit -m "feat: 添加登录功能"
+# Author Date: 2026-01-15 10:00:00
+# Committer Date: 2026-01-15 10:00:00
+
+# 修改 commit message
+git commit --amend -m "feat(auth): 添加用户登录功能"
+# Author Date: 2026-01-15 10:00:00 (不变)
+# Committer Date: 2026-01-15 10:30:00 (更新)
+
+# 再次修改
+git commit --amend --no-edit
+# Author Date: 2026-01-15 10:00:00 (不变)
+# Committer Date: 2026-01-15 11:00:00 (再次更新)
+```
+
+### 🔄 两者的关系
+
+| 操作                 | Author Date        | Committer Date     |
+| -------------------- | ------------------ | ------------------ |
+| `git commit`         | 设置为当前时间     | 设置为当前时间     |
+| `git commit --amend` | 保持不变           | 更新为当前时间     |
+| `git rebase`         | 保持不变           | 更新为当前时间     |
+| `git cherry-pick`    | 保持原 commit 时间 | 设置为当前时间     |
+| `git merge`          | 保持原 commit 时间 | 保持原 commit 时间 |
+
+### 🎯 为什么要同时修改两者？
+
+在大多数情况下，我们希望这两个时间保持一致，因为：
+
+1. **简化理解**: 避免混淆，一个 commit 只有一个时间
+2. **历史清晰**: 提交历史更容易理解和追溯
+3. **避免误导**: 防止出现"作者时间是昨天，但提交时间是今天"的困惑
+
+**本命令默认同时修改两者**，确保时间一致性。
+
+### 📊 查看两个时间
+
+```bash
+# 查看 Author Date
+git log --format="%ai %s"
+# 输出: 2026-01-15 10:00:00 +0800 feat: 添加登录功能
+
+# 查看 Committer Date
+git log --format="%ci %s"
+# 输出: 2026-01-15 10:00:00 +0800 feat: 添加登录功能
+
+# 同时查看两者
+git log --format="Author: %ai | Committer: %ci | %s"
+# 输出: Author: 2026-01-15 10:00:00 +0800 | Committer: 2026-01-15 10:00:00 +0800 | feat: 添加登录功能
+
+# 使用 gw log 查看（更友好）
+gw log
+```
+
+### 实现方式
+
+**最新 commit**:
+
+```bash
+GIT_AUTHOR_DATE="2026-01-15 00:00:00" \
+GIT_COMMITTER_DATE="2026-01-15 00:00:00" \
+git commit --amend --no-edit
+```
+
+**历史 commit**:
+
+```bash
+git filter-branch -f --env-filter '
+  if [ "$GIT_COMMIT" = "commit-hash" ]; then
+    export GIT_AUTHOR_DATE="2026-01-15 00:00:00"
+    export GIT_COMMITTER_DATE="2026-01-15 00:00:00"
+  fi
+' parent-hash..HEAD
+```
+
+## 常见问题
+
+### Q: 为什么 Git 要有两个时间？
+
+A: 这是为了区分"谁写的代码"和"谁提交的代码"。在团队协作中很有用：
+
+**场景 1: 代码审查**
+
+```bash
+# 小明写了代码
+git commit -m "feat: 添加功能"
+# Author: 小明, Author Date: 2026-01-15
+
+# 小红审查后合并（使用 cherry-pick）
+git cherry-pick abc123
+# Author: 小明, Author Date: 2026-01-15 (保留原作者)
+# Committer: 小红, Committer Date: 2026-01-16 (记录合并者)
+```
+
+**场景 2: 补丁应用**
+
+```bash
+# 开源项目收到贡献者的补丁
+git am < patch.diff
+# Author: 贡献者, Author Date: 补丁创建时间
+# Committer: 维护者, Committer Date: 应用补丁时间
+```
+
+### Q: 为什么时间是 00:00:00？
+
+A: 为了简化操作，只需要输入日期（YYYY-MM-DD），时间默认为 00:00:00。大多数情况下，我们只关心日期，不需要精确到秒。
+
+### Q: 可以修改时间部分吗？
+
+A: 当前版本只支持修改日期，时间固定为 00:00:00。如需精确时间，可以手动使用 git 命令：
+
+```bash
+# 修改最新 commit 的时间为指定的精确时间
+GIT_AUTHOR_DATE="2026-01-15 14:30:00" \
+GIT_COMMITTER_DATE="2026-01-15 14:30:00" \
+git commit --amend --no-edit
+```
+
+### Q: 什么时候两个时间会不一致？
+
+A: 以下操作会导致两个时间不一致：
+
+1. **修改 commit**: `git commit --amend` 会更新 Committer Date
+2. **Rebase**: `git rebase` 会更新所有 commit 的 Committer Date
+3. **Cherry-pick**: `git cherry-pick` 会保留 Author Date，但设置新的 Committer Date
+4. **手动修改**: 使用环境变量单独修改某个时间
+
+**示例**:
+
+```bash
+# 原始 commit
+git commit -m "feat: 功能"
+# Author Date: 2026-01-15 10:00:00
+# Committer Date: 2026-01-15 10:00:00
+
+# 修改 commit message
+git commit --amend -m "feat: 新功能"
+# Author Date: 2026-01-15 10:00:00 (不变)
+# Committer Date: 2026-01-15 11:00:00 (更新)
+```
+
+### Q: 为什么本命令要同时修改两者？
+
+A: 保持时间一致性，避免混淆。如果你需要单独修改某个时间，可以使用原生 git 命令：
+
+```bash
+# 只修改 Author Date
+GIT_AUTHOR_DATE="2026-01-15 00:00:00" git commit --amend --no-edit
+
+# 只修改 Committer Date
+GIT_COMMITTER_DATE="2026-01-15 00:00:00" git commit --amend --no-edit
+```
+
+### Q: 修改后如何验证？
+
+A: 使用 `gw log` 或 `git log` 查看提交历史，确认时间已更新。
+
+### Q: 修改失败怎么办？
+
+A: 如果修改历史 commit 失败，可以使用 `git reflog` 找回之前的状态：
+
+```bash
+git reflog
+git reset --hard HEAD@{1}
+```