File Path Header README

Portuguese (Brazil): README.pt-BR.md

Effortlessly add relative file path headers to the top (or bottom) of your code files with the File Path Header extension for Visual Studio Code or any OpenVSX-compatible IDE. This extension is designed to enhance your workflow, especially when leveraging large language models (LLMs) such as ChatGPT, Claude, and other AI assistants to write and manage your code.

Extension Page

• Open VSX: https://open-vsx.org/extension/FlavioCoutinhoGO/file-path-header
• VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=FlavioCoutinhoGO.file-path-header

Features

• Automatic File Path Headers: Automatically insert the relative path of your file as a header at the top (or footer) of your code files upon opening.
• Language Support: Supports a wide range of programming languages including JavaScript, TypeScript, Python, Java, C, C++, C#, HTML, CSS, PHP, Ruby, Perl, Lua, and many more.
• Duplicate Prevention: Ensures the header is only added if it doesn't already exist, preventing duplicate entries.
• Customizable Include Paths: Specify which directories should have file path headers added.
• Control over Header Position: Switch between inserting the comment at the header or footer; changes automatically move an existing comment to the new location when this option changes.
• Flexible Header Template: Use placeholders such as {path}, {directory}, {filename}, {workspaceFolder}, and {workspaceName} (now including a trailing separator for directories) to compose whatever comment format you need.
• Apply Modes & Batch Update: Choose between all and missingOnly to control automatic behavior and use the Update All Relative Path Comments command to refresh every eligible file with progress/cancel support.

Requirements

No additional requirements or dependencies are needed for this extension.

Extension Settings

This extension contributes the following settings:

• filePathHeader.includePaths: (Default: ["src"]) - An array of paths to include for file path headers. Paths are relative to the workspace root. The extension only targets files under the directories declared here.
• filePathHeader.pathSeparator: (Default: "auto") - A string to define what separator to use:
  • "auto" - (use OS separator, / for Unix-based systems, \ for Windows),
  • "forward" - (/)
  • "backward" - (\).
• filePathHeader.position: (Default: "header") - Controls where the path comment is inserted:
  • "header" - top of file
  • "footer" - bottom of file
  • When this option changes, the extension moves an existing comment from top to bottom (or the reverse) automatically.
• filePathHeader.headerTemplate: (Default: "{path}") - Template for comment content.
  • Supported placeholders: {path}, {directory}, {filename}, {workspaceFolder}, {workspaceName}
• filePathHeader.applyMode: (Default: "all") - Controls update behavior for both auto-open processing and batch update command.
  • "all" - create/update/move existing comments according to current settings
  • "missingOnly" - only insert comments in files that do not have one yet

filePathHeader.pathSeparator controls how the generated path appears in the header comment. Example for the same file path:

• "auto": uses your OS default separator
• "forward": src/components/Button.tsx
• "backward": src\components\Button.tsx

By default, only files in the "src" folder will have headers added. You can customize this behavior in your VS Code settings.

How to Customize Include Paths

1. Open VS Code Settings (File > Preferences > Settings)
2. Search for "File Path Header"
3. Find the "Include Paths" setting
4. Click on "Edit in settings.json"
5. Add or modify the filePathHeader.includePaths array. For example:

{
  "filePathHeader.includePaths": ["src", "tests", "lib"]
}

This configuration will add file path headers to files in the "src", "tests", and "lib" directories and their subdirectories.

How to Customize Separator

1. Open VS Code Settings (File > Preferences > Settings)
2. Search for "File Path Header"
3. Find the "Separator" setting
4. Click on "Edit in settings.json"
5. Add or modify the filePathHeader.pathSeparator string. For example:

{
  "filePathHeader.pathSeparator": "forward"
}

How to Customize Template

{
  "filePathHeader.headerTemplate": "{filename} - {path}"
}

Available placeholders:

• {path}
• {filename}
• {workspaceFolder}
• {workspaceName}

Batch Update Command

Use File Path Header: Update All Relative Path Comments from Command Palette to update all eligible files at once.

Known Issues

There are no known issues at this time. If you encounter any problems, please open an issue on the GitHub repository.

Release Notes

1.1.0

• Added filePathHeader.position with header/footer options.
• Added automatic comment relocation when position changes (header <-> footer), preventing duplicates.
• Added filePathHeader.headerTemplate with placeholders ({path}, {filename}, {workspaceFolder}, {workspaceName}).
• Added Update All Relative Path Comments command for workspace-wide updates with progress/cancel support.
• Added VS Code Marketplace link to extension docs.

1.0.1

• Build output entry updated from extension.js to extension.cjs to fix extension activation/runtime compatibility with the current packaging setup (type: module + CommonJS bundle).
• Added localization for extension metadata and settings/command labels (English + Portuguese/Brazilian) via package.nls files.

1.0.0

• Initial release of File Path Header.