modern-git

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Modern Git Commands

现代Git命令

Purpose: This skill teaches AI agents to use modern, intuitive Git commands instead of legacy multi-purpose commands like

git checkout

. Modern commands are clearer, safer, and make code intent more obvious.

用途： 本技能旨在教会AI Agent使用现代、直观的Git命令，替代

git checkout

这类传统的多用途命令。现代命令更清晰、更安全，能让代码操作意图更明确。

Core Principles

核心原则

Use
git switch
for branch operations - NOT
```
git checkout
```
Use
git restore
for file operations - NOT
```
git checkout --
```

Use
git push --force-with-lease
- NOT

git push --force

Be explicit about intent - Clear commands prevent mistakes

分支操作使用
git switch
- 而非
```
git checkout
```
文件操作使用
git restore
- 而非
```
git checkout --
```

使用
git push --force-with-lease
- 而非

git push --force

明确操作意图 - 清晰的命令可避免错误

Quick Reference

快速参考

Branch Operations → Use

git switch

分支操作 → 使用

git switch

bash

undefined

bash

undefined

✓ CORRECT: Modern commands

✓ 正确：现代命令

git switch main # Switch to existing branch git switch -c feature-branch # Create and switch to new branch git switch - # Switch to previous branch

git switch main # 切换到已有分支 git switch -c feature-branch # 创建并切换到新分支 git switch - # 切换到上一个分支

✗ AVOID: Legacy commands

✗ 避免：传统命令

git checkout main # Overloaded command, unclear intent git checkout -b feature-branch # Same operation, less clear git checkout - # Same, but what does "-" mean?


**Why:** `git switch` has a single, clear purpose: branch operations. It provides better error messages and is harder to misuse.

git checkout main # 重载命令，意图不明确 git checkout -b feature-branch # 相同操作，但不够清晰 git checkout - # 相同功能，但“-”的含义模糊？


**原因：** `git switch`的单一明确用途就是分支操作。它能提供更友好的错误提示，且更难被误用。

File Operations → Use

git restore

文件操作 → 使用

git restore

bash

undefined

bash

undefined

✓ CORRECT: Modern commands

✓ 正确：现代命令

git restore src/app.js # Discard working directory changes git restore --staged src/app.js # Unstage file git restore --source=abc123 src/app.js # Restore from specific commit git restore --staged --worktree src/app.js # Unstage AND discard

git restore src/app.js # 丢弃工作区的修改 git restore --staged src/app.js # 取消暂存文件 git restore --source=abc123 src/app.js # 从指定提交中恢复文件 git restore --staged --worktree src/app.js # 同时取消暂存并丢弃修改

✗ AVOID: Legacy commands

✗ 避免：传统命令

git checkout -- src/app.js # Requires confusing "--" separator git reset HEAD src/app.js # "reset" sounds destructive git checkout abc123 -- src/app.js # Unclear what's happening


**Why:** `git restore` is dedicated to file operations with explicit flags (`--staged`, `--worktree`, `--source`) that make intent crystal clear.

git checkout -- src/app.js # 需要易混淆的“--”分隔符 git reset HEAD src/app.js # “reset”听起来具有破坏性 git checkout abc123 -- src/app.js # 操作意图不明确


**原因：** `git restore`专门用于文件操作，通过明确的参数（`--staged`、`--worktree`、`--source`）让操作意图一目了然。

Force Push → Use

--force-with-lease

强制推送 → 使用

--force-with-lease

bash

undefined

bash

undefined

✓ CORRECT: Safe force push

✓ 正确：安全的强制推送

git push --force-with-lease origin feature-branch

✗ AVOID: Dangerous force push

✗ 避免：危险的强制推送

git push --force origin feature-branch


**Why:** `--force-with-lease` checks if the remote branch has been updated by others before force pushing. Prevents accidental overwrites.

git push --force origin feature-branch


**原因：** `--force-with-lease`会在强制推送前检查远程分支是否被他人更新，可防止意外覆盖他人的提交。

Decision Trees

决策树

"I need to switch branches"

“我需要切换分支”

Do you need to create the branch first?
├─ YES → git switch -c <new-branch>
└─ NO  → git switch <existing-branch>

Special cases:
├─ Previous branch → git switch -
└─ With uncommitted changes → git stash && git switch <branch> && git stash pop
                              OR git switch -c <new-branch>  (bring changes with you)

是否需要先创建分支？
├─ 是 → git switch -c <new-branch>
└─ 否 → git switch <existing-branch>

特殊情况：
├─ 切换到上一个分支 → git switch -
└─ 存在未提交修改 → git stash && git switch <branch> && git stash pop
                              或者 git switch -c <new-branch> （携带修改到新分支）

"I need to fix a file"

“我需要修复文件”

What do you want to fix?
├─ Discard working directory changes
│  └─> git restore <file>
│
├─ Unstage file (keep changes in working directory)
│  └─> git restore --staged <file>
│
├─ Discard AND unstage
│  └─> git restore --staged --worktree <file>
│
└─ Restore from specific commit
   └─> git restore --source=<commit> <file>

你想要执行什么操作？
├─ 丢弃工作区修改
│  └─> git restore <file>
│
├─ 取消暂存文件（保留工作区修改）
│  └─> git restore --staged <file>
│
├─ 同时取消暂存并丢弃修改
│  └─> git restore --staged --worktree <file>
│
└─ 从指定提交恢复文件
   └─> git restore --source=<commit> <file>

"I need to force push"

“我需要强制推送”

Why do you need to force push?
├─ After rebase/amend (common, safe scenario)
│  └─> git push --force-with-lease origin <branch>
│
├─ To overwrite remote (rare, potentially dangerous)
│  ├─ Are you SURE no one else has pushed?
│  │  ├─ YES → git push --force-with-lease origin <branch>
│  │  └─ NO  → git fetch && git rebase origin/<branch>
│  │
│  └─> Tip: ALWAYS prefer --force-with-lease over --force

为什么需要强制推送？
├─ 变基/修改提交后（常见且安全的场景）
│  └─> git push --force-with-lease origin <branch>
│
├─ 覆盖远程分支（罕见且有风险）
│  ├─ 你确定没有其他人推送过吗？
│  │  ├─ 是 → git push --force-with-lease origin <branch>
│  │  └─ 否 → git fetch && git rebase origin/<branch>
│  │
│  └─> 提示：始终优先使用--force-with-lease而非--force

Common Workflows

常见工作流

Workflow 1: Start New Feature

工作流1：启动新功能

bash

undefined

bash

undefined

✓ CORRECT

✓ 正确

git switch main git pull git switch -c feature/new-feature

✗ AVOID

✗ 避免

git checkout main git pull git checkout -b feature/new-feature

undefined

git checkout main git pull git checkout -b feature/new-feature

undefined

Workflow 2: Discard File Changes

工作流2：丢弃文件修改

bash

undefined

bash

undefined

✓ CORRECT

✓ 正确

git restore src/broken.js # Single file git restore . # All files in current directory

git restore src/broken.js # 单个文件 git restore . # 当前目录下所有文件

✗ AVOID

✗ 避免

git checkout -- src/broken.js git checkout -- .

undefined

git checkout -- src/broken.js git checkout -- .

undefined

Workflow 3: Unstage and Discard

工作流3：取消暂存并丢弃修改

bash

undefined

bash

undefined

✓ CORRECT

✓ 正确

git restore --staged --worktree src/app.js

OR two steps for clarity

或者分两步操作更清晰

git restore --staged src/app.js # Unstage git restore src/app.js # Then discard

git restore --staged src/app.js # 取消暂存 git restore src/app.js # 然后丢弃修改

✗ AVOID

✗ 避免

git reset HEAD src/app.js git checkout -- src/app.js

undefined

git reset HEAD src/app.js git checkout -- src/app.js

undefined

Workflow 4: Restore from Specific Commit

工作流4：从指定提交恢复文件

bash

undefined

bash

undefined

✓ CORRECT

✓ 正确

git restore --source=abc123 src/legacy.js git restore --source=HEAD~3 src/config.js

✗ AVOID

✗ 避免

git checkout abc123 -- src/legacy.js git checkout HEAD~3 -- src/config.js

undefined

git checkout abc123 -- src/legacy.js git checkout HEAD~3 -- src/config.js

undefined

Workflow 5: Safe Rebase and Push

工作流5：安全变基并推送

bash

undefined

bash

undefined

✓ CORRECT

✓ 正确

git switch feature-branch git rebase main git push --force-with-lease origin feature-branch

✗ AVOID

✗ 避免

git checkout feature-branch git rebase main git push --force origin feature-branch

undefined

git checkout feature-branch git rebase main git push --force origin feature-branch

undefined

Safety Guidelines

安全指南

1. Always Use Modern Commands for Common Operations

1. 常规操作始终使用现代命令

Operation	Use This	NOT This
Switch branch	`git switch <branch>`	`git checkout <branch>`
Create branch	`git switch -c <branch>`	`git checkout -b <branch>`
Discard changes	`git restore <file>`	`git checkout -- <file>`
Unstage	`git restore --staged <file>`	`git reset HEAD <file>`
Force push	`git push --force-with-lease`	`git push --force`

操作	使用该命令	不要使用
切换分支	`git switch <branch>`	`git checkout <branch>`
创建分支	`git switch -c <branch>`	`git checkout -b <branch>`
丢弃修改	`git restore <file>`	`git checkout -- <file>`
取消暂存	`git restore --staged <file>`	`git reset HEAD <file>`
强制推送	`git push --force-with-lease`	`git push --force`

2. Be Explicit About Intent

2. 明确操作意图

bash

undefined

bash

undefined

✓ GOOD: Intent is obvious

✓ 良好：意图明确

git restore --staged src/app.js # Clearly unstaging git restore --source=HEAD~1 src/app.js # Clearly restoring from parent commit

git restore --staged src/app.js # 明确取消暂存 git restore --source=HEAD~1 src/app.js # 明确从父提交恢复

✗ UNCLEAR: What's happening?

✗ 模糊：操作意图不明确

git checkout -- src/app.js # Restoring? From where? git checkout HEAD~1 -- src/app.js # Is this switching branches or restoring?

undefined

git checkout -- src/app.js # 是恢复？从哪里恢复？ git checkout HEAD~1 -- src/app.js # 是切换分支还是恢复文件？

undefined

3. Protect Against Accidents

3. 防止意外操作

bash

undefined

bash

undefined

✓ SAFE: --force-with-lease protects against overwrites

✓ 安全：--force-with-lease可防止覆盖他人提交

git push --force-with-lease origin feature-branch

✗ DANGEROUS: Can overwrite others' work

✗ 危险：可能覆盖他人的工作

git push --force origin feature-branch

✓ SAFE: git switch refuses to switch with uncommitted changes

✓ 安全：存在未提交修改时git switch会拒绝切换

git switch main # Errors if uncommitted changes

git switch main # 如果有未提交修改会报错

✗ RISKY: Need to remember --discard flag

✗ 有风险：需要记住--discard参数

git switch --discard-changes main # Only use when you WANT to lose changes

undefined

git switch --discard-changes main # 仅当你确实想要丢弃修改时使用

undefined

4. Use Stash for Experimentation

4. 使用Stash进行实验性操作

bash

undefined

bash

undefined

✓ SAFE: Can recover if experiment fails

✓ 安全：实验失败可恢复

git stash push -m "Before risky operation"

Try risky operation

执行有风险的操作

git restore --source=old-commit .

If it fails:

如果失败：

git stash pop # Recover

git stash pop # 恢复之前的状态

✗ RISKY: No recovery option

✗ 有风险：无法恢复

git restore --source=old-commit .

Changes lost forever!

修改将永久丢失！

undefined

undefined

When Legacy Commands Are Still OK

仍可使用传统命令的场景

Some scenarios don't have modern equivalents:

bash

undefined

部分场景尚无现代替代命令：

bash

undefined

Exploring history (detached HEAD)

查看历史记录（分离HEAD状态）

git checkout abc123 # Still acceptable git switch --detach abc123 # More explicit alternative

git checkout abc123 # 仍然可以使用 git switch --detach abc123 # 更明确的替代命令

Complex remote tracking

复杂远程跟踪设置

git checkout -b local origin/remote # Still commonly used


**Rule of thumb:** If there's a modern equivalent for your use case, use it. Legacy commands are OK only when no modern alternative exists.

git checkout -b local origin/remote # 仍然被广泛使用


**经验法则：** 如果你的操作场景有对应的现代命令，请优先使用。仅当没有现代替代命令时，才使用传统命令。

Common Mistakes to Avoid

需避免的常见错误

Mistake 1: Using

git checkout

for Everything

错误1：所有操作都使用

git checkout

bash

undefined

bash

undefined

✗ BAD: Unclear intent, error-prone

✗ 糟糕：意图不明确，容易出错

git checkout main git checkout -b feature git checkout -- src/app.js

✓ GOOD: Clear intent for each operation

✓ 良好：每个操作的意图清晰

git switch main git switch -c feature git restore src/app.js

undefined

git switch main git switch -c feature git restore src/app.js

undefined

Mistake 2: Forgetting

--force-with-lease

错误2：忘记使用

--force-with-lease

bash

undefined

bash

undefined

✗ BAD: Can overwrite others' commits

✗ 糟糕：可能覆盖他人的提交

git rebase main git push --force origin feature-branch

✓ GOOD: Safe against overwrites

✓ 良好：可防止意外覆盖

git rebase main git push --force-with-lease origin feature-branch

undefined

git rebase main git push --force-with-lease origin feature-branch

undefined

Mistake 3: Confusing

--staged

and

--worktree

错误3：混淆

--staged

和

--worktree

bash

undefined

bash

undefined

✗ WRONG: Only unstages, doesn't discard changes

✗ 错误：仅取消暂存，并未丢弃修改

git restore --staged src/app.js

File still modified in working directory!

文件在工作区仍然是修改状态！

✓ CORRECT: Specify both if you want both

✓ 正确：如果需要同时执行两个操作，请明确指定

git restore --staged --worktree src/app.js

OR

或者

git restore --staged src/app.js # Unstage git restore src/app.js # Then discard

undefined

git restore --staged src/app.js # 取消暂存 git restore src/app.js # 然后丢弃修改

undefined

Mistake 4: Not Checking Before Discarding

错误4：丢弃修改前未检查

bash

undefined

bash

undefined

✗ RISKY: Blindly discarding without checking

✗ 有风险：盲目丢弃修改而不检查

git restore .

✓ SAFE: Check what you're losing first

✓ 安全：先检查将要丢失的内容

git status git diff git restore .

undefined

git status git diff git restore .

undefined

Integration with AI Code Generation

与AI代码生成的集成

When generating Git commands in code or documentation:

在代码或文档中生成Git命令时：

1. Default to Modern Commands

1. 默认使用现代命令

markdown

undefined

markdown

undefined

✓ GOOD: Use modern commands in examples

✓ 良好：示例中使用现代命令

To discard your changes, run: ```bash git restore src/app.js ```

要丢弃修改，请执行： ```bash git restore src/app.js ```

✗ AVOID: Don't teach legacy commands

✗ 避免：不要教授传统命令

To discard your changes, run: ```bash git checkout -- src/app.js ```

undefined

要丢弃修改，请执行： ```bash git checkout -- src/app.js ```

undefined

2. Explain Why Modern Commands Are Better

2. 解释现代命令更优的原因

markdown

undefined

markdown

undefined

✓ GOOD: Educate users

✓ 良好：引导用户理解

Use

git switch

instead of

git checkout

for branch operations. This makes your intent clearer and provides better error messages.

分支操作请使用

git switch

而非

git checkout

。这能让你的操作意图更清晰，并获得更友好的错误提示。

✗ INSUFFICIENT: Just showing command without context

✗ 不足：仅展示命令而不提供上下文

Use

git switch main

to switch branches.

undefined

使用

git switch main

切换分支。

undefined

3. Use Consistent Command Patterns

3. 使用一致的命令模式

bash

undefined

bash

undefined

✓ GOOD: Consistent modern commands throughout

✓ 良好：全程使用一致的现代命令

git switch develop git pull git switch -c feature/new-feature git restore --staged accidental-file.js

✗ INCONSISTENT: Mixing old and new

✗ 不一致：混合使用新旧命令

git checkout develop git pull git switch -c feature/new-feature git checkout -- accidental-file.js

undefined

git checkout develop git pull git switch -c feature/new-feature git checkout -- accidental-file.js

undefined

Reference Documentation

参考文档

For detailed comparisons and advanced scenarios:

Command Comparison - Side-by-side legacy vs modern command comparisons
Migration Guide - Detailed patterns for complex scenarios

如需详细对比和高级场景说明：

命令对比 - 传统命令与现代命令的逐项对比
迁移指南 - 复杂场景下的详细迁移模式

Summary Table

汇总表

Use Case	Command	Key Flags	Notes
Switch to branch	`git switch <branch>`	`-c` (create), `-` (previous)	Replaces `git checkout <branch>`
Discard file changes	`git restore <file>`	`--worktree` (default)	Replaces `git checkout -- <file>`
Unstage file	`git restore --staged <file>`	`--staged`	Replaces `git reset HEAD <file>`
Restore from commit	`git restore --source=<commit> <file>`	`--source`	Replaces `git checkout <commit> -- <file>`
Force push safely	`git push --force-with-lease`	`--force-with-lease`	Replaces `git push --force`

使用场景	命令	关键参数	说明
切换分支	`git switch <branch>`	`-c` （创建）、 `-` （上一个）	替代 `git checkout <branch>`
丢弃文件修改	`git restore <file>`	`--worktree` （默认）	替代 `git checkout -- <file>`
取消暂存文件	`git restore --staged <file>`	`--staged`	替代 `git reset HEAD <file>`
从提交恢复文件	`git restore --source=<commit> <file>`	`--source`	替代 `git checkout <commit> -- <file>`
安全强制推送	`git push --force-with-lease`	`--force-with-lease`	替代 `git push --force`

Key Takeaway

核心要点

Always prefer modern commands for clarity, safety, and better error messages. Your future self (and code reviewers) will thank you.

When in doubt:

Branch operations →
```
git switch
```
File operations →
```
git restore
```
Force push →
```
--force-with-lease
```

始终优先使用现代命令，以提升清晰度、安全性并获得更好的错误提示。你的未来自我（以及代码评审人员）会为此感谢你。

如有疑问：

分支操作 →
```
git switch
```
文件操作 →
```
git restore
```
强制推送 →
```
--force-with-lease
```

modern-git

Original

Translation

Modern Git Commands

现代Git命令

Core Principles

核心原则

Quick Reference

快速参考

Branch Operations → Use git switch

分支操作 → 使用git switch

✓ CORRECT: Modern commands

✓ 正确：现代命令

✗ AVOID: Legacy commands

✗ 避免：传统命令

File Operations → Use git restore

文件操作 → 使用git restore

✓ CORRECT: Modern commands

✓ 正确：现代命令

✗ AVOID: Legacy commands

✗ 避免：传统命令

Force Push → Use --force-with-lease

强制推送 → 使用--force-with-lease

✓ CORRECT: Safe force push

✓ 正确：安全的强制推送

✗ AVOID: Dangerous force push

✗ 避免：危险的强制推送

Decision Trees

决策树

"I need to switch branches"

“我需要切换分支”

"I need to fix a file"

“我需要修复文件”

"I need to force push"

“我需要强制推送”

Common Workflows

常见工作流

Workflow 1: Start New Feature

工作流1：启动新功能

✓ CORRECT

✓ 正确

✗ AVOID

✗ 避免

Workflow 2: Discard File Changes

工作流2：丢弃文件修改

✓ CORRECT

✓ 正确

✗ AVOID

✗ 避免

Workflow 3: Unstage and Discard

工作流3：取消暂存并丢弃修改

✓ CORRECT

✓ 正确

OR two steps for clarity

或者分两步操作更清晰

✗ AVOID

✗ 避免

Workflow 4: Restore from Specific Commit

工作流4：从指定提交恢复文件

✓ CORRECT

✓ 正确

✗ AVOID

✗ 避免

Workflow 5: Safe Rebase and Push

工作流5：安全变基并推送

✓ CORRECT

✓ 正确

✗ AVOID

✗ 避免

Safety Guidelines

安全指南

1. Always Use Modern Commands for Common Operations

1. 常规操作始终使用现代命令

2. Be Explicit About Intent

2. 明确操作意图

✓ GOOD: Intent is obvious

✓ 良好：意图明确

✗ UNCLEAR: What's happening?

✗ 模糊：操作意图不明确

3. Protect Against Accidents

Branch Operations → Use
`git switch`

分支操作 → 使用
`git switch`

File Operations → Use
`git restore`

文件操作 → 使用
`git restore`

Force Push → Use
`--force-with-lease`

强制推送 → 使用
`--force-with-lease`

Mistake 1: Using
`git checkout`
for Everything

错误1：所有操作都使用
`git checkout`

Mistake 2: Forgetting
`--force-with-lease`

错误2：忘记使用
`--force-with-lease`

Mistake 3: Confusing
`--staged`
and
`--worktree`

错误3：混淆
`--staged`
和
`--worktree`