Troubleshoot source control
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Troubleshoot source control View as Markdown Ask in VS Code Ask in VS Code Insiders Use this article to resolve common Git problems in Visual Studio Code.
Start with the symptom that matches your problem, then use the Git Output window to collect more information if the suggested fix doesn't resolve it. Git not found If VS Code reports 'Git not found', it can't locate a Git executable in the environment where your repository is open. Run git --version in a terminal in that environment. For a remote workspace, check the remote environment, not only your local machine. If the command isn't found, follow the Git installation prerequisites , then restart VS Code.
If Git works in the terminal but not in VS Code, check the Git Output window for the executable paths it tried. If needed, set git.path Open in VS Code Open in VS Code Insiders to the full path of the Git executable, then restart VS Code. When detection succeeds, the Git Output window shows the Git executable and version, and the Source Control view can open your repository. A commit fails because user.name or user.email is missing The error 'Make sure you configure your "user.name" and "user.email" in git' means Git doesn't have the author identity needed to create a commit.
Signing in to your Git hosting service doesn't configure this identity. In a terminal opened in the repository folder, check the effective values: git config --get user.name git config --get user.email Set any missing or incorrect values for this repository: git config user.name "<your-name>" git config user.email "<your-email>" These commands affect only the current repository. To use the same identity across repositories, follow the global configuration steps .
Retry the commit. The new commit uses the configured name and email. This doesn't change existing commits. Ignored files still appear in Source Control Git ignore rules apply to untracked files. Adding a file to .gitignore doesn't stop Git from tracking a file that is already committed or staged. In a terminal opened in the repository folder, check whether the file is in Git's index: git ls-files -- "<file>" If the command lists the file, Git is tracking it.
If you only staged a new file, unstage it and add an ignore rule. If the file is already committed, keep it tracked or use the procedure below to stop tracking it. If the command doesn't list the file, inspect the ignore rule that applies: git check-ignore -v -- "<file>" Correct missing or negated patterns in .gitignore . A pattern beginning with ! makes a matching file eligible for inclusion again. See the Git ignore pattern reference for pattern syntax.
After a matching ignore rule applies, the untracked file no longer appears as a change. The files.exclude Open in VS Code Open in VS Code Insiders setting hides files in the Explorer. It doesn't change Git tracking or ignore rules. Stop tracking a file without deleting the local copy Use this procedure only when an already committed file should no longer be part of the repository: Caution Removing a tracked file from Git's index stages a deletion from the repository, not from your working folder.
Committing and pushing it changes tracking for everyone. When collaborators pull the commit, Git can remove their tracked copies. Coordinate this change before sharing it. The file remains in earlier commits. Add an ignore rule for the file to .gitignore . Remove the file from Git's index while keeping your working copy: git rm --cached -- "<file>" Review and commit .gitignore and the staged deletion when you're ready to share the tracking change.
After the commit, your local file remains on disk and is ignored. To hide a file from the Explorer without changing repository tracking, use files.exclude Open in VS Code Open in VS Code Insiders instead. Push is rejected because the remote has new commits A rejection containing non-fast-forward or fetch first means the remote branch has commits that your local branch doesn't contain. Git rejects the push to avoid overwriting remote history.
Fetch the remote commits and review incoming and outgoing history . Confirm that you're working on the intended branch and remote. Commit your local changes or stash unfinished work before integrating the incoming commits. Pull the remote commits , using your team's merge or rebase workflow. If conflicts occur, resolve them and complete the operation . Push again . The push can succeed once your branch includes the remote history and you have permission to update it.
Caution Don't force push to bypass this rejection. A force push can overwrite commits that others depend on. If you intentionally rewrote shared history, agree on a recovery plan with your collaborators first. If the error instead mentions permissions or branch protection, use the next section rather than pulling repeatedly. Permission denied, read-only repository, or protected branch These errors have different causes.
Check the Git Output window for the failing command and the full error. Run git remote -v in the repository folder to confirm that the fetch and push URLs point to the intended repository. Symptom Diagnosis and action Authentication failed or Permission denied (publickey) Git couldn't authenticate. For HTTPS, check the account and credentials stored by your credential helper . For SSH, check your key and agent using the SSH authentication guidance .
Retry after correcting the credentials. The remote reports that you don't have permission to push Your account might have read access but not write access, or Git might be using credentials for the wrong account. Update the stored credentials, request write access from a maintainer, or push a branch to a fork you own. The remote rejects an update to a protected branch or reports a repository rule violation Authentication succeeded, but the host's policy blocks the update.
Push your work to an allowed feature branch and open a pull request, or follow the checks required by your repository. Changing credentials or force pushing doesn't bypass these rules. A local path reports Permission denied or Read-only file system Git can't write to the working folder or .git directory. Check filesystem permissions, ownership, and whether the drive is mounted read-only. Restore write access for your account before retrying.
Retry the failed operation after correcting its cause. Successful authentication doesn't grant repository write access or override branch protection. Push, pull, or sync doesn't finish A Git operation that doesn't finish often indicates that Git is waiting for authentication but the credential prompt isn't visible. Open the Git Output window and check the most recent command for an authentication error. Configure a Git credential helper for your operating system.
Run the operation again and complete any sign-in prompt. Git Credential Manager is the recommended credential helper for Windows, macOS, and Linux. Git for Windows includes Git Credential Manager. Git authentication prompts appear repeatedly If git.autofetch Open in VS Code Open in VS Code Insiders is on, background fetches can trigger repeated authentication prompts even when you haven't selected a Git action. Automatic fetching is off by default in the editor window and on by default in the Agents window.
Check the Git Output window to see which command triggered the prompt. Configure a Git credential helper to store valid credentials for the remote. If you don't want background fetches, turn off git.autofetch Open in VS Code Open in VS Code Insiders . This stops those fetches but doesn't fix credentials needed for manual fetch, pull, or push operations. Git actions are unavailable after initializing a repository Push, pull, an
The rest of this page is on the live site.