Umgang mit dem Fehler 'error: untracked working tree files would be overwritten by checkout' in Git

Einleitung

Git ist ein leistungsstarkes Versionskontrollsystem, das für die moderne Softwareentwicklung unerlässlich ist. Bei der Verwendung von Git können Sie auf die Fehlermeldung stoßen: "error: untracked working tree files would be overwritten by checkout". Dieser Fehler tritt auf, wenn Sie versuchen, den Branch zu wechseln, Git aber erkennt, dass diese Aktion Dateien in Ihrem aktuellen Arbeitsverzeichnis überschreiben würde, die noch nicht von Git verfolgt werden. Diese Sicherheitsfunktion verhindert versehentlichen Datenverlust.

In diesem Lab lernen Sie die Ursache dieses häufigen Fehlers, wie Sie die widersprüchlichen Dateien identifizieren und verschiedene Methoden zur Behebung kennen. Am Ende dieser Anleitung werden Sie in der Lage sein, Ihren Git-Workflow effektiver zu verwalten und diesen Fehler mit Zuversicht zu beheben.

Reproduzieren des Checkout-Fehlers

Um zu verstehen, wie der Fehler behoben werden kann, müssen wir ihn zunächst reproduzieren. Dies hilft zu verdeutlichen, warum Git einen Konflikt meldet. Unser Setup-Skript hat bereits ein Git-Repository mit zwei Branches erstellt: main und feature-branch. Der feature-branch enthält eine Datei, die wir nun lokal im main-Branch erstellen werden.

Navigieren Sie zunächst in das Projektverzeichnis. Alle Befehle in diesem Lab werden von diesem Verzeichnis aus ausgeführt.

cd ~/project/git-checkout-demo

Überprüfen wir den aktuellen Status unseres Repositories, um sicherzustellen, dass alles sauber ist.

git status

Die Ausgabe sollte wie folgt aussehen:

On branch main
nothing to commit, working tree clean

Dies bestätigt, dass wir uns im main-Branch befinden und keine ausstehenden Änderungen haben. Lassen Sie uns nun die verfügbaren Branches auflisten.

git branch

Sie sehen die beiden Branches, wobei * den aktuellen Branch anzeigt:

  feature-branch
* main

Lassen Sie uns nun den Konflikt erzeugen. Wir erstellen eine neue Datei namens feature.md in unserem aktuellen Arbeitsverzeichnis. Diese Datei ist im main-Branch derzeit "untracked" (nicht verfolgt) von Git, aber eine Datei mit demselben Namen existiert bereits und ist im feature-branch verfolgt.

echo "## My local changes to feature documentation" > feature.md

Überprüfen Sie den Status erneut, um die neue, nicht verfolgte Datei zu sehen.

git status

Die Ausgabe zeigt nun feature.md als nicht verfolgte Datei an:

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)

Versuchen wir schließlich, zum feature-branch zu wechseln.

git checkout feature-branch

Dieser Befehl schlägt fehl und gibt den Fehler aus, den wir untersuchen:

error: The following untracked working tree files would be overwritten by checkout:
	feature.md
Please move or remove them before you switch branches.
Aborting

Git hat den Checkout abgebrochen, um Ihre lokale, nicht verfolgte Datei feature.md davor zu schützen, von der Version aus dem feature-branch überschrieben zu werden. In den nächsten Schritten werden wir verschiedene Möglichkeiten zur Behebung dieses Problems untersuchen.

Beheben des Konflikts mit git stash

Eine der sichersten und gebräuchlichsten Methoden zur Behebung dieses Fehlers ist die Verwendung von git stash. Dieser Befehl speichert Ihre lokalen Änderungen (sowohl gestagte als auch ungestagte) temporär und setzt das Arbeitsverzeichnis auf den letzten Commit zurück. Dies ermöglicht es Ihnen, frei zwischen Branches zu wechseln.

Wir befinden uns derzeit im main-Branch mit der nicht verfolgten Datei feature.md, die den Konflikt verursacht.

Um nicht verfolgte Dateien zu stashen, müssen Sie die Option --include-untracked (oder -u) verwenden.

git stash push --include-untracked

Sie sehen eine Bestätigungsmeldung:

Saved working directory and index state WIP on main: <commit_hash> Initial commit with README

Überprüfen Sie nun erneut den Status Ihres Repositories.

git status

Das Arbeitsverzeichnis ist sauber und die nicht verfolgte Datei ist verschwunden:

On branch main
nothing to commit, working tree clean

Da das Arbeitsverzeichnis sauber ist, können Sie nun ohne Fehler zum feature-branch wechseln.

git checkout feature-branch

Der Befehl wird erfolgreich ausgeführt:

Switched to branch 'feature-branch'

Sie befinden sich nun im feature-branch. Wenn Sie feature.md überprüfen, sehen Sie die Version, die zu diesem Branch gehört.

cat feature.md

## Official Feature Documentation

Ihre lokalen Änderungen sind sicher im Stash gespeichert. Um sie zurückzuholen, können Sie zurück zum main-Branch wechseln und den Stash anwenden.

git checkout main
git stash pop

Der Befehl git stash pop wendet die gestashten Änderungen erneut an und entfernt sie aus der Stash-Liste. Ihre Datei feature.md ist nun wieder in Ihrem Arbeitsverzeichnis vorhanden.

Für den nächsten Schritt stellen wir sicher, dass wir uns wieder im Konfliktzustand befinden. Wenn Sie dem Befehl git stash pop gefolgt sind, sind Sie bereits dort.

Beheben des Konflikts mit git clean

Eine weitere Möglichkeit, den Konflikt zu beheben, ist das Löschen der nicht verfolgten Dateien. Diese Methode ist nur dann geeignet, wenn Sie sicher sind, dass Sie die nicht verfolgten Dateien nicht benötigen. Der Befehl git clean wird zu diesem Zweck verwendet.

Warnung: Dieser Befehl löscht Dateien dauerhaft, verwenden Sie ihn daher mit Vorsicht.

Zuerst stellen wir sicher, dass wir uns im Konfliktzustand im main-Branch mit der nicht verfolgten Datei feature.md befinden.

cd ~/project/git-checkout-demo
git checkout main
## If feature.md doesn't exist, recreate it
if [ ! -f "feature.md" ]; then echo "## My local changes" > feature.md; fi
git status

Bevor Sie etwas löschen, ist es bewährte Praxis, einen "Trockenlauf" mit dem Flag -n durchzuführen. Dies zeigt Ihnen, welche Dateien gelöscht würden, ohne sie tatsächlich zu löschen.

git clean -n

Die Ausgabe listet die zu entfernenden Dateien auf:

Would remove feature.md

Sobald Sie bestätigt haben, dass Sie diese Dateien löschen möchten, können Sie den Befehl erneut mit dem Flag -f (force) ausführen.

git clean -f

Git bestätigt die Entfernung:

Removing feature.md

Da die nicht verfolgte Datei nun entfernt ist, ist Ihr Arbeitsverzeichnis sauber und Sie können die Branches ohne Probleme wechseln.

git checkout feature-branch

Der Checkout wird erfolgreich sein.

Switched to branch 'feature-branch'

Diese Methode ist schnell, aber destruktiv. Die git stash-Methode aus dem vorherigen Schritt ist im Allgemeinen sicherer, da sie Ihre Arbeit bewahrt.

Beheben durch Nachverfolgen der Datei und Best Practices

Manchmal ist die nicht verfolgte Datei nicht entbehrlich; es handelt sich um Arbeit, die Sie behalten möchten. In diesem Fall ist der richtige Ansatz, die Datei in Git's Nachverfolgungssystem aufzunehmen, indem Sie sie committen. Dieser Abschnitt behandelt auch Best Practices, um zu verhindern, dass dieser Fehler überhaupt auftritt.

Zuerst kehren wir zum main-Branch zurück und erstellen unsere widersprüchliche Datei neu.

cd ~/project/git-checkout-demo
git checkout main
echo "## My local changes to feature documentation" > feature.md

Methode: Die Datei nachverfolgen

Wenn die nicht verfolgte Datei wichtig ist, sollten Sie sie in den aktuellen Branch committen.

1. Fügen Sie die Datei zum Staging-Bereich hinzu.

   git add feature.md

2. Comitten Sie die gestagte Datei.

   git commit -m "Add local version of feature.md"

Nachdem Ihre Änderungen nun sicher im main-Branch committet sind, kann Git den Wechsel handhaben. Wenn Sie feature-branch auschecken, ersetzt Git die Arbeitsbereichdatei einfach durch die Version aus diesem Branch.

git checkout feature-branch

Der Checkout ist erfolgreich. Ihre committeten Änderungen sind sicher in der Historie des main-Branches.

Best Practice: .gitignore verwenden

Um zu verhindern, dass bestimmte Dateien (wie Protokolle, Build-Artefakte oder Umgebungsdateien) jemals nachverfolgt werden, sollten Sie eine .gitignore-Datei verwenden. Git ignoriert alle Dateien oder Verzeichnisse, die den Mustern in .gitignore entsprechen, und verhindert so, dass sie zu widersprüchlichen, nicht verfolgten Dateien werden.

Erstellen wir eine .gitignore-Datei, um alle .log-Dateien zu ignorieren.

## Switch back to main to add the .gitignore file
git checkout main

## Create the .gitignore file
echo "*.log" > .gitignore

Erstellen Sie nun eine Log-Datei.

touch app.log

Überprüfen Sie den Status.

git status

Beachten Sie, dass app.log nicht als nicht verfolgte Datei erscheint. Die .gitignore-Datei selbst ist jedoch nicht verfolgt.

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)

Sie sollten Ihre .gitignore-Datei immer committen, damit die Regeln projektübergreifend geteilt werden.

git add .gitignore
git commit -m "Add .gitignore to ignore log files"

Durch häufiges Committen und effektive Nutzung von .gitignore können Sie die Wahrscheinlichkeit, diesen Checkout-Fehler zu erhalten, erheblich reduzieren.

Zusammenfassung

In diesem Lab haben Sie gelernt, wie Sie den Fehler "error: untracked working tree files would be overwritten by checkout" in Git diagnostizieren und beheben.

Sie haben Folgendes erreicht:

1. Fehler repliziert: Sie haben erfolgreich ein Szenario erstellt, das den Fehler auslöst, und so ein klares Verständnis seiner Ursache gewonnen.
2. Mit git stash behoben: Sie haben gelernt, wie Sie git stash verwenden, um nicht verfolgte Dateien vorübergehend zu speichern, sodass Sie sicher zwischen Branches wechseln können, ohne Arbeit zu verlieren.
3. Mit git clean behoben: Sie haben gelernt, wie Sie git clean verwenden, um nicht verfolgte Dateien zu entfernen, wenn sie nicht mehr benötigt werden, nachdem Sie zuerst einen Trockenlauf durchgeführt haben, um Fehler zu vermeiden.
4. Durch Nachverfolgen von Dateien behoben: Sie haben gelernt, das Problem zu beheben, indem Sie die nicht verfolgte Datei committen, was der richtige Ansatz für Arbeit ist, die Sie behalten möchten.
5. Best Practices gelernt: Sie haben gelernt, wie Sie eine .gitignore-Datei verwenden, um zu verhindern, dass temporäre oder Build-bezogene Dateien Konflikte verursachen.

Durch die Beherrschung dieser Techniken können Sie einen saubereren, effizienteren Git-Workflow aufrechterhalten und eines der häufigsten Probleme, mit denen Entwickler konfrontiert sind, souverän bewältigen.