New Rule: Thou Shalt Document Any Magic File Your Code Complains Or Warns The User About
from Third Spruce Tree On The Left
From the
And ANOTHER thing...
department..
ok, #NewRule – if you write an app or service that uses a #directory to save important files, and you generate #errors in your logs about the files in said directory, but don't document what, if anything the user can do about it, that folder needs to have a README.txt
or .dirinfo
or something that explains what each of the files mean.. or what files should or shouldn't be there.
For a while now, everytime I apt upgrade
I get a bunch of these:
Notice: Ignoring file 'scootersoftware.list.migrate' in directory '/etc/apt/sources.list.d/' as it has an invalid filename extension
Notice: Ignoring file 'google-chrome.list.migrate' in directory '/etc/apt/sources.list.d/' as it has an invalid filename extension
Notice: Ignoring file 'vscode.list.migrate' in directory '/etc/apt/sources.list.d/' as it has an invalid filename extension
There's nothing in the apt
man page even about the /etc/apt/sources.list.d/
folder at all, let alone what a .migrate
file is. Nothing in anything in /etc/apt/
.
I found the code repo (https://github.com/Debian/apt) and there isn't anything there either.
Like, I have 3 brain cells, I'm guessing a .migrate
file in /etc/apt/sources.list.d
is a temporary file from – duh – migration, but if apt is throwing a msg like “hey, unexpected file, I'm going to ignore it” error then clearly the file shouldn't.. be.. there? And if so, what can/should I do about this?
So is it OK to delete .migrate
files? But but but,
tezoatlipoca@pickles17:/etc/apt/sources.list.d$ grep scooter *
scootersoftware.list.migrate:deb [signed-by=/usr/share/keyrings/scootersoftware-keyring.gpg] https://www.scootersoftware.com/ bcompare4 non-free
I DO use Beyond Compare from Scootersoft. And the Scootersoft package repo information isn't anywhere else:
tezoatlipoca@pickles17:/etc/apt$ grep -R -i scooter *
sources.list.d/scootersoftware.list.migrate:deb [signed-by=/usr/share/keyrings/scootersoftware-keyring.gpg] https://www.scootersoftware.com/ bcompare4 non-free
Would it be so hard to modify the apt
error message to add
Notice: Ignoring file "scootersoftware.list.migrate" in directory "/etc/apt/sources.list.d/" as it has an invalid filename extension - see "man apt datafiles" for more info.
Or,
Notice: Ignoring file "scootersoftware.list.migrate" in directory "/etc/apt/sources.list.d/" - this temp file can be safely deleted.
Because of search engine #enshittification I've been using Lycos , but IT wasn't giving me any useful results for [https://search1.lycos.com/web/?q=apt+.migrate+files]. In desperation, I turned to Google where Gemini reinforced my suspicion:
Google: apt ".migrate" files in /etc/apt/sources.list.d
AI Overview Files ending with .migrate in /etc/apt/sources.list.d/ are typically renamed or temporary files that were created during an upgrade or migration process, such as a system upgrade or a software migration. These files are usually ignored by apt because they do not have the expected .list extension. The apt package manager expects source list files in /etc/apt/sources.list.d/ to end with .list. When apt encounters a file with an extension like .list.migrate, it will generally ignore it and issue a warning message indicating an “invalid filename extension.” To resolve this, if the .migrate file contains valid source list entries that are intended to be active, it should be renamed to have a .list extension. For example, filename.list.migrate should be renamed to filename.list. If a corresponding .list file already exists, the .migrate file can often be safely deleted after verifying its content. Example: sudo mv /etc/apt/sources.list.d/webmin.list.migrate /etc/apt/sources.list.d/webmin.list
However, since I can't find a legit and authoritative second source to corroborate that .migrate
files in /etc/apt/sources.list.d
are in fact redundant, safe-to-delete files, I'll just have to take Gemini's word for it? (we all know how THAT goes usually).
At work, where I write the documentation that noone reads, our (Windows) software writes a bunch of magic files alongside the data files that the user provides. Since this data store is owned by the user, and users like shooting their own foot off, there's a chapter in the Admin guide that explains what each of the app's magic files do, how they're used by our app, and which ones the user is free to customize, how and why, and which ones the user should never ever modify. Along with when the file is created, and if its missing/corrupt (because our app tells them “Magic file is bork, please fix it”, how they can fix it... even if the fix is “call Innitech Support”.
The files within C:\Program Files\Innitech\App
are OURs and we don't document THOSE. But if your code is going to bitch about a magic file, but then doesn't explain at all about a magic file, that's not cool.
Changelog
2025-07-30 – initial