Automatic File Headers

Code name: auto-header

Automatically configures VS Code with customizable file headers based on your project’s license, company, and team information.

Also included automatically: repairs broken host paths in your git config and restores your SSH commit-signing key on every attach, on both local and cloud containers, with nothing to set up on your end — see helpers4-common for how it works.

When to use this

Use this when you want every new file in a project to carry a consistent license/copyright header — SPDX identifier, project name, company, contributors — without anyone copy-pasting it by hand or forgetting it.

Alternatives:

• VS Code extensions like psioniq File Header do the same job, but you configure the template yourself in settings.json; this feature derives the template from projectName/license/ company options and writes the VS Code config for you.
• A CI-side license-header linter (e.g. a pre-commit hook or a dedicated Actions step) enforces headers on files that slip through, which pairs well with this feature rather than replacing it — this one generates headers as you create files, a linter catches anything that wasn’t.

Features

✨ Two header styles:

• Simple (default): Standard 3-line header with project, copyright, and license
• Custom: Your own multi-line header template

🔧 Flexible configuration:

• Project name (required)
• License in SPDX format (default: MIT)
• Company/organization name (optional)
• Copyright start year (optional, defaults to current year)
• Contributors list (optional)

🚀 Helper script: h4-init-headers command to initialize headers in any project

Requirements

This feature requires jq, which is provided by the common-utils feature. All official devcontainers base images (mcr.microsoft.com/devcontainers/*) include it automatically.

If you use a minimal base image (e.g. ubuntu:latest), add common-utils first:

{
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {},
    "ghcr.io/helpers4/devcontainer/auto-header:1": { ... }
  }
}

Installation

Add to your .devcontainer/devcontainer.json:

Simple Header (Default)

{
  "features": {
    "ghcr.io/helpers4/devcontainer/auto-header:1": {
      "projectName": "my-awesome-project",
      "license": "MIT",
      "company": "Acme Corp",
      "sinceYear": "2024"
    }
  }
}

This generates headers like:

// This file is part of my-awesome-project.
// Copyright (C) 2024-2026 Acme Corp
// SPDX-License-Identifier: MIT

Custom Header

{
  "features": {
    "ghcr.io/helpers4/devcontainer/auto-header:1": {
      "headerType": "custom",
      "projectName": "my-awesome-project",
      "customHeaderLines": "/**\n * @project my-awesome-project\n * @author Team\n * @license MIT\n */"
    }
  }
}

Usage

After the container is created, initialize headers in your project:

h4-init-headers

This command:

1. Reads your feature configuration
2. Generates appropriate header settings
3. Creates or merges with .vscode/settings.json

Configuration Options

Option	Type	Default	Description
headerType	string	simple	Header style: simple or custom
projectName	string	required	Project name for header
license	string	MIT	SPDX license identifier
company	string	optional	Company or organization name
contributors	string	optional	Comma-separated contributor names
sinceYear	string	current year	Copyright start year
customHeaderLines	string	required for custom	Custom header lines (separated by literal \n). Supports placeholders: {{projectName}}, {{license}}, {{company}}, {{contributors}}, {{sinceYear}}, {{currentYear}}, {{copyrightYears}}, {{author}} (= company or projectName).

Examples

TypeScript Project with LGPL License

{
  "features": {
    "ghcr.io/helpers4/devcontainer/auto-header:1": {
      "projectName": "helpers4-typescript",
      "license": "LGPL-3.0",
      "company": "helpers4",
      "sinceYear": "2025",
      "contributors": "Alice, Bob, Charlie"
    }
  }
}

Apache Licensed Corporate Project

{
  "features": {
    "ghcr.io/helpers4/devcontainer/auto-header:1": {
      "projectName": "enterprise-app",
      "license": "Apache-2.0",
      "company": "ACME Industries",
      "sinceYear": "2020"
    }
  }
}

Custom Header with Specific Format

{
  "features": {
    "ghcr.io/helpers4/devcontainer/auto-header:1": {
      "headerType": "custom",
      "projectName": "my-lib",
      "license": "LGPL-3.0-or-later",
      "company": "ACME",
      "sinceYear": "2024",
      "customHeaderLines": "/*!\n * @file part of {{projectName}}\n * @copyright Copyright (C) {{copyrightYears}} {{author}}\n * @license SPDX-License-Identifier: {{license}}\n */"
    }
  }
}

What Gets Created

After running h4-init-headers:

• .vscode/settings.json: Updated with file header configuration
• Feature configuration: Stored in /etc/h4-auto-header/config.json (system-wide)

Typical Workflow

# 1. Add feature to devcontainer.json
# 2. Rebuild container (feature runs automatically)
# 3. Run initialization command
h4-init-headers

# 4. Start creating files - headers will be added automatically
# 5. Save files - headers auto-update on file changes

Integrating with Your Workflow

Auto-initialize on Container Creation

Add postCreateCommand to auto-initialize:

{
  "features": {
    "ghcr.io/helpers4/devcontainer/auto-header:1": {
      "projectName": "my-project",
      "license": "MIT"
    }
  },
  "postCreateCommand": "h4-init-headers"
}

Multiple Projects

Run h4-init-headers in each project directory:

cd project-a && h4-init-headers
cd project-b && h4-init-headers

The script will use the appropriate .vscode directory for each project.

Common License Identifiers

• MIT - MIT License
• Apache-2.0 - Apache License 2.0
• GPL-3.0 - GNU General Public License v3.0
• LGPL-3.0 - GNU Lesser General Public License v3.0
• BSD-2-Clause - BSD 2-Clause License
• BSD-3-Clause - BSD 3-Clause License
• ISC - ISC License
• MPL-2.0 - Mozilla Public License 2.0

See SPDX License List for complete list.

Troubleshooting

Script not found

# Ensure feature was installed
which h4-init-headers

# If not found, reinstall feature or recreate container

Settings not applied

# Verify configuration file exists
cat /etc/h4-auto-header/config.json

# Re-run initialization
h4-init-headers

# Check VS Code has correct workspace open

Headers not auto-inserting

1. Verify file header support is installed and enabled
2. Check .vscode/settings.json exists and has correct config
3. Restart VS Code or reload window: Ctrl+Shift+P → “Developer: Reload Window”

Year not updating automatically

The headers are generated with fixed copyright years (e.g., 2024-2026) at the time the devcontainer is created. If you want the year to automatically update:

1. Rebuild the devcontainer to regenerate the configuration with current year
2. Or manually update the copyright years in .vscode/settings.json

Integration with helpers4 Projects

This feature complements the helpers4 development environment:

• typescript: Work with properly licensed utility functions
• devcontainer: Ensure consistent headers across team
• action: Validate file headers in CI/CD pipelines

License

Copyright (c) 2025 helpers4
Licensed under LGPL-3.0 - see LICENSE file for details

See Also

• psi-header Extension
• SPDX License Identifiers
• Conventional Commits

Version History

• v1.2.4: Added Rust (.rs) file headers, using // line comments.
• v1.2.3: Documentation only, no functional change — added a “When to use this” section with alternatives, matching the equivalent sections other features in this catalog already had.
• v1.2.2: Documentation only, no functional change — the previous wording sweep made the JSON description field far too long, shifting focus away from the feature itself onto the self-heal side benefit. Shortened to 5 words and kept generic (no implementation detail like “git config”), matching the original’s brevity and level of detail.
• v1.2.1: Documentation only, no functional change — the self-heal callout above (and the JSON description field) led with internal jargon (“helpers4’s self-heal”) instead of the actual benefit; reworded to lead with what it does, with the full mechanism staying in helpers4-common’s own README.
• v1.2.0: Documentation only, no functional change — mentions that helpers4-common’s automatic git-config self-heal (see above) now comes along with this feature.
• v1.1.0: Switched from an inline copy of helpers4-common’s bootstrap (user detection, apt helpers) to a direct dependsOn on the helpers4-common feature — no behavior change, just a single source of truth for that logic instead of a copy every feature had to keep in sync.