Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

UserInterfaceState.xcuserstate keeps showing up in git status

ErrorUserInterfaceState.xcuserstate shows as modified in git status after adding it to .gitignore

Short answer

A .gitignore rule never affects a file Git already tracks. If xcuserstate was committed once, remove it from the index with git rm --cached, then keep the ignore rule. If it was never tracked and still shows up, the pattern or its location is wrong. Ask git check-ignore which rule matches.

  • Applies to Git 2.4x, Xcode 26, macOS 26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Git whether the file is tracked and which rule would ignore it. Tracked files are hidden from the plain check, so use --no-index to see the rule.

    git ls-files | grep xcuserstate
    git check-ignore -v --no-index MyApp.xcodeproj/project.xcworkspace/xcuserdata/*/UserInterfaceState.xcuserstate
  2. 2Match what you see, then jump to its fix

    1. 1git ls-files lists the xcuserstate path, and git status shows it as modifiedThe file was committed before the ignore rule existedFix
    2. 2git check-ignore -v --no-index prints nothing for the file, or prints a rule starting with !The pattern does not match the pathFix

What does the error look like?

  • UserInterfaceState.xcuserstate shows as modified in git status after adding it to .gitignore
  • xcuserdata/<user>.xcuserdatad/UserInterfaceState.xcuserstate

Cause 1 of 2

The file was committed before the ignore rule existed

1Check

The gitignore documentation says files already tracked by Git are not affected by the file. The rule is correct but never applies to this path.

git ls-files | grep -E 'xcuserstate|xcuserdata'

2Fix

Remove the files from the index only. This keeps them on disk, and the ignore rule then keeps them out of later commits. Commit the removal.

git ls-files -z '*xcuserdata*' | xargs -0 git rm --cached
git commit -m "Stop tracking Xcode user state"

3Verify

git status shows a clean tree after you open and close the project in Xcode.

git status --short

Confirmed by git-scm.com

Did this fix it?

Cause 2 of 2

The pattern does not match the path

1Check

A pattern with a slash at the start or in the middle is relative to the folder of that .gitignore. A trailing slash makes the pattern match only directories, so a rule written as *.xcuserstate/ never matches the file. A negated rule (!) re-includes a file, and a file cannot be re-included when its parent directory is excluded.

git check-ignore -v --no-index -- MyApp.xcodeproj/project.xcworkspace/xcuserdata/*/UserInterfaceState.xcuserstate

2Fix

Use patterns that match at any depth: no leading slash, and a trailing slash only on folders.

# .gitignore
xcuserdata/
*.xcuserstate

3Verify

The verbose check now prints the rule with the file name.

git check-ignore -v --no-index -- MyApp.xcodeproj/project.xcworkspace/xcuserdata/*/UserInterfaceState.xcuserstate

Confirmed by git-scm.com

Did this fix it?

How do I stop it coming back?

  • Add xcuserdata/ and *.xcuserstate to .gitignore in the first commit of every Xcode project.
  • Run git status after the first commit and before pushing, so a file that should be ignored is caught early.
  • Use git check-ignore -v when a rule seems not to work, instead of editing patterns at random.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Mobile apps

App record creation fails because you lack permission

You cannot add a new app in App Store Connect as a Developer or limited user

Only the Account Holder, an Admin or an App Manager can create an app record, and Apple blocks it until the Account Holder has signed the latest agreement.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.