Git 是一个强大的版本控制系统，对于现代软件开发至关重要。在使用 Git 时，你可能会遇到这样的错误消息：“error: untracked working tree files would be overwritten by checkout”。当你尝试切换分支时，如果 Git 检测到此操作会覆盖当前工作目录中尚未被 Git 跟踪的文件，就会出现此错误。这项安全功能可防止意外数据丢失。
在本实验中，你将了解此常见错误的原因、如何识别冲突文件以及解决此问题的几种方法。在本教程结束时，你将能够更有效地管理你的 Git 工作流程，并自信地处理此错误。
为了了解如何修复此错误，我们首先需要复现它。这将有助于阐明 Git 报告冲突的原因。我们的设置脚本已经创建了一个包含两个分支（main 和 feature-branch）的 Git 仓库。feature-branch 中包含一个文件，我们现在将在 main 分支中本地创建该文件。
首先，导航到项目目录。本实验中的所有命令都将在此目录中运行。
cd ~/project/git-checkout-demo让我们检查一下仓库的当前状态，以确保一切都干净。
git status输出应为：
On branch main
nothing to commit, working tree clean这证实了我们位于 main 分支，没有待处理的更改。现在，让我们列出可用的分支。
git branch你将看到两个分支，其中 * 指示当前分支：
feature-branch
* main现在，让我们创建冲突。我们将在当前工作目录中创建一个名为 feature.md 的新文件。此文件当前在 main 分支上未被 Git 跟踪，但同名文件已存在于 feature-branch 上并被跟踪。
echo "## My local changes to feature documentation" > feature.md再次检查状态，查看新的未跟踪文件。
git status输出现在显示 feature.md 是一个未跟踪的文件：
On branch main
Untracked files:
(use "git add <file>..." to include in what will be committed)
feature.md
nothing added to commit but untracked files present (use "git add" to track)最后，让我们尝试切换到 feature-branch。
git checkout feature-branch此命令将失败并产生我们正在研究的错误：
error: The following untracked working tree files would be overwritten by checkout:
feature.md
Please move or remove them before you switch branches.
AbortingGit 已中止 checkout 操作，以保护你本地未跟踪的 feature.md 文件不被 feature-branch 中的版本覆盖。在接下来的步骤中，我们将探讨解决此问题的不同方法。
git stash 解决冲突解决此错误最安全、最常见的方法之一是使用 git stash。此命令会临时保存你的本地修改（包括已暂存和未暂存的），并将工作目录恢复到与上次提交匹配的状态。这使你能够自由地切换分支。
我们目前在 main 分支上，未跟踪的 feature.md 文件导致了冲突。
要暂存未跟踪的文件，你需要使用 --include-untracked（或 -u）选项。
git stash push --include-untracked你将看到一条确认消息：
Saved working directory and index state WIP on main: <commit_hash> Initial commit with README现在，再次检查你的仓库状态。
git status工作目录是干净的，未跟踪的文件也消失了：
On branch main
nothing to commit, working tree clean在工作目录干净的情况下，你现在可以切换到 feature-branch 而不会出现任何错误。
git checkout feature-branch命令将成功执行：
Switched to branch 'feature-branch'你现在位于 feature-branch。如果你查看 feature.md，你将看到属于此分支的版本。
cat feature.md## Official Feature Documentation你的本地更改已安全地存储在 stash 中。要恢复它们，你可以切换回 main 分支并应用 stash。
git checkout main
git stash popgit stash pop 命令会重新应用暂存的更改，并将其从 stash 列表中移除。你的 feature.md 文件现在已返回到你的工作目录。
对于下一步，让我们确保我们回到了冲突状态。如果你执行了 git stash pop 命令，你已经在那里了。
git clean 解决冲突解决冲突的另一种方法是删除未跟踪的文件。此方法仅适用于你确定不需要未跟踪文件的情况。git clean 命令用于此目的。
**警告：**此命令会永久删除文件，请谨慎使用。
首先，让我们确保我们处于 main 分支的冲突状态，并且存在未跟踪的 feature.md 文件。
cd ~/project/git-checkout-demo
git checkout main
## 如果 feature.md 不存在，请重新创建它
if [ ! -f "feature.md" ]; then echo "## My local changes" > feature.md; fi
git status在删除任何内容之前，最佳实践是使用 -n 标志执行“试运行”。这将显示将要删除的文件，而不会实际删除它们。
git clean -n输出将列出要删除的文件：
Would remove feature.md一旦你确认要删除这些文件，就可以使用 -f（强制）标志再次运行该命令。
git clean -fGit 将确认删除：
Removing feature.md现在未跟踪的文件已消失，你的工作目录是干净的，你可以顺利地切换分支。
git checkout feature-branchCheckout 将会成功。
Switched to branch 'feature-branch'此方法速度快但具有破坏性。上一步中的 git stash 方法通常更安全，因为它会保留你的工作。
有时，未跟踪的文件是不可丢弃的；它们是你想要保留的工作。在这种情况下，正确的方法是通过提交将文件添加到 Git 的跟踪系统。本节还涵盖了防止此错误首次发生的最佳实践。
首先，让我们回到 main 分支并重新创建我们的冲突文件。
cd ~/project/git-checkout-demo
git checkout main
echo "## My local changes to feature documentation" > feature.md如果未跟踪的文件很重要，你应该将其提交到当前分支。
将文件添加到暂存区。
git add feature.md提交暂存的文件。
git commit -m "Add local version of feature.md"现在你的更改已安全提交到 main 分支，Git 可以处理切换操作。当你检出 feature-branch 时，Git 将简单地用该分支的版本替换工作区文件。
git checkout feature-branch检出成功。你的已提交更改安全地保存在 main 分支的历史记录中。
.gitignore为了防止某些文件（如日志、构建产物或环境文件）被跟踪，你应该使用 .gitignore 文件。Git 将忽略任何匹配 .gitignore 中模式的文件或目录，从而防止它们成为冲突的未跟踪文件。
让我们创建一个 .gitignore 文件来忽略所有 .log 文件。
## 切换回 main 以添加 .gitignore 文件
git checkout main
## 创建 .gitignore 文件
echo "*.log" > .gitignore现在，创建一个日志文件。
touch app.log检查状态。
git status请注意，app.log 没有显示为未跟踪文件。但是，.gitignore 文件本身是未跟踪的。
On branch main
Untracked files:
(use "git add <file>..." to include in what will be committed)
.gitignore
nothing added to commit but untracked files present (use "git add" to track)你应该始终提交你的 .gitignore 文件，以便规则在整个项目中共享。
git add .gitignore
git commit -m "Add .gitignore to ignore log files"通过频繁提交和有效使用 .gitignore，你可以显著降低遇到此检出错误的几率。
在本实验中，你学习了如何诊断和解决 Git 中的“error: untracked working tree files would be overwritten by checkout”错误。
你完成了以下操作：
git stash 解决：你学习了如何使用 git stash 来临时保存未跟踪的文件，从而可以在不丢失工作的情况下安全地切换分支。git clean 解决：你学习了如何在不再需要未跟踪文件时使用 git clean 来删除它们，并在执行此操作前进行了试运行以避免错误。.gitignore 文件来防止临时文件或与构建相关的文件引起冲突。通过掌握这些技术，你可以维护一个更干净、更高效的 Git 工作流程，并自信地处理开发者面临的最常见问题之一。
