DirCore
DirCore is a Visual Studio Code extension that automatically keeps a small tracker file in empty workspace directories. This helps preserve folder structure in Git and other tools that normally ignore empty directories.
The default tracker filename is .folder-tracker.
Features
- Creates a tracker inside empty workspace directories.
- Removes only DirCore-owned trackers when a directory receives real content.
- Restores trackers when the last real file or subdirectory is removed.
- Works recursively across all workspace roots.
- Watches file create, delete, change, move, and rename events.
- Includes a periodic reconciliation fallback for missed filesystem events.
- Supports configurable excluded directories.
- Supports a configurable tracker filename.
- Uses a safety-first ownership marker:
DIRCORE_TRACKER_V1.
- Commands for workspace reconciliation, toggling tracking, and viewing diagnostics.
- No backend, account, network connection, telemetry, or shell execution.
Example
When you create an empty folder:
my-project/
`-- components/
`-- .folder-tracker
When you add a real file:
my-project/
`-- components/
`-- Button.tsx
DirCore removes only its own tracker file. It never deletes or overwrites user-created files.
Installation From VSIX
After a .vsix package has been generated:
- Open VS Code.
- Open the Command Palette.
- Run Extensions: Install from VSIX....
- Select the generated
dircore-0.0.1.vsix file.
- Reload VS Code if prompted.
Development
npm install
npm run compile
npm test
Press F5 in VS Code to launch an Extension Development Host after dependencies are installed.
Configuration
DirCore settings are available under the dircore namespace.
| Setting |
Default |
Description |
dircore.enabled |
true |
Enables or disables automatic tracking. |
dircore.trackerFileName |
.folder-tracker |
Tracker file name to create in empty folders. |
dircore.exclude |
.git, node_modules, .vscode |
Directory names or glob patterns to skip. |
dircore.reconcileInterval |
5000 |
Periodic reconciliation interval in milliseconds. Use 0 to disable periodic reconciliation. |
Invalid tracker names are rejected. Empty names, ., .., names with path separators, and names containing null characters are not allowed.
Commands
| Command |
ID |
Description |
| DirCore: Reconcile Workspace |
dircore.reconcileWorkspace |
Scans all workspace roots and repairs tracker state. |
| DirCore: Toggle Automatic Tracking |
dircore.toggle |
Enables or disables automatic tracking for the workspace. |
| DirCore: Show Output |
dircore.showOutput |
Opens the DirCore output channel. |
Exclusions
Excluded directories are not scanned or modified. Existing tracker-named files inside excluded directories are left untouched.
Examples:
{
"dircore.exclude": [
".git",
"node_modules",
".vscode",
"**/dist/**",
"**/coverage/**"
]
}
Ownership And Safety
DirCore writes this marker at the beginning of every tracker it creates:
DIRCORE_TRACKER_V1
Before removing a tracker, DirCore reads the file and verifies the marker. A matching filename alone is not treated as ownership proof. If .folder-tracker already exists and does not contain the marker, DirCore preserves it and logs the decision.
Safety guarantees:
- DirCore does not overwrite existing files.
- DirCore does not recursively delete directories.
- DirCore does not intentionally modify paths outside the active workspace roots.
- DirCore skips symbolic-link directories during recursive scans.
- DirCore does not collect or transmit user data.
Limitations:
- Filesystem events can be delayed or missed on remote, network, virtual, or heavily loaded filesystems.
- If a user edits or replaces a tracker file and removes the marker, DirCore will preserve it as unowned.
- A marker is a safety signal, not cryptographic proof of authorship.
Testing
npm test
The test script compiles the extension, compiles the test files, and runs Node's built-in test runner.
Package A VSIX
npm install
npm run compile
npm run package
The output file will be named like:
dircore-0.0.1.vsix
Publish To The Visual Studio Marketplace
Do not publish until you have chosen a real Marketplace publisher ID and reviewed the package contents.
Create a publisher at https://marketplace.visualstudio.com/manage.
Update the publisher field in package.json.
Create a Personal Access Token in Azure DevOps with Marketplace publish permissions.
Sign in with VSCE:
npx vsce login your-publisher-id
Package and publish:
npm run package
npx vsce publish
Troubleshooting
- Use DirCore: Show Output to inspect diagnostics.
- Run DirCore: Reconcile Workspace if the folder state looks stale.
- Check
dircore.exclude if a directory is not receiving a tracker.
- Check
dircore.enabled if automatic tracking is not running.
- Use
dircore.reconcileInterval: 0 if you only want event-driven reconciliation.
Supported Environments
DirCore targets VS Code ^1.92.0 on Windows, macOS, and Linux. Behavior depends on VS Code filesystem APIs and the reliability of the underlying filesystem provider.
