Troubleshooting VS Code and Git
Intermediate VS Code UI
Why this matters
Most "VS Code is broken" reports are one of a dozen things, and half of them are Git rather than the editor. Knowing which is which saves the time of the person you would otherwise ask.
The two panels that diagnose everything
- View → Output → Git — every command VS Code ran, and Git's reply. This alone explains most surprises.
- The integrated terminal — run the same command yourself. If it works there and not in the editor, the problem is the editor; if it fails in both, the problem is Git or the repository.
That second step is the useful split, and it is worth doing before anything else.
The twelve
| Symptom | Cause | Fix |
|---|---|---|
| "Git not found. Install it or configure it using the 'git.path' setting" | Git missing, or installed after VS Code started | Install Git, restart VS Code, then set git.path if it persists (lesson 15.1) |
| Source Control view is empty | The open folder is not the repository root | Open the folder containing .git (lesson 15.4) |
| Commit committed files you did not stage | git.enableSmartCommit is on |
Turn it off |
| A push asks for a password every time | No credential manager | Configure one (lesson 8.4) |
| "Authentication failed" after months | The token expired | New token, update the stored credential (lesson 15.3) |
| Signed in to GitHub but pushes still fail | Two separate authentications | The editor's account is not Git's credential |
| Push rejected, "non-fast-forward" | The branch moved on the server | Pull, resolve, push (lesson 7.6) |
| "Your branch has no upstream" | The branch was never published | Publish Branch |
| Changes vanished after switching branches | VS Code offered Stash & Checkout and you accepted | … → Stash → Pop Latest Stash |
| A file keeps reappearing in commits | It is not ignored, or it was committed before being ignored | .gitignore, then git rm --cached (lesson 4.3) |
| The merge editor will not open | git.mergeEditor is off, or the file has no conflict left |
Use Resolve in Merge Editor on the file, or check the file is still conflicted |
| Everything is slow in a large repository | Autofetch plus decorations on a huge tree | Turn off git.autofetch temporarily, and reduce GitLens decorations |
"index.lock exists"
The full message is Unable to create '…/.git/index.lock': File exists. Git creates that file while it works and removes it afterwards; a crashed or interrupted operation can leave it behind.
- Make sure no Git operation is genuinely running: no terminal command, no other editor window.
- Then delete the file:
rm -f .git/index.lock. - Run
git statusto confirm the repository is healthy.
Deleting it while something is running is how a repository gets into a genuinely odd state, which is why step 1 comes first.
Line endings warnings on Windows
warning: LF will be replaced by CRLF appears on every file. It is a warning rather than an error, and it is configuration rather than a problem (lesson 4.5). The fix is a .gitattributes in the repository, which is a team decision, not a personal setting.
When to stop and ask
Ask when: the repository state is one you cannot describe, several people see the same problem, or a required check is failing for reasons that are not yours. Include the four things that make the question answerable (lesson 13.9):
- What you were doing, in plain words.
- The exact command, copied from Output → Git.
- The exact error text.
git statusandgit log --oneline -3.
How to do it
The three commands that describe any state:
$ git status
$ git log --oneline -3
$ git remote -vThey change nothing and they answer most questions, including whether the problem is the editor at all.
- View → Output → Git for the command log
- Developer: Reload Window for anything that looks stuck
- Git: Show Git Output as a shortcut to the channel
- Help → Toggle Developer Tools → Console for extension errors, occasionally
The Git → Console tab is the equivalent log, and Help → Collect Logs gathers everything for a support question. See lesson 16.12.
If the failure is on the platform rather than in the editor, the merge request page and the job log are authoritative (lesson 14.3).
The same, in the Checks tab.
Common mistakes
- Reinstalling the editor for a Git problem.
- Not reading Output → Git, which usually contains the answer verbatim.
- Deleting
.git/index.lockwhile an operation is running. - Reporting "it doesn't work" without the command and the error.
- Changing several settings at once while diagnosing, so the cause is never identified.
Try it yourself
Goal: practise the diagnosis, not the fixes.
- Cause a problem deliberately: open a subfolder of your project instead of the root.
- Read what the Source Control view says, and name the cause before fixing it.
- Cause a second: commit on
mainand try to push to a protected branch, or push a branch that has moved on the server. - Read Output → Git, find Git's exact reply, and match it against the table above.
- Write the question you would ask if you could not fix it, with all four required parts.
Expected result: two problems diagnosed from the panels rather than guessed at, and a written question that would get an answer in one reply.
Show solution
Step 4 is the habit that generalises. Nearly every error in this table is a message Git printed, relayed by the editor. Once you read the output channel first, editor problems and Git problems separate themselves, and the second kind is covered by the whole of Section 12.