English | 中文

A powerful VS Code extension that allows you to add customizable aliases and remarks to files and folders in your file tree, making project navigation and organization more intuitive.

• Customizable Aliases: Add meaningful names and descriptions to any file or folder
• Dual Configuration: Support for both public (shared) and private (personal) aliases
• Visual Integration: Seamlessly integrated into VS Code's file explorer
• Easy Management: Simple right-click interface for adding and modifying aliases
• Persistent Storage: Aliases are saved in JSON configuration files within your workspace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Folder Alias"
4. Click Install
5. Reload VS Code when prompted

1. Download the latest .vsix file from releases
2. Open VS Code
3. Go to Extensions
4. Click ... (More Actions) → Install from VSIX...
5. Select the downloaded .vsix file

1. Right-click on any file or folder in the VS Code Explorer
2. Select "Add Alias"
3. Choose the alias scope:
   • Public: Saved in folder-alias.json (can be committed to version control)
   • Private: Saved in private-folder-alias.json (ignored by version control)
4. Enter your desired alias/description
5. Press Enter to save

1. Right-click on a file/folder that already has an alias
2. Select "Add Alias"
3. Edit the existing text or clear it to remove the alias
4. Press Enter to update

After manually editing the JSON configuration files, you can refresh the file explorer display:

1. Right-click anywhere in the Explorer
2. Select "Refresh Aliases"
3. Or use Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and type "Refresh Aliases"
4. The file explorer will reload all alias configurations from the JSON files

The extension supports two configuration locations with smart priority:

The extension will prioritize .vscode directory over root directory:

• .vscode/folder-alias.json - Public aliases (highest priority)
• .vscode/private-folder-alias.json - Private aliases (highest priority)
• folder-alias.json - Public aliases (fallback)
• private-folder-alias.json - Private aliases (fallback)

Behavior Rules:

• Reading: If .vscode/folder-alias.json exists, it will be used instead of root folder-alias.json
• Initialization: The extension will only create configuration files in the root directory if no corresponding files exist in .vscode
• Saving: When saving aliases, the extension will save to .vscode only if the corresponding file already exists there, otherwise to root directory

You can organize your aliases in either location:

• .vscode/ directory: Keeps your workspace root clean and organized
• Root directory: Traditional location, compatible with existing setups

{
  "src/components/Button": {
    "description": "🎛️ Reusable Button Component",
    "tooltip": "Primary button component with variants"
  },
  "docs/api": {
    "description": "📚 API Documentation",
    "tooltip": "REST API endpoints documentation"
  }
}

• Node.js (v18+)
• pnpm (preferred package manager)
• VS Code

# Clone the repository
git clone https://github.com/Muromi-Rikka/folder-alias.git
cd folder-alias

# Install dependencies
pnpm install

# Build the extension
pnpm build

# Run in development mode (with watch)
pnpm dev

1. Open the project in VS Code
2. Press F5 to open a new Extension Development Host window
3. Make changes to the source code
4. Reload (Ctrl+R / Cmd+R) the Extension Development Host to see changes

The extension automatically creates and manages configuration files in your workspace. No additional settings are required.

For team collaboration, consider adding this to your .gitignore:

# Folder Alias - Personal aliases
private-folder-alias.json

• src/index.ts - Extension entry point and activation
• src/command/add-alias.command.ts - Command handler for adding/modifying aliases
• src/file-alias.ts - File decoration provider and alias management
• src/utils/file.util.ts - File I/O utilities for configuration management

• TypeScript - Primary language
• reactive-vscode - Reactive programming for VS Code extensions
• tsdown - Build tool for TypeScript
• ESLint - Code linting
• Vitest - Testing framework

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes
4. Run tests: pnpm test
5. Run linting: pnpm lint
6. Commit your changes: git commit -am 'Add new feature'
7. Push to the branch: git push origin feature/new-feature
8. Submit a pull request

This project is licensed under the GPLv3 License.

If you encounter any issues or have feature requests, please create an issue on GitHub.

See CHANGELOG.md for a detailed history of changes and updates.

Made with ❤️ by Rikka