Git Course 0%

Troubleshooting IntelliJ and Git

Intermediate IntelliJ UI ≈ 8 min

Before this lesson

What you will learn

  • A repeatable way to diagnose any IDE Git problem
  • The common symptoms and their causes
  • What to include when asking for help

After this lesson you can

  • I can fix most IntelliJ Git problems myself and describe the rest precisely

Why this matters

Half of what looks like an IDE problem is Git speaking, relayed. Separating the two takes one minute and decides everything about what to do next.

The one-minute diagnosis

  1. Git tool window → Console: read the command the IDE ran and Git's exact reply.
  2. Terminal (⌥F12): run the same command yourself.
  3. If it fails in both, it is Git or the repository (Section 12). If it works in the terminal and not in the IDE, it is IntelliJ.

The common dozen

Symptom Cause Fix
No Git menu, no VCS widget The open folder is not a repository, or a subfolder was opened Open the folder containing .git (lesson 16.3)
"Cannot run program git" The Git path is wrong Settings → Version Control → Git → Path to Git executable, then Test
The IDE is busy for minutes after a clone Indexing, not Git Wait; it is much faster afterwards
git status shows changes the Commit window does not Changelists, or a file in a different changelist Look at all changelists, or enable the staging area (lesson 16.5)
Work disappeared after switching branches Smart Checkout shelved it The Shelf tab (lesson 16.6)
Commits show the wrong author git config user.email Set it per repository (lesson 3.4)
Push fails with Authentication failed Git's credential, not the IDE account Clear it in Settings → Passwords and push again (lesson 16.2)
Push rejected, non-fast-forward The branch moved on the server Update Project, then push (lesson 7.6)
Merge Requests window is empty The platform account is missing or its token expired Re-add the account with a token that has api
A commit contains reformatting you did not do Before Commit options are on Settings → Version Control → Commit (lesson 16.1)
A file keeps coming back in commits Not ignored, or committed before being ignored .gitignore, then git rm --cached (lesson 4.3)
"index.lock" errors An interrupted Git operation left the file Confirm nothing is running, then delete .git/index.lock

Work that seems to have vanished

Four places to look, in order:

  1. The Shelf tab — Smart Checkout and manual shelving both put things there.
  2. The Stash tab — or git stash list in the terminal.
  3. Local History on the file or folder — the only place uncommitted work survives (lesson 16.8).
  4. git reflog in the terminal — for anything that was committed (lesson 12.1).

Between them, those four cover almost everything that can go missing. The order matters: the first two are IDE features, the third is the IDE's safety net for uncommitted work, and the fourth is Git's for committed work.

Asking for help

Include the four things that make the question answerable (lesson 13.9):

  • What you were doing, in plain words.
  • The exact command, copied from the Console tab.
  • Git's exact reply.
  • git status and git log --oneline -3 from the terminal.

For an IDE problem rather than a Git one, Help → Collect Logs and Diagnostic Data gathers what JetBrains support asks for.

How to do it

Terminal
$ git status
$ git log --oneline -3
$ git remote -v

They change nothing and they answer most questions, starting with whether the IDE is involved at all.

Common mistakes

  • Reinstalling the IDE for a Git problem.
  • Not reading the Console, which usually contains the answer verbatim.
  • Invalidating caches to fix a Git issue; that is for indexing.
  • Deleting .git/index.lock while an operation is running.
  • Reporting "it doesn't work" without the command and the reply.

Try it yourself

Goal: practise the diagnosis rather than the fixes.

  1. Open a subfolder of your project as a project, and note the symptom: no Git menu, no VCS widget.
  2. Reopen the correct folder.
  3. Make a change, switch branches, and accept Smart Checkout. Then find your change in the Shelf tab before unshelving it.
  4. Cause a rejected push (push a branch that has moved on the server) and read Git's reply in the Console.
  5. Write the help request you would send for step 4, with all four required parts.

Expected result: three symptoms recognised from their signatures, and one written question that would get an answer in a single reply.

Show solution

Step 3 is the one that saves real distress. "My changes are gone" after switching branches is almost always Smart Checkout, and the Shelf tab has them. Knowing the four places work can hide, in order, turns a frightening moment into a thirty-second check.

Check yourself

1. Where should you look first when a Git action in IntelliJ misbehaves?
2. Your uncommitted changes disappeared after switching branches. Where are they?
3. When is Invalidate Caches the right action?

Key terms

Logs (program output) Configuration IDE

Related