Skip to content

Troubleshooting

Jump to bottom
Loky edited this page Oct 14, 2026 · 6 revisions

Troubleshooting and Known Limitations

Plugin / setup

Symptom Cause / fix
Gitot disables itself at startup ([Gitot Fatal] line) git not found on PATH. Install Git and restart the editor.
Push/pull hangs then is killed Waiting on a credential prompt. See Credentials and GitHub Token. Large asset transfers: raise network_timeout_sec.
LFS panel shows a setup guide git-lfs missing or git lfs install not run. Follow the guide's button. See Git LFS.
Issues tab missing Disabled in Settings (github_issues_enabled).
Console warns "This Godot project is the folder … of its git repository" Gitot needs the project folder to be the repository root: file lists and editor refresh would point at the wrong files. Open the repo root as the Godot project.
Dock shows "No git repository in this project folder." The folder has no .git. Press Initialize repository. If a .git exists but git rejects it (broken repo, "dubious ownership"), no init is offered and the panels show git's own error.
Branches list is empty right after Initialize repository Normal: git lists no branch until the first commit. The status line already shows main. Commit once.
"Could not initialize a git repository" Git older than 2.28 (no git init -b) or a read-only project folder.
A network command logs "Refused: ... unsafe for the shell." Push, pull and fetch pass through a shell, so a branch / tag name must use only A-Za-z0-9._/@+:-, and the project folder path must not contain " or % (Windows), or ", $, backtick, \ (Linux / macOS). Nothing was run. Rename it or move the project.
Push asks for a URL, then "Could not add the remote 'origin'" The URL is not https://, ssh:// or git@host:path, has user:token@ in it, or an origin already exists (git remote -v).
owner/repo in the status line is not a link By design when origin is http://, has user:token@ or a port, uses an ssh user other than git, or is a local path. Use https://host/owner/repo, git@host:owner/repo or ssh://git@host/owner/repo.
Branch switch, restore or create fails with "not a git command" Git older than 2.32 (no switch/restore). Update Git.
Log says "Skipped: another git write is running." Another write (commit, push, pull...) held the lock. Wait until Commit leaves "Working...", then retry.
Issues tab says "Issues are only available for repositories hosted on github.com." By design: the origin is GitLab, Gitea or another host. Every other Gitot feature still works.
Lists end with "N more files not shown" Only the first 500 rows of a list are drawn. Press Show all, or add a .gitignore rule for the folder that floods the list. Stage All stages every file either way.

Editor refresh limits (Godot, not Gitot)

  • After Pull, branch switch, Restore or Stash Pop, Godot has no API to reload an open script tab. Gitot recompiles the class and shows a toast, but the visible text updates on the next editor focus change (click away and back). If it still doesn't: Project → Reload Current Project or restart. Best practice: close the script tab before switching/pulling/popping. Engine issues: godot#104540, godot#73808.
  • resource_saved doesn't fire for every save path (e.g. Run auto-saves). Use Refresh Diff Gutter, or leave and re-enter the editor window.
  • Switching to a branch with a different project.godot triggers Godot's own "File has been modified outside Godot" dialog. Click Reload from Disk.

Branches

  • The ahead/behind line names the branch Gitot last read. After a switch made outside Gitot (terminal), it can show the previous branch until the next refresh.
  • Changed-file detection uses the reflog (HEAD@{1}): it only compares with the previous checkout. After a fresh clone or rapid successive switches Gitot shows a warning toast. Reopen scenes/scripts manually.

Stash

  • Stash includes untracked files (-u). Popping after a branch switch can reintroduce conflicting files.
  • Pop refreshes only the files git reports. On older Git without --include-untracked support for stash show, or on failure, you get a "couldn't verify changed files" toast. After a conflicting pop nothing is refreshed: check for conflict markers.

Diff viewer and gutter

  • Merge commits aren't handled specially (combined diff, file list may be short or empty). Binary files are listed with an empty diff. Git-quoted (non-ASCII) names may fail to load their diff.
  • The gutter only works on tracked files.

Git LFS

  • Tracking is pattern-based and only affects files committed after the rule exists. Already-committed blobs need git lfs migrate (terminal). Commit .gitattributes for the rule to apply.
  • Only the root .gitattributes is read. Names with spaces appear escaped and aren't exempt from the Large-File Guard.
  • On GitHub stats are an estimate (origin's file list at last fetch), not your quota.

Non-ASCII text on Windows

Git output is re-decoded as UTF-8. Verified on Windows-1252 only. Other code pages (CJK) are untested and may show wrong characters.

Still stuck? Open an Issue with OS, Godot version and steps to reproduce.

Clone this wiki locally